Kubernetes Ingress to Gateway API Migration Guide: Routes, Policies, Controllers, and Rollback Checks
KubernetesGateway APIIngressHTTPRoutetraffic managementplatform engineering

Kubernetes Ingress to Gateway API Migration Guide: Routes, Policies, Controllers, and Rollback Checks

OOracles Cloud Editorial Team
2026-11-21
7 min read

A practical Kubernetes checklist for migrating Ingress to Gateway API while protecting routes, TLS, policies, observability, and rollback paths.

Migrating from Kubernetes Ingress to Gateway API is more than replacing one manifest kind with another. This guide provides a reusable checklist for inventorying routes, selecting a controller, translating listeners and policies, validating TLS and cross-namespace access, observing traffic, and rolling back without losing control of production entry points.

Overview

Kubernetes Ingress provides a familiar, widely supported model for exposing HTTP and HTTPS services, but its configuration often depends on controller-specific annotations. Gateway API separates infrastructure ownership from application routing through explicit resources such as GatewayClass, Gateway, and HTTPRoute. That separation can make platform responsibilities, route ownership, and policy boundaries easier to review, provided the target controller implements the features your environment needs.

The migration should therefore be treated as a controlled traffic change rather than a manifest conversion. Begin by documenting current behavior, including routes that are expressed only through annotations. Then create an equivalent Gateway API configuration in a staging environment, test it against realistic requests, and introduce production traffic gradually. Keep the existing Ingress path available until the new path has passed functional, security, and operational checks.

AreaIngressGateway API
Primary routing objectIngress combines host and path rules with backend references.HTTPRoute describes application routing and attaches to a Gateway.
Infrastructure selectionUsually selected through an ingress class and controller-specific behavior.GatewayClass identifies the controller and its implementation.
ListenersOften embedded in the Ingress specification.Explicit Gateway listeners define ports, protocols, hostnames, and TLS.
Ownership modelApplication teams may configure infrastructure details in one resource.Platform teams can own Gateways while application teams own HTTPRoutes.
CustomizationFrequently relies on annotations that vary by controller.Uses typed fields, route filters, and controller-supported policy resources.
Cross-namespace accessBehavior commonly depends on controller conventions.Attachment and references are governed by explicit namespace rules and, where required, ReferenceGrant.

Gateway API support is not identical across controllers. Before implementation, check the target controller's supported Gateway API release, conformance information, policy model, cloud integration, and limitations. Treat those details as deployment inputs that must be reviewed whenever the controller or Kubernetes version changes.

Checklist by scenario

1. Before converting any manifests

  • Record every Ingress, ingress class, hostname, path, path type, backend service, service port, and namespace.
  • Export controller-specific annotations and classify each one as routing, TLS, authentication, redirects, timeouts, buffering, rate limiting, access control, or observability.
  • Identify default backends, wildcard hostnames, rewrite behavior, regular-expression paths, websocket or streaming traffic, and non-HTTP listeners.
  • Document DNS records, load balancer addresses, health checks, firewall rules, source IP expectations, and any external identity or certificate integration.
  • Capture representative requests and expected responses, including status codes, redirects, headers, authentication failures, and upstream error behavior.
  • Confirm the destination controller's GatewayClass name, supported resources, policy extensions, and managed-Kubernetes integration requirements.

Keep this inventory in version control or an operational repository. A GitOps repository can provide a useful structure for separating shared platform resources from environment-specific route definitions; see the GitOps repository structure guide for related promotion and rollback practices.

2. Designing the Gateway and listeners

  • Select the appropriate GatewayClass and verify that its controller is installed, healthy, and permitted to manage the resource.
  • Define one or more listeners with explicit names, protocols, ports, hostnames, and TLS settings. Avoid relying on an undocumented default.
  • Decide which namespaces may attach routes using listener settings such as same-namespace or selector-based access.
  • Define whether HTTP should redirect to HTTPS and confirm that the redirect is implemented by a supported filter or policy rather than an annotation assumption.
  • Choose ownership boundaries: platform teams typically manage Gateway infrastructure, while service teams manage HTTPRoutes and backend references.
  • Label resources with environment, service, owner, and cost-allocation metadata so the new entry point remains discoverable. The Kubernetes and cloud cost allocation guide covers related labeling practices.

3. Converting routes

A simple Ingress rule commonly becomes an HTTPRoute with a hostname, a path match, a parentRefs entry pointing to the Gateway, and a backendRefs entry pointing to the Service. A simplified example is:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: shop
  namespace: apps
spec:
  parentRefs:
  - name: public
    namespace: edge
  hostnames:
  - shop.example.test
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /
    backendRefs:
    - name: shop
      port: 8080
  • Translate each host and path deliberately; do not assume annotation-based rewrites or regex behavior have an equivalent default.
  • Confirm path matching precedence and test overlapping paths, trailing slashes, encoded characters, and case-sensitive application behavior.
  • Map redirects, header modification, URL rewriting, request mirroring, and traffic splitting only where the controller supports the relevant Gateway API feature.
  • Keep backend service names and ports exact. A valid route can still return upstream errors if the Service selector, port, or readiness behavior is wrong.
  • Use separate HTTPRoutes when different teams own different paths, but test the combined listener for conflicts and unexpected precedence.

