Published: September 6, 2026 · Last updated: September 6, 2026 · Author: Softix
A Kubernetes Gateway API migration is not a command-line replacement for every Ingress annotation. It is a change in how a cluster expresses traffic ownership. The Kubernetes Gateway API documentation describes a role-oriented model in which infrastructure owners can define a Gateway, while application teams attach routes such as HTTPRoute.
That separation can make shared clusters easier to govern, but it also introduces a new API surface, controller-specific behavior, and a one-time conversion from Ingress. Softix recommends Map–Shadow–Route–Retire: map the current behavior, shadow the new resources beside the old path, move one route at a time, and retire legacy configuration only after evidence.
What Gateway API changes
The older Ingress object is a compact HTTP routing API. It is familiar, but many teams extend it with controller-specific annotations for rewrites, authentication, rate limits, snippets, and load-balancer behavior. Those annotations can become a hidden platform contract.
Gateway API splits responsibilities across resources. A GatewayClass identifies the implementation. A Gateway represents a traffic-handling boundary. HTTPRoute expresses application routing and can attach to a Gateway. Other route kinds support additional protocols when the selected implementation and conformance profile support them. Read the official Gateway API concepts rather than assuming every controller implements every field.
The value is not merely a larger YAML vocabulary. A platform team can own listeners, addresses, and TLS policy while a product team owns routes within an allowed namespace boundary. That boundary is explicit and reviewable. It can be more useful than asking every developer to understand a collection of annotations.
Gateway API is not implemented by Kubernetes itself. It is a set of custom resources plus an implementation supplied by a controller or gateway product. Install the CRDs and choose an implementation deliberately.
The Softix Map–Shadow–Route–Retire model
1. Map the behavior, not just the manifests
Export current Ingress objects, Services, certificates, DNS records, controller configuration, and relevant annotations. For each host and path, document:
Public hostname and certificate owner.
Backend Service, port, namespace, and readiness assumptions.
Path matching and rewrite behavior.
Authentication, authorization, WAF, rate limits, and IP restrictions.
Timeouts, retries, body limits, WebSockets, gRPC, and upload behavior.
Observability: access logs, request IDs, status codes, latency, and error ownership.
Rollback action and the person authorized to perform it.
Do not treat an Ingress YAML file as the complete contract. The controller may have defaults or annotations outside the manifest. A route that looks like /api may be rewritten before it reaches the application. A TLS secret may be created by a certificate controller. Map the data path from DNS to the application and back.
The Kubernetes ingress2gateway project can help print candidate Gateway API resources from supported providers. Treat generated output as a translation aid, not an approved production change. Complex snippets and provider-specific behavior still need human review.
2. Shadow the new resources
Install the Gateway API CRDs and the chosen implementation in a non-production cluster or an isolated namespace first. Check the implementation’s support matrix and conformance profiles. “Supports Gateway API” can mean different things across core resources, versions, route types, and optional features.
Convert one representative route that exercises the difficult parts: TLS, a path prefix, a health endpoint, and an application that returns meaningful errors. Keep the old Ingress path intact while the new route is validated. If the implementation cannot bind the route, read status conditions and controller events instead of repeatedly editing YAML until it appears green.
Shadowing can mean running an alternate hostname, sending a controlled test slice, or replaying sanitized requests in staging. Do not duplicate production writes casually. A request that creates an order or triggers a webhook is not a harmless test merely because it uses a second hostname.
Verify the operational contract:
The intended host and path reach the intended Service.
TLS uses the expected certificate and minimum policy.
Unknown hosts fail safely.
Cross-namespace references are explicit and authorized.
Readiness and startup behavior do not send traffic to an unready Pod.
Timeouts and retries do not multiply a slow dependency’s load.
Logs and metrics preserve the route identity operators need.
3. Route a small production slice
Choose a low-risk, reversible workload first. A read-only dashboard or staging-like internal service is better than the checkout path. Define the migration window, on-call owner, success signals, and rollback command before changing DNS or the load balancer.
A route migration should test more than a 200 response. Exercise redirects, authentication failures, large headers, uploads, WebSockets or gRPC if used, cache behavior, and dependency timeouts. Test from the networks your customers use. A local curl does not reveal a corporate proxy, mobile carrier, or regional DNS issue.
Use application-level correlation IDs so an operator can follow a request across the Gateway, Service, and application. Compare status-code distribution and latency against the old route without claiming that a new controller is faster by default. The point of the first slice is confidence, not a benchmark headline.
Keep security controls layered. Kubernetes NetworkPolicy documentation explains that network policy controls traffic at the Pod level; a Gateway route is not a substitute for authorization. Validate tenant and user permissions in the application, and ensure the Gateway does not accidentally expose an administrative Service.
4. Retire legacy configuration deliberately
When a route has passed its observation window, update the source-of-truth repository and remove obsolete annotations from the migration plan. Do not delete every Ingress object because the first Gateway route worked. Migrate by application boundary and keep a clear list of remaining legacy behavior.
Set a retirement condition: all routes are represented, provider-specific exceptions have owners, dashboards use the new route identity, and rollback no longer depends on an undocumented controller flag. Archive the old manifests after the final cutover so future operators can understand the change without restoring them accidentally.
Controller support is a product decision
Gateway API resources are portable only within the capabilities they share. A controller may add policy resources, plugins, or annotations that are valuable but not portable. Record three layers separately:
Standard behavior: fields and resources covered by the Gateway API version and conformance profile.
Implementation behavior: features offered by the selected controller or cloud load balancer.
Application behavior: assumptions made by services, middleware, and clients.
If a requirement depends on layer two, name the dependency in the architecture record. That is not a reason to avoid the controller; it is a reason to avoid describing the deployment as vendor-neutral when it is not.
TLS deserves the same treatment. Certificate provisioning, secret references, listener attachment, and policy enforcement may be separate components. Test renewal, expired certificates, a missing secret, and a certificate for the wrong hostname. A route that works until renewal is not production-ready.
Decision table for a small team
Situation Sensible next move Do not do this
One cluster and simple HTTP Ingress Pilot one Gateway and one HTTPRoute in staging Rewrite every manifest without mapping annotations
Many teams share a cluster Define Gateway ownership and route attachment policy Give every namespace unrestricted listener control
Heavy controller-specific snippets Inventory and redesign the behavior first Assume ingress2gateway preserves every snippet
Need TCP, UDP, or gRPC Confirm implementation and conformance support Infer support from an HTTP demo
Small operations team Keep one supported implementation and a rollback runbook Operate several controllers for theoretical portability
A 30-day migration plan
Days 1–7 — Map: export resources, list annotations, identify traffic owners, and select a low-risk route.
Days 8–14 — Shadow: install CRDs and the implementation in a safe environment, convert the route, and test status conditions, TLS, and logs.
Days 15–21 — Route: move one production slice with an explicit rollback, then compare user-visible behavior and operational signals.
Days 22–30 — Retire: update platform documentation, remove duplicate configuration, add conformance checks to CI, and schedule the next route only when ownership is clear.
Common mistakes
Treating Gateway API as a drop-in annotation translator.
Choosing a controller before listing required protocols and policies.
Testing only successful requests.
Forgetting cross-namespace reference permissions.
Moving DNS before a rollback path exists.
Treating a healthy Gateway status as proof that application authorization is correct.
Claiming performance improvements without field measurements.
FAQ
Should every small team migrate from Ingress now?
No. A migration is justified when the current controller contract is hard to govern, teams need clearer ownership, or a supported platform direction makes Gateway API the better long-term interface. A stable API does not remove the cost of testing your current behavior.
Can Gateway API and Ingress run together?
A staged migration can keep old and new resources during testing, subject to the chosen implementation’s behavior and conflict rules. Validate the exact controller and avoid two resources claiming the same traffic unintentionally.
Does Gateway API secure a Kubernetes application?
It can express routing and some policy integration, but it does not replace application authentication, authorization, network policy, secrets management, or image and workload security.
A practical next step
If your cluster’s Ingress configuration is a mixture of annotations, controller defaults, and tribal knowledge, Softix can map the behavior before proposing a Gateway API migration. Explore custom software development or contact Softix for a scoped platform review.
Share
