Gateway API

Octopus reconciles a subset of the standard Kubernetes Gateway API (gateway.networking.k8s.io/v1, plus ReferenceGrant at v1beta1) into its router. This page documents only the fields the translators actually honor — examples avoid fields that are parsed but ignored, or not modeled at all.

Install the upstream Gateway API CRDs separately (see Install); Octopus does not ship them.

GatewayClass01

Octopus claims the controllerName gateway.octopus.io/gateway-controller. Create a GatewayClass pointing at it, and point your Gateway at that class:

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: octopus
spec:
  controllerName: gateway.octopus.io/gateway-controller

Gateway02

A Gateway declares listeners. Octopus reads listener hostnames (to constrain attached routes) and, when TLS termination is enabled, listener TLS config.

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: octopus-gateway
  namespace: infra
spec:
  gatewayClassName: octopus
  listeners:
    - name: web
      hostname: "*.example.com"
      port: 8080
      protocol: HTTP
    - name: websecure
      hostname: api.example.com
      port: 443
      protocol: HTTPS
      tls:
        mode: Terminate
        certificateRefs:
          - kind: Secret
            name: api-tls

Honored GatewaySpec fields: gatewayClassName, and per-listener name, hostname, port, protocol, and tls (mode, certificateRefs). A listener's hostname is intersected with each attached route's hostnames (see hostname intersection).

HTTPRoute03

An HTTPRoute attaches to one or more parent gateways and declares routing rules. Each rule produces one upstream cluster (from its backendRefs) and a set of routes — one per host × match × path × method.

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: api-route
  namespace: default
spec:
  parentRefs:
    - name: octopus-gateway
      namespace: infra
  hostnames:
    - api.example.com
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /api
          method: GET
      filters:
        - type: URLRewrite
          urlRewrite:
            path:
              type: ReplacePrefixMatch
              replacePrefixMatch: /v2
      backendRefs:
        - name: api-svc
          port: 8080
          weight: 100

Honored fields

Not honored

These are parsed (so manifests using them still apply) but do not currently affect routing, so don't rely on them:

• matches[].headers (header matching).

• URLRewrite hostname rewrite and path.type: ReplaceFullPath; non-URLRewrite filters such as RequestRedirect and RequestHeaderModifier.

A rule with no backendRefs is skipped with a warning.

Backend resolution

A backendRef resolves to the in-cluster Service DNS name <name>.<namespace>.svc on the given port (the route's own namespace is used when backendRef.namespace is omitted). With multiple backends in a rule, the cluster uses weighted round-robin and each backend's weight (default 1) sets its share.

Hostnames and listener intersection

The effective hosts for a route are the Gateway API intersection of the route's hostnames with its parent listener's hostname:

• both empty → matches any host;

• one empty → the non-empty side constrains;

• both set → pairwise overlap (exact vs. wildcard *.x); a non-overlapping pair attaches nothing.

So an HTTPRoute with hostnames: [api.acme.com, evil.com] attached to a listener with hostname: "*.acme.com" only serves api.acme.com.

GRPCRoute04

A GRPCRoute is reconciled like an HTTPRoute, but gRPC calls are HTTP/2 POSTs to /{service}/{method}. Each rule produces one upstream cluster and one route per match.

apiVersion: gateway.networking.k8s.io/v1
kind: GRPCRoute
metadata:
  name: echo-route
  namespace: default
spec:
  parentRefs:
    - name: octopus-gateway
      namespace: infra
  rules:
    - matches:
        - method:
            service: echo.Echo
            method: Ping
      backendRefs:
        - name: echo-svc
          port: 50051

Honored fields: parentRefs, hostnames (same intersection as HTTPRoute), rules[].matches[].method (service + method), and rules[].backendRefs[]. The method match maps to a path:

GRPCRoute matches[].headers and any filters[] are parsed but not honored; a rule with no backendRefs is skipped.

ReferenceGrant (cross-namespace backends)05

A reference from a resource in one namespace to a target in another (e.g. a backend Service, or a TLS Secret) requires a ReferenceGrant in the target's namespace. Same-namespace references never need a grant. The grant's from lists the permitted referencing (group, kind, namespace) tuples; to lists the permitted target (group, kind, [name]) — omitting name permits all names of that kind.

apiVersion: gateway.networking.k8s.io/v1beta1
kind: ReferenceGrant
metadata:
  name: allow-routes-from-app
  namespace: backends            # lives in the TARGET namespace
spec:
  from:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      namespace: app             # who may reference
  to:
    - group: ""
      kind: Service              # what may be referenced (here, all Services in `backends`)

How it reconciles into the router06

Every honored Gateway API resource is translated into the same intermediate route table that Octopus CRDs and your static config feed into, then applied to the live router — see Operator for the merge pipeline, and Octopus CRDs for layering Octopus-specific behavior (auth, rate limiting) onto these routes with OctopusPolicy.