Kubernetes Gateway API: Migrer fra Ingress i 12 Steg

Ingress har vært standardveien inn i Kubernetes-klynger siden 2015, men API-en var aldri bygget for moderne routing-behov. Gateway API er etterfølgeren, og med versjon 1.6.2 (utgitt 3. september 2026) er kjernedelen av spesifikasjonen moden nok til at de fleste team bør begynne planleggingen nå, ikke om et år. Denne guiden viser deg, steg for steg, hvordan du går fra en fungerende Ingress-oppsett til Gateway API uten å ta ned trafikk underveis.

Du får en komplett migrasjonsplan: kartlegging av eksisterende ruter, installasjon av CRD-er og controller, manuell og automatisert konvertering med verktøyet ingress2gateway, TLS-oppsett, cross-namespace-ruting og en trygg cutover-prosess. Vi dekker også de vanligste fallgruvene og en feilsøkingsseksjon du kan slå opp i når noe ikke fungerer som forventet.

Hva er Gateway API og hvorfor er det viktig nå

Gateway API er en samling Kubernetes-ressurser som beskriver hvordan trafikk skal rutes inn i en klynge. I motsetning til Ingress, som pakket alt inn i én ressurstype og lente seg tungt på leverandørspesifikke annotasjoner, deler Gateway API ansvaret i tre lag: GatewayClass for infrastruktur-typen, Gateway for selve lytteren (port, protokoll, TLS), og HTTPRoute for selve rutingreglene. Kubernetes-dokumentasjonen beskriver det slik: “Gateway API is the successor to the Ingress API.” Det er ikke en tilleggsfunksjon ved siden av Ingress, det er den offisielle etterfølgeren.

Per september 2026 er GatewayClass, Gateway og HTTPRoute stabile (GA) ressurser i Gateway API. GRPCRoute, ReferenceGrant, TLSRoute, TCPRoute og UDPRoute har ulik modenhet avhengig av hvilken kanal (Standard eller Experimental) og hvilken controller du bruker. Det betyr at ikke alt i v1.6.2 er like produksjonsklart, og du må sjekke conformance-matrisen til akkurat den implementasjonen du planlegger å bruke før du legger arkitekturen din på is.

Den praktiske driveren for mange team er at kjente Ingress-annotasjoner, snippets og controller-spesifikke hacks ikke overlever en migrasjon uendret. Samtidig gir Gateway API en fordel Ingress aldri hadde: platform-team kan eie GatewayClass og Gateway, mens applikasjonsteam eier sine egne HTTPRoute-objekter i egne namespaces. Det er en rollefordeling mange organisasjoner har etterspurt i årevis.

Historikken er verdt å kjenne til før du planlegger en migrering. Gateway API gikk til beta i juli 2022, og siden den gang har utviklingen fulgt en kanalmodell der nye funksjoner starter i en Experimental-kanal og gradvis flyttes til Standard-kanalen etter hvert som de er testet og ansett stabile på tvers av flere implementasjoner. Det er grunnen til at API-en fortsatt utvikler seg selv om kjernedelen har vært produksjonsklar i flere år: prosjektet legger bevisst til nye ressurser i eksperimentell form fremfor å presse alt gjennom som stabilt fra dag én. For deg som migrerer betyr det at du bør sjekke hvilken kanal en gitt ressurs tilhører før du bygger kritisk infrastruktur rundt den, spesielt for de nyere ressursene som TCPRoute og UDPRoute.

Ingress mot Gateway API: kjernebegrepene

Før du åpner en eneste YAML-fil er det verdt å forstå hvordan begrepene fra den gamle verdenen kartlegges til den nye. Kubernetes-bloggen omtaler dette som en engangs-konvertering: “A one-time conversion from your existing Ingress resources to Gateway API resources is necessary.” Tabellen under viser den konseptuelle oversettelsen du kommer til å bruke gjennom hele denne guiden.

Ingress-konsept	Gateway API-ekvivalent	Kommentar
IngressClass	GatewayClass	Definerer hvilken controller som eier ressursen
Ingress (lytterdel)	Gateway	Port, protokoll og TLS-terminering samlet ett sted
Ingress-regler (host/path)	HTTPRoute	Egen ressurstype, kan eies av applikasjonsteamet
TLS-blokk i Ingress	Gateway listener TLS + certificateRefs	Sertifikatreferanse flyttes til Gateway-nivå
Controller-spesifikke annotasjoner	Typede felt, filtre eller policy-ressurser	Krever manuell oversettelse per annotasjon
Backend service	HTTPRoute.backendRefs	Selve Service-objektet endres normalt ikke

Legg merke til at Gateway API “represents a superset of Ingress functionality, enabling more advanced concepts”, som Kubernetes-teamet skrev da API-en gikk til beta. Det betyr i praksis at du får ting Ingress aldri støttet ordentlig: vektbasert trafikkdeling, typed header-modifikasjon, native gRPC-ruting og eksplisitt cross-namespace-kontroll via ReferenceGrant.

Sikkerhet og styringsmodell: hvorfor mange team bytter nå

