Gateway API

TL;DR

• Gateway API is Ingress’s successor; fixes Ingress’s limitations: annotation sprawl, single flattened object, limited protocols
• Three-object model: GatewayClass (infra tier) → Gateway (platform tier) → HTTPRoute (app tier); separates RBAC boundaries
• Supports TCP, UDP, TLS, gRPC natively (not Ingress limitations)
• HTTPRoute owns routing rules; attaches to Gateway (may be cross-namespace via ReferenceGrant)
• Separate GatewayClass per controller implementation (like IngressClass); controller instantiates Gateways
• Not all Ingress Controllers support Gateway API yet; verify controller compatibility before adopting

Core Concepts

Three-Layer Architecture

GatewayClass: Template for Gateways; specifies which controller implementation to use (e.g., “nginx-gateway”, “istio”). Cluster-level resource; created by infrastructure team once.

Gateway: Instance of a GatewayClass; specifies listeners (protocol, port, TLS), allocated to a specific namespace. Created and owned by platform team. Controls resource quotas and which routes can attach.

HTTPRoute: L7 routing rules (host/path matching); owned by application team. References a Gateway to attach; can be in different namespace (with ReferenceGrant).

This hierarchy maps to RBAC boundaries: infra controls GatewayClass, platform controls Gateway, apps own HTTPRoute.

HTTPRoute Attachment

HTTPRoute specifies parentRefs to one or more Gateways. Can reference Gateways in different namespaces if:

1. Gateway’s allowedRoutes permits it (allowedRoutes.namespaces.from: All, Selector, etc.)
2. A ReferenceGrant exists authorizing the cross-namespace reference

Protocol Support

Gateway API natively supports:

• HTTP/HTTPS (L7 routing)
• TCP (L4, port-based)
• UDP (L4, port-based)
• TLS (L4 encryption)
• gRPC (L7, gRPC-specific routing)

Ingress never natively supported these (required service mesh or workarounds).

ReferenceGrant

Explicitly authorizes cross-namespace references. Prevents namespace A from accidentally (or maliciously) hijacking a Gateway in namespace B.

Example:

apiVersion: gateway.networking.k8s.io/v1beta1
kind: ReferenceGrant
metadata:
  name: allow-app-routes
  namespace: platform  # Gateway's namespace
spec:
  from:
  - group: gateway.networking.k8s.io
    kind: HTTPRoute
    namespace: app-team-1  # Allow HTTPRoute from this namespace
  to:
  - group: gateway.networking.k8s.io
    kind: Gateway
    name: main-gateway  # Reference specifically this Gateway (optional)

GatewayClass as Controller Selector

Similar to IngressClass. Each Gateway controller (nginx, Istio, Envoy, cloud providers) provides a GatewayClass. Gateways reference the class; controller watches for matching Gateways and instantiates real infrastructure.

Comparison Table

Command Reference

GatewayClass Definition

apiVersion: gateway.networking.k8s.io/v1beta1
kind: GatewayClass
metadata:
  name: nginx-gateway
spec:
  controllerName: k8s.io/ingress-nginx/gateway
  description: "Nginx Gateway Controller"
  parametersRef:
    group: gateway.networking.k8s.io
    kind: GatewayConfig
    name: nginx-config

Gateway Definition

apiVersion: gateway.networking.k8s.io/v1beta1
kind: Gateway
metadata:
  name: main-gateway
  namespace: platform
spec:
  gatewayClassName: nginx-gateway
  listeners:
  - name: http
    port: 80
    protocol: HTTP
  - name: https
    port: 443
    protocol: HTTPS
    tls:
      certificateRefs:
      - name: api-tls-cert
  allowedRoutes:
    namespaces:
      from: Selector
      selector:
        matchLabels:
          gateway-access: "true"

HTTPRoute Definition

apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
  name: api-routes
  namespace: api-team
spec:
  parentRefs:
  - name: main-gateway
    namespace: platform
  hostnames:
  - api.example.com
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /users
    backendRefs:
    - name: user-service
      port: 8080
  - matches:
    - path:
        type: PathPrefix
        value: /orders
    backendRefs:
    - name: order-service
      port: 8080

ReferenceGrant for Cross-Namespace

apiVersion: gateway.networking.k8s.io/v1beta1
kind: ReferenceGrant
metadata:
  name: allow-api-team-routes
  namespace: platform
spec:
  from:
  - group: gateway.networking.k8s.io
    kind: HTTPRoute
    namespace: api-team
  to:
  - group: gateway.networking.k8s.io
    kind: Gateway

Essential Commands

# List GatewayClasses
kubectl get gatewayclasses

# List Gateways
kubectl get gateways -A

# List HTTPRoutes
kubectl get httproutes -A

