Migrate from kgateway OSS

Seamlessly migrate your OSS kgateway proxies to the Solo Enterprise for kgateway control plane without downtime so that you can start using enterprise features, such as Portal, staged transformations, Web Application Firewall (WAF), and built-in extauth and rate limiting servers.

Migration approach

Solo Enterprise for kgateway builds on the open-source kgateway project to provide enterprise functionality for your API gateway. Because Solo Enterprise for kgateway uses a different GatewayClass controller (solo.io/enterprise-kgateway) than kgateway (kgateway.dev/kgateway), the control plane migration always follows a canary approach. You run the enterprise control plane alongside the open source control plane until all proxies are migrated. This design prevents controller conflicts when both control planes are deployed simultaneously and enables a clean, predictable handoff.

To migrate the gateway proxies, you can choose between the following update strategies:

Strategy	Summary	Best for
In-place update	Change the `gatewayClassName` on existing Gateway resources to the enterprise GatewayClass. The enterprise control plane takes over the management of the gateway and performs a rolling update of the proxy pod with zero downtime. No changes to routes or services are required.	Teams that want a simple cut-over with minimal resource overhead.
Canary deployment	Create new Solo Enterprise for kgateway Gateway resources alongside the existing open source Gateways. Update all your routes to target both gateways. Then, validate and shift all traffic to the enterprise gateway proxies and remove the open source proxies from your routes.	Teams that need side-by-side testing or an explicit rollback point before migrating.

The following diagrams show what each step of the migration looks like.

Overview step 1: Initial state

In the initial state, you have an existing kgateway installation in your cluster and one or more kgateway proxies that serve the traffic for your apps. The proxy is managed by the kgateway control plane.

    flowchart LR
    User["👤 User"]:::external

    subgraph cluster["Kubernetes Cluster"]
        KCP["kgateway <br/>control plane"]:::cp
        GP["kgateway proxy"]:::dp
        httpbin["httpbin"]:::dp

        KCP -.->|manages| GP
        GP --> httpbin
    end

    User -->|traffic| GP

    classDef external stroke:#6B7280
    classDef cp stroke:#2986CC
    classDef dp stroke:#16a34a

Overview step 2: Install Solo Enterprise for kgateway

You install the Solo Enterprise for kgateway control plane alongside kgateway. The Solo Enterprise for kgateway CRDs are a superset of the kgateway CRDs. Because of that, you must install the Helm chart for the enterprise CRDs in the same namespace and with the same Helm installation name as your kgateway CRD Helm chart to avoid Helm CRD conflicts. However, you can install the enterprise control plane Helm chart in the namespace of your choice.

    flowchart LR
    User["👤 User"]:::external

    subgraph cluster["Kubernetes Cluster"]
        ECP["Solo Enterprise for kgateway<br/>control plane"]:::ent
        KCP["kgateway <br/>control plane"]:::cp
        GP["kgateway proxy"]:::dp
        httpbin["httpbin"]:::dp

        KCP -.->|manages| GP
        GP --> httpbin
        KCP ~~~ ECP
    end

    User -->|traffic| GP

    classDef external stroke:#6B7280
    classDef cp stroke:#2986CC
    classDef dp stroke:#16a34a
    classDef ent fill:#FEF3E2,stroke:#E69138,color:#1a1a1a

Overview step 3: Migrate proxies

When you are ready to migrate, choose the data plane strategy that best fits your requirements.

    flowchart LR
    User["👤 User"]:::external

    subgraph cluster["Kubernetes Cluster"]
        KCP["kgateway <br/>control plane"]:::cp
        ECP["Solo Enterprise for kgateway<br/>control plane"]:::ent
        GP["kgateway proxy"]:::dp
        httpbin["httpbin"]:::dp

        ECP -.->|manages| GP
        GP --> httpbin
        ECP ~~~ KCP
    end

    User -->|traffic| GP

    classDef external stroke:#6B7280
    classDef cp stroke:#2986CC
    classDef dp stroke:#16a34a
    classDef ent fill:#FEF3E2,stroke:#E69138,color:#1a1a1a

Overview step 4: Uninstall kgateway

When all proxies are migrated and served by the Solo Enterprise for kgateway control plane, you can remove the open source control plane from your cluster.

    flowchart LR
    User["👤 User"]:::external

    subgraph cluster["Kubernetes Cluster"]
        ECP["Solo Enterprise for kgateway<br/>control plane"]:::ent
        GP["kgateway proxy"]:::dp
        httpbin["httpbin"]:::dp

        ECP -.->|manages| GP
        GP --> httpbin
    end

    User -->|traffic| GP

    classDef external stroke:#6B7280
    classDef cp stroke:#2986CC
    classDef dp stroke:#16a34a
    classDef ent fill:#FEF3E2,stroke:#E69138,color:#1a1a1a

