Gateway API
Gateway API is the recommended path for new vCluster endpoint and tenant routing deployments. It provides a Kubernetes-native model for shared traffic infrastructure, explicit route attachment, and controller-owned status conditions.
vCluster uses Gateway API in two main ways:
- Expose the tenant cluster API server with a
TLSRoute. - Sync tenant workload routes, such as
HTTPRouteresources, to the Control Plane Cluster.
vCluster Platform also uses Gateway API for Gateway-backed endpoint and auto sleep workflows. These workflows require Gateway API CRDs and a compatible controller on the connected Control Plane Cluster.
Relationship to ingress-nginx​
The upstream ingress-nginx project is deprecated. Existing ingress-based vCluster and Platform configurations continue to work in vCluster v0.35 and vCluster Platform v4.10, but Gateway API is the forward path for new deployments.
There is no automatic ingress-to-Gateway migration in vCluster v0.35 or Platform v4.10. Plan the move explicitly: keep existing ingress configurations in place, validate a Gateway controller, create a test tenant cluster with Gateway-backed endpoints, and then migrate selected workloads.
For a step-by-step adoption path, see Migrate from ingress-nginx to Gateway API.
Gateway API uses in vCluster​
| Use case | Gateway API resource | Where to configure |
|---|---|---|
| Expose the tenant cluster API server with TLS passthrough | TLSRoute | Access and expose vCluster |
| Let tenants publish HTTP workloads through a Gateway controller in the Control Plane Cluster | HTTPRoute | Gateway API sync |
| Let tenants create their own Gateway resources | Gateway | Gateway API sync |
| Let tenants attach routes to an admin-approved shared Gateway | Imported Gateway and GatewayClass | Imported Gateways and GatewayClasses |
| Wake sleeping tenant clusters through HTTP traffic | HTTPRoute with RequestMirror support | Auto Sleep |
Prerequisites​
Before adopting Gateway API, verify:
- Gateway API CRDs are installed on the Control Plane Cluster.
- A Gateway API-compatible controller is installed and healthy.
- At least one
GatewayClassis available for the controller you plan to use. - DNS and certificates are planned for the Gateway listener hostnames.
- The selected controller supports the route kinds you need, such as
TLSRoutefor tenant cluster API server exposure andHTTPRoutefor application traffic. - If you need Gateway-backed auto sleep, the selected controller supports
HTTPRouterequest mirroring or is explicitly allowed by Platform configuration.
Gateway API support is controller-specific. A controller can support Gateway endpoints without supporting every feature needed for auto sleep wakeup.
Use shared gateways for tenancy​
Platform teams often want a small number of administrator-owned Gateways and many tenant-owned Routes. In that model, administrators create and operate the Gateway in the Control Plane Cluster. vCluster then imports a read-only representation into tenant clusters.
Tenants attach HTTPRoute resources to that approved Gateway instead of creating their own Gateway.
Use this model when DNS, certificates, listener policy, and infrastructure ownership should stay with the platform team. Use tenant-created Gateways when the tenant is allowed to own Gateway lifecycle and the controller supports that operating model.
For the configuration model, see Imported Gateways and GatewayClasses.
Validate routes​
Use these checks when validating a Gateway API rollout:
kubectl get crd gatewayclasses.gateway.networking.k8s.io gateways.gateway.networking.k8s.io httproutes.gateway.networking.k8s.io
kubectl get gatewayclass
kubectl describe gatewayclass my-gateway-class
kubectl get httproute,tlsroute -A
kubectl describe httproute my-route -n my-namespace
kubectl describe tlsroute my-route -n my-namespace
Look for accepted and programmed status conditions on Routes. If a Route is not accepted, check the referenced Gateway, Gateway listener settings, route kind support, cross-namespace attachment policy, and any required ReferenceGrant resources.