Skip to main content
Source

This page is generated from devops-agent/eks-ingress-migration/references/gateway-api.md. Edit the source, not this page.

Gateway API Prerequisites (input to Migration Options → Option 1)

Not a standalone rated section. These findings feed Option 1 (Gateway API) in the report (report-generation.md). "Not yet installed" prerequisites are 🟡 Low impact — the reason is that no live traffic is at stake (a prerequisite serves nothing until routes cut over), not that they are easy to deploy (effort never sets severity) — per the Impact Indicator; never a standalone blocker. All checks are read-only (Kubernetes API get/list, AWS Describe/List).

Automation: when routes are already on LBC ALB Ingress, prefer the official lbc-migrate toolkit to auto-translate Ingress → Gateway API rather than hand-authoring HTTPRoutes — see references/lbc-migrate-toolkit.md. The CLI ships in the LBC v3.4.0 release (build it from that tag); its Gateway API runtime prerequisite is the same as the hand-authored path — the production floor below (v3.0.0). Pair the controller with the standard Gateway API CRDs that release targets: v1.5.0 for the v3.4.0 tag, v1.6.0 for the v3.5.0 line. If the controller is below the production floor, Option 1 is blocked until it is upgraded — recommend upgrading to the v3.5.0 release line, which clears the floor and still carries the lbc-migrate CLI, rather than hand-authoring routes against a controller upstream did not recommend for production.

Version & naming facts (cite these)​

Other automation — ingress2gateway (SIG-Network), for the NGINX hop. lbc-migrate above converts LBC ALB Ingress → Gateway API. For an estate still on raw ingress-nginx, the upstream ingress2gateway CLI has an ingress-nginx provider that reads nginx Ingress objects and their annotations and emits core Gateway API resources, so it can do the routing-skeleton translation directly. Two limits decide how to present it: its emitter list (standard, agentgateway, airlock-microgateway, envoy-gateway, gce, kgateway) has no AWS / LBC emitter, so it produces Gateway + HTTPRoute but none of the AWS CRDs the ALB Gateway needs (LoadBalancerConfiguration, TargetGroupConfiguration, ListenerRuleConfiguration) — scheme, certificates, target groups and OIDC still have to be hand-authored; and it does not know the ALB feature gaps this skill scores, so a Tier-A snippet route is translated structurally rather than flagged. Treat it as complementary — a head start on the route objects — not a single-hop NGINX → ALB-Gateway path, and never as a substitute for the assessment.

Version currency — single source of truth for this skill. Checked 2026-09-13: latest AWS Load Balancer Controller release = v3.5.0 (2026-08-03); latest upstream Gateway API release = v1.6.2 (2026-09-03). (v1.6.1 was 2026-07-16; the CRD pairing this skill pins is unchanged — it keys on the v1.6.0 minor.) Every other file in this skill refers to "the v3.5.0 line" without re-asserting currency — re-check here, not there, and update this one note when it moves.

  • AWS LB Controller Gateway API reconciliation exists since L4 (TCP/UDP/TLSRoute) v2.13.3 and L7 (HTTPRoute/GRPCRoute) v2.14.0. ⚠️ The production floor is higher — v3.0.0. The upstream Gateway API guide carried the warning "Using the LBC and Gateway API together is not suggested for production workloads (yet!)" across the entire v2.x line — still present at v2.17.1, the last v2.x release — and it is absent from v3.0.0 (released 2026-01-23) onward. So every v2.x reconciles Gateway API while remaining pre-production; do not pass any of them as production-ready.
  • GatewayClass controllerName: gateway.k8s.aws/alb. Install the standard Gateway API CRDs the controller release targets — v1.5.0 for LBC v3.4.0, v1.6.0 for the v3.5.0 line. Note the CRD version a controller targets is not necessarily the newest Gateway API release (see the currency note above). From Gateway API v1.6.0 TCPRoute/UDPRoute are in the standard channel, so the experimental install is no longer required for L4 routes. The LBC reconciles the Gateway API v1 API.
  • On EKS Auto Mode the built-in controller (eks.amazonaws.com API group) covers Ingress (the eks.amazonaws.com/alb IngressClass) and Service type: LoadBalancer — not Gateway API. As of 2026-09-01 the Auto Mode load-balancing documentation describes Service and Ingress only, so a Gateway API target still needs a self-managed LBC at ≥ v3.0.0, even on Auto Mode.

Caveats & Risks (MUST surface in Option 1)​

  • L7 feature parity is still maturing — verify the TLS handling and routing filters each route needs against the installed LBC version before cutover.
  • EKS Auto Mode + self-managed LBC ownership conflict — if both run, two reconcilers contend for the same load balancer; scope distinct GatewayClass/IngressClass per controller, or reconcile to a single owner before any apply. Flag whenever both are present.
  • Blast radius — prefer per-security-boundary Gateways (e.g. public-gateway for web, separate private-gateway for payments) over one shared Gateway, even at extra cost.

Prerequisite checks (read-only — gather for Option 1, Phase 1)​

  1. CRDs — list CustomResourceDefinition (apiextensions.k8s.io/v1) and filter for gateway.networking.k8s.io; need GatewayClass, Gateway, HTTPRoute, ReferenceGrant at v1. If missing → install the standard release standard-install.yaml matching the controller line (v1.6.0 for v3.5.0, v1.5.0 for v3.4.0) — a low-impact Phase-1 step, run by the cluster owner.

    Runtime caveat: apiextensions.k8s.io and the gateway.networking.k8s.io CRD group are outside the built-in groups an access entry is likely to grant, so expect a 403 here unless a supplementary ClusterRole was bound. A denied read means Gateway API adoption is unconfirmed, never "not installed" — do not recommend installing CRDs on the strength of a 403. See references/supplementary-rbac.md.

  2. Controller version — aws-load-balancer-controller image tag ≥ v3.0.0 (the production floor for Gateway API; see Version facts); IRSA/Pod Identity present; healthy with 2+ replicas. < v3.0.0 → upgrade in Phase 1, even if it reconciles routes (v2.13.3/v2.14.0 only mark where L4/L7 reconciliation began, and upstream flagged those lines as not for production). Not covered by Auto Mode's built-in controller — Gateway API needs a self-managed LBC.
  3. GatewayClass — spec.controllerName: gateway.k8s.aws/alb, status Accepted: True. None → create in Phase 1.
  4. Adoption status — list existing Gateway/HTTPRoute/GRPCRoute to tell greenfield from a partial migration (informational).

Record these as Option 1 Phase-1 foundation steps, not standalone high-impact findings.