Den vanligste feilkilden i store Ingress-oppsett har aldri vært selve rutingen, men hvem som har lov til å endre hva. Med én flat Ingress-ressurs kunne et enkelt applikasjonsteam, ved et uhell eller med vilje, overskrive en global TLS-innstilling eller kapre et hostname som tilhørte en annen avdeling. Ingress hadde ingen innebygd måte å håndheve grenser mellom teamene på, utover det RBAC ga deg på selve objektnivået.

Gateway API løser dette strukturelt i stedet for å plastre over det med policyer. Fordi GatewayClass og Gateway normalt ligger i et namespace platform-teamet kontrollerer, mens HTTPRoute kan spres ut til hvert enkelt applikasjonsteams eget namespace, blir det umulig for et team å endre TLS-terminering eller lytteroppsett de ikke eier. ReferenceGrant gjør cross-namespace-tilgang eksplisitt i stedet for implisitt, noe som betyr at hver referanse på tvers av namespace-grenser må godkjennes av eieren av målressursen, ikke bare av den som oppretter referansen.

For organisasjoner underlagt krav om sporbarhet, for eksempel innen finans eller offentlig sektor i Norden, er dette mer enn en teknisk detalj. Revisjon blir enklere når du kan vise at hver enkelt cross-namespace-referanse er eksplisitt godkjent i et eget Kubernetes-objekt, i stedet for å måtte forklare hvorfor en Ingress-annotasjon tilfeldigvis ga tilgang på tvers av team. Det samme gjelder ved sikkerhetsrevisjoner: en ReferenceGrant er lett å liste ut og gjennomgå i sin helhet, mens implisitte Ingress-avhengigheter ofte må spores manuelt gjennom annotasjoner og controller-konfigurasjon.

Tenk deg en klynge delt mellom fem produktteam, der ett team tidligere kunne skrive en Ingress-regel som utilsiktet fanget opp trafikk ment for et annet teams hostname, rett og slett fordi Ingress-controlleren evaluerte regler på tvers av hele klyngen uten naturlige grenser. Med Gateway API må det teamet eksplisitt inn i en allowedRoutes-konfigurasjon på riktig Gateway, og enhver referanse til ressurser utenfor eget namespace krever en synlig ReferenceGrant fra eieren. Feilkonfigurasjonen blir med andre ord synlig i selve objektmodellen, ikke bare noe du oppdager i etterkant via en trafikklogg.

Planlegg migreringen: tidslinje, roller og kommunikasjon

Den tekniske migreringen er sjelden det som tar lengst tid. Det som faktisk forsinker de fleste Gateway API-prosjekter er koordinering mellom platform-team og de applikasjonsteamene som eier trafikken. Sett av tid til fire faser fremfor å behandle dette som en helgejobb.

Kartleggingsfase (1–2 uker): Inventarier alle Ingress-objekter, annotasjoner og avhengigheter på tvers av klynger, som beskrevet i steg 1.
Pilotfase (2–4 uker): Velg én lavrisiko-applikasjon, gjerne en intern tjeneste uten eksterne SLA-er, og kjør hele migreringsløpet fra CRD-installasjon til cutover.
Utrullingsfase (varierer med antall team): Migrer applikasjon for applikasjon, ikke klynge for klynge. Gi hvert applikasjonsteam et konkret sjekkpunkt de selv kan verifisere før du går videre til neste.
Opprydningsfase (etter en avtalt karensperiode): Fjern gamle Ingress-controllere, ressurser og tilhørende RBAC-regler først når alle team har bekreftet stabil drift på den nye løsningen.

Kommuniser tydelig til applikasjonsteamene hva som faktisk endrer seg for dem. De fleste vil oppleve at deres egen Service-definisjon ikke rører seg i det hele tatt, mens de får et nytt objekt (HTTPRoute) å eie i sitt eget namespace i stedet for å be platform-teamet om endringer i en delt Ingress-fil. Dette alene reduserer ofte antall supportsaker mellom teamene betraktelig, fordi flaskehalsen med å vente på at platform-teamet skal redigere en sentral konfigurasjonsfil forsvinner.

Skriv ned en konkret rollback-plan før pilotfasen starter, ikke etter at noe har gått galt. Planen bør beskrive nøyaktig hvilken DNS-oppføring som pekes tilbake, hvem som har fullmakt til å utføre rollback uten å vente på godkjenning, og hvor lenge den gamle Ingress-controlleren skal holdes i live etter cutover. Team som hopper over dette steget bruker ofte langt mer tid på å improvisere en rollback midt i en hendelse enn de ville brukt på å skrive planen på forhånd.

Forutsetninger: verktøy og versjoner

Sjekk følgende før du starter migrasjonen. Versjonsnumrene under er de nyeste bekreftede per 23. september 2026, men Gateway API-versjoner er ikke bundet én-til-én til Kubernetes-versjoner, så en controller kan støtte et spenn av begge.

