ingress-nginx stopt: zo migreer je naar de Gateway API

De community-controller ingress-nginx (kubernetes/ingress-nginx) krijgt sinds maart 2026 geen releases, bugfixes of securityfixes meer, en de repository is op 24 maart 2026 gearchiveerd. Je bestaande installatie blijft werken, maar elke nieuwe kwetsbaarheid blijft vanaf nu open. De aanbevolen route is de Gateway API met een actief onderhouden implementatie; dit artikel laat stap voor stap zien hoe je die overstap maakt zonder je webshop of Laravel-platform plat te leggen.

Wat er precies is gebeurd

De tijdlijn, gecontroleerd op kubernetes.io en de GitHub-repository:

• 11 november 2025: SIG Network en het Security Response Committee kondigen de retirement aan. Best-effort onderhoud loopt door tot maart 2026.
• 29 januari 2026: de Steering Committee en het Security Response Committee publiceren een extra statement. De kern: wie na de retirement op ingress-nginx blijft, laat zichzelf en zijn gebruikers kwetsbaar voor aanvallen.
• Maart 2026: einde van het onderhoud. De supported-versions-tabel toont v1.15.1 (Helm-chart 4.15.1) als laatste regel.
• 24 maart 2026: de repository wordt gearchiveerd en is sindsdien read-only.

Ook InGate, het project dat ingress-nginx moest opvolgen, is gestopt. Het is nooit volwassen genoeg geworden.

De achtergrond is geen geheim. In maart 2025 kwamen de IngressNightmare-kwetsbaarheden naar buiten, waaronder CVE-2025-1974 met een CVSS-score van 9.8. Een project dat vrijwel volledig op een paar vrijwilligers draaide, kon dat tempo niet bijhouden.

Belangrijk om te weten: dit gaat over kubernetes/ingress-nginx, de community-controller. De NGINX Ingress Controller van F5 (nginxinc/kubernetes-ingress) is een ander project met eigen onderhoud. Kijk in je cluster welke je draait voordat je in paniek raakt:

kubectl get pods -A -l app.kubernetes.io/name=ingress-nginx \
  -o jsonpath='{range .items[*]}{.metadata.namespace}{"\t"}{.spec.containers[0].image}{"\n"}{end}'

Zie je registry.k8s.io/ingress-nginx/controller, dan is dit artikel voor jou.

De Ingress API zelf verdwijnt niet

Er gaat veel verwarring rond. Het Ingress-object (networking.k8s.io/v1) blijft gewoon in Kubernetes. Er zijn geen plannen om het te verwijderen. Het is wel feature-frozen: er komt niets meer bij.

Dat geeft je twee realistische routes:

1. Naar de Gateway API. De richting waar de Kubernetes-community zelf naar wijst. Meer mogelijkheden, rolverdeling tussen platform en applicatie, en geen annotatie-wildgroei.
2. Naar een andere ingress-controller. Traefik, HAProxy of de F5-controller lezen ook Ingress-objecten. Minder werk op korte termijn, maar je annotaties zijn controllerspecifiek en moeten alsnog worden omgezet.

De officiële communicatie is daar eerlijk over: geen enkel alternatief is een drop-in replacement. Je moet in beide gevallen je configuratie nalopen. Doe je dat werk toch, dan kies je in de praktijk liever meteen voor de Gateway API.

Er bestaan ook commerciële forks met gepatchte images, bijvoorbeeld van Chainguard. Dat kan een brug zijn als je tijd nodig hebt. Het is geen eindstation: je verschuift het probleem naar een leverancier en je blijft op een API die niet meer groeit.

De Gateway API in vijf minuten

De Gateway API splitst wat bij Ingress in één object zat over meerdere resources:

• GatewayClass: welk type load balancer (Envoy Gateway, NGINX Gateway Fabric, Cilium...). Beheerd door het platform.
• Gateway: de daadwerkelijke listener. Poorten, hostnames, TLS-certificaten. Beheerd door het platform.
• HTTPRoute: routeringsregels voor een applicatie. Beheerd door het team van die applicatie.
• ReferenceGrant: expliciete toestemming om naar resources in een andere namespace te verwijzen.

De standaard is inmiddels volwassen. Gateway API v1.5 kwam op 27 februari 2026 uit en zette onder meer ListenerSet, TLSRoute en ReferenceGrant in het Standard-kanaal. Versie 1.6 volgde op 30 juni 2026, met TCPRoute en UDPRoute als GA. Voor een webshop heb je vrijwel alleen HTTPRoute en Gateway nodig, en die zijn al jaren stabiel.

Wat je wint ten opzichte van Ingress:

• Gewogen routering (canary) zit in de standaard, niet in annotaties.
• Header- en query-matching, redirects, rewrites en header-aanpassingen zijn gewone velden.
• Timeouts per route zijn standaard (timeouts.request).
• Een applicatieteam kan geen Gateway kapot maken door een verkeerde annotatie.

