This guide covers migrating from Kubernetes Ingress to Gateway API: what is changing, why, and what you need to do.
The Kubernetes Ingress API has been stable since v1.19 (2020) and is feature-frozen. With Gateway API v1.0 graduating to GA in October 2023, the Kubernetes community designated it as the successor to Ingress. New features are no longer added to Ingress; development effort goes into Gateway API, which addresses Ingress limitations while remaining implementation-agnostic.
ingress-nginx is the most widely deployed Ingress controller. The Kubernetes SIG Network and Security Response Committee announced that ingress-nginx will enter retirement mode with best-effort maintenance until March 2026. After that date:
This applies to the community ingress-nginx controller, not the Ingress API itself. Because ingress-nginx is so widely deployed, this timeline makes migration planning urgent.
Other ingress controllers (Traefik, HAProxy, etc.) may continue support, but the ecosystem is converging on Gateway API.
See also: Ingress NGINX: Statement from the Kubernetes Steering and Security Response Committees
| Feature | Ingress | Gateway API |
|---|---|---|
| Role separation | Single resource | GatewayClass → Gateway → Routes (platform provider, operator, developer) |
| Protocol support | HTTP/HTTPS only | HTTP, HTTPS, gRPC, TCP, UDP, TLS |
| Header manipulation | Annotation-dependent | Native support |
| Traffic splitting | Limited | Built-in weighted routing |
| Cross-namespace routing | Complex | First-class ReferenceGrant support |
| Portability | Vendor annotations | Standardized API |
Ingress World Gateway API World
───────────── ─────────────────
IngressClass → GatewayClass
↓ ↓
Ingress → Gateway
(rules + backend) ↓
HTTPRoute / GRPCRoute / TCPRoute / etc.
↓
Service
Migrating from Ingress to Gateway API is not a one-shot process. The effort depends on how complex your current Ingress setup is, and you may hit roadblocks. Evaluate your setup and plan the migration accordingly.
Assess these areas:
Your Ingress controller runs its own LoadBalancer Service. Gateway API creates a separate LoadBalancer Service with a different IP. Plan for DNS cutover accordingly.
Ingress Controller LB (10.0.0.1) → Gateway LB (10.0.0.2)
↑ ↑
Current DNS New DNS target
Option A - Blue-Green:
Option B - Gradual Migration:
external-dns can manage records for both Ingress and Gateway simultaneously during migration.
When the same hostname exists on both Ingress and Gateway:
Existing TLS certificates do not carry over to Gateway resources; cert-manager must issue new ones. To avoid downtime during validation, use DNS01 challenges. If your Gateway is in the same namespace as your Ingress, both can share the same Secret.
You cannot gradually shift traffic percentages between Ingress and Gateway, and there is no canary support between them. DNS is the switch, and it is all or nothing per hostname. Test thoroughly before flipping.
KubeLB includes a migration tool that converts Ingress resources to Gateway API. It is free to use and open source.
Do not use this tool directly in production. Run it first in testing/staging environments, verify the results, identify resources that could not be migrated, and migrate those manually.
The tool covers the assessment points above, including DNS cutover strategy, overlapping hostnames, and certificate continuity. It can add a suffix to all new Gateway resources to avoid conflicts with existing Ingress resources. Verify the new Gateway resources work as expected, then flip DNS to the new Gateway IP.
Supported Ingress controllers:
Supported Gateway API implementations:
See the KubeLB Ingress to Gateway API Converter page for detailed documentation.
For an interactive workflow, the KubeLB CLI and its local web dashboard can list, preview, and convert Ingresses step by step; see the CLI & Dashboard guide.
The community tool ingress2gateway migrates Ingress resources to Gateway API. While KubeLB handles annotations for ingress-nginx only, ingress2gateway supports additional Ingress controllers.
Supported providers:
See the ingress2gateway repository.
Ingress:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: example
annotations:
nginx.ingress.kubernetes.io/rewrite-target: /
spec:
ingressClassName: nginx
rules:
- host: example.com
http:
paths:
- path: /api
pathType: Prefix
backend:
service:
name: api-service
port:
number: 80
tls:
- hosts:
- example.com
secretName: example-tls
Equivalent Gateway API:
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
name: example
spec:
gatewayClassName: kubelb
listeners:
- name: https
protocol: HTTPS
port: 443
hostname: example.com
tls:
mode: Terminate
certificateRefs:
- name: example-tls
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: api-route
spec:
parentRefs:
- name: example
hostnames:
- example.com
rules:
- matches:
- path:
type: PathPrefix
value: /api
filters:
- type: URLRewrite
urlRewrite:
path:
type: ReplacePrefixMatch
replacePrefixMatch: /
backendRefs:
- name: api-service
port: 80
Supporting tools also need updates when migrating to Gateway API. The following pages cover how to adapt cert-manager and external-dns configurations:
KubeLB is not dropping Ingress support, and ingress-nginx remains supported. We encourage users to migrate to Gateway API as soon as possible.
KubeLB will patch and upgrade the ingress-nginx controller while updates are available upstream. Once upstream support ends, KubeLB will ship the last available ingress-nginx release.