The Ingress API served Kubernetes well for years, but its limitations — reliance on unportable annotations, no standard for traffic splitting, header matching, or delegation — led the community to build its successor: the Gateway API. It's now the officially recommended way to handle ingress traffic in Kubernetes.

1. Why Gateway API Replaces Ingress

The Resource Model

2. GatewayClass & Gateway

GatewayClass — "What implementation?"

# Installed by the controller vendor (like IngressClass):
apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: nginx                      # or: cilium, envoy, istio, etc.
spec:
  controllerName: gateway.nginx.org/nginx-gateway-controller

Common GatewayClass controllers:

Gateway — "Where to listen?"

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: production-gateway
  namespace: infra
spec:
  gatewayClassName: nginx             # Reference to GatewayClass
  listeners:
    - name: http
      protocol: HTTP
      port: 80
      allowedRoutes:
        namespaces:
          from: All                   # Any namespace can attach routes
    - name: https
      protocol: HTTPS
      port: 443
      tls:
        mode: Terminate
        certificateRefs:
          - name: wildcard-tls        # TLS Secret
            namespace: infra
      allowedRoutes:
        namespaces:
          from: Selector
          selector:
            matchLabels:
              gateway-access: "true"  # Only labeled namespaces can use HTTPS

allowedRoutes — The Guardrail

3. HTTPRoute — "How to route?"

Basic Routing

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: web-routes
  namespace: app-team              # App team's namespace
spec:
  parentRefs:
    - name: production-gateway     # Attach to which Gateway
      namespace: infra
  hostnames:
    - "app.example.com"
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /api
      backendRefs:
        - name: api-svc
          port: 80
    - matches:
        - path:
            type: PathPrefix
            value: /
      backendRefs:
        - name: web-svc
          port: 80

Rich Matching (Beyond Ingress Capabilities)

rules:
  - matches:
      - path:
          type: PathPrefix
          value: /api
        headers:                       # ← Match by HTTP header
          - name: X-Version
            value: "beta"
        method: GET                     # ← Match by HTTP method
        queryParams:                    # ← Match by query parameter
          - name: debug
            value: "true"
    backendRefs:
      - name: api-beta-svc
        port: 80

Traffic Splitting (Canary/Blue-Green)

rules:
  - matches:
      - path:
          type: PathPrefix
          value: /
    backendRefs:
      - name: web-v1                   # 90% of traffic
        port: 80
        weight: 90
      - name: web-v2                   # 10% canary
        port: 80
        weight: 10

Filters — Request/Response Manipulation

rules:
  - matches:
      - path:
          type: PathPrefix
          value: /old-path
    filters:
      - type: RequestRedirect          # 301/302 redirect
        requestRedirect:
          scheme: https
          hostname: new.example.com
          statusCode: 301
  - matches:
      - path:
          type: PathPrefix
          value: /api/v1
    filters:
      - type: URLRewrite               # Rewrite before forwarding
        urlRewrite:
          path:
            type: ReplacePrefixMatch
            replacePrefixMatch: /v1
      - type: RequestHeaderModifier    # Add/set/remove headers
        requestHeaderModifier:
          add:
            - name: X-Forwarded-By
              value: gateway
          remove:
            - X-Internal-Only
    backendRefs:
      - name: api-svc
        port: 80

Available Filter Types

4. Beyond HTTP — Other Route Types

# GRPCRoute example — route by gRPC service/method:
apiVersion: gateway.networking.k8s.io/v1
kind: GRPCRoute
metadata:
  name: grpc-routes
spec:
  parentRefs:
    - name: production-gateway
  rules:
    - matches:
        - method:
            service: myapp.UserService
            method: GetUser
      backendRefs:
        - name: user-svc
          port: 50051

5. Migrating from Ingress to Gateway API

Comparison: Same routing, different specs

# OLD — Ingress:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: web
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
spec:
  ingressClassName: nginx
  rules:
    - host: app.example.com
      http:
        paths:
          - path: /api
            pathType: Prefix
            backend:
              service:
                name: api-svc
                port:
                  number: 80

# NEW — Gateway API:
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: web
spec:
  parentRefs:
    - name: production-gateway
  hostnames: ["app.example.com"]
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /api
      filters:
        - type: URLRewrite
          urlRewrite:
            path:
              type: ReplacePrefixMatch
              replacePrefixMatch: /
      backendRefs:
        - name: api-svc
          port: 80

Migration Strategy

1. Install a Gateway API controller (e.g., NGINX Gateway Fabric, Cilium, Envoy Gateway)
2. Create GatewayClass + Gateway (platform team)
3. Run both in parallel — Ingress and Gateway API can coexist
4. Migrate routes one by one — convert Ingress → HTTPRoute
5. Validate traffic — confirm identical behavior
6. Remove old Ingress resources and controller

6. NGINX Gateway Fabric — The Official Successor

NGINX Gateway Fabric is the official replacement for ingress-nginx. It implements the Gateway API spec using NGINX as the data plane.

# Installation:
kubectl apply -f https://github.com/nginxinc/nginx-gateway-fabric/releases/latest/download/crds.yaml
kubectl apply -f https://github.com/nginxinc/nginx-gateway-fabric/releases/latest/download/nginx-gateway.yaml

# Creates GatewayClass "nginx" automatically

Summary

backendRefs:
  - name: web-stable
    port: 80
    weight: 95
  - name: web-canary
    port: 80
    weight: 5