Gateway API

The next-generation Kubernetes ingress API — expressive, extensible, and role-oriented. Gateway API replaces Ingress for advanced traffic management while preserving a clean separation between infrastructure operators and application developers.

Why Gateway API Exists

Ingress (covered in 05-ingress.html) was never designed for the routing complexity modern platforms require. It lacks native support for traffic splitting, header-based routing, protocol awareness, and cross-namespace delegation. Every controller vendor ended up encoding these capabilities as proprietary annotations — creating a fragmented ecosystem where NGINX annotations don't work on Traefik, and vice versa.

Gateway API is a SIG-Network project that became GA in Kubernetes 1.31. It solves these problems by:

• Expressiveness — traffic splitting, header routing, request mirroring, URL rewriting are first-class API concepts, not annotations.
• Extensibility — a well-defined extension points model via policy attachment (BackendTLSPolicy, etc.).
• Role separation — GatewayClass/Gateway owned by infra team; HTTPRoute owned by app team. Cross-namespace safely controlled by ReferenceGrant.
• Portability — Core conformance is standardized; moving between controllers requires minimal manifest changes.

Resource Model

Gateway API introduces a hierarchy of resources, each scoped to a different concern and owned by a different persona:

GatewayClass

GatewayClass is cluster-scoped. It identifies which controller implementation handles Gateways that reference this class — analogous to IngressClass but richer:

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: cilium
spec:
  controllerName: io.cilium/gateway-controller
  description: "Cilium Gateway API implementation"
  parametersRef:                    # optional: controller-specific config CRD
    group: cilium.io
    kind: CiliumGatewayConfig
    name: default
    namespace: kube-system
Copy

Gateway

A Gateway represents a deployment of a load-balancing infrastructure (e.g., a provisioned cloud LB or an Envoy Deployment). It is typically owned by the infrastructure team and lives in a shared namespace:

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: prod-gateway
  namespace: gateway-infra
spec:
  gatewayClassName: cilium
  listeners:
    - name: http
      port: 80
      protocol: HTTP
      allowedRoutes:
        namespaces:
          from: Selector
          selector:
            matchLabels:
              gateway-access: "true"    # only namespaces with this label
    - name: https
      port: 443
      protocol: HTTPS
      tls:
        mode: Terminate                  # Terminate | Passthrough
        certificateRefs:
          - name: prod-tls-secret
            kind: Secret
      allowedRoutes:
        namespaces:
          from: All                      # or: Same | Selector
    - name: grpc-tls
      port: 8443
      protocol: HTTPS                    # HTTPS for gRPC-TLS
      tls:
        mode: Terminate
        certificateRefs:
          - name: grpc-tls-secret
Copy

After provisioning, the Gateway controller writes status conditions:

kubectl get gateway prod-gateway -n gateway-infra -o yaml
# status:
#   addresses:
#     - type: IPAddress
#       value: 203.0.113.42
#   conditions:
#     - type: Accepted
#       status: "True"
#     - type: Programmed
#       status: "True"
Copy

Role Separation

This is Gateway API's most important design principle. Three distinct personas each own different resources:

HTTPRoute — Full Reference

HTTPRoute is the workhorse of Gateway API. It expresses HTTP/HTTPS routing rules with first-class support for path matching, header matching, traffic splitting, and request/response transformation.

Basic Routing

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: store-route
  namespace: my-app                  # app developer's namespace
spec:
  parentRefs:
    - name: prod-gateway
      namespace: gateway-infra       # must match Gateway namespace
      sectionName: https             # bind to specific listener by name
  hostnames:
    - "store.example.com"
    - "*.example.com"                # wildcard hostnames supported
  rules:
    - matches:
        - path:
            type: PathPrefix         # Exact | PathPrefix | RegularExpression
            value: /api
          headers:
            - name: X-Version
              type: Exact            # Exact | RegularExpression
              value: "v2"
      backendRefs:
        - name: api-v2-svc
          port: 8080
          weight: 100
    - matches:
        - path:
            type: PathPrefix
            value: /
      backendRefs:
        - name: frontend-svc
          port: 80
Copy

Traffic Splitting (Canary / Blue-Green)

Unlike Ingress canary which requires two Ingress objects, Gateway API handles it in a single HTTPRoute with weight fields on backendRefs:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: canary-route
  namespace: my-app
spec:
  parentRefs:
    - name: prod-gateway
      namespace: gateway-infra
  hostnames: ["app.example.com"]
  rules:
    - backendRefs:
        - name: app-stable
          port: 80
          weight: 90        # 90% traffic to stable
        - name: app-canary
          port: 80
          weight: 10        # 10% traffic to canary
Copy

Header-Based Routing

