Moving from Kubernetes Ingress to Gateway API is not a simple manifest replacement. This guide gives platform and application teams a practical way to compare the two models, discover compatibility gaps, convert routes safely, and plan a staged migration with a clear rollback path.
Overview
Kubernetes Ingress remains a widely used way to expose HTTP and HTTPS services, but its core API is intentionally narrow. Teams often rely on controller-specific annotations to add features such as redirects, rewrites, authentication, timeouts, or traffic controls. Those annotations can make an Ingress manifest difficult to move between controllers or review across teams.
Gateway API addresses this by separating infrastructure ownership from application routing. A platform team can manage a GatewayClass and Gateway, while application teams attach HTTPRoute resources to define which requests reach their services. The model also provides a clearer place for protocol-specific and cross-namespace routing features.
That does not mean Gateway API is automatically the better choice for every cluster. The right decision depends on your controller, cloud provider integration, required routing features, team boundaries, operational tooling, and tolerance for running two API models during a transition. Treat this as a migration planning exercise, not a search-and-replace operation.
Gateway API vs Ingress compatibility matrix
| Area | Ingress | Gateway API | Migration question |
|---|---|---|---|
| Routing model | Usually one resource describes host and path routing. | Routing is divided among Gateway and route resources such as HTTPRoute. | Which team should own listeners, hostnames, and application paths? |
| Controller support | Supported by most established Kubernetes ingress controllers, with differences in annotations. | Support varies by controller and by feature channel. | Does the selected controller implement every field your routes require? |
| TLS | TLS configuration is commonly placed in the Ingress resource. | TLS is associated with Gateway listeners and referenced secrets. | Who manages certificates, secrets, and listener changes? |
| Annotations | Often essential for controller-specific behavior. | Uses structured fields for supported behavior, with implementation-specific extensions where necessary. | Which annotations have no direct equivalent? |
| Multi-team ownership | Ownership is often concentrated in one Ingress object. | Gateway and route resources can support clearer platform and application boundaries. | Can application teams attach routes without changing shared infrastructure? |
| Portability | Basic rules are portable, but annotations frequently are not. | Core fields improve portability, while controller-specific features still require review. | Which behavior depends on the current controller? |
| Rollback | Existing Ingress resources can remain active during preparation. | Parallel listeners, hostnames, or controllers may be used depending on the environment. | Can traffic return to the original route without changing application code? |
Before committing to a migration, record the exact Kubernetes version, Gateway API resources installed in the cluster, controller version, supported feature levels, cloud load balancer behavior, and admission or policy controls. Capability is not guaranteed merely because a controller advertises Gateway API support.
Checklist by scenario
Scenario 1: Evaluating whether to migrate
- List the problems you are trying to solve. Examples include annotation sprawl, unclear ownership, repeated listener configuration, or a need for richer routing.
- Inventory every Ingress, Service, TLS secret, hostname, path rule, rewrite, redirect, authentication setting, rate limit, and controller-specific annotation.
- Separate portable routing requirements from implementation-specific behavior. A path match may translate cleanly while an annotation-driven rewrite may not.
- Ask whether the current controller already supports the required Gateway API resources. If it does not, include controller replacement, cloud integration, and operational training in the project scope.
- Define success measures such as unchanged response behavior, no certificate interruption, preserved observability, and a documented rollback window.
Scenario 2: Converting a simple application
Start with an application that has one hostname, one backend service, and ordinary HTTP or HTTPS traffic. A simplified Ingress might look like this:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web
spec:
ingressClassName: example
rules:
- host: app.example.test
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: web
port:
number: 80
The equivalent Gateway API design normally separates the shared entry point from the application route:
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: web
spec:
parentRefs:
- name: shared-gateway
namespace: platform
hostnames:
- app.example.test
rules:
- matches:
- path:
type: PathPrefix
value: /
backendRefs:
- name: web
port: 80
This example assumes that a compatible Gateway and listener already exist and that the route is permitted to attach across namespaces. Names, API versions, feature support, and cross-namespace references must be checked against your cluster and controller documentation.
Scenario 3: Migrating a shared or complex entry point
- Group routes by ownership rather than copying a large Ingress into one large HTTPRoute.
- Map each hostname to a listener and confirm that hostname ownership rules prevent accidental route attachment.
- Review cross-namespace references, including the rules governing which namespaces may attach routes to a shared Gateway.
- Test weighted backends, header matching, redirects, rewrites, timeouts, and other advanced behavior independently. Do not assume that an annotation has a direct structured replacement.
- Preserve the old route until the new route has passed functional, security, and observability checks.
Scenario 4: Preparing a production cutover
- Install or enable the required Gateway API resources in a non-production cluster first.
- Validate manifests with the Kubernetes API server and the controller's own status conditions.
- Confirm that the Gateway receives an address, listeners become ready, and HTTPRoute resources report accepted and programmed states.
- Exercise DNS, TLS, redirects, authentication, health checks, WebSocket or streaming behavior, and failure responses where relevant.
- Compare request volume, status codes, latency, upstream errors, and access logs between the old and new paths.
- Define the exact command, manifest change, or DNS action that returns traffic to the Ingress path.
What to double-check
Controller and cloud-provider behavior
Gateway API is a set of Kubernetes resources, not a complete load-balancer implementation. The controller determines how those resources become proxies, cloud load balancers, listeners, firewall rules, health checks, and data-plane configuration. Check supported resource versions, feature maturity, implementation-specific extensions, status reporting, and upgrade guidance before selecting a migration target.
Also verify whether creating a Gateway provisions a new external address or reuses an existing one. A change in address, firewall policy, source IP handling, idle timeout, or health-check behavior can affect clients even when the route rules appear equivalent.
TLS and secrets
Confirm the certificate secret namespace, listener hostname coverage, certificate rotation process, and how the controller reports invalid references. Review who can read or reference TLS material. If your migration changes secret ownership, use the same care described in a secrets management review rather than treating the reference as a harmless YAML change.
Policy and security controls
Admission policies may allow Ingress resources but reject Gateway or route resources, or they may impose different naming and namespace rules. Update policy-as-code tests, RBAC, audit rules, and deployment pipelines before production rollout. A useful companion is a review of policy as code with OPA and Kyverno.
Observability and operations
Identify the logs, metrics, traces, dashboards, and alerts for both the old and new data paths. Confirm that request identity, forwarded headers, client IP information, status codes, and upstream timing remain available in the expected format. Update runbooks so on-call engineers know whether to inspect a Gateway, HTTPRoute, Service, EndpointSlice, cloud load balancer, or application pod.
Common mistakes
- Assuming every annotation converts directly. Create a behavior map for each annotation and label it as native, controller-specific, unsupported, or requiring application changes.
- Testing only resource acceptance. A route can be syntactically valid while TLS, DNS, redirects, headers, or backend health checks behave differently.
- Changing the controller and API at the same time. If possible, isolate variables so a failed request can be traced to the route model, controller, cloud integration, or application.
- Ignoring ownership boundaries. Shared Gateways need explicit rules for who can create listeners, claim hostnames, attach routes, and modify security-sensitive behavior.
- Removing Ingress too early. Keep the old configuration available until monitoring confirms stable behavior and the rollback decision has an owner.
- Forgetting generated configuration. Helm values, GitOps templates, Terraform modules, and deployment pipelines may still emit Ingress resources. Review the source of truth, not only the rendered manifest. The Helm chart review checklist can help structure that inspection.
When to revisit
Revisit this migration plan before seasonal planning cycles, cluster upgrades, controller upgrades, cloud networking changes, and onboarding a new application group. The compatibility matrix should also be reviewed whenever a team changes ingress controllers, introduces a new authentication or routing requirement, or changes ownership of shared Gateways.
At minimum, record the date of the last review and recheck the installed Kubernetes and controller versions, supported Gateway API resources, feature status, cloud-provider behavior, deprecated fields, policy rules, and rollback procedure. Repeat the validation in a non-production environment after meaningful workflow or tool changes.
For the next action, choose one low-risk application and complete the discovery worksheet: current Ingress manifest, annotations, DNS records, certificates, backend services, ownership, observability signals, and rollback trigger. Convert only that route, run the acceptance tests, and document the result. A small, evidence-based pilot will tell you more than a cluster-wide migration estimate based only on manifest counts.