Een implementatie kiezen

De Gateway API is een specificatie. Je hebt een controller nodig die hem uitvoert. De serieuze kandidaten:

Onze keuze-criteria in de praktijk:

• Wat draait er al? Gebruik je Cilium als CNI, dan is één component minder beheren een echt voordeel.
• Welke policies heb je nodig? Rate limiting, client-IP-detectie, body size. Dat zit bij elke implementatie in eigen CRD's.
• Ondersteuning door je managed provider. Op GKE is er een eigen Gateway-implementatie. Op andere platforms installeer je zelf. Zie Managed Kubernetes kiezen.
• Release-tempo en onderhoud. Dat is precies wat bij ingress-nginx misging. Kijk naar het aantal actieve maintainers en wie ze betaalt.

Envoy Gateway installeren gaat met één Helm-commando. Controleer de actuele versie op gateway.envoyproxy.io; op het moment van schrijven is dat v1.8.1:

helm install eg oci://docker.io/envoyproxy/gateway-helm \
  --version v1.8.1 \
  -n envoy-gateway-system --create-namespace

Daarna een GatewayClass en een Gateway:

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: envoy
spec:
  controllerName: gateway.envoyproxy.io/gatewayclass-controller
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: web
  namespace: gateway
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt
spec:
  gatewayClassName: envoy
  listeners:
    - name: http
      protocol: HTTP
      port: 80
      allowedRoutes:
        namespaces:
          from: All
    - name: https
      protocol: HTTPS
      port: 443
      hostname: www.voorbeeldshop.nl
      tls:
        mode: Terminate
        certificateRefs:
          - name: voorbeeldshop-tls
      allowedRoutes:
        namespaces:
          from: All

In productie zet je from: All liever op Selector met een label, zodat alleen de namespaces die jij aanwijst routes mogen koppelen.

Stap 1: inventariseer wat je nu hebt

Begin niet met converteren. Begin met tellen. Je wilt weten hoeveel Ingress-objecten er zijn en welke annotaties ze gebruiken:

kubectl get ingress -A

kubectl get ingress -A -o json \
  | jq -r '.items[].metadata.annotations // {} | keys[]' \
  | grep nginx.ingress.kubernetes.io \
  | sort | uniq -c | sort -rn

Die tweede lijst is je werklijst. Elke annotatie moet een plek krijgen in de nieuwe setup, of bewust vervallen. Let extra op configuration-snippet en server-snippet. Daar zit vaak handwerk in dat niemand meer kent, en die snippets waren een deel van het securityprobleem.

Kijk ook naar de ConfigMap van de controller zelf. Globale instellingen als proxy-body-size, use-forwarded-headers of real-ip-header staan daar en niet op de Ingress.

Stap 2: laat ingress2gateway het eerste werk doen

De Kubernetes-community onderhoudt een conversietool: ingress2gateway. Versie 1.0 kwam op 20 maart 2026 uit en ondersteunt meer dan dertig ingress-nginx-annotaties, waar dat eerder drie waren. Er zijn sindsdien nieuwere versies uitgebracht.

brew install ingress2gateway
# of
go install github.com/kubernetes-sigs/[email protected]

# alles in één namespace omzetten en bekijken
ingress2gateway print --providers=ingress-nginx -n shop

# vanuit bestanden in je Git-repo, met implementatiespecifieke output
ingress2gateway print --providers=ingress-nginx \
  --input-file=k8s/shop/ingress.yaml \
  --emitter=envoy-gateway > k8s/shop/gateway-routes.yaml

Met --emitter krijg je naast standaard Gateway API-resources ook de policy-objecten van je gekozen implementatie. Beschikbare emitters zijn onder meer standard, envoy-gateway, kgateway en agentgateway.

Behandel de output als een concept. De tool zegt zelf dat je het resultaat moet reviewen. Alles wat hij niet begrijpt, meldt hij; lees die meldingen.

Stap 3: de annotaties die je zelf moet vertalen

Dit zijn de annotaties die we in Magento- en Laravel-setups het vaakst tegenkomen, met hun plek in de Gateway API:

De HTTP-naar-HTTPS-redirect wordt een eigen route die alleen aan de HTTP-listener hangt:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: shop-redirect
  namespace: shop
spec:
  parentRefs:
    - name: web
      namespace: gateway
      sectionName: http
  hostnames:
    - www.voorbeeldshop.nl
  rules:
    - filters:
        - type: RequestRedirect
          requestRedirect:
            scheme: https
            statusCode: 301

En de eigenlijke route voor de shop, hier met Varnish als backend en een ruime timeout voor zware adminacties:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: shop
  namespace: shop
