Gateway API v1.6 and Ingress2Gateway v1.2: A Migration Guide for Platform Teams

Key Takeaways

• Gateway API v1.6.0 was released at the end of June 2026, and the Kubernetes project published its release overview on August 3.
• The central v1.6 change is the graduation of TCPRoute and UDPRoute to the Standard channel and v1 API. Their v1alpha2 versions are deprecated.
• Gateway API v1.6 also establishes a clearer boundary for new experimental resources through the gateway.networking.x-k8s.io group and X-prefixed kinds.
• Ingress2Gateway 1.0 was announced on March 20, 2026, and v1.2.0 was tagged on July 7. The tool accelerates conversion, but its output still requires human review and implementation-specific testing.
• Before rollout, verify that the selected Gateway API controller supports the v1.6 resources and conformance profiles your migration needs. Upstream API stability does not guarantee controller support.

Two Milestones, One Migration Decision

Gateway API and Ingress2Gateway address different parts of the Kubernetes networking transition.

Gateway API defines role-oriented Kubernetes resources for infrastructure and application routing. Ingress2Gateway reads existing Ingress resources and provider-specific configuration, then generates Gateway API resources while reporting behavior it cannot translate. One project improves the target contract; the other reduces the work required to reach it.

They are relevant together, but the release history matters:

For platform teams, these milestones make it practical to ask whether they can create a safer, testable path from accumulated Ingress behavior to a controller-supported Gateway API contract.

What Gateway API v1.6 Actually Changes

The Gateway API v1.6.0 release notes contain many validation, conformance, and documentation changes. Two themes are especially important for platform teams.

TCPRoute and UDPRoute Graduate to Standard

TCPRoute and UDPRoute now use the Standard channel and the gateway.networking.k8s.io/v1 API. Their earlier v1alpha2 forms are deprecated and will be removed in a future release.

This gives platform teams a stable Kubernetes API for raw layer 4 traffic such as databases, DNS, VoIP, gaming, and IoT protocols. It also expands the migration conversation beyond HTTP Ingress. A platform can use the same role-oriented model for HTTP, gRPC, TLS, TCP, and UDP traffic, subject to controller support.

The qualification is critical. A v1 resource in the upstream specification is not useful if the installed controller does not reconcile that resource or does not support the fields your workload uses.

Experimental APIs Move Behind a Clearer Boundary

The Kubernetes release overview explains the new direction for experimental resources. New experimental kinds use the gateway.networking.x-k8s.io group and an X prefix, such as XBackend or XMesh. When a resource graduates, it moves to the standard API group and drops the prefix.

This separation makes risk visible in manifests and admission policy. Platform teams can allow Standard resources broadly while restricting experimental CRDs to controlled clusters. It also reduces the chance that users interpret an alpha version in the standard group as almost stable.

Do not treat the experimental channel as a compatibility promise. Pin the Gateway API CRD release, record which experimental kinds are installed, and plan explicit cleanup or conversion when those kinds change.

Smaller Changes Still Affect Validation

The v1.6 release also tightens validation for HTTPRoute retries, increases several reference and object limits, extends BackendTLSPolicy use to more route types, and adds TCP/UDP conformance coverage. These changes can affect CI even when a migration focuses on HTTP traffic.

Validate representative manifests against the exact v1.6 CRDs before installing them in production. Schema acceptance is only the first step; the Kubernetes API server, etcd, admission policy, and controller must also handle the selected resource sizes and fields.

What Ingress2Gateway v1.2 Contributes

The Ingress2Gateway 1.0 announcement describes the tool as an assistant. It translates Ingress resources and implementation-specific annotations, warns about configuration it cannot translate, and provides suggestions for the remaining work.

That is the right mental model. Ingress2Gateway is not a controller and does not change live traffic. It produces candidate Gateway API resources for review.

The Ingress2Gateway release list shows that v1.2.0 was tagged on July 7, 2026. Version 1.1 added provider conversions such as Traefik support and more ingress-nginx and GCE behavior. Version 1.2 added an Airlock Microgateway emitter and fixed a regex-rewrite warning.

Use the current release for its accumulated provider and bug-fix coverage, but do not infer that it generates or validates every Gateway API v1.6 feature. Check the generated apiVersion values, tool notifications, and the support matrix of the destination controller.

For an initial inventory in the current Kubernetes context and namespace, the documented command is:

ingress2gateway print --providers=ingress-nginx

The command reads cluster credentials from the active context and prints generated resources. Run it first in a non-production context or against exported manifests. Save both the output and warnings as migration evidence; a clean YAML file without its conversion notifications is incomplete.

Gateway API Defines Intent; the Controller Implements It

Gateway API separates responsibilities through several resources:

