<div id="readability-page-1" class="page"><div><img src="https://devstarsj.github.io/assets/https://images.unsplash.com/photo-1667372393119-3d4c48d07fc9?w=1200&amp;auto=format&amp;fit=crop"><h2 id="kubernetes-gateway-api-why-you-should-migrate-from-ingress-now">Kubernetes Gateway API: Why You Should Migrate from Ingress Now</h2>The Kubernetes <code>Ingress</code> resource turned 7 years old in 2026, and it’s showing its age. Every production cluster has a story: NGINX annotations that only work with one controller, custom CRDs bolted on because Ingress couldn’t express the required traffic shape, or a fragile regex in an annotation that nobody dares touch. Gateway API — now GA-stable and backed by every major cloud provider and ingress controller vendor — was designed to fix all of this. Here’s why the migration is worth it, and how to actually do it.<img src="https://images.unsplash.com/photo-1558494949-ef010cbdcc31?w=1000&amp;auto=format&amp;fit=crop" alt="Kubernetes networking diagram"> Photo by Thomas Jensen on Unsplash<h2 id="why-ingress-is-broken">Why Ingress Is Broken</h2>Ingress’s problems are structural:1. Annotation Hell Ingress has a minimal spec. Anything beyond basic host/path routing requires controller-specific annotations:<div><pre><code># NGINX-specific — completely non-portable
nginx.ingress.kubernetes.io/rate-limit: "100"
nginx.ingress.kubernetes.io/rate-limit-window: "1m"
nginx.ingress.kubernetes.io/upstream-hash-by: "$request_uri"
</code></pre></div>2. No Role Separation Infrastructure teams and application teams fight over the same Ingress resource. There’s no clean ownership model.3. Limited Expressiveness Traffic splitting, header-based routing, request mirroring, and TLS passthrough all require workarounds or controller-specific CRDs.<h2 id="gateway-api-the-design-philosophy">Gateway API: The Design Philosophy</h2>Gateway API introduces a role-oriented model with three distinct resource types:<div><pre><code>GatewayClass ← Managed by: Cloud Provider / Infra Team
 └── Gateway ← Managed by: Cluster Operator
 └── HTTPRoute ← Managed by: Application Team
</code></pre></div>This separation means app teams can manage their routing rules without touching the underlying load balancer configuration.<h2 id="core-resources">Core Resources</h2><h3 id="gatewayclass">GatewayClass</h3>Defines the controller type — set by your infrastructure provider:<div><pre><code>apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
 name: istio
spec:
 controllerName: istio.io/gateway-controller
</code></pre></div><h3 id="gateway">Gateway</h3>Defines the listener — managed by cluster operators:<div><pre><code>apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
 name: prod-gateway
 namespace: istio-system
spec:
 gatewayClassName: istio
 listeners:
 - name: https
 protocol: HTTPS
 port: 443
 tls:
 mode: Terminate
 certificateRefs:
 - name: prod-tls-secret
 namespace: istio-system
 allowedRoutes:
 namespaces:
 from: Selector
 selector:
 matchLabels:
 gateway-access: "allowed"
</code></pre></div><h3 id="httproute">HTTPRoute</h3>Defines routing rules — managed by application teams:<div><pre><code>apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
 name: api-routes
 namespace: my-app
spec:
 parentRefs:
 - name: prod-gateway
 namespace: istio-system
 hostnames:
 - "api.example.com"
 rules:
 - matches:
 - path:
 type: PathPrefix
 value: /v2/
 backendRefs:
 - name: api-v2-service
 port: 8080
 weight: 90
 - name: api-v2-canary
 port: 8080
 weight: 10
 - matches:
 - path:
 type: PathPrefix
 value: /v1/
 backendRefs:
 - name: api-v1-service
 port: 8080
</code></pre></div>Notice what just happened: canary traffic splitting with weights — something that requires annotations or custom CRDs in classic Ingress — is a first-class spec feature.<h2 id="advanced-traffic-patterns">Advanced Traffic Patterns</h2><div><pre><code>rules:
 - matches:
 - headers:
 - name: "X-Beta-User"
 value: "true"
 backendRefs:
 - name: beta-service
 port: 8080
 - matches:
 - path:
 type: PathPrefix
 value: /
 backendRefs:
 - name: stable-service
 port: 8080