4. Migrating TLS and cross-namespace references

  • Inventory every certificate, secret name, issuer or external certificate source, renewal process, and hostname covered by the certificate.
  • Configure TLS at the appropriate Gateway listener and verify that the certificate reference points to the expected Secret and namespace.
  • Confirm whether the controller supports the intended certificate integration. Do not assume an Ingress annotation will be recognized by a Gateway.
  • For cross-namespace route attachment or backend and certificate references, check namespace permissions and create the required explicit grant resources where supported.
  • Test the complete certificate chain, SNI behavior, renewal, and failure handling. The TLS certificate operations guide provides a reusable review list.

5. Staging, cutover, and rollback

  1. Apply the GatewayClass, Gateway, policies, and HTTPRoutes to a staging cluster or isolated environment.
  2. Inspect resource status and conditions. A successful kubectl apply does not prove that a listener was accepted or that a route attached successfully.
  3. Run automated and manual tests for every hostname, path, method, redirect, authentication flow, TLS certificate, and backend failure mode.
  4. Exercise observability: confirm access logs, request metrics, traces, latency measurements, upstream errors, and controller events are available. These signals belong in the same operational review as other observability tools.
  5. Plan the production cutover. Options include a separate test hostname, a temporary load balancer address, DNS change, or controlled listener transition, depending on the platform.
  6. Define rollback thresholds in advance, such as elevated 4xx or 5xx responses, TLS failures, increased latency, missing logs, or route attachment errors.
  7. Keep the original Ingress configuration intact until the observation window ends. Record the exact DNS, load balancer, or manifest change that restores the old path.

What to double-check

  • Controller readiness: Verify the controller watches the intended Gateway API resources and that its GatewayClass is accepted. Check events and status conditions rather than only pod health.
  • Listener conflicts: Check for duplicate ports, overlapping hostnames, incompatible protocols, and listener names referenced incorrectly by routes.
  • Route attachment: Confirm that every HTTPRoute has an accepted parent and that namespace restrictions do not silently prevent attachment.
  • Policy scope: Separate portable routing configuration from implementation-specific authentication, authorization, rate limiting, WAF, timeout, and access-log policies. Document where those policies attach and what happens when they are unsupported.
  • TLS references: Verify Secret type, namespace, certificate names, key pair validity, hostname coverage, renewal ownership, and behavior during certificate replacement.
  • Backend health: Test readiness, service endpoints, port names, network policies, and application-generated redirects. The route layer cannot correct an unhealthy or incorrectly addressed backend.
  • Client compatibility: Check HTTP methods, large headers, uploads, websockets, server-sent events, connection timeouts, and source IP handling if applications depend on them.
  • Operational recovery: Ensure the team knows how to inspect Gateway API status, controller events, logs, and metrics. Include the rollback command or change procedure in the runbook.

Common mistakes

  • Converting only the visible YAML: Important behavior may be hidden in annotations, controller defaults, DNS, certificate automation, or external policies. Inventory the whole request path.
  • Assuming annotation parity: An annotation from one Ingress controller may have no Gateway API equivalent, or it may require a controller-specific policy resource. Re-test its actual effect.
  • Changing DNS and routing simultaneously: When possible, separate configuration validation from public traffic movement so failures are easier to localize.
  • Ignoring namespace boundaries: A route in one namespace cannot automatically use every Gateway, Secret, or Service in another. Make allowed relationships explicit and review them as access controls.
  • Removing the old route too early: Keep a tested rollback path until traffic, certificates, logs, and dependent clients have been observed under normal and failure conditions.
  • Testing only a 200 response: A basic success check misses redirects, authorization failures, oversized requests, timeout behavior, streaming, and upstream error propagation.
  • Mixing controller upgrades with migration: If possible, avoid changing the ingress controller, Kubernetes version, DNS, and route model in one release. The Kubernetes cluster upgrade checklist can help isolate upgrade-related risk.

When to revisit

Revisit this checklist before each service migration, ingress-controller replacement, new routing requirement, planned Kubernetes upgrade, or major certificate and identity change. It should also be reviewed after a traffic incident, a policy change, or a post-migration performance review.

At least twice a year, confirm the target controller's supported Gateway API version, implementation differences, policy resources, deprecated annotations, and managed-Kubernetes integration notes. Check that example manifests still match the versions and conventions used by your clusters. During seasonal planning cycles, review route ownership, hostname inventory, TLS renewal coverage, rollback procedures, and observability dashboards.

For the next migration, start with a small, low-risk service. Create the inventory, map each behavior to an explicit Gateway API field or documented controller policy, validate in staging, and record the production rollback point. Only then schedule the cutover. This approach turns an Ingress to Gateway API migration into a repeatable platform operation rather than a one-time configuration rewrite.

Related Topics

#Kubernetes#Gateway API#Ingress#HTTPRoute#traffic management#platform engineering
O

Oracles Cloud Editorial Team

Cloud-Native Infrastructure Editors

Senior editor and content strategist. Writing about technology, design, and the future of digital media. Follow along for deep dives into the industry's moving parts.