Migrate to Gateway API

This guide walks you through migrating Valohai Deployments from the NGINX Ingress Controller to the Kubernetes Gateway API.

---

Prerequisites

• Access to your Kubernetes cluster with sufficient permissions

• kubectl configured and pointing at the correct cluster

• Existing Valohai Deployments running via NGINX Ingress Controller

---

Step 1 — Install Gateway API Resource Definitions

Install the standard channel Gateway API CRDs from the official Gateway API repository.

This introduces core Kubernetes objects including Gateway and HTTPRoute, which form the foundation of the new routing setup.

kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.4.0/standard-install.yaml

Note: v1.4.0 is the latest stable release at the time of writing. Always check the Gateway API releases page for the most current version before installing.

Note: Make sure the Gateway API version you install is compatible with your chosen Gateway controller (Step 2). Most controllers document which Gateway API versions they support in their own release notes or compatibility matrix.

Verify the installation by checking that the CRDs are present:

kubectl get crd gateways.gateway.networking.k8s.io httproutes.gateway.networking.k8s.io

---

Step 2 — Select and Install a Gateway Controller

A Gateway controller is a concrete implementation of the Gateway API interface. Choose a controller that fits your infrastructure from the official implementations list.

The following are a few example controllers to illustrate the range of available options. Refer to the full implementations list to find the best fit for your infrastructure.

Controller	Notes
Cilium	Good for clusters already using Cilium CNI
Traefik	Lightweight with dynamic configuration and strong Kubernetes integration
Istio	Feature-rich option with service mesh capabilities
Envoy Gateway	CNCF project built on Envoy Proxy, designed specifically for the Gateway API

Follow the installation instructions specific to your chosen controller.

---

Step 3 — Create and Configure a Gateway

Create a Gateway resource that Valohai Deployments will route traffic through. This Gateway acts as the base URL / domain that all Valohai Deployment Endpoints will be hosted under.

Key considerations:

• TLS termination for https:// should be configured on the Gateway itself.

• The exact configuration will depend on your chosen Gateway controller — refer to its documentation.

Example Gateway manifest (adjust for your controller and domain):

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: valohai-gateway
  namespace: valohai
spec:
  gatewayClassName: <your-gateway-class>
  listeners:
    - name: https
      protocol: HTTPS
      port: 443
      tls:
        mode: Terminate
        certificateRefs:
          - kind: Secret
            group: ""
            name: <your-tls-secret>

Important: Note down the Gateway name and namespace — you will need these in later steps.

---

Step 4 — Disable All Valohai Deployments

Temporarily disable all active Valohai Deployments. This causes Valohai to automatically clean up the old NGINX Ingress Controller objects associated with those deployments.

Important: Make a note of which Deployments you disable so you can re-enable them in Step 7.

---

Step 5 — Grant Permissions to Manage Gateway HTTP Routes

Update the Valohai role in your cluster to allow it to manage HTTPRoute resources. Add the following rule to the relevant Role or ClusterRole:

- apiGroups: ["gateway.networking.k8s.io"]
  resources: ["httproutes"]
  verbs: ["create", "delete", "deletecollection", "get", "list", "patch", "update", "watch"]

Apply the updated role with kubectl apply or patch it directly:

kubectl edit clusterrole <valohai-role-name>

---

Step 6 — Inform Valohai Support

Before re-enabling your deployments, contact Valohai support so they can update the configuration on their end. Please provide the following:

• Gateway name — the name of the Gateway resource created in Step 3

• Gateway namespace — the namespace the Gateway was created in

• Base URL scheme — whether the new base URL should use https:// (TLS) or http:// (non-TLS)

Wait for confirmation from Valohai support before proceeding to the next step.

Step 7 — Re-enable Valohai Deployments

Re-enable all the Valohai Deployments you disabled in Step 4. Valohai will now create HTTPRoute objects instead of Ingress objects, routing traffic through the Gateway configured in Step 3.

Verify that the HTTPRoute resources have been created:

bash

kubectl get httproutes -n <valohai-namespace>

Confirm your Deployment Endpoints are accessible and responding as expected before proceeding.

---

Step 8 — Remove the NGINX Ingress Controller (Optional)

Once you have verified that all Valohai Deployments are working correctly through the Gateway API, you can remove the NGINX Ingress Controller from the cluster.

⚠️ Before removing NGINX, confirm that there are no non-Valohai Ingress objects still in use:

bash

kubectl get ingress --all-namespaces

Any remaining Ingress objects outside of Valohai Deployments must be migrated or accounted for before uninstalling NGINX.

---

Summary

Step	Action
1	Install Gateway API CRDs
2	Install a Gateway controller
3	Create a Gateway and note its name/namespace
4	Disable Valohai Deployments (note which ones)
5	Add httproutes RBAC permissions to the Valohai role
6	Contact Valohai support with Gateway name, namespace, and base URL scheme
7	Re-enable Valohai Deployments
8	Remove NGINX Ingress Controller (after verification)