</code></pre></div><h3 id="request-mirroring-shadow-traffic">Request Mirroring (Shadow Traffic)</h3><div><pre><code>rules:
 - matches:
 - path:
 type: PathPrefix
 value: /api
 backendRefs:
 - name: production-service
 port: 8080
 filters:
 - type: RequestMirror
 requestMirror:
 backendRef:
 name: shadow-service
 port: 8080
</code></pre></div><h3 id="url-rewriting">URL Rewriting</h3><div><pre><code>filters:
 - type: URLRewrite
 urlRewrite:
 path:
 type: ReplacePrefixMatch
 replacePrefixMatch: /newpath
</code></pre></div><h3 id="grpc-routes">GRPC Routes</h3>Gateway API v1 includes <code>GRPCRoute</code> as a first-class resource:<div><pre><code>apiVersion: gateway.networking.k8s.io/v1
kind: GRPCRoute
metadata:
 name: grpc-routes
spec:
 parentRefs:
 - name: prod-gateway
 rules:
 - matches:
 - method:
 service: com.example.ProductService
 method: GetProduct
 backendRefs:
 - name: product-service
 port: 50051
</code></pre></div><h2 id="migration-from-nginx-ingress">Migration from NGINX Ingress</h2><h3 id="step-1-inventory-your-ingress-resources">Step 1: Inventory Your Ingress Resources</h3><div><pre><code>kubectl get ingress -A -o json | jq '.items[] | {
 name: .metadata.name,
 namespace: .metadata.namespace,
 annotations: (.metadata.annotations | keys)
}'
</code></pre></div><h3 id="step-2-map-annotations-to-httproute-features">Step 2: Map Annotations to HTTPRoute Features</h3><table><thead><tr><th>NGINX Annotation</th><th>HTTPRoute Equivalent</th></tr></thead><tbody><tr><td><code>nginx.ingress.kubernetes.io/rewrite-target</code></td><td><code>URLRewrite</code> filter</td></tr><tr><td><code>nginx.ingress.kubernetes.io/canary-weight</code></td><td><code>weight</code> in <code>backendRefs</code></td></tr><tr><td><code>nginx.ingress.kubernetes.io/use-regex</code></td><td><code>RegularExpression</code> path match</td></tr><tr><td><code>nginx.ingress.kubernetes.io/proxy-set-headers</code></td><td><code>RequestHeaderModifier</code> filter</td></tr></tbody></table><h3 id="step-3-deploy-in-parallel">Step 3: Deploy in Parallel</h3>Both Ingress and HTTPRoute can coexist. Run them in parallel, validate the HTTPRoute behavior, then remove the old Ingress:<div><pre><code># Install Gateway API CRDs
kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.2.0/standard-install.yaml

# Create GatewayClass + Gateway
kubectl apply -f gateway.yaml

# Create HTTPRoute alongside existing Ingress
kubectl apply -f httproute.yaml

# Test via HTTPRoute endpoint
curl -H "Host: api.example.com" https://new-gateway-ip/api/health

# Remove Ingress after validation
kubectl delete ingress old-ingress
</code></pre></div><h2 id="controller-support-in-2026">Controller Support in 2026</h2>Every major controller supports Gateway API:<ul><li>AWS Load Balancer Controller — full GA support</li><li>GKE Gateway — native GKE integration</li><li>Azure Application Gateway — AGIC v2</li><li>Istio — first-class support since 1.16</li><li>Envoy Gateway — reference implementation</li><li>NGINX Gateway Fabric — official NGINX implementation</li><li>Cilium — eBPF-accelerated Gateway API</li><li>Traefik — v3.x full support</li></ul><h2 id="status-conditions-better-observability">Status Conditions: Better Observability</h2>One underrated improvement: Gateway API resources expose structured status conditions:<div><pre><code>kubectl describe httproute api-routes