Kubernetes-klynge på minst versjon 1.31 (nyeste offisielle utgivelse er 1.36.4, med 1.37.0 listet i kildekode-repoet)
kubectl, samme minor-versjon som klyngen eller nyere
Gateway API CRD-er versjon 1.6.2 (Standard-kanal), eventuelt supplert med Experimental-kanalen for TCPRoute/UDPRoute
En valgt Gateway API-implementasjon: Envoy Gateway v1.7.0, NGINX Gateway Fabric v2.4.0, Cilium 1.19, kgateway 2.4.x eller tilsvarende
Helm 3, hvis controlleren din distribueres som Helm-chart
cert-manager, dersom du terminerer TLS med automatisk sertifikatutstedelse
Verktøyet ingress2gateway for automatisert konvertering av eksisterende manifester
Tilgang til å opprette CustomResourceDefinitions og cluster-scoped RBAC-roller

Hvis du kjører en administrert tjeneste er versjonsbildet litt annerledes. Azures AKS-dokumentasjon oppgir at AKS på Kubernetes 1.37 bruker Gateway API v1.6.1 Standard-kanal CRD-er, med TCPRoute og UDPRoute gradert opp til stabil status i den administrerte bunten. Sjekk alltid skyleverandørens egen dokumentasjon for nøyaktig CRD-versjon før du installerer noe manuelt oppå en administrert klynge, ellers risikerer du konflikt mellom to sett CRD-er.

Steg 1: Kartlegg eksisterende Ingress-ressurser

Start med en fullstendig oversikt over hva som faktisk kjører i klyngen. Mange team oppdager Ingress-objekter fra prosjekter ingen lenger husker eier. List ut alle ressurser, IngressClass-typer og de mest brukte annotasjonene før du planlegger noe som helst.

kubectl get ingress -A -o json > ingress-inventory.json

# Tell hvor mange Ingress-objekter som bruker hver IngressClass
kubectl get ingress -A -o jsonpath='{range .items[*]}{.spec.ingressClassName}{"\n"}{end}' | sort | uniq -c

# Finn de mest brukte annotasjonene på tvers av klyngen
kubectl get ingress -A -o json | jq -r '.items[].metadata.annotations | keys[]?' | sort | uniq -c | sort -rn

Noter spesielt annotasjoner knyttet til rewrite-regler, rate limiting, autentisering, WAF og last-balansering. Disse har sjelden et direkte felt i Gateway API og krever enten filtre, egne policy-ressurser fra implementasjonen din, eller en bevisst arkitekturendring. Ingress-controllere som lener seg på frie NGINX-direktiver eller Lua-skript har ofte ingen portabel erstatning, og her må du regne med reelt utviklingsarbeid, ikke bare en YAML-oversettelse.

I praksis faller de fleste annotasjoner i norske og nordiske produksjonsmiljøer i tre kategorier: rene rewrite/redirect-regler, som som regel har et greit filter-ekvivalent i HTTPRoute, tilgangskontroll og rate limiting, som ofte krever en implementasjonsspesifikk policy-ressurs, og til slutt observability-relaterte annotasjoner for logging og tracing, som gjerne kan fjernes helt siden mange Gateway API-implementasjoner eksponerer tilsvarende data direkte via Prometheus og OpenTelemetry uten ekstra konfigurasjon. Del listen din i disse tre bøttene før du begynner å skrive en eneste HTTPRoute, det gjør resten av arbeidet langt mer forutsigbart.

Steg 2: Installer Gateway API CRD-ene

Gateway API er en spesifikasjon, ikke en kjørende komponent, og v1.6.2 er nyeste offisielle utgivelse per september 2026. Du må installere CRD-ene separat fra selve controlleren. Standard-kanalen inneholder de stabile ressursene, mens Experimental-kanalen legger til ressurser som fortsatt endrer seg mellom versjoner.

# Standard-kanal (GatewayClass, Gateway, HTTPRoute, GRPCRoute, ReferenceGrant)
kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.6.2/standard-install.yaml

# Experimental-kanal, kun hvis implementasjonen din krever TCPRoute/UDPRoute
kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.6.2/experimental-install.yaml

# Bekreft at CRD-ene er registrert
kubectl get crd | grep gateway.networking.k8s.io

Ikke bland Standard- og Experimental-kanalen tilfeldig. Hvis en teamkollega senere installerer motstridende CRD-versjoner oppå hverandre, ender du med typefeil som er vonde å feilsøke. Lås CRD-versjonen i infrastrukturkoden din (Helm, Kustomize eller Terraform) slik at alle miljøer er synkronisert.

Steg 3 og 4: Velg og installer en implementasjon

CRD-ene alene gjør ingenting. Du trenger en controller som faktisk implementerer spesifikasjonen og programmerer en data-plane. Konformansen er dessuten funksjonsspesifikk, ikke alt-eller-ingenting. En controller kan støtte kjernefunksjonene i HTTP-ruting utmerket, men mangle utvidede funksjoner som TCPRoute eller cross-namespace TLS. Tabellen viser noen av de mest brukte implementasjonene og hva de dekker per september 2026.