spec:
  parentRefs:
    - name: web
      namespace: gateway
      sectionName: https
  hostnames:
    - www.voorbeeldshop.nl
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      backendRefs:
        - name: varnish
          port: 80
      timeouts:
        request: 300s

Stap 4: TLS met cert-manager

Draai je cert-manager al voor je Ingress-certificaten, dan kun je hem houden. Gateway API-ondersteuning zit sinds cert-manager 1.15 niet meer achter een feature flag, maar je moet hem wel aanzetten:

helm upgrade --install cert-manager oci://quay.io/jetstack/charts/cert-manager \
  --namespace cert-manager \
  --set config.gatewayAPI.enabled=true

Installeer de Gateway API-CRD's vóór cert-manager, of herstart cert-manager daarna, anders ziet hij ze niet. Vervolgens werkt het via de annotatie op de Gateway, zoals in het voorbeeld hierboven. Cert-manager maakt dan per HTTPS-listener met een hostname een Certificate aan.

Twee dingen om te weten:

• Een listener zonder hostname slaat cert-manager over.
• Het Secret moet in dezelfde namespace staan als de Gateway.

Wil je dat applicatieteams zelf hun certificaten regelen zonder de Gateway aan te raken, kijk dan naar ListenerSet. Cert-manager 1.20 ondersteunt dat als alpha-feature. Meer over de hele TLS-keten op Ingress, Gateway API en TLS.

Stap 5: parallel draaien en omschakelen

De veiligste migratie is er een waarin beide paden tegelijk werken. De nieuwe Gateway krijgt een eigen LoadBalancer en een eigen extern IP-adres. Je oude ingress-nginx blijft draaien.

Het stappenplan dat we hanteren:

1. Gateway en HTTPRoutes uitrollen via Git, net als de rest van je manifests. Zie GitOps met Argo CD.
2. Testen tegen het nieuwe IP met een vaste resolve, zonder DNS te wijzigen:

GW_IP=$(kubectl get gateway web -n gateway -o jsonpath='{.status.addresses[0].value}')
curl -sI --resolve www.voorbeeldshop.nl:443:$GW_IP https://www.voorbeeldshop.nl/
curl -sI --resolve www.voorbeeldshop.nl:443:$GW_IP https://www.voorbeeldshop.nl/checkout/

1. Een rooktest draaien op de kritieke paden: homepage, categorie, product, winkelwagen, checkout, admin-login, API-endpoints en webhooks van je betaalprovider.
2. De DNS-TTL een dag van tevoren verlagen.
3. DNS omzetten en logs en foutpercentages van beide paden volgen.
4. Na een rustige periode de Ingress-objecten en de oude controller opruimen.

Staat er een CDN of Cloudflare voor je cluster, dan zet je de origin daar om in plaats van publieke DNS. Dat gaat sneller en is sneller terug te draaien.

Valkuilen bij Magento en Laravel

Een paar dingen die bij een webshop specifiek misgaan:

• Echte client-IP. Magento gebruikt het IP-adres voor onder meer fraudechecks en admin-IP-restricties. Achter een cloud load balancer moet je controller X-Forwarded-For of het PROXY-protocol correct verwerken. In Envoy Gateway regel je dat met een ClientTrafficPolicy. Test het: log het IP dat in PHP aankomt.
• Uploads en imports. Productimports en afbeeldingen in de admin lopen tegen body-size-limieten aan. ingress-nginx had een proxy-body-size in je ConfigMap; vergeet die niet over te zetten.
• Lange requests. Exports, indexering via de admin of API-calls van een ERP kunnen lang lopen. Zet timeouts per route, niet globaal ruim.
• Websockets. Laravel Reverb gebruikt websockets. Envoy-gebaseerde gateways ondersteunen dat, maar controleer of je timeouts lange verbindingen niet afkappen.
• Varnish ertussen. Laat de Gateway TLS afhandelen en naar Varnish routeren. Varnish moet dan weten welke headers het mag vertrouwen voor het protocol, anders krijg je redirect-loops.

Meer over de opbouw van zo'n stack staat in ons artikel over Magento op Kubernetes: de architectuur en op de pagina Magento 2 op Kubernetes.

De eerlijke versie

Draai je één shop op één cluster met een handvol Ingress-objecten, dan is dit een klus van dagen, niet van weken. Het meeste werk zit in de inventarisatie en het testen, niet in de YAML.

Draai je ingress-nginx omdat iemand ooit Kubernetes heeft opgezet en niemand er nu nog naar kijkt? Dan is dit het moment om je af te vragen of Kubernetes voor jouw situatie wel loont. Soms is goede managed hosting de betere keuze. Daarover schreven we Kubernetes of managed hosting voor je webshop.

Wil je dat iemand meekijkt naar je huidige ingress-configuratie en een migratieplan maakt? Neem contact op. Het vaste team dat het bouwt, voert het ook uit.