Kubernetes Ingress vs Gateway API: Migration Guide and Feature Comparison

Overview

The question is not whether Gateway API is universally better than Ingress. The useful question is whether its model solves a problem your platform already has. A small application cluster with straightforward host and path routing may have little to gain from changing. A multi-team environment with shared gateways, different traffic policies, or complex routing requirements may benefit from Gateway API's clearer separation of responsibilities.

Kubernetes Ingress is a long-established API for exposing HTTP and HTTPS services. Its basic resources describe hosts, paths, and backends, but many controllers extend that model through annotations or controller-specific configuration. Those extensions can be effective, yet they may make manifests harder to move between controllers or understand across teams.

Gateway API introduces several resource types for different operational roles. A GatewayClass identifies the implementation, a Gateway represents a traffic entry point, and an HTTPRoute connects application routes to backend services. The model can let a platform team manage shared infrastructure while application teams manage routes within defined boundaries. Exact capabilities still depend on the Gateway API release and the controller supporting it, so compatibility must be checked rather than assumed.

Gateway API is therefore best viewed as an option for improving the API boundary between platform infrastructure and application delivery. It is not a guarantee of portability, and it does not remove the need to understand the selected controller's behavior.

Checklist by scenario

Keep Ingress for now when

• Your routes use only standard host, path, backend, and TLS behavior.
• Your current ingress controller is supported, monitored, and meeting operational requirements.
• Most advanced behavior is stable, documented, and not creating maintenance problems.
• Your team cannot allocate time for parallel testing and rollback planning.
• The controller you would use for Gateway API lacks support for features your applications require.

Keeping Ingress is a valid platform decision. Record the reason, review controller and Kubernetes compatibility during upgrade planning, and avoid adding unnecessary controller-specific annotations without documenting their purpose.

Evaluate Gateway API when

• Platform and application teams need clearer ownership of shared entry points.
• You use several route types, traffic splits, redirects, rewrites, or cross-namespace patterns.
• Controller-specific annotations have become difficult to audit or migrate.
• You are standardizing ingress behavior across clusters or environments.
• You are introducing a new controller and can test Gateway API before committing to legacy configuration.

Begin with a representative route rather than a full-cluster conversion. Select one service with ordinary traffic, one route with TLS, and—if relevant—one route using an advanced policy. This exposes compatibility gaps early without turning the first test into a platform-wide change.

Use this migration inventory

Before creating new resources, make a route inventory. For each Ingress, record:

• Namespace, hostname, path, path type, and backend service.
• Ports, TLS secrets, certificate ownership, and redirect behavior.
• Annotations and the controller features they activate.
• Authentication, rate limits, headers, rewrites, timeouts, retries, and traffic policies.
• Cross-namespace references, external backends, health checks, and network restrictions.
• Observability requirements, including access logs, metrics, traces, and alert names.
• Business criticality, acceptable maintenance window, and rollback method.

Mark every item as “core API,” “controller-specific,” or “unknown.” Unknown behavior should be tested before migration. This inventory is also useful during recurring route audits because it reveals configuration that exists only in annotations or external controller files.

Follow a staged conversion workflow

1. Confirm versions and support. Check the Kubernetes version, Gateway API resources, controller release, supported feature levels, and installation procedure. Treat the controller's support matrix as authoritative for implementation-specific behavior.
2. Map responsibilities. Decide who owns the GatewayClass, Gateway, listeners, certificates, and HTTPRoutes. Define which namespaces and references are permitted.
3. Convert a representative route. Recreate the hostname, path matching, backend reference, TLS listener, and any required filters using the controller's documented syntax.
4. Inspect status conditions. Do not rely only on an applied manifest. Confirm that the Gateway and route report accepted, programmed, or equivalent healthy conditions for the implementation.
5. Test from outside the cluster. Verify DNS, certificates, redirects, status codes, headers, request paths, authentication, timeouts, and error handling. Test both expected and invalid requests.
6. Compare observability. Ensure dashboards, logs, traces, alerts, and request identifiers still provide enough information to troubleshoot the route.
7. Run in parallel where possible. Use a separate hostname, path, or controlled traffic mechanism rather than changing the production route immediately.
8. Document rollback. Keep the original Ingress manifest, record the DNS or load-balancer changes, and define the signal that triggers a return to the previous configuration.
9. Expand by route class. Migrate ordinary routes first, then TLS variations, policy-heavy routes, and cross-namespace arrangements.

What to double-check

Routing semantics: Similar-looking path rules may not produce identical results. Check path matching, trailing slashes, precedence, redirects, rewrites, and handling of unmatched requests.

TLS behavior: Confirm which resource references the certificate, which namespace owns the secret, how listener names and ports are defined, and how certificate rotation is handled. Test expired, mismatched, and missing certificates where appropriate.

Controller-specific features: An annotation does not automatically have a direct Gateway API equivalent. Identify whether the behavior maps to a standard field, an implementation-specific policy, a custom resource, or no supported feature at all.

Cross-namespace access: Gateway API can make relationships between shared gateways and application routes explicit, but those relationships still require permitted references and correct controller configuration. Test both allowed and denied attachment cases.

Traffic policies: Rate limits, authentication, retries, load-balancing choices, header manipulation, and timeouts may be implemented outside the core route resource. Verify effective behavior at runtime rather than assuming that a manifest conversion preserved it.

Operational signals: A successful deployment is not the same as a successful migration. Compare latency, error rates, backend health, certificate alerts, reload behavior, and controller logs before and after the change.

Common mistakes

• Converting YAML mechanically. A field-by-field rewrite can miss annotations that carry important production behavior.
• Assuming every controller supports every feature. Gateway API defines a model, but implementation coverage and feature maturity can differ.
• Changing the controller and API at the same time. Separate infrastructure changes from route-model changes when possible so failures are easier to isolate.
• Ignoring ownership. Shared Gateways require explicit rules for who can create listeners, attach routes, manage certificates, and approve cross-namespace references.
• Testing only a healthy request. Include redirects, authentication failures, unavailable backends, large headers, long requests, and certificate problems relevant to your service.
• Deleting Ingress too early. Preserve the original configuration until the new route has passed its monitoring period and rollback criteria are understood.
• Confusing API compatibility with application compatibility. A resource can be accepted by the cluster while the application still experiences changed headers, timeouts, redirects, or client behavior.

When to revisit

Review the decision before a Kubernetes upgrade, an ingress-controller replacement, a major Gateway API release, or a platform standardization project. Revisit it when a team adds complex routing, adopts multi-namespace application ownership, introduces new security policies, or finds that annotations are becoming a maintenance burden.

A practical quarterly review can use the same inventory created for migration. Remove unused routes, identify controller-specific settings, check the current compatibility matrix, and select one route for a fresh validation test. Also review whether logs, metrics, certificates, and rollback procedures still work as documented.

For a safe next step, choose one low-risk representative service, capture its current behavior, verify the target controller's supported features, and create a reversible Gateway API version. Treat the result as an evidence-gathering exercise—not a commitment to migrate everything. If the new route improves ownership and maintainability without losing required behavior, expand by route class. If it does not, keeping Ingress while documenting the decision is the more disciplined outcome.