Implementasjon	Versjon	Støttet Gateway API	Merknad
Envoy Gateway	v1.7.0	Standard-kanal, feature-spesifikk conformance	God dokumentasjon av per-funksjon-støtte
NGINX Gateway Fabric	v2.4.0	Kjerne + utvalgte extended features	Naturlig valg om du migrerer fra NGINX Ingress
Cilium	1.19.0-pre.2	Dokumentert i offisiell matrise	Aktuelt hvis du allerede kjører Cilium som CNI
kgateway	2.4.x	Gateway API 1.4–1.6	Støtter Kubernetes 1.32–1.36
agentgateway	1.4.x	Gateway API 1.4–1.6	Støtter Kubernetes 1.31–1.36
Traefik	Støtter v1.4-spesifikasjonen	Kjerne HTTP + utvalgte extended features	Leverandørens egen rapportering, ikke uavhengig verifisert

Før du bestemmer deg, sjekk implementasjonens egen conformance-rapport for nettopp de ressurstypene du trenger. Gateway API-prosjektet publiserer en offisiell implementasjonsmatrise der hver controller rapporterer hvilke funksjoner den består testene for, ressurs for ressurs. Det er langt tryggere å bruke fem minutter på å lese denne matrisen enn å oppdage seks uker inn i migreringen at valgt controller ikke støtter cross-namespace TLS-referanser du er avhengig av.

Installer den du velger via Helm, og pek den mot GatewayClass-navnet du skal opprette i neste steg. Eksempelet under bruker Envoy Gateway, men samme mønster gjelder for de fleste implementasjoner.

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

kubectl wait --timeout=5m -n envoy-gateway-system \
  deployment/envoy-gateway --for=condition=Available

Steg 5: Opprett en GatewayClass

GatewayClass er cluster-scoped og eies typisk av platform-teamet. Den peker på hvilken controller som skal programmere alle Gateway-objekter av denne klassen, akkurat slik IngressClass gjorde for Ingress.

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: eg
spec:
  controllerName: gateway.envoyproxy.io/gatewayclass-controller

Etter apply, sjekk statusfeltet med det samme. Gateway API er bygget rundt statuskondisjoner, ikke bare vellykket opprettelse av objektet. En GatewayClass som ikke blir akseptert av controlleren vil aldri gi deg en fungerende Gateway, uansett hvor riktig resten av YAML-en din ser ut.

kubectl get gatewayclass eg -o jsonpath='{.status.conditions}' | jq

Steg 6: Opprett Gateway-ressursen med lyttere

Gateway-objektet erstatter det Ingress tidligere gjorde implisitt: definere port, protokoll og TLS-oppsett. Her setter du opp en HTTPS-lytter som tillater ruter fra alle namespaces, kontrollert eksplisitt via allowedRoutes.

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: public-gateway
  namespace: networking
spec:
  gatewayClassName: eg
  listeners:
    - name: https
      protocol: HTTPS
      port: 443
      hostname: "*.eksempel.no"
      tls:
        mode: Terminate
        certificateRefs:
          - name: eksempel-no-cert
      allowedRoutes:
        namespaces:
          from: All

Merk at Gateway ligger i namespace networking, mens rutene senere kan bo i helt andre namespaces eid av applikasjonsteamene. Dette er selve poenget med å skille infrastruktur fra applikasjonsruting. Sjekk at lytteren blir “Programmed” før du går videre.

kubectl get gateway public-gateway -n networking -o jsonpath='{.status.listeners}' | jq

Steg 7: Konverter Ingress-regler til HTTPRoute manuelt

For enkle host/path-regler er konverteringen rett frem. En Ingress-regel som ruter app.eksempel.no/ til en Service på port 8080 blir en HTTPRoute som refererer til Gateway-en fra forrige steg via parentRefs.

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: webshop
  namespace: default
spec:
  parentRefs:
    - name: public-gateway
      namespace: networking
  hostnames:
    - "app.eksempel.no"
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      backendRefs:
        - name: webshop-svc
          port: 8080

Utfordringen dukker opp når Ingress-regelen har annotasjoner for rewrite, rate limiting eller header-manipulasjon. Disse må oversettes til filters i HTTPRoute-spesifikasjonen, eller til en egen policy-ressurs fra implementasjonen din. Behold den gamle Service-en uendret, den delen av arkitekturen rører du normalt ikke i det hele tatt.

Steg 8: Automatiser konverteringen med ingress2gateway

For klynger med mange Ingress-objekter er manuell konvertering upraktisk. Kubernetes SIG Network løste dette selv: “Today we are releasing ingress2gateway, a tool that can help you migrate from Ingress to Gateway API.” Verktøyet leser eksisterende Ingress-manifester og genererer tilsvarende Gateway API-ressurser automatisk, slik prosjektets egen blogg beskriver det: “ingress2gateway assists in the migration by converting your existing Ingress resources into Gateway API resources.”

# Installer verktøyet
go install sigs.k8s.io/ingress2gateway@latest

# Kjør konvertering mot en spesifikk IngressClass og skriv resultatet til fil
ingress2gateway print \
  --input-file ingress-inventory.json \
  --providers ingress-nginx > gateway-api-generert.yaml

