Route

A Route defines how the gateway forwards traffic to a backend. Each route attaches to one or more Gateway CRs and may apply any number of Middleware CRs.

API group: gateway.jkaninda.dev
Version: v1alpha1
Kind: Route

When the goma-k8s-provider sidecar is enabled (default), changes to Route resources are hot-reloaded into the gateway without a pod restart.

Minimal example

A single backend, host-based routing, attached to a Gateway named gateway:

apiVersion: gateway.jkaninda.dev/v1alpha1
kind: Route
metadata:
  name: api
  namespace: default
spec:
  gateways:
    - gateway
  path: /
  hosts:
    - api.example.com
  target: http://api-service.default.svc.cluster.local:8080
  methods:
    - GET
    - POST

Load-balanced backends

Use backends instead of target to distribute traffic across multiple endpoints. Active health checks remove unhealthy backends from rotation.

apiVersion: gateway.jkaninda.dev/v1alpha1
kind: Route
metadata:
  name: api-lb
spec:
  gateways:
    - gateway
  path: /api
  rewrite: /
  hosts:
    - api.example.com
  backends:
    # 80/20 weighted split between v1 and v2.
    - endpoint: http://api-v1.default.svc.cluster.local:8080
      weight: 80
    - endpoint: http://api-v2.default.svc.cluster.local:8080
      weight: 20
    # Canary backend — only receives traffic carrying X-Canary: true.
    # `exclusive: true` keeps it out of the general LB pool.
    - endpoint: http://api-canary.default.svc.cluster.local:8080
      exclusive: true
      match:
        - source: header
          name: X-Canary
          operator: equals
          value: "true"
  healthCheck:
    path: /healthz
    interval: 15s
    timeout: 3s
    healthyStatuses: [200, 204]

Backend matching

match rules pin requests to a specific backend based on request attributes. Sources: header, cookie, query, ip. Operators: equals, not_equals, contains, not_contains, starts_with, ends_with, regex, in.

When exclusive: true, the backend only receives matched traffic. When false (default), matched traffic is pinned but the backend still participates in normal load balancing.

Per-route TLS

Serve a custom certificate for the route’s hosts. Reference a kubernetes.io/tls Secret:

spec:
  hosts:
    - api.example.com
  tls:
    secretName: api-example-com-tls

When the K8s provider sidecar is enabled, the cert/key are written to disk and hot-reloaded — no pod restart.

For ACME-managed certificates, configure certManager on the parent Gateway instead.

Backend TLS / mTLS

Control how the gateway connects to backend servers (separate from the cert it serves to clients):

spec:
  security:
    forwardHostHeaders: true
    enableExploitProtection: true       # SQLi / XSS heuristics
    tls:
      insecureSkipVerify: false
      rootCAsSecret: backend-ca         # Secret with custom CA bundle
      clientCertSecret: backend-client  # kubernetes.io/tls secret for mTLS

Maintenance mode

Return a static response instead of proxying to the backend:

spec:
  maintenance:
    enabled: true
    status: 503
    body: |
      {"error":"maintenance","message":"Back at 14:00 UTC."}

Attaching middlewares

List Middleware CR names by metadata.name. They are applied in order:

spec:
  middlewares:
    - api-jwt
    - api-rate-limit

See the Middleware documentation for the supported types and their configuration.

Spec reference

Field	Type	Description
`gateways`	[]string	Required. Names of `Gateway` CRs (same namespace) this route attaches to.
`path`	string	Required. URL path matched by this route.
`rewrite`	string	Path rewrite (e.g. `/api` → `/`).
`target`	string	Single backend URL. Mutually exclusive with `backends`.
`methods`	[]string	Allowed HTTP methods (e.g. `GET`, `POST`). Empty = all.
`enabled`	bool	Whether the route is active. Default: `true`.
`priority`	int	Match order — higher matches first.
`hosts`	[]string	Hostnames for host-based routing.
`backends`	[]object	Multiple backends for load balancing (see below).
`healthCheck`	object	Active backend health check (see below).
`security`	object	Per-route security settings.
`middlewares`	[]string	Middleware CR names to apply.
`disableMetrics`	bool	Suppress Prometheus per-route metrics for this route.
`tls`	object	`secretName` of a `kubernetes.io/tls` Secret to serve for the route’s hosts.
`maintenance`	object	Maintenance mode (see above).

`spec.backends[]`

Field	Type	Description
`endpoint`	string	Backend URL.
`weight`	int	Load-balancing weight.
`exclusive`	bool	When `true`, only matched requests reach this backend.
`match[].source`	enum	`header`, `cookie`, `query`, `ip`.
`match[].name`	string	Header / cookie / query parameter name.
`match[].operator`	enum	`equals`, `not_equals`, `contains`, `not_contains`, `starts_with`, `ends_with`, `regex`, `in`.
`match[].value`	string	Comparison value (comma-separated for `in`).

`spec.healthCheck`

Field	Type	Default	Description
`path`	string	—	Health check path.
`interval`	string	`30s`	Check interval.
`timeout`	string	`5s`	Per-check timeout.
`healthyStatuses`	[]int	—	HTTP statuses considered healthy.

`spec.security`

Field	Type	Default	Description
`forwardHostHeaders`	bool	`true`	Forward `X-Forwarded-Host` and related headers.
`enableExploitProtection`	bool	`false`	Block common SQLi / XSS patterns.
`tls.insecureSkipVerify`	bool	`false`	Skip backend TLS verification (not recommended).
`tls.rootCAsSecret`	string	—	Secret with CA bundle for backend TLS.
`tls.clientCertSecret`	string	—	`kubernetes.io/tls` Secret for backend mTLS.

Status

kubectl get routes

NAME   GATEWAYS      PATH   TARGET                                READY   AGE
api    [gateway]     /      http://api.default.svc.cluster.local  true    2m

Ready: true means the route is valid and synced into the parent Gateway’s configuration.