Migrate to Solo Enterprise for kgateway

Perform a sample migration of kgateway proxies to Solo Enterprise for kgateway.

Before you begin

This guide assumes that you have an existing installation of the kgateway open source project and the httpbin sample app.

As a reference, you can follow these kgateway open source guides:

Step 1: Install Solo Enterprise for kgateway

Set your Solo Enterprise for kgateway license key as an environment variable. If you do not have one, contact an account representative.
```
export LICENSE_KEY=<license-key>
```
Install the Solo Enterprise for kgateway CRDs. The following command uses version 2.2.6. The Solo Enterprise for kgateway CRDs are a superset of the kgateway OSS CRDs. To avoid CRD conflicts, you install the enterprise CRD Helm chart with the same name and in the same namespace as the open source CRDs.
The CRD Helm installation name must be kgateway-crds and the namespace must be kgateway-system. These values must match your existing kgateway CRD installation. Using different values causes Helm to treat the CRDs as a separate release and creates conflicts.
```
helm upgrade -i enterprise-kgateway-crds oci://us-docker.pkg.dev/solo-public/enterprise-kgateway/charts/enterprise-kgateway-crds \
--create-namespace \
--namespace kgateway-system \
--version 2.2.6 
```

Install Solo Enterprise for kgateway by using Helm.

helm upgrade -i enterprise-kgateway oci://us-docker.pkg.dev/solo-public/enterprise-kgateway/charts/enterprise-kgateway \
  -n kgateway-system \
  --version 2.2.6 \
  --set licensing.licenseKey=$LICENSE_KEY

Make sure that the enterprise-kgateway control plane is running.
```
kubectl get pods -n kgateway-system
```
Example output:
```
NAME                                             READY   STATUS    RESTARTS   AGE
enterprise-kgateway-5495d98459-46dpk             1/1     Running   0          19s
kgateway-659c56576c-fvzzw                        1/1     Running   0          5m20s
```
At this point, two control planes are running simultaneously. This is expected. Because each control plane uses a distinct GatewayClass controller name (kgateway.dev/kgateway for kgateway OSS and solo.io/enterprise-kgateway for Solo Enterprise for kgateway), they cannot accidentally reconcile each other’s resources or cause configuration conflicts.

Step 2: Migrate proxies

Choose the data plane migration strategy that best fits your requirements. The Solo Enterprise for kgateway control plane runs alongside the kgateway OSS control plane throughout this step.

This option updates your existing Gateway resources to use the enterprise-kgateway GatewayClass. The Solo Enterprise for kgateway control plane takes over management of these proxies and uses a rolling update strategy when adopting Gateways. The old proxy continues to serve traffic until the new proxy is fully ready, ensuring zero downtime. No changes to routes, services, or DNS are required.

Create a curl pod that continuously sends requests to the httpbin app. If a request fails and does not return a 200 HTTP response code, the message ALERT: dropped request, got HTTP $status is logged. You use this curl pod to verify that the migration of your gateway proxies finished without any disruption for your app.