# Se over output før du applyer noe som helst
less gateway-api-generert.yaml

Behandle output som et utkast, ikke et ferdig produkt. Verktøyet oversetter strukturen korrekt, men det kan ikke gjette hvilke av dine egendefinerte annotasjoner som har et trygt Gateway API-ekvivalent og hvilke som krever ny arkitektur. Gå gjennom hver genererte HTTPRoute manuelt før apply, spesielt de med uvanlige rewrite- eller autentiseringsregler.

Steg 9: Sett opp TLS-terminering med cert-manager

De fleste Ingress-oppsett bruker cert-manager til automatisk sertifikatutstedelse via en Certificate-ressurs og en tls-blokk direkte på Ingress-objektet. Med Gateway API flyttes referansen til Gateway-lytterens certificateRefs-felt, mens selve Certificate-ressursen fra cert-manager forblir uendret.

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: eksempel-no-cert
  namespace: networking
spec:
  secretName: eksempel-no-cert
  dnsNames:
    - "*.eksempel.no"
  issuerRef:
    name: letsencrypt-prod
    kind: ClusterIssuer

Sjekk at Secret-navnet i sertifikatet stemmer nøyaktig overens med certificateRefs i Gateway-objektet fra steg 6, og at begge ressursene ligger i samme namespace, med mindre du eksplisitt har satt opp en ReferenceGrant for cross-namespace-tilgang.

Steg 10: Cross-namespace-ruting med ReferenceGrant

Gateway API krever eksplisitt tillatelse når en ressurs i ett namespace refererer til en ressurs i et annet. Dette var utenkelig med Ingress, hvor alt lå implisitt åpent. Vil applikasjonsteamet i namespace default peke sin HTTPRoute mot et sertifikat i namespace networking, må platform-teamet først opprette en ReferenceGrant som eksplisitt tillater det.

apiVersion: gateway.networking.k8s.io/v1beta1
kind: ReferenceGrant
metadata:
  name: allow-default-to-networking
  namespace: networking
spec:
  from:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      namespace: default
  to:
    - group: ""
      kind: Secret
      name: eksempel-no-cert

Denne eksplisitte modellen er en sikkerhetsforbedring sammenlignet med Ingress, men den er også den vanligste årsaken til at ferske migreringer feiler stille: ruten opprettes, men blir aldri tatt i bruk fordi referansen mangler godkjenning.

Steg 11 og 12: Parallell drift, cutover og opprydding

Ingress og Gateway API kan kjøre side om side i samme klynge uten konflikt, så lenge de ikke konkurrerer om samme eksterne IP eller port. Den tryggeste migreringsmodellen er derfor gradvis: installer den nye controlleren, opprett Gateway API-ressursene, og valider trafikk mot den nye inngangen før du rører DNS.

Test den nye Gateway-en direkte via dens LoadBalancer-IP eller en midlertidig test-hostname, uten å endre produksjons-DNS
Kjør automatiserte smoke-tester mot alle kritiske ruter (helse-endepunkter, autentisering, statiske filer)
Flytt en liten prosentandel av reell trafikk over, for eksempel via vektet DNS eller en canary-hostname
Overvåk feilrater, latens og statuskondisjoner i minst én full driftssyklus (typisk 24–72 timer)
Flytt DNS fullstendig til den nye Gateway-ens adresse når alt er stabilt
Behold den gamle Ingress-controlleren kjørende, men uten trafikk, i en avtalt karensperiode
Avinstaller den gamle Ingress-controlleren og slett de utdaterte Ingress-objektene først når karensperioden er over

Ikke slett den gamle Ingress-oppsettet før DNS, TLS, helsesjekker, observability og en reell rollback-prosedyre er testet i praksis. En rollback på Gateway API-nivå er billig (pek DNS tilbake), men bare hvis den gamle infrastrukturen fortsatt eksisterer når du trenger den.

Under selve canary-fasen bør du følge minst tre målinger side om side for gammel og ny inngang: feilrate på HTTP 5xx, p99-latens og andel vellykkede TLS-håndtrykk. Avvik i noen av disse tre er nesten alltid det første tegnet på et migreringsproblem, gjerne lenge før brukere begynner å melde inn feil selv. Sett en eksplisitt terskel for når du automatisk ruller tilbake (for eksempel mer enn dobbel feilrate sammenlignet med den gamle inngangen over ti minutter), i stedet for å basere beslutningen på magefølelse midt i en pågående utrulling.

Vanlige fallgruver ved Gateway API-migrering

De fleste feilene under en Gateway API-migrering handler ikke om at YAML-en er syntaktisk feil, den valideres jo av Kubernetes API-serveren med det samme. Problemet er nesten alltid semantisk: en referanse som ikke er godkjent, en annotasjon som ikke har noe ekvivalent, eller en antakelse om at gammel oppførsel videreføres uendret. Her er de syv fallgruvene vi ser oftest hos team som migrerer fra Ingress.