# Status:
# Parents:
# Parent Ref:
# Group: gateway.networking.k8s.io
# Kind: Gateway
# Name: prod-gateway
# Conditions:
# Type: Accepted
# Status: True
# Reason: Accepted
# Type: ResolvedRefs
# Status: True
</code></pre></div>Compare this to debugging why an Ingress annotation isn’t working — which usually involves reading controller logs and hoping.<h2 id="when-to-stay-with-ingress">When to Stay with Ingress</h2>Gateway API isn’t always the right choice:<ul><li>Simple single-team clusters — the role model adds complexity without benefit</li><li>Controller without GA support — check compatibility first</li><li>Minimal routing needs — basic host/path routing still works fine with Ingress</li></ul><h2 id="the-bottom-line">The Bottom Line</h2>Gateway API solves real problems that teams have been working around for years. The role-based model, first-class traffic splitting, and native extensibility points make it genuinely superior for production multi-team clusters. With every major cloud provider and controller vendor now supporting it, the migration risk is low.If you’re running Ingress with more than a handful of annotations, the migration is worth planning now. Start with a non-production namespace, get familiar with <code>HTTPRoute</code>, then migrate service by service.The annotations were always a hack. Now there’s a real API.<h2 id="references">References</h2><ul><li><a href="https://gateway-api.sigs.k8s.io/">Gateway API Documentation</a></li><li><a href="https://github.com/kubernetes-sigs/gateway-api">Gateway API GitHub</a></li><li><a href="https://github.com/nginx/nginx-gateway-fabric">NGINX Gateway Fabric</a></li><li><a href="https://gateway-api.sigs.k8s.io/guides/migrating-from-ingress/">Migrating from Ingress — official guide</a></li></ul> <div>이 글이 도움이 되셨다면 공감 및 광고 클릭을 부탁드립니다 :) </div></div></div>

Dev Note

Kubernetes Gateway API: Why You Should Migrate from Ingress Now
The Kubernetes Ingress resource turned 7 years old in 2026, and it’s showing its age. Every production cluster has a story: NGINX annotations that only work with one controller, custom CRDs bolted on because Ingress couldn’t express the required traffic shape, or a fragile regex in an annotation that nobody dares touch. Gateway API — now GA-stable and backed by every major cloud provider and ingress controller vendor — was designed to fix all of this. Here’s why the migration is worth it, and how to actually do it.
Photo by Thomas Jensen on Unsplash
Why Ingress Is Broken
Ingress’s problems are structural:
1. Annotation Hell
Ingress has a minimal spec. Anything beyond basic host/path routing requires controller-specific annotations:
# NGINX-specific — completely non-portable
nginx.ingress.kubernetes.io/rate-limit: "100"
nginx.ingress.kubernetes.io/rate-limit-window: "1m"
nginx.ingress.kubernetes.io/upstream-hash-by: "$request_uri"
2. No Role Separation
Infrastructure teams and application teams fight over the same Ingress resource. There’s no clean ownership model.
3. Limited Expressiveness
Traffic splitting, header-based routing, request mirroring, and TLS passthrough all require workarounds or controller-specific CRDs.
Gateway API: The Design Philosophy
Gateway API introduces a role-oriented model with three distinct resource types:
GatewayClass    ← Managed by: Cloud Provider / Infra Team
    └── Gateway     ← Managed by: Cluster Operator
            └── HTTPRoute   ← Managed by: Application Team
This separation means app teams can manage their routing rules without touching the underlying load balancer configuration.
Core Resources
GatewayClass
Defines the controller type — set by your infrastructure provider:
apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: istio
spec:
  controllerName: istio.io/gateway-controller
Gateway
Defines the listener — managed by cluster operators:
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: prod-gateway
  namespace: istio-system
spec:
  gatewayClassName: istio
  listeners:
    - name: https
      protocol: HTTPS
      port: 443
      tls:
        mode: Terminate
        certificateRefs:
          - name: prod-tls-secret
            namespace: istio-system
      allowedRoutes:
        namespaces:
          from: Selector
          selector:
            matchLabels:
              gateway-access: "allowed"
HTTPRoute
Defines routing rules — managed by application teams:
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: api-routes
  namespace: my-app
spec:
  parentRefs:
    - name: prod-gateway
      namespace: istio-system
  hostnames:
    - "api.example.com"
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /v2/
      backendRefs:
        - name: api-v2-service
          port: 8080
          weight: 90
        - name: api-v2-canary
          port: 8080
          weight: 10
    - matches:
        - path:
            type: PathPrefix
            value: /v1/
      backendRefs:
        - name: api-v1-service
          port: 8080