rules:
  # Route internal users to canary based on header
  - matches:
      - headers:
          - name: X-Canary-User
            type: Exact
            value: "true"
    backendRefs:
      - name: app-canary
        port: 80

  # Route by query parameter
  - matches:
      - queryParams:
          - name: debug
            type: Exact
            value: "1"
    backendRefs:
      - name: app-debug
        port: 80

  # Method-based routing
  - matches:
      - method: POST
        path:
          type: PathPrefix
          value: /api/write
    backendRefs:
      - name: write-service
        port: 8080
Copy

HTTPRoute Filters

Filters transform requests and responses inline. Multiple filters can be applied per rule or per backendRef:

rules:
  - matches:
      - path:
          type: PathPrefix
          value: /api
    filters:
      # Strip /api prefix before forwarding
      - type: URLRewrite
        urlRewrite:
          path:
            type: ReplacePrefixMatch
            replacePrefixMatch: /      # /api/users → /users

      # Add tracing header
      - type: RequestHeaderModifier
        requestHeaderModifier:
          add:
            - name: X-Forwarded-Prefix
              value: /api
          remove:
            - X-Internal-Debug

      # Shadow 10% to mirror service (fire-and-forget, response ignored)
      - type: RequestMirror
        requestMirror:
          backendRef:
            name: shadow-service
            port: 80

    backendRefs:
      - name: api-service
        port: 8080

  # HTTPS redirect on HTTP listener
  - matches:
      - path:
          type: PathPrefix
          value: /
    filters:
      - type: RequestRedirect
        requestRedirect:
          scheme: https
          statusCode: 301
Copy

ReferenceGrant — Cross-Namespace Security

By default, HTTPRoute can only reference backends (backendRef) in the same namespace. Cross-namespace references require explicit approval from the target namespace via a ReferenceGrant object. This prevents a compromised application namespace from routing traffic to services in other namespaces.

# In the TARGET namespace (where the Service lives)
apiVersion: gateway.networking.k8s.io/v1beta1
kind: ReferenceGrant
metadata:
  name: allow-store-to-payments
  namespace: payments             # the namespace being accessed
spec:
  from:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      namespace: store            # the namespace making the reference
  to:
    - group: ""
      kind: Service
      name: payment-svc           # optional: restrict to specific service name
                                  # omit to allow any Service in this namespace
Copy

The same mechanism protects Gateway TLS certificates. A Gateway referencing a Secret in another namespace also needs a ReferenceGrant from that Secret's namespace.

GRPCRoute

GRPCRoute (GA in v1.31) provides gRPC-aware routing with service and method matching. Unlike HTTPRoute with gRPC, it understands gRPC framing natively:

apiVersion: gateway.networking.k8s.io/v1
kind: GRPCRoute
metadata:
  name: grpc-route
  namespace: my-app
spec:
  parentRefs:
    - name: prod-gateway
      namespace: gateway-infra
      sectionName: grpc-tls
  hostnames: ["grpc.example.com"]
  rules:
    - matches:
        - method:
            type: Exact                # Exact | RegularExpression
            service: com.example.UserService
            method: GetUser            # omit to match all methods in service
      backendRefs:
        - name: user-service-grpc
          port: 9090
          weight: 80
        - name: user-service-grpc-v2
          port: 9090
          weight: 20
    - matches:
        - method:
            service: com.example.AdminService  # match all AdminService RPCs
      filters:
        - type: RequestHeaderModifier
          requestHeaderModifier:
            add:
              - name: X-Admin-Route
                value: "true"
      backendRefs:
        - name: admin-service-grpc
          port: 9090
Copy

L4 Routes: TCPRoute, UDPRoute, TLSRoute

These resources are still in v1alpha2 but are widely used for non-HTTP load balancing:

TCPRoute

apiVersion: gateway.networking.k8s.io/v1alpha2
kind: TCPRoute
metadata:
  name: postgres-route
  namespace: database
spec:
  parentRefs:
    - name: prod-gateway
      namespace: gateway-infra
      sectionName: postgres         # listener: port 5432, protocol TCP
  rules:
    - backendRefs:
        - name: postgres-primary
          port: 5432
          weight: 100
Copy

TLSRoute (Passthrough)

apiVersion: gateway.networking.k8s.io/v1alpha2
kind: TLSRoute
metadata:
  name: db-tls-passthrough
  namespace: database
spec:
  parentRefs:
    - name: prod-gateway
      namespace: gateway-infra
      sectionName: db-tls           # listener: port 5433, protocol TLS, mode Passthrough
  hostnames:
    - "db.internal.example.com"
  rules:
    - backendRefs:
        - name: postgres-tls
          port: 5432
