The Problem with Kubernetes Ingress

The Kubernetes Ingress resource has served the community well since 2015, but it was designed for a simpler era. It was never meant to handle the traffic complexity that modern microservices demand: traffic splitting, header-based routing, cross-namespace references, or multi-protocol support beyond HTTP/HTTPS.

The result? A fragmented landscape of controller-specific annotations — thousands of lines of nginx.ingress.kubernetes.io/* or traefik.ingress.kubernetes.io/* annotations that are impossible to migrate between providers.

Gateway API is the official solution to this mess.

Photo by Lars Kienle on Unsplash

What Is the Gateway API?

The Gateway API is a collection of Kubernetes CRDs (Custom Resource Definitions) developed by the SIG-Network community. It reached GA (v1.0) in October 2023 and has been rapidly adopted by every major Ingress controller and service mesh.

The core resources are:

This role-oriented design is the key insight: infrastructure teams own GatewayClass and Gateway; dev teams own their HTTPRoute objects. No more needing cluster-admin to configure routing.

Hands-On Examples

Basic HTTPRoute

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: my-app
  namespace: production
spec:
  parentRefs:
    - name: prod-gateway
      namespace: infra
  hostnames:
    - "api.example.com"
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /v1
      backendRefs:
        - name: api-service
          port: 8080

Traffic Splitting (Canary Deployments)

One of the killer features of Gateway API: native traffic splitting without any annotations.

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: api-canary
spec:
  parentRefs:
    - name: prod-gateway
  hostnames:
    - "api.example.com"
  rules:
    - backendRefs:
        - name: api-stable
          port: 8080
          weight: 90
        - name: api-canary
          port: 8080
          weight: 10

Ship to 10% of traffic, monitor metrics, then bump to 100%. Pure YAML, no annotations, works with any conformant controller.

Header-Based Routing

rules:
  - matches:
      - headers:
          - name: X-Feature-Flag
            value: new-checkout
    backendRefs:
      - name: checkout-v2
        port: 8080
  - backendRefs:
      - name: checkout-v1
        port: 8080

This enables feature-flag based routing at the infrastructure level — incredibly useful for A/B testing.

Conformance and Implementation Landscape

The Gateway API defines a conformance test suite, so you know exactly what each implementation supports. In 2026, virtually every major project is conformant:

• Envoy-based: Contour, Emissary-ingress, Istio
• NGINX-based: NGINX Gateway Fabric (official), Traefik
• Cloud-managed: AWS Load Balancer Controller, GKE Gateway, Azure Application Gateway
• eBPF-based: Cilium Gateway API

The multi-implementation story is real: write your HTTPRoute once and it works across all of them.

Advanced Features: Policy Attachment

Gateway API v1.1 introduced Policy Attachment — a pattern for attaching cross-cutting policies (timeouts, retries, auth, rate limiting) to routes without modifying the route itself.

apiVersion: gateway.networking.k8s.io/v1alpha2
kind: BackendLBPolicy
metadata:
  name: api-lb-policy
spec:
  targetRef:
    group: ""
    kind: Service
    name: api-service
  sessionPersistence:
    sessionName: api-session
    type: Cookie

This separates the concerns of where traffic goes (HTTPRoute) from how traffic is handled (Policy). Platform teams can enforce organization-wide policies without touching application routes.

Migrating from Ingress

The migration is straightforward for simple cases:

# Before (Ingress)
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-app
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
spec:
  rules:
    - host: app.example.com
      http:
        paths:
          - path: /api
            pathType: Prefix
            backend:
              service:
                name: api-service
                port:
                  number: 8080

# After (Gateway API)
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: my-app
spec:
  parentRefs:
    - name: main-gateway
  hostnames:
    - "app.example.com"
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /api
      filters:
        - type: URLRewrite
          urlRewrite:
            path:
              type: ReplacePrefixMatch
              replacePrefixMatch: /
      backendRefs:
        - name: api-service
          port: 8080

Notice: no annotations needed. The rewrite is a first-class filter.

Conclusion

The Kubernetes Gateway API is not just “Ingress v2” — it’s a fundamental redesign that addresses years of pain with the original resource. If you’re still running vanilla Ingress in 2026, the migration is worth the effort. You get portability, expressiveness, role-based delegation, and a foundation that the entire cloud-native ecosystem is building on.

The annotations era is over. Embrace structured configuration.

Resources:

• Gateway API Official Docs
• Conformance Status by Implementation
• Migration Guide from Ingress

이 글이 도움이 되셨다면 공감 및 광고 클릭을 부탁드립니다 :)