• GatewayClass identifies the controller responsible for a class of gateways.
• Gateway describes listeners and the requested network entry point.
• HTTPRoute, GRPCRoute, TLSRoute, TCPRoute, and UDPRoute express application routing intent.
• Policy resources and implementation extensions attach behavior that is not part of core route matching.

This model is more explicit than packing infrastructure, routing, TLS, and controller-specific behavior into one Ingress object and a collection of annotations. It does not eliminate implementation differences.

Before adopting v1.6, record:

• the controller and version that owns each GatewayClass,
• the Gateway API CRD version installed in the cluster,
• supported resource kinds and API versions,
• supported Core, Extended, and implementation-specific fields,
• relevant conformance profiles and test results,
• and the extension policies needed to replace old annotations.

The Gateway API project publishes implementation and conformance information, but production acceptance should be based on the exact controller build you deploy. A conformance report for one profile does not imply support for every route type or experimental field.

A Seven-Step Migration Workflow

1. Inventory Resources and Providers

List Ingress classes, controllers, annotations, ConfigMaps, certificates, external load balancer settings, and provider-specific CRDs. Group workloads by controller and business owner. An annotation that appears unused may still encode a production dependency.

2. Choose the Destination Controller First

Select the controller and gateway runtime before converting manifests. Review its Gateway API support table, required CRDs, extension policies, and conformance reports. If TCP or UDP routing is required, confirm support for the v1 forms introduced by Gateway API v1.6 rather than assuming that older v1alpha2 support is equivalent.

3. Pin the Migration Tool and API Versions

Record the Ingress2Gateway version, Gateway API CRD version, controller version, and source manifests used for each conversion batch. This makes output review reproducible and prevents a tool upgrade from silently changing generated resources halfway through the program.

4. Generate Candidate Resources Outside Production

Run Ingress2Gateway against exported manifests or a controlled cluster context. Store generated resources separately from the source. Treat warnings, unsupported annotations, and ambiguous mappings as work items rather than suppressing them.

5. Separate Routing from Runtime Policy

Decide which behavior belongs in Standard Gateway API resources and which requires controller policy or gateway plugins. Host and path matching may map cleanly to HTTPRoute; authentication, advanced rate limiting, request transformations, retries, and observability may require policy attachments or implementation-specific extensions.

Do not replace an annotation with a similarly named field without comparing failure behavior, precedence, defaults, and status reporting.

6. Test Reconciliation and Live Behavior

Apply the candidate resources in staging and inspect their status conditions. Confirm that the intended controller accepts each parent reference and programs the routes. Then test DNS, TLS, redirects, path rewrites, headers, authentication, rate limits, gRPC or streaming behavior, and backend failure modes.

Schema validation proves only that Kubernetes accepted the object. Request tests prove whether the controller and gateway produced the intended behavior.

7. Roll Out with Ownership and Rollback

Migrate a bounded domain or application group first. Keep a rollback path to the previous Ingress configuration, avoid two controllers claiming the same traffic unintentionally, and compare route incidents, configuration drift, rollout time, and debugging time before expanding the migration.

Where Apache APISIX Fits

Gateway API is a Kubernetes configuration contract. A gateway runtime still processes traffic and enforces authentication, rate limits, transformations, observability, and upstream policy.

APISIX Ingress Controller translates Gateway API, Kubernetes Ingress, or APISIX custom resources into Apache APISIX configuration. Its Gateway API support table lists support by resource, field category, and API version. That table should be checked for the exact release being deployed.

This is especially important for v1.6 migration planning. The upstream promotion of TCPRoute and UDPRoute to v1 does not automatically upgrade an installed APISIX Ingress Controller or any other implementation. If the support table lists an older API version or a field as partial or unsupported, keep that workload out of the migration batch or select a supported alternative.

API7.ai has previously covered the role model in A Quick Glance at the Kubernetes Gateway API. The additional decision now is how to pair that model with verified controller support and a disciplined conversion workflow.

Conclusion

Gateway API v1.6.0 gives platform teams a stronger Standard API for layer 4 routing and a clearer boundary for experimental resources. Ingress2Gateway v1.2.0 gives them a current migration assistant with broader provider coverage than the original 1.0 release.

Neither removes the need for engineering review. Generated manifests must be checked against the selected controller, its conformance profiles, extension policies, and live gateway behavior. The safest adoption path is to pin versions, convert a bounded workload, preserve tool warnings, test request behavior, and expand only after operational evidence is positive.

Teams using Apache APISIX can start with the APISIX Ingress Controller Gateway API documentation, compare its support matrix with their required v1.6 resources, and use Ingress2Gateway as a first draft rather than an autopilot.