Sletter gammel Ingress for tidlig. Rollback blir umulig uten den, og de fleste feil dukker opp først etter reell produksjonstrafikk, ikke i staging.
Antar at annotasjoner oversettes automatisk. Rewrite, rate limiting, WAF og autentiserings-annotasjoner har ofte ingen direkte Gateway API-ekvivalent og krever ny design.
Glemmer ReferenceGrant for cross-namespace-referanser. Ruten ser riktig ut, men blir aldri programmert fordi tilgangen ikke er eksplisitt godkjent.
Blander Standard- og Experimental-kanalens CRD-er uten å låse versjon i infrastrukturkoden, noe som fører til inkonsistente klyngetilstander mellom miljøer.
Antar full conformance hos valgt implementasjon. Én controller kan støtte kjerne-HTTP utmerket, men mangle TCPRoute, UDPRoute eller cross-namespace TLS-håndtering.
Installerer controller før CRD-ene, noe som får controlleren til å krasje eller feile stille ved oppstart.
Stoler på “ressursen ble opprettet” fremfor statuskondisjoner. Et vellykket kubectl apply betyr ikke at Gateway-en faktisk er programmert og ruter trafikk.

Feilsøking: de vanligste problemene og løsningene

Symptom	Sannsynlig årsak	Løsning
GatewayClass status Accepted=False	Controlleren kjører ikke eller mangler RBAC	Sjekk controller-loggene og at controllerName matcher nøyaktig
Gateway status Programmed=False	Feil i listener-konfigurasjon eller manglende sertifikat	Inspiser status.listeners og bekreft at Secret finnes
HTTPRoute ikke akseptert (ResolvedRefs=False)	backendRefs peker på Service som ikke finnes	Bekreft Service-navn, namespace og portnummer
404 fra Gateway-en	Hostname eller path matcher ikke det klienten sender	Sjekk matches-blokken og hostnames-feltet nøyaktig
TLS-håndtrykk feiler	certificateRefs peker på feil namespace eller feil Secret-navn	Sammenlign Secret-navn i Certificate og Gateway nøyaktig
Rute blokkert på tvers av namespace	Manglende ReferenceGrant	Opprett ReferenceGrant som eksplisitt tillater referansen
Kolliderende lyttere på samme port	To Gateway-objekter definerer identisk port/protokoll/hostname	Bruk unike hostname-kombinasjoner eller slå sammen lytterne
Trafikk går fortsatt til gammel Ingress	DNS peker fortsatt på den gamle LoadBalancer-IP-en	Oppdater DNS-oppføringen og verifiser med dig/nslookup
TCPRoute/UDPRoute virker ikke	Valgt implementasjon støtter ikke ressurstypen ennå	Sjekk implementasjonens conformance-matrise før bruk

Når noe ikke fungerer, start alltid med statuskondisjonene fremfor å anta at problemet ligger i selve trafikken. Kommandoen kubectl describe httproute og tilsvarende for gateway og gatewayclass viser nesten alltid årsaken direkte i condition-meldingene, uten at du trenger å grave i controller-logger først.

Bygg denne rekkefølgen inn som en vane hos alle som feilsøker Gateway API i klyngen din: sjekk GatewayClass først (er den akseptert av controlleren i det hele tatt), deretter Gateway (er lytteren programmert og har den et gyldig sertifikat), og til slutt HTTPRoute (er den akseptert og er backend-referansene løst opp). De aller fleste feilsøkingssesjoner løses på under fem minutter når du følger denne rekkefølgen konsekvent, i stedet for å hoppe rett til controller-loggene eller anta at det er et nettverksproblem.

Avanserte tips for produksjonsmiljøer

Når grunnoppsettet fungerer, åpner Gateway API for mønstre Ingress rett og slett ikke kunne løse rent. Vektbasert trafikkdeling i HTTPRoute.rules.backendRefs gir deg canary-utrulling uten en separat service mesh, ved å fordele prosentandeler direkte mellom to Service-versjoner. GRPCRoute gir typet ruting for gRPC-tjenester basert på service- og metodenavn, noe Ingress aldri håndterte pent.

For større organisasjoner er rollefordelingen selve gevinsten: la platform-teamet eie GatewayClass og Gateway-objektene sentralt, mens hvert applikasjonsteam får RBAC-tilgang til kun sine egne HTTPRoute-objekter i eget namespace. Kombiner dette med BackendTLSPolicy der implementasjonen støtter det, for å kryptere trafikken helt fram til backend-Poden, ikke bare fram til Gateway-en. Sett også opp automatisk varsling på Programmed=False-kondisjoner via din eksisterende overvåkingsstack, slik at platform-teamet fanger opp brutte Gateway-er før applikasjonsteamene melder inn nedetid.

Et annet grep som lønner seg tidlig, er å behandle HTTPRoute-objektene som versjonskontrollert kode på lik linje med selve applikasjonen, ikke som en sentral konfigurasjonsfil platform-teamet redigerer manuelt. Legg ruten i samme repo som applikasjonen, la den gå gjennom vanlig pull request-flyt, og la en CI-jobb validere at HTTPRoute-en refererer til et gyldig Gateway-navn før den slipper til produksjon. Dette hindrer den klassiske situasjonen der en Ingress-fil vokser seg til flere tusen linjer og ingen lenger tør å røre den.

