Skip to main content
Version: main 🚧

Migrate from ingress-nginx to Gateway API

Supported Configurations
Running the control plane as a container with:

Gateway API is the recommended path for new vCluster endpoint and tenant routing deployments. Existing ingress-based configurations continue to work in vCluster v0.35 and vCluster Platform v4.10, but ingress-nginx is deprecated upstream and should not be the default choice for new rollouts.

Migration is explicit. vCluster does not automatically convert existing Ingress resources, Platform ingress access settings, or ingress-nginx annotations to Gateway API resources.

Before you migrate​

Validate the Gateway API foundation on the Control Plane Cluster:

  • Gateway API CRDs are installed.
  • A supported Gateway API controller is installed and healthy.
  • At least one GatewayClass is visible.
  • A Gateway exists for the listener and protocol you need.
  • DNS points to the Gateway infrastructure.
  • Certificate ownership and TLS termination or passthrough behavior are clear.
  • Cross-namespace attachment rules and ReferenceGrant resources are planned.

For tenant cluster API server exposure, verify that your controller supports TLSRoute and TLS passthrough. For workload HTTP routing and Gateway-backed auto sleep, verify HTTPRoute support.

For Gateway-backed auto sleep wakeup, also verify request mirroring support.

  1. Keep existing ingress configurations running.
  2. Install Gateway API CRDs and the selected Gateway controller in a non-production Control Plane Cluster.
  3. Create or select a GatewayClass and Gateway that match the intended production model.
  4. Create a test tenant cluster with a Gateway-backed TLSRoute endpoint.
  5. Enable Gateway API sync for selected test workloads and validate HTTPRoute behavior.
  6. Test auto sleep and wakeup if the workload depends on Gateway-backed activity detection.
  7. Migrate one tenant or workload group at a time.
  8. Keep ingress fallback available until DNS, certificates, route status, and wakeup behavior are verified.

What to check​

Before moving production traffic, confirm:

  • Tenant cluster API access works through the Gateway-backed endpoint.
  • TLSRoute and HTTPRoute resources show accepted and programmed status conditions.
  • The selected controller supports the Gateway API resources and filters you use.
  • Gateway-backed auto sleep works only when the controller supports HTTPRoute request mirroring.
  • Tenants cannot attach routes to Gateways they should not use.
  • Shared-node tenants use approved shared Gateways or constrained tenant-created Gateways.
  • Private nodes, standalone clusters, or externally managed control plane clusters have a clear endpoint and Gateway ownership model.

Compatibility caveats​

Gateway API support varies by controller. A controller can accept HTTPRoute resources and serve traffic while still lacking request mirroring support for Gateway-backed auto sleep.

In that case, Gateway endpoints can still be usable, but automatic wakeup from HTTP traffic is not available through that controller.

If Gateway API CRDs are installed after vCluster Platform is already running, restart Platform so it discovers the new resource types and starts Gateway API sleep-mode controllers:

Restart vCluster Platform
kubectl rollout restart deployment/loft -n vcluster-platform

If your Platform release or namespace name differs, adjust the deployment and namespace.

Fallback strategy​

During the deprecation window, you can keep existing ingress-based access while you validate Gateway API. Do not delete ingress resources, DNS records, or ingress-nginx controller configuration until Gateway status, endpoint reachability, certificate behavior, and sleep/wakeup behavior are all confirmed.

For new deployments, prefer Gateway API. For the vCluster API server endpoint example, see Access and expose vCluster.