Ingress-NGINX to Kubernetes Gateway API Migration Lab (Course #gateway-api-migration)
For Kubernetes operators, platform engineers, SREs, security engineers.
By the end, you can
By the end of this course, you will be able to migrate an Ingress-NGINX estate to Gateway API on evidence — an annotation inventory classified three ways, an automated parity suite and a rehearsed rollback — so that traffic moves only after the behaviour change has been measured rather than assumed.
Running case study
Halvorsen Media serves 6 streaming and advertising properties across 3 clusters behind Ingress-NGINX, with 190 Ingress objects carrying 47 distinct annotations, 11 of them snippet-based. Since the controller stopped receiving security updates in March 2026, the security team has given the platform team 2 quarters to move off it without a partner-visible outage. Peak is 12,000 req/s during live events, and the ad-serving path cannot tolerate a request-size behaviour change.
Programme every line is something you do
4 modules · 12 topics · in course-flow order
-
Module 1
Inventory before you convert
Objective. Produce the annotation and route inventory that determines how much of the estate a converter can actually carry.
- Extract every Ingress object and annotation across the 3 clusters and rank them by traffic served, not by count
- Flag the security-relevant subset first: snippet annotations inject arbitrary configuration and are named as a retirement driver
- Record what the retirement actually means — existing installs keep serving, but receive no releases, bugfixes or security updates
-
Module 2
What the converter will not carry
Objective. Classify every inventoried annotation as translated, implementation-specific, or without equivalent on the target.
- Run the conversion and read the warnings as the deliverable; over 30 common annotations translate, provider-specific ones may not
- Handle the no-equivalent cases explicitly — proxy-body-size has no Gateway API equivalent and is not translated
- Decide per case between an implementation-specific emitter extension and a design change, and record the reason for all 47 annotations
-
Module 3
Parity is a test suite
Objective. Construct the automated parity suite that must pass before any production traffic moves.
- Assert matching precedence, rewrite behaviour, header handling and error responses on 100% of routes carrying partner traffic
- Test the request-size path explicitly, since a silent ceiling change is invisible until a real upload fails
- Run the suite against both stacks simultaneously and require zero unexplained differences before scheduling a cutover
-
Module 4
Rollback you have rehearsed
Objective. Design and exercise the reversal path, then sequence the cutover waves against it.
- Rehearse the reversal end to end within a 15-minute recovery window before the first wave, not after
- Sequence waves by blast radius, starting below 5% of peak traffic and holding each wave for one full event cycle
- Define the abort signals in advance — error rate, p99 latency, partner-reported failures — and who is authorised to call them
References & Official Documentation every claim above has a source
Module 1
- IngressMuleSoft Docs
- Ingress NGINX Retirement: What You Need to KnowMuleSoft Docs
Module 2
- Additional annotations support for ingress-nginxcommunity
- Announcing Ingress2Gateway 1.0MuleSoft Docs
Module 3
- Gateway API getting startedMuleSoft Docs
- Gateway API implementationsMuleSoft Docs
Module 4
- HTTPRouteMuleSoft Docs