/gateway-api

name: gateway-api
description: Migrate from the retired ingress-nginx controller to Kubernetes Gateway API, and design, debug, and review Gateway API ingress. Covers annotation inventory and risk triage, ingress2gateway conversion, implementation choice (Envoy Gateway default, Cilium, Istio, NGINX Gateway Fabric, AWS Load Balancer Controller), CRD channel and lifecycle, shared-Gateway ownership, cert-manager listener TLS, Flux layering, parallel-run DNS cutover, and rollback. Use when asked to "migrate off ingress-nginx", "convert my Ingresses to HTTPRoute", "set up Gateway API", "why is my HTTPRoute not attached", or "plan the ingress cutover". Flux reconciliation stuck → /platform-skills:gitops. East-west HTTPRoute in a mesh → /platform-skills:linkerd.
argument-hint: "[assess|convert|scaffold|cutover|debug|review|rollback] [namespace, file, or description]"
title: "Gateway API Command"
sidebar_label: "gateway-api"
custom_edit_url: null

Move ingress traffic off the retired ingress-nginx controller onto Gateway API without a user-visible change, and keep a fast rollback until the old path is provably unused.

Read `references/gateway-api.md` before responding. It holds the implementation matrix, the ownership model, CRD channel rules, the ingress2gateway v1.2.0 annotation coverage table, cert-manager requirements, Flux layering, the seven-phase cutover, rollback by stage, and the troubleshooting table. The working layout is `examples/fluxcd/basic-monorepo`; a before/after pair for one Ingress is in `examples/gateway-api`.

**This command is interactive by default.** With no arguments, ask the three questions below, then run the matching mode. Never apply converted manifests or change DNS yourself: produce the change, the validation, and the rollback, and let the user run it.

Questions (no arguments)

Ask one at a time:

1. **Where are you?** `assess` (have ingress-nginx, not started) / `convert` (ready to translate) / `scaffold` (new cluster, no Ingress yet) / `cutover` (Gateway works, traffic not moved) / `debug` (a route or Gateway is not working) / `review` (check existing Gateway API config) / `rollback` 2. **Which implementation?** Envoy Gateway (default) / Cilium / Istio / NGINX Gateway Fabric / AWS Load Balancer Controller / undecided. If undecided, apply the "Choosing an implementation" table: pick by what the team already operates 3. **How is the cluster delivered?** Flux / Argo CD / Helm or kubectl directly

Mode dispatch

| Mode | What it does | Mutates anything? | |---|---|---| | `assess` | Inventories Ingresses, classes and annotations; classifies each annotation as auto, decision, or blocked | No | | `convert` | Runs ingress2gateway, then rewrites output for the shared-Gateway model | Writes files only | | `scaffold` | Generates CRDs, controller, GatewayClass, Gateway, cert-manager and Flux layers | Writes files only | | `cutover` | Produces the per-hostname shadow test, DNS plan, soak criteria and decommission gate | No | | `debug` | Diagnoses a route, listener, certificate or Gateway address problem | No | | `review` | Reviews Gateway API manifests for correctness, security and operational safety | No | | `rollback` | Picks the rollback for the stage reached | No |

---

Mode: assess

1. Collect:

   kubectl get ingressclass
   # One row per Ingress annotation, keeping the resource identity and hosts,
   # so every annotation can be traced to the Ingress that carries it.
   # Columns: namespace, name, class, hosts, annotation, value. The value is
   # kept because several blockers are value-dependent (`rewrite-target: /$1`
   # uses a capture group; a snippet's body is what has to be redesigned).
   # @tsv escapes tabs and newlines, so a multi-line snippet stays on one row.
   # An Ingress with no nginx annotation still gets one row with "-".
   kubectl get ingress -A -o json | jq -r '
     .items[]
     | (.metadata.annotations // {}) as $a
     | [.metadata.namespace, .metadata.name,
        (.spec.ingressClassName // $a["kubernetes.io/ingress.class"] // "-"),
        ([.spec.rules[]?.host // "*"] | unique | join(","))] as $id
     | ([$a | to_entries[] | select(.key | startswith("nginx.ingress.kubernetes.io/")) | [.key, .value]]
        | if length == 0 then [["-", "-"]] else . end)[]
     | $id + . | @tsv' > ingress-inventory.tsv
   column -t -s $'\t' ingress-inventory.tsv
   # Cluster-wide count per annotation, to size the work
   kubectl get ingress -A -o json \
     | jq -r '.items[] | .metadata.annotations // {} | keys[]' \
     | grep '^nginx.ingress.kubernetes.io/' | sort | uniq -c | sort -rn
   # Controller-wide settings also change behaviour, not just annotations
   kubectl get configmap -A -l app.kubernetes.io/name=ingress-nginx -o yaml

2. Classify every annotation against the coverage table in `references/gateway-api.md`:

• **auto**: ingress2gateway converts it to core Gateway API
• **decision**: converted to an implementation-specific policy, or converted with different semantics (timeouts, IP ranges, regex)
• **blocked**: warned-and-dropped or not recognised (`configuration-snippet`, `server-snippet`, auth, rate limiting). Each needs an owner and a design before conversion

3. Flag controller ConfigMap keys that set global behaviour (custom headers, timeouts, `use-forwarded-headers`, `ssl-redirect`). They do not appear on any Ingress and are the easiest to lose 4. Output a table: namespace, Ingress, host, class, annotations by category, owner, blocking yes/no. End with the count of blocked items. Do not proceed to `convert` while any item is blocked without an agreed decision

Mode: convert

1. Confirm `assess` has no open blocked items 2. Run, one namespace at a time:

   ingress2gateway print --providers=ingress-nginx --emitter=envoy-gateway \
     -n <namespace> > converted-<namespace>.yaml

Use `--emitter=standard` for a non-Envoy implementation, and `--ingress-nginx-ingress-class=<class