Updated November 2026

Migrating from Ingress NGINX to the Kubernetes Gateway API

Class Duration

7 hours of live training delivered over 1 day.

Student Prerequisites

Working experience with Kubernetes: Deployments, Services, and kubectl
Familiarity with Ingress resources and the ingress-nginx controller
Basic understanding of DNS, TLS certificates, and HTTP routing
Helm experience is helpful but not required

Target Audience

Platform engineers, SREs, DevOps engineers, and cluster operators who run the community ingress-nginx controller, plus developers who own Ingress manifests. It also fits architects choosing a Gateway API implementation across clusters or clouds. Teams that need Kubernetes foundations first can take Kubernetes Essentials for Programmers.

Description

The Kubernetes project retired the community ingress-nginx controller in March 2026 and archived its repository. This one-day course moves teams to the Kubernetes Gateway API, the role-oriented successor to Ingress. Students learn the Gateway API resource model and choose an implementation from conformance data. They translate Ingress resources with ingress2gateway and map annotations to filters and policies. The course ends with TLS, canary releases, and a side-by-side cutover with a tested rollback.

Learning Outcomes

Explain what ingress-nginx retirement means for existing clusters.
Tell community ingress-nginx apart from vendor-maintained NGINX controllers.
Describe GatewayClass, Gateway, ListenerSet, and the route types.
Choose a Gateway API implementation from conformance reports and feature needs.
Inventory Ingress resources and annotations.
Translate Ingress resources with ingress2gateway.
Map ingress-nginx annotations to Gateway API filters and policies.
Identify ingress-nginx behaviors that need redesign.
Configure TLS termination, passthrough, and backend TLS.
Replace canary annotations with weighted traffic splitting.
Run a side-by-side cutover with a tested rollback.

Training Materials

Comprehensive courseware is distributed online at the start of class. All students receive a downloadable MP4 recording of the training.

Software Requirements

Students will need a free, personal GitHub account to access the courseware, Docker Desktop or Podman, kind (or another local Kubernetes cluster), kubectl, Helm, and Visual Studio Code. The course is taught with Gateway API v1.7 and ingress2gateway v1.2.

Training Topics

Why ingress-nginx Was Retired

The retirement announcement and timeline
Final releases and the archived repository
No further bug fixes or security patches
Existing installations keep running
Community ingress-nginx vs. F5 NGINX Ingress Controller
Ingress is frozen, not deprecated
Finding ingress-nginx in your clusters
Assessing exposure

Gateway API Concepts

Infrastructure, cluster, and application roles
GatewayClass, Gateway, and ListenerSet
HTTPRoute and GRPCRoute
TLSRoute, TCPRoute, and UDPRoute
ReferenceGrant for cross-namespace references
Standard and experimental channels
Core, Extended, and Implementation-specific support
Policy attachment

Choosing an Implementation

Reading conformance reports
Envoy Gateway, Istio, and Cilium
NGINX Gateway Fabric, Traefik, Kong, and kgateway
GKE Gateway and the AWS Load Balancer Controller
Application Gateway for Containers
The AKS application routing add-on
Selection criteria
One or several implementations per cluster

Inventory and Translation with ingress2gateway

Inventorying Ingress resources and IngressClasses
Cataloging annotations
Translating resources with ingress2gateway
Standard vs. implementation-specific emitters
Untranslated annotation notifications
Committing generated manifests to Git

Annotation Mapping and Behavior Differences

rewrite-target to URLRewrite
ssl-redirect and force-ssl-redirect to RequestRedirect
CORS annotations to the CORS filter
Timeouts, retries, and backend protocols
Authentication and rate limiting policies
IP allow lists
Snippets with no Gateway API equivalent
Redesigning configuration-snippet and server-snippet
Case-insensitive regex matching
Host-wide use-regex
Implied regex from rewrite-target
Trailing-slash redirects and URL normalization

TLS and Certificates

TLS termination on Gateway listeners
Cross-namespace certificates with ReferenceGrant
cert-manager with the Gateway API
HTTP-to-HTTPS redirects
TLS passthrough with TLSRoute
Backend TLS with BackendTLSPolicy

Canary Releases and Traffic Splitting

Mapping canary, canary-weight, and canary-by-header
Weighted backendRefs on HTTPRoute
Header matching for targeted canaries
Request mirroring
Progressive delivery with Argo Rollouts or Flagger

Cutover and Rollback

Running ingress-nginx and Gateway side by side
DNS weights and low TTLs
Validating routes, certificates, and error rates
Rollback triggers
A tested rollback path
Removing ingress-nginx and IngressClasses
Gateway API resources in GitOps