Kubernetes Gateway API vs Ingress: Migration Guide

Ingress did one thing with one resource and one pile of controller-specific annotations. Gateway API is its designated successor, and it is not a drop-in replacement: it separates "where traffic enters" from "how it is routed", makes the features that used to hide in annotations portable, and adds extension points for everything else. If you are planning a migration — or just trying to read a Gateway YAML for the first time — this guide maps the old world onto the new one.

Three Differences That Explain Everything

The practical consequence: the same routing intent expressed with five Ingress annotations across three controllers becomes one portable field in an HTTPRoute — but anything genuinely implementation-specific still needs that implementation's own resource.

Concept Mapping

# Before: Ingress
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: web-ingress
spec:
  rules:
  - host: app.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: web-svc
            port:
              number: 80
---
# After: Gateway (entry points) + HTTPRoute (routing)
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: example-gateway
spec:
  gatewayClassName: example-gateway-class
  listeners:
  - name: http
    protocol: HTTP
    port: 80
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: web-route
spec:
  parentRefs:
  - name: example-gateway
  hostnames:
  - "app.example.com"
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /
    backendRefs:
    - name: web-svc
      port: 80

Two structural changes jump out: entry points must now be declared explicitly (a listener for port 80 or 443, instead of whatever the controller happened to configure), and routes attach to a Gateway through parentRefs rather than being installed globally.

Rules That Decide Behaviour

• Hostname matching: an HTTPRoute's hostnames must match the Gateway listener's hostname, otherwise the listener ignores those routing rules. This is the most common "my route does nothing" cause.
• Route merging: a Gateway implementation must merge rules from all HTTPRoutes attached to a listener. Where they conflict, the API design guide applies — more specific matches win over less specific ones.
• Per-route semantics: in Ingress each hostname had its own routing rules; in HTTPRoute the rules apply across all hostnames on that route, so split routes per hostname when the intent differs.

Migrating Without Downtime

1. Run both controllers side by side. A Gateway API controller and your existing Ingress controller can coexist and will receive different external IPs, so the new path can be tested in isolation.
2. Start with ingress2gateway. It translates Ingress resources into Gateway and HTTPRoute objects; treat the output as a draft and review every annotation it could not map.
3. Verify with real traffic against the new external IP — status codes, TLS chain, redirects, timeouts — before touching DNS.
4. Cut over with DNS or the load balancer, keeping the Ingress objects in place until the rollback window closes.
5. Test edge cases deliberately: the regex path type, traffic splitting during a canary, and any authentication that used to be an annotation.

What to Watch For

• Annotation inventory: list every annotation in use across the cluster before migrating; unmapped ones are your real project scope.
• Controller maturity: Gateway API features vary by implementation and conformance level — verify the features you depend on are supported, not just the API objects accepted.
• RBAC and ownership: splitting Gateway from HTTPRoute lets platform teams own entry points while app teams own routes. That is the point — use it, rather than giving everyone Gateway write access.
• Two APIs to monitor: while both exist, your dashboards need to cover both entry paths or incidents will hide in the one nobody watches.

相关阅读：Kubernetes NetworkPolicy 默认拒绝模式、Calico、Cilium 与 Flannel CNI 对比 以及 NGINX 反向代理配置。

原文链接：Kubernetes Gateway API - Migrating from Ingress