Multi-cluster og service mesh: Gateway API utover én klynge

Mange organisasjoner kjører i dag mer enn én Kubernetes-klynge, enten for redundans, for å isolere miljøer, eller fordi ulike team har egne klynger av historiske årsaker. Her viser Gateway API en fordel Ingress aldri hadde: fordi ressursmodellen er standardisert på tvers av implementasjoner, kan du i prinsippet bruke samme HTTPRoute-definisjon mot flere ulike controllere, så lenge de alle støtter samme sett funksjoner. Det gjør det enklere å bygge en konsistent plattform på tvers av klynger som eies av forskjellige team eller kjører i forskjellige skyer.

For team som allerede kjører en service mesh som Istio eller Cilium, overlapper Gateway API delvis med mesh-ens egen trafikkstyring. Den vanlige praksisen er å la Gateway API håndtere nord-sør-trafikk, altså trafikk som kommer inn utenfra klyngen, mens meshet fortsatt håndterer øst-vest-trafikk mellom tjenester internt. Cilium sin Gateway API-implementasjon er et konkret eksempel på dette: samme CNI som allerede håndterer nettverkspolicyer internt i klyngen, kan også programmere Gateway-objektene for ekstern trafikk, uten at du trenger en helt separat ingress-løsning ved siden av.

Dette reduserer også antall bevegelige deler du må drifte. Der mange klynger tidligere kjørte både en dedikert ingress-controller og en separat service mesh med overlappende funksjonalitet for TLS-terminering og trafikkstyring, lar Gateway API deg samle mer av dette i én konsistent modell. Det er fortsatt fornuftig å beholde meshet for avansert intern trafikkstyring, retry-logikk og mTLS mellom tjenester, men selve inngangspunktet til klyngen kan i mange tilfeller forenkles betydelig ved overgangen.

Komplett eksempelprosjekt: fra Ingress til Gateway API

Under følger et samlet, fungerende eksempel som binder sammen alle stegene over for en enkel nettbutikk-applikasjon: én GatewayClass, én Gateway med TLS, én HTTPRoute og en ReferenceGrant for cross-namespace-tilgang til sertifikatet.

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: eg
spec:
  controllerName: gateway.envoyproxy.io/gatewayclass-controller
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: public-gateway
  namespace: networking
spec:
  gatewayClassName: eg
  listeners:
    - name: https
      protocol: HTTPS
      port: 443
      hostname: "webshop.eksempel.no"
      tls:
        mode: Terminate
        certificateRefs:
          - name: eksempel-no-cert
      allowedRoutes:
        namespaces:
          from: All
---
apiVersion: gateway.networking.k8s.io/v1beta1
kind: ReferenceGrant
metadata:
  name: allow-webshop-to-networking
  namespace: networking
spec:
  from:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      namespace: webshop
  to:
    - group: ""
      kind: Secret
      name: eksempel-no-cert
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: webshop
  namespace: webshop
spec:
  parentRefs:
    - name: public-gateway
      namespace: networking
  hostnames:
    - "webshop.eksempel.no"
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      backendRefs:
        - name: webshop-svc
          port: 8080
          weight: 90
        - name: webshop-svc-canary
          port: 8080
          weight: 10

Legg merke til de to backendRefs-oppføringene med vekting 90/10 helt til slutt. Det er canary-utrullingen fra forrige seksjon, implementert med rene Gateway API-primitiver og ingen ekstra kontrollere. Valider oppsettet med:

kubectl apply -f webshop-gateway-api.yaml
kubectl get httproute webshop -n webshop -o jsonpath='{.status.parents}' | jq
curl -v --resolve webshop.eksempel.no:443:GATEWAY_IP https://webshop.eksempel.no/

Får du en gyldig respons og status.parents viser Accepted: True og ResolvedRefs: True, er migreringen for denne applikasjonen fullført. Gjenta prosessen namespace for namespace, ikke i én stor migrering, slik at hvert team kan validere sin egen trafikk uavhengig.

Overvåking og drift etter migreringen

Migreringen er ikke ferdig i det øyeblikket trafikken flyter gjennom den nye Gateway-en. Gateway API endrer hvilke signaler du bør overvåke i det daglige. Med Ingress fulgte de fleste team med på selve controller-loggen og eventuelt en håndfull metrics fra ingress-controlleren. Med Gateway API bør overvåkingen bygges rundt statuskondisjonene direkte, siden de er den primære kilden til sannhet for om trafikken faktisk rutes riktig.

Sett opp periodisk polling eller en kontroller-basert vakthund som sjekker Programmed-kondisjonen på alle Gateway-objekter og Accepted/ResolvedRefs på alle HTTPRoute-objekter, og send varsel til platform-teamet så snart en av dem går til False. De fleste implementasjoner, inkludert Envoy Gateway og NGINX Gateway Fabric, eksponerer også Prometheus-metrics for antall programmerte lyttere, avviste ruter og backend-helse, som bør kobles inn i eksisterende dashboards fremfor å bygge en helt separat overvåkingsstack for Gateway API alene.

