Migrate to Gateway API
Migrate ZenML Helm deployments from Ingress to Kubernetes Gateway API.
Gateway API is the Kubernetes networking successor to the legacy Ingress model. If you currently expose ZenML through server.ingress, this guide shows how to migrate to server.gateway with minimal downtime.
Why migrate
Gateway API is the long-term Kubernetes direction for north-south traffic.
It provides clearer separation between shared infrastructure ownership (
Gateway) and app routing ownership (HTTPRoute).It maps well to multi-tenant environments where platform teams manage shared gateways and application teams manage routes.
Prerequisites
Kubernetes 1.26+
A Gateway API implementation with
v1CRDs available (for example,gateway.networking.k8s.io/v1forGatewayandHTTPRoute; Envoy Gateway, Istio, NGINX Gateway Fabric, GKE Gateway)A
Gatewayresource already provisioned and reachable using the installed Gateway APIv1CRDsDNS access for cutover planning
ZenML renders
HTTPRouteresources withapiVersion: gateway.networking.k8s.io/v1. Clusters that only have older Gateway API CRDs installed (for example,v1beta1) must upgrade those CRDs before enablingserver.gateway.
Migration overview
Install or verify your Gateway API implementation.
Create a shared
Gateway(platform-managed).Enable
server.gatewayin ZenML Helm values (alongside existingserver.ingressfor zero-downtime migration).Deploy and verify
HTTPRoutestatus and application health.Perform DNS cutover (if using a new load balancer).
Disable
server.ingressafter stabilization.
Helm values migration
Step 1: Enable both (parallel period)
Both server.ingress.enabled and server.gateway.enabled can be true simultaneously. The chart renders both an Ingress and an HTTPRoute. Kubernetes controllers only act on resources they own — an ingress controller ignores HTTPRoutes and a Gateway controller ignores Ingresses — so enabling both creates no conflict.
At this point, traffic still flows through the ingress controller (DNS points to its load balancer). The HTTPRoute is ready on the Gateway side but idle.
Step 2: DNS cutover
Update DNS to point to the Gateway's load balancer. Both the Ingress and HTTPRoute exist, so the transition is seamless — the ingress controller handles traffic until DNS propagates, then the Gateway takes over.
Step 3: Disable Ingress (cleanup)
After DNS is stable and traffic is flowing through the Gateway, disable Ingress:
Gateway implementation examples
Envoy Gateway
Use a shared GatewayClass and Gateway, then attach ZenML HTTPRoute resources via parentRefs.
Istio
Use Istio's Gateway API support (managed Gateway + HTTPRoute) and keep ZenML route ownership in tenant namespaces.
NGINX Gateway Fabric
Deploy NGINX Gateway Fabric and configure a shared Gateway listener; point ZenML gatewayRef to that shared gateway.
GKE Gateway
Create a GKE-managed Gateway and map your external DNS hostnames to the provisioned load balancer.
Custom annotations
You can add custom annotations to the HTTPRoute resource:
This is useful for attaching Envoy-specific policies, adding metadata for service mesh integration, or custom routing labels.
TLS options
You can terminate TLS in one of two common ways:
Gateway-managed TLS (e.g. cert-manager certificate references in gateway listeners)
Cloud load balancer TLS termination (e.g. ACM on AWS NLB) with HTTP forwarded to Gateway listeners
Choose the model that matches your platform standards. ZenML only needs the correct external hostname and reachable Gateway listener.
Validation checklist
kubectl get gateway -Ashows the target gateway as accepted/programmedkubectl get httproute -Ashows ZenML routes attached/acceptedcurl https://<zenml-host>/healthreturns successOptional: test large uploads and UI/API login flows
DNS cutover
If migration introduces a new load balancer:
Lower DNS TTL (for example 60s) before cutover.
Update CNAME/A records to the new load balancer.
Monitor health, latency, and error rate.
Restore normal TTL after stabilization.
Rollback
Since both Ingress and Gateway can be enabled simultaneously, rollback during the parallel period is simply a DNS change — point DNS back to the ingress controller's load balancer. No Helm changes needed.
If you've already disabled Ingress (Step 3), re-enable it:
Re-deploy, repoint DNS to the ingress controller's load balancer, and verify /health and login.
Keep both infrastructure paths available during stabilization to ensure a low-risk rollback.
Last updated
Was this helpful?