Copy

BackendTLSPolicy — mTLS to Backends

BackendTLSPolicy (v1alpha3) configures TLS from the Gateway to the backend service — independent of whether the client connection is TLS or plain HTTP. This enables mTLS or one-way TLS for all traffic within the cluster:

apiVersion: gateway.networking.k8s.io/v1alpha3
kind: BackendTLSPolicy
metadata:
  name: api-backend-tls
  namespace: my-app
spec:
  targetRefs:
    - group: ""
      kind: Service
      name: api-service             # applies to this Service's port 8443
      namespace: my-app
  validation:
    caCertificateRefs:
      - group: ""
        kind: ConfigMap
        name: backend-ca-cert       # CA that signed the backend's certificate
    hostname: api.internal          # SNI hostname for cert verification
    wellKnownCACertificates: System  # alternative: use system CA bundle
Copy

BackendTLSPolicy follows the direct policy attachment model — it attaches directly to a Service, not to a route. This means any route (HTTPRoute, GRPCRoute) that references that Service will automatically use TLS when BackendTLSPolicy is present.

ParentReference — Multi-Listener Binding

An HTTPRoute can bind to multiple Gateways or multiple listeners on the same Gateway. Each parentRef entry can specify an optional sectionName (listener name) and port:

spec:
  parentRefs:
    # Bind to HTTPS listener on prod gateway
    - name: prod-gateway
      namespace: gateway-infra
      sectionName: https
      port: 443

    # Also bind to staging gateway (different namespace)
    - name: staging-gateway
      namespace: staging-infra
      sectionName: https
      port: 443
Copy

Route status is per-parentRef — each attachment reports its own Accepted and ResolvedRefs conditions:

kubectl get httproute store-route -n my-app -o jsonpath='{.status.parents}'
# [
#   {
#     "parentRef": {"name":"prod-gateway","namespace":"gateway-infra","sectionName":"https"},
#     "conditions": [
#       {"type":"Accepted","status":"True","reason":"Accepted"},
#       {"type":"ResolvedRefs","status":"True","reason":"ResolvedRefs"}
#     ]
#   }
# ]
Copy

Status Conditions Reference

Gateway Conditions

Listener Conditions

HTTPRoute Conditions

Controller Implementations

Conformance Profiles

Gateway API defines three tiers of conformance. Check an implementation's conformance report before choosing:

Installation

Gateway API CRDs are not bundled with Kubernetes — install them separately. Two channels available:

# Standard channel (stable: GatewayClass, Gateway, HTTPRoute, GRPCRoute, ReferenceGrant)
kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.2.0/standard-install.yaml

# Experimental channel (adds TCPRoute, UDPRoute, TLSRoute, BackendTLSPolicy, etc.)
kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.2.0/experimental-install.yaml

# Verify CRDs installed
kubectl get crd | grep gateway.networking.k8s.io
Copy

Then install your chosen controller. Example with Envoy Gateway:

helm install eg oci://docker.io/envoyproxy/gateway-helm \
  --version v1.1.0 \
  --namespace envoy-gateway-system \
  --create-namespace

# Verify
kubectl get pods -n envoy-gateway-system
kubectl get gatewayclass
Copy

Migration from Ingress

Most NGINX Ingress configurations map directly to HTTPRoute equivalents. Key differences:

cert-manager with Gateway API

# cert-manager v1.14+ supports Gateway API natively
# Annotation on Gateway resource:
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: prod-gateway
  namespace: gateway-infra
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod   # same as Ingress
spec:
  gatewayClassName: cilium
  listeners:
    - name: https
      port: 443
      protocol: HTTPS
      hostname: "*.example.com"
      tls:
        mode: Terminate
        certificateRefs:
          - name: wildcard-tls     # cert-manager creates this Secret
Copy

Advanced Patterns

Shared Gateway Multi-Tenancy

A single Gateway can serve hundreds of application teams. Each team creates HTTPRoutes in their namespace pointing at the shared Gateway. The Gateway's allowedRoutes controls which namespaces can attach:

# Infrastructure team creates one Gateway per environment
# Gateway in: gateway-infra namespace
# App teams create HTTPRoutes in their own namespaces

# Team A: namespace "team-a" (has label gateway-access: "true")
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: team-a-app
  namespace: team-a
spec:
  parentRefs:
    - name: prod-gateway
      namespace: gateway-infra
  hostnames: ["app-a.company.com"]
  rules:
    - backendRefs:
        - name: app-a-svc
          port: 80

# Team B: namespace "team-b"
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: team-b-app
  namespace: team-b
spec:
  parentRefs:
    - name: prod-gateway
      namespace: gateway-infra
  hostnames: ["app-b.company.com"]
  rules:
    - backendRefs:
        - name: app-b-svc
          port: 80
Copy

Timeouts and Retries (Extended)

rules:
  - matches:
      - path:
          type: PathPrefix
          value: /api
    timeouts:
      request: 30s              # total request timeout (client → backend)
      backendRequest: 10s       # per-attempt timeout to backend
    retry:                      # Extended conformance
      codes: [503, 504]         # retry on these status codes
      attempts: 3
      backoff: 250ms
    backendRefs:
      - name: api-service
        port: 8080
Copy

Session Persistence (Extended)

rules:
  - backendRefs:
      - name: session-app
        port: 80
    sessionPersistence:
      sessionName: "shop-session"
      absoluteTimeout: 1h
      idleTimeout: 30m
      type: Cookie              # Cookie | Header
      cookieConfig:
        lifetimeType: Session   # Session | Permanent
Copy

Ingress vs Gateway API Comparison

For a more complete Ingress reference, see 05-ingress.html. This table focuses on the architectural tradeoffs:

Metrics, Alerting & Troubleshooting

Key Metrics to Watch

Alerting Rules

# Alert: HTTPRoute not accepted
- alert: HTTPRouteNotAccepted
  expr: |
    kube_httproute_status_conditions{condition="Accepted",status="False"} > 0
  for: 5m
  labels:
    severity: warning
  annotations:
    summary: "HTTPRoute {{ $labels.name }} in {{ $labels.namespace }} is not accepted"

# Alert: Gateway not programmed
- alert: GatewayNotProgrammed
  expr: |
    kube_gateway_status_conditions{condition="Programmed",status="False"} > 0
  for: 10m
  labels:
    severity: critical
  annotations:
    summary: "Gateway {{ $labels.name }} is not programmed"

# Alert: High error rate through gateway
- alert: GatewayHighErrorRate
  expr: |
    rate(envoy_http_downstream_rq_5xx[5m]) /
    rate(envoy_http_downstream_rq_total[5m]) > 0.05
  for: 5m
  labels:
    severity: warning

# Alert: Backend response latency P99 > 2s
- alert: GatewayBackendHighLatency
  expr: |
    histogram_quantile(0.99,
      rate(envoy_cluster_upstream_rq_time_bucket[5m])
    ) > 2000
  for: 10m
  labels:
    severity: warning
Copy

Troubleshooting Runbooks

# Check route status
kubectl get httproute my-route -n my-app -o yaml | grep -A20 status

# Common reasons and fixes:
# NotAllowedByListeners → namespace missing gateway-access label
kubectl label namespace my-app gateway-access=true

# NoMatchingListenerHostname → route hostname doesn't match listener hostname
# NoMatchingParent → Gateway name/namespace/sectionName is wrong
# RefNotPermitted → ReferenceGrant missing for cross-namespace backendRef

# Check gateway status
kubectl get gateway prod-gateway -n gateway-infra -o yaml

# Check controller pod logs
kubectl logs -n envoy-gateway-system -l app=gateway-helm -f

# Common causes:
# - GatewayClass controller not running
# - TLS certificate Secret missing or in wrong namespace + no ReferenceGrant
# - Cloud LB provisioning failure (check controller events)
kubectl describe gateway prod-gateway -n gateway-infra

# Check route status for ResolvedRefs condition
kubectl get httproute my-route -n my-app -o jsonpath='{.status.parents[*].conditions}'

# BackendNotFound: Service doesn't exist or wrong name/port
kubectl get svc api-service -n my-app

# RefNotPermitted: cross-namespace backendRef without ReferenceGrant
# Create ReferenceGrant in the target namespace:
cat <

# Verify HTTPRoute has correct weights
kubectl get httproute canary-route -n my-app -o jsonpath='{.spec.rules[*].backendRefs}'

# Check both services have ready endpoints
kubectl get endpointslices -n my-app

# Check if controller supports traffic splitting (Extended conformance)
kubectl get gatewayclass cilium -o yaml | grep -i conformance

# Generate test traffic and measure split
for i in $(seq 1 100); do curl -s https://app.example.com/ -o /dev/null -w "%{http_code}\n"; done

# 502 usually means gateway can't reach backend
# Check pod readiness
kubectl get pods -n my-app -l app=api-service

# Check if Service has endpoints
kubectl get endpoints api-service -n my-app

# If BackendTLSPolicy is configured: verify backend is serving TLS on the right port
kubectl exec -n my-app deploy/api-service -- openssl s_server -help 2>&1 | head

# Check if port matches between Service.spec.ports and BackendTLSPolicy targetRef
kubectl describe backendtlspolicy api-backend-tls -n my-app