Et praktisk grep mange team gjør er å sette opp en enkel, tidsstyrt jobb som kjører kubectl get httproute -A -o json og flagger alle ruter der status.parents[].conditions ikke inneholder Accepted: True. Dette fanger opp stille feil, for eksempel når noen legger til en ny rute som glemmer ReferenceGrant, lenge før en bruker melder inn at en tjeneste er utilgjengelig.

Ofte stilte spørsmål om Gateway API-migrering

Må jeg migrere fra Ingress til Gateway API med det samme?

Nei, Ingress fjernes ikke fra Kubernetes over natten, og de to API-ene kan kjøre parallelt i samme klynge. Men siden Gateway API offisielt er etterfølgeren, lønner det seg å planlegge migreringen nå fremfor å utsette den til en tvungen deadline dukker opp. Start gjerne med én ny applikasjon på Gateway API fremfor å migrere hele den eksisterende Ingress-porteføljen på én gang, slik at teamet ditt bygger praktisk erfaring før den store jobben.

Hva er egentlig forskjellen mellom IngressClass og GatewayClass?

Begge peker på en controller, men GatewayClass er en mer eksplisitt del av en tredelt modell (GatewayClass, Gateway, HTTPRoute) fremfor én samlet ressurs. Det gir bedre rollefordeling mellom platform- og applikasjonsteam.

Støtter alle Kubernetes-distribusjoner Gateway API ut av boksen?

Nei. Du må alltid installere CRD-ene og en implementasjon separat, med mindre du bruker en administrert tjeneste som AKS, som allerede leverer Gateway API-CRD-er som del av klyngeoppsettet. Sjekk alltid skyleverandørens dokumentasjon for nøyaktig versjon før du installerer noe manuelt oppå.

Kan jeg kjøre Ingress og Gateway API samtidig i produksjon?

Ja, dette er faktisk den anbefalte migreringsstrategien. Installer den nye controlleren ved siden av den gamle, valider trafikk gradvis, og fjern først Ingress-oppsettet når Gateway API-ruten er bevist stabil over tid.

Hva skjer med mine eksisterende NGINX-annotasjoner?

De overføres ikke automatisk. Annotasjoner for rewrite, autentisering, rate limiting og WAF må oversettes manuelt til typede felt, filtre i HTTPRoute, eller egne policy-ressurser fra implementasjonen din. Verktøyet ingress2gateway hjelper med strukturen, men ikke med denne typen leverandørspesifikk logikk.

Er Gateway API stabilt nok for produksjon i dag?

Kjerneressursene GatewayClass, Gateway og HTTPRoute er stabile (GA). Utvidede ressurser som GRPCRoute, TCPRoute og UDPRoute varierer i modenhet mellom implementasjoner, så sjekk alltid conformance-matrisen til akkurat den controlleren du planlegger å bruke.

Hvilken Gateway API-implementasjon bør jeg velge?

Det avhenger av hva du allerede kjører. Bruker du Cilium som CNI, gir det mening å bruke dens innebygde Gateway API-støtte. Migrerer du fra NGINX Ingress, er NGINX Gateway Fabric det mest nærliggende sporet. Kjører du på en administrert tjeneste, bruk den innebygde Gateway API-integrasjonen der det er tilgjengelig fremfor å installere en egen controller ved siden av.

Hvordan tester jeg migreringen uten å påvirke ekte brukere?

Bruk curl --resolve til å teste den nye Gateway-ens IP direkte mot ditt produksjonshostnavn, uten å endre DNS. Dette lar deg validere TLS, ruting og backend-tilkobling fullstendig isolert fra reell trafikk, før du flytter en eneste bruker over.

Hva gjør jeg hvis ingress2gateway ikke støtter min Ingress-controller?

Verktøyet støtter et begrenset sett providere, primært ingress-nginx og noen andre store controllere. Bruker du en mindre utbredt eller kommersiell controller uten støtte i verktøyet, må du konvertere manuelt slik steg 7 beskriver, ved å gå gjennom hver Ingress-regel og bygge tilsvarende HTTPRoute for hånd. Start med de enkleste rutene uten spesialannotasjoner, så bygger du erfaring før du tar de mer kompliserte reglene.

Bør jeg vente på at flere ressurser blir GA før jeg migrerer?

Nei, det er sjelden en god grunn til å vente på hele API-en dersom kjernebehovet ditt allerede dekkes av de stabile ressursene. De fleste produksjonsmiljøer trenger i utgangspunktet bare GatewayClass, Gateway og HTTPRoute, som alle er GA. Vent heller med å ta i bruk ressurser fra Experimental-kanalen, som deler av TCPRoute og UDPRoute, til du har bekreftet at akkurat din valgte implementasjon har stabil støtte for dem gjennom deres egen conformance-rapport.

Kubernetes Gateway API: Migrer fra Ingress i 12 Steg [2026]