# Check Gateway status
kubectl describe gateway main-gateway -n platform

# Check HTTPRoute status
kubectl describe httproute api-routes -n api-team

# Check listener readiness
kubectl get gateway main-gateway -n platform -o json | jq '.status.listeners'

Common Pitfalls

Pitfall: HTTPRoute Cannot Attach to Gateway (Silent Failure) HTTPRoute created, but status shows attachment failed; no error message.

• Why: Gateway’s allowedRoutes doesn’t permit the HTTPRoute’s namespace, or no ReferenceGrant exists for cross-namespace reference.
• Fix: Check HTTPRoute status: kubectl describe httproute <name>. Check Gateway allowedRoutes config: kubectl describe gateway <name>. Create ReferenceGrant if cross-namespace: specify from (HTTPRoute namespace) and to (Gateway name).

Pitfall: Assuming All Ingress Controllers Support Gateway API Migrating from Ingress to Gateway API; controller doesn’t support it.

• Why: Gateway API is newer; not all Ingress Controller implementations have added support yet. Support varies by controller and version.
• Fix: Verify controller’s Gateway API support before adopting. Check controller documentation or GitHub repo for feature matrix. Run pilot deployment in non-production cluster first.

Pitfall: GatewayClass Not Found Gateway creation fails; “specified gatewayClassName doesn’t exist.”

• Why: GatewayClass needs to be created first. It’s typically installed by the controller provider or manually by infrastructure team.
• Fix: Verify GatewayClass exists: kubectl get gatewayclasses. If not present, install the Gateway controller (e.g., helm install nginx-gateway). Verify controller is running: kubectl get pods -n kube-system | grep gateway.

Pitfall: Listener Port Conflict Multiple Gateways in cluster trying to bind same port (80, 443) on same node.

• Why: Ports are host resources; only one Gateway listener can bind per port. Multiple Gateways need different ports or different load balancers.
• Fix: Use non-overlapping port ranges per Gateway, or use separate external load balancers per Gateway. Or consolidate Gateways into single shared Gateway (add listeners, increase replicas).

Pitfall: TLS Certificate Missing in Gateway Listener HTTPRoute with HTTPS listener fails; certificate not found.

• Why: Gateway listener specifies certificateRefs, but Secret doesn’t exist in Gateway’s namespace.
• Fix: Verify Secret exists: kubectl get secret -n <gateway-namespace>. Create Secret if missing: kubectl create secret tls <cert-name> --cert=tls.crt --key=tls.key. Ensure Secret is in same namespace as Gateway.

Interview Questions

Q — What is the three-layer architecture of Gateway API, and how does it improve RBAC compared to Ingress? Gateway API separates concerns into three layers: GatewayClass (infra, specifies controller), Gateway (platform, specifies infrastructure and allowed routes), HTTPRoute (app, specifies routing rules). This maps to real team boundaries: infrastructure team creates GatewayClass once and manages Gateways, platform team owns Gateway configs and RBAC, app teams own HTTPRoute specs. Ingress flattens everything into one object—the Gateway object becomes a bottleneck requiring shared ownership. Gateway API’s three-layer design avoids this by explicit RBAC separation.

Q — Why does Gateway API support TCP, UDP, and gRPC while Ingress does not? Ingress is L7-HTTP-only; it was designed with HTTP host/path routing as primary concern. TCP, UDP, TLS, and gRPC are L4 or non-HTTP-L7 concerns, outside Ingress’s scope. Gateway API’s protocol-agnostic design supports any listener protocol (HTTP, HTTPS, TCP, UDP, TLS) via Listener objects. This enables single Gateway to serve mixed protocol traffic (HTTP on port 80, gRPC on port 50051) without service mesh or workarounds.

Q — How does ReferenceGrant work, and why is it necessary for cross-namespace HTTPRoute-to-Gateway attachment? ReferenceGrant explicitly authorizes one namespace to reference resources in another namespace, preventing unintended or malicious cross-namespace coupling. Without ReferenceGrant, if HTTPRoute can freely attach to any Gateway, namespace A could hijack infrastructure Gateways in namespace B (platform). ReferenceGrant is created in the target namespace (Gateway’s namespace) and explicitly lists which source namespaces/kinds can reference it. Gateway’s allowedRoutes config further filters which namespaces are permitted.

Q — What happens if a Gateway is deleted while HTTPRoutes are attached to it? HTTPRoutes referencing the deleted Gateway remain in cluster but are immediately detached. The parentRefs no longer resolve; traffic stops routing. HTTPRoute status shows attachment condition as false. Routes are not auto-deleted (by design, preserving them for manual recovery). To cleanly migrate, delete HTTPRoutes first, then Gateway. Or create new Gateway and update HTTPRoute parentRefs, then delete old Gateway.