# 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](https://gateway-api.sigs.k8s.io/guides/getting-started/#install-standard-channel).

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

```bash
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](https://github.com/kubernetes-sigs/gateway-api/releases) 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:
>
> ```bash
> 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](https://gateway-api.sigs.k8s.io/implementations/#gateway-controller-implementation-status).

The following are a few example controllers to illustrate the range of available options. Refer to the full [implementations list](https://gateway-api.sigs.k8s.io/implementations/#gateway-controller-implementation-status) to find the best fit for your infrastructure.

| Controller                                                                              | Notes                                                                        |
| --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| [Cilium](https://docs.cilium.io/en/stable/network/servicemesh/gateway-api/gateway-api/) | Good for clusters already using Cilium CNI                                   |
| [Traefik](https://doc.traefik.io/traefik/routing/providers/kubernetes-gateway/)         | Lightweight with dynamic configuration and strong Kubernetes integration     |
| [Istio](https://istio.io/latest/docs/tasks/traffic-management/ingress/gateway-api/)     | Feature-rich option with service mesh capabilities                           |
| [Envoy Gateway](https://gateway.envoyproxy.io/)                                         | 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):

```yaml
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`:

```yaml
- 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:

```bash
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

```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
>
> ```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)                      |