Notice what just happened: canary traffic splitting with weights — something that requires annotations or custom CRDs in classic Ingress — is a first-class spec feature.
Advanced Traffic Patterns
Header-Based Routing
rules:
  - matches:
      - headers:
          - name: "X-Beta-User"
            value: "true"
    backendRefs:
      - name: beta-service
        port: 8080
  - matches:
      - path:
          type: PathPrefix
          value: /
    backendRefs:
      - name: stable-service
        port: 8080
Request Mirroring (Shadow Traffic)
rules:
  - matches:
      - path:
          type: PathPrefix
          value: /api
    backendRefs:
      - name: production-service
        port: 8080
    filters:
      - type: RequestMirror
        requestMirror:
          backendRef:
            name: shadow-service
            port: 8080
URL Rewriting
filters:
  - type: URLRewrite
    urlRewrite:
      path:
        type: ReplacePrefixMatch
        replacePrefixMatch: /newpath
GRPC Routes
Gateway API v1 includes GRPCRoute as a first-class resource:
apiVersion: gateway.networking.k8s.io/v1
kind: GRPCRoute
metadata:
  name: grpc-routes
spec:
  parentRefs:
    - name: prod-gateway
  rules:
    - matches:
        - method:
            service: com.example.ProductService
            method: GetProduct
      backendRefs:
        - name: product-service
          port: 50051
Migration from NGINX Ingress
Step 1: Inventory Your Ingress Resources
kubectl get ingress -A -o json | jq '.items[] | {
  name: .metadata.name,
  namespace: .metadata.namespace,
  annotations: (.metadata.annotations | keys)
}'
Step 2: Map Annotations to HTTPRoute Features
NGINX Annotation
      HTTPRoute Equivalent
    
nginx.ingress.kubernetes.io/rewrite-target
      URLRewrite filter
    
nginx.ingress.kubernetes.io/canary-weight
      weight in backendRefs
    
nginx.ingress.kubernetes.io/use-regex
      RegularExpression path match
    
nginx.ingress.kubernetes.io/proxy-set-headers
      RequestHeaderModifier filter
    
Step 3: Deploy in Parallel
Both Ingress and HTTPRoute can coexist. Run them in parallel, validate the HTTPRoute behavior, then remove the old Ingress:
# Install Gateway API CRDs
kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.2.0/standard-install.yaml
# Create GatewayClass + Gateway
kubectl apply -f gateway.yaml
# Create HTTPRoute alongside existing Ingress
kubectl apply -f httproute.yaml
# Test via HTTPRoute endpoint
curl -H "Host: api.example.com" https://new-gateway-ip/api/health
# Remove Ingress after validation
kubectl delete ingress old-ingress
Controller Support in 2026
Every major controller supports Gateway API:
AWS Load Balancer Controller — full GA support
GKE Gateway — native GKE integration
Azure Application Gateway — AGIC v2
Istio — first-class support since 1.16
Envoy Gateway — reference implementation
NGINX Gateway Fabric — official NGINX implementation
Cilium — eBPF-accelerated Gateway API
Traefik — v3.x full support
Status Conditions: Better Observability
One underrated improvement: Gateway API resources expose structured status conditions:
kubectl describe httproute api-routes
# Status:
# Parents:
#   Parent Ref:
#     Group: gateway.networking.k8s.io
#     Kind: Gateway
#     Name: prod-gateway
#   Conditions:
#     Type: Accepted
#     Status: True
#     Reason: Accepted
#     Type: ResolvedRefs
#     Status: True
Compare this to debugging why an Ingress annotation isn’t working — which usually involves reading controller logs and hoping.
When to Stay with Ingress
Gateway API isn’t always the right choice:
Simple single-team clusters — the role model adds complexity without benefit
Controller without GA support — check compatibility first
Minimal routing needs — basic host/path routing still works fine with Ingress
The Bottom Line
Gateway API solves real problems that teams have been working around for years. The role-based model, first-class traffic splitting, and native extensibility points make it genuinely superior for production multi-team clusters. With every major cloud provider and controller vendor now supporting it, the migration risk is low.
If you’re running Ingress with more than a handful of annotations, the migration is worth planning now. Start with a non-production namespace, get familiar with HTTPRoute, then migrate service by service.
The annotations were always a hack. Now there’s a real API.
References
Gateway API Documentation
Gateway API GitHub
NGINX Gateway Fabric
Migrating from Ingress — official guide

Kubernetes Gateway API: Why You Should Migrate from Ingress Now

댓글