migrate-ingress-nginx

Migrate ingress-nginx to Gateway API

When to use

• The cluster runs the community ingress-nginx controller (retired March 2026; see legacy/ingress-nginx).
• The user asks to adopt Gateway API.

Before you start

• Inventory (write it to the PR or docs/ingress-inventory.md):

  kubectl get ingressclass
  kubectl get ingress -A -o json | jq -r '.items[] | [.metadata.namespace, .metadata.name, (.spec.ingressClassName // "-"), ([.spec.rules[]?.host] | join(","))] | @tsv'
  kubectl get ingress -A -o json | jq -r '.items[].metadata.annotations // {} | keys[]' | grep nginx.ingress | sort | uniq -c | sort -rn
  

  Also note TLS secrets and cert-manager issuers, ConfigMap-level settings (global timeouts, headers, use-forwarded-headers), external auth, rate limits, and any snippet annotations.

• Ask the user:

  • which Gateway API implementation (Envoy Gateway, Istio, Cilium, NGINX Gateway Fabric, Traefik, Kong, or the cloud provider's controller); the default is whatever the platform team already runs;
  • how traffic reaches the cluster (cloud load balancer, external DNS) and the cut-over window;
  • whether installing ingress2gateway (v1.2.0, brew install ingress2gateway or go install github.com/kubernetes-sigs/[email protected]) and the controller is approved (core/supply-chain).

• Work in Git (GitOps repo or Helm values); no ad hoc kubectl apply to production.

Steps

1. Install the Gateway API CRDs (the version the implementation supports) and the implementation, with its own GatewayClass and load balancer, next to ingress-nginx.

2. Convert:

   ingress2gateway print --providers=ingress-nginx -A > gateway-api.yaml
   # or from files: ingress2gateway print --providers=ingress-nginx --input-file k8s/ingress.yaml
   

   Read every warning. Annotations that need manual work include snippets (configuration-snippet, server-snippet), cookie-based canaries, capture-group rewrites ($1), custom headers ConfigMaps, auth-url external auth, and rate limits; map them to the implementation's policies (filters, BackendTLSPolicy, extension CRDs) or the application.

3. Review the output: one Gateway per entry point with TLS listeners referencing the existing certificates; HTTPRoute/GRPCRoute per Ingress with parentRefs; ReferenceGrant where routes cross namespaces. Commit it to the repo.

4. Parallel run: apply to the new Gateway, then compare each host through both entry points: