Skip to main content

Route

A Route defines how incoming HTTP traffic is matched and forwarded to backend services. It supports path and host matching, request rewriting, CORS, method filtering, health checks, load balancing, middleware, and more.

Configuration Options​

Below are the configuration options for defining routes in Goma Gateway:

Basic Route Options​

  • path (string): Path to match (e.g., /api/v1/resource).

  • name (string): Unique name for the route.

  • enabled (boolean): Enables or disables the route. If set to false, the route will not be proxied.

  • hosts ([]string): Optional list of allowed hostnames.

  • rewrite (string): Rewrites the request path before forwarding.

    For advanced rewriting (regex-based), consider using the rewriteRegex middleware.

  • methods ([]string): Allowed HTTP methods (e.g., GET, POST). Defaults to all if omitted.

  • target (string): Single backend target (overridden if backends is set).

  • backends ([]Backend): List of backend endpoints for load balancing.

  • security: Per-route security configuration.

  • tls: Per-route TLS settings.

  • priority (int): Optional priority for route matching. Lower values take precedence.

  • disableMetrics (boolean): If true, disables metrics collection for this route.

Minimal Route Configuration​

version: 2
gateway:
  routes:
    - name: Example
      path: /cart
      target: http://cart-service:8080

Health Check Configuration​

Configure periodic health checks for route backends:

healthCheck:
  path: "/health"
  interval: 30s      # Default: 30s
  timeout: 10s       # Default: 10s
  healthyStatuses: [200, 404]
  • path (string): URL path used for health checks.
  • interval (duration): How frequently to check.
  • timeout (duration): Timeout for the health check request.
  • healthyStatuses ([]int): List of HTTP status codes considered healthy.

Security Configuration​

Control forwarding behavior and backend TLS validation:

security:
  forwardHostHeaders: true
  enableExploitProtection: false
  tls:
    insecureSkipVerify: false
    rootCAs: /etc/goma/certs/root.ca.pem
  • forwardHostHeaders (bool, default: true): Whether to forward the original Host header.
  • enableExploitProtection (bool, default: false): Enable built-in protections against known exploits.
  • tls.insecureSkipVerify (bool, default: false): Disable TLS certificate verification for backend.
  • tls.rootCAs: Custom root CA (file path, raw PEM, or base64-encoded string).

CORS​

CORS is configured with the responseHeaders middleware and listed in the route's middlewares:

middlewares:
  - name: api-cors
    type: responseHeaders
    rule:
      cors:
        enabled: true
        origins:
          - http://localhost:3000
          - https://dev.example.com
        allowedHeaders:
          - Origin
          - Authorization
        maxAge: 1728000
        allowCredentials: true

gateway:
  routes:
    - name: api
      path: /api
      target: http://api:8080
      middlewares: [api-cors]
Removed in v1.0

The per-route cors block was removed in v1.0. See Cross-Origin Resource Sharing for the replacement, and the v1.0 upgrade note for everything else that moved.

Route Priority​

  • If no route has a priority defined, routes are matched by longest path.
  • If priority is set, lower numbers take precedence during matching.

Example: Route with Security​

version: 2
gateway:
  routes:
    - name: cart
      path: /cart
      rewrite: /
      target: http://cart-service:8080
      security:
        forwardHostHeaders: true
        enableExploitProtection: true
        tls:
          insecureSkipVerify: true
          rootCAs: /etc/goma/certs/root.ca.pem

Example: Limited HTTP Methods​

version: 2
gateway:
  routes:
    - name: Example
      enabled: false
      path: /store/cart
      target: http://cart-service:8080
      methods: [POST, GET]
      middlewares:
        - api-forbidden-paths
        - jwt-auth

Example: Route with Health Check​

version: 2
gateway:
  routes:
    - name: Example
      path: /store/cart
      backends:
        - endpoint: http://cart-service:8080
      methods: [PATCH, GET]
      healthCheck:
        path: "/health/live"
        interval: 30s
        timeout: 5s
        healthyStatuses: [200, 404]

Example: Route with Middleware​

version: 2
gateway:
  routes:
    - name: Example
      path: /store/cart
      rewrite: /
      backends:
        - endpoint: http://cart-service:8080
      healthCheck:
        path: "/health/live"
        interval: 30s
        timeout: 5s
        healthyStatuses: [200, 404]
      middlewares:
        - api-forbidden-paths
        - jwt-auth

Example: Route with Load Balancing​

version: 2
gateway:
  routes:
    - path: /
      name: example route
      hosts:
        - example.com
        - example.localhost
      rewrite: /
      backends:
        - endpoint: https://example.com
          weight: 1
        - endpoint: https://example1.com
          weight: 3
        - endpoint: https://example2.com
          weight: 2
      healthCheck:
        path: /
        interval: 30s
        timeout: 10s
        healthyStatuses: [200, 404]