kubectl run curl-test -it --rm --image=curlimages/curl --restart=Never -- \
  sh -c '
  while true; do
    status=$(curl -s -o /dev/null -w "%{http_code}" http://http.kgateway-system.svc.cluster.local:8080/headers -H "host: www.example.com")
    if [ "$status" != "200" ]; then
      echo "ALERT: dropped request, got HTTP $status"
    fi
    sleep 0.25
  done
'

Example output:

All commands and output from this session will be recorded in container logs, including credentials and sensitive information passed through the command prompt.
If you don't see a command prompt, try pressing enter.

Update the GatewayClass for your Gateway resources to point to the Solo Enterprise for kgateway control plane by changing the kgateway GatewayClass to enterprise-kgateway.

Example command to update a single Gateway:

kubectl patch gateway http -n kgateway-system --type=merge -p '{"spec":{"gatewayClassName":"enterprise-kgateway"}}'

Example command to update all kgateway Gateways at once:

kubectl get gateways --all-namespaces -o json \
  | jq -r '.items[] | select(.spec.gatewayClassName=="kgateway") | [.metadata.namespace, .metadata.name] | @tsv' \
  | while IFS=$'\t' read -r ns name; do
      kubectl patch gateway "$name" -n "$ns" --type=merge -p '{"spec":{"gatewayClassName":"enterprise-kgateway"}}'
    done

Monitor the rollout of the new gateway proxy pods. Verify that a new gateway proxy pod is deployed while the old one is being terminated.

kubectl get pods -n kgateway-system

Example output:

NAME                                  READY   STATUS        RESTARTS   AGE
http-65c76c754c-vvbbd                 1/1     Running       0          24s
http-78f5744788-7z58j                 1/1     Terminating   0          78m
kgateway-6c959579f6-d757w             1/1     Running       0          98m
enterprise-kgateway-5495d98459-46dpk  1/1     Running       0          50m

Verify that no requests were dropped during the rollout. If a request was dropped, you see an ALERT: dropped request, got HTTP 503 message in the CLI output of the curl pod that you deployed earlier.

This option creates new Solo Enterprise for kgateway Gateway resources alongside your existing kgateway open source Gateways. You route traffic to both gateway proxies simultaneously. During this time, you validate the enterprise Gateways. After successful validation, you remove the kgateway open source Gateways. Use this option when you need side-by-side comparison or an explicit rollback point before cutting over completely.

Because the new enterprise Gateways are separate resources, they receive new IP addresses or hostnames. Update your DNS records or load balancer configuration to route traffic to the new addresses before removing the old Gateways. This approach also requires duplicate Gateway resources and route updates while both are live.

Create a new Gateway resource that uses the enterprise-kgateway GatewayClass.

kubectl apply -f - <<EOF
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: enterprise-gateway
  namespace: kgateway-system
spec:
  gatewayClassName: enterprise-kgateway
  listeners:
  - name: http
    port: 80
    protocol: HTTP
    allowedRoutes:
      namespaces:
        from: Same
EOF

Update your HTTPRoutes to reference both the original kgateway Gateway and the new enterprise Gateway. This way, you allow live traffic to flow through both Gateways simultaneously so you can compare behavior before committing. The following example updates the httpbin route.

kubectl apply -f - <<EOF
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: httpbin
  namespace: httpbin
spec:
  parentRefs:
  - name: http              # Original kgateway Gateway
    namespace: kgateway-system
  - name: enterprise-gateway   # Enterprise Gateway
    namespace: kgateway-system
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /
    backendRefs:
    - name: httpbin
      port: 8000
EOF

Send test traffic to the enterprise Gateway to validate its behavior.

Cloud Provider LoadBalancer address:

export INGRESS_GW_ADDRESS=$(kubectl get svc -n kgateway-system enterprise-gateway -o jsonpath="{.status.loadBalancer.ingress[0]['hostname','ip']}")
echo $INGRESS_GW_ADDRESS

curl -i http://$INGRESS_GW_ADDRESS/headers -H "host: www.example.com"

Port forward for local testing:

kubectl port-forward svc/enterprise-gateway 8081:80 -n kgateway-system

curl -i http://localhost:8081/headers -H "host: www.example.com"

When validation is complete, update your routes to reference only the enterprise Gateway.

kubectl apply -f - <<EOF
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: httpbin
  namespace: httpbin
spec:
  parentRefs:
  - name: enterprise-gateway
    namespace: kgateway-system
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /
    backendRefs:
    - name: httpbin
      port: 8000
EOF

Delete the original open source Gateway.

kubectl delete gateway http -n kgateway-system

Step 3: Uninstall kgateway OSS

Now that you finished the migration of your gateway proxies, you can uninstall the upstream kgateway control plane.

helm uninstall kgateway

Do not remove the upstream kgateway-crds Helm chart or the kgateway-system namespace from your environment. These components are required by Solo Enterprise for kgateway to properly translate and manage your gateway proxies.

Congratulations, you successfully migrated your gateway proxies to Solo Enterprise for kgateway.

Next: Enable enterprise features

All existing kgateway OSS resources continue to work unchanged after your migration. You do not need to update any configuration immediately. Instead, you can adopt enterprise features incrementally.

The following table shows the enterprise CRDs that you can adopt and the features that these introduce.

OSS resource	Enterprise equivalent	Notes	Docs
`TrafficPolicy` (`gateway.kgateway.dev/v1alpha1`)	`EnterpriseKgatewayTrafficPolicy`	The enterprise policy is a superset of `TrafficPolicy`. It includes all OSS fields plus fields for external auth, JWT, WAF, staged transformations, and global rate limiting. Migrate a `TrafficPolicy` to an `EnterpriseKgatewayTrafficPolicy` when you want to add enterprise capabilities to the same route or Gateway.	Traffic policy
n/a	`AuthConfig`	Defines external authentication providers (API key, OIDC, LDAP, OPA, and more). Referenced from an `EnterpriseKgatewayTrafficPolicy`.	External authentication
n/a	`RateLimitConfig`	Defines global rate limiting policies enforced by the enterprise rate limiter. Referenced from an `EnterpriseKgatewayTrafficPolicy`.	Rate limiting
n/a	`Portal`, `ApiDoc`, `ApiProduct`	Developer portal resources for publishing and managing APIs.	Developer portal

Install in air-gapped environments TLS encryption

Was this page helpful?