Upgrade

Upgrade the control plane and any gateway proxies that run in your cluster.

Prepare to upgrade

Before you upgrade Solo Enterprise for agentgateway, review the following information.

Review the Solo Enterprise for agentgateway release notes for any breaking changes or new features that you need to be aware of.
Review the upstream agentgateway release notes for any breaking changes or new features that you need to be aware of. You can find the commit of the upstream agentgateway release in the Solo Enterprise for agentgateway release notes that you previously reviewed.

Check the supported version compatibility matrix. If the version of Solo Enterprise for agentgateway that you are upgrading to requires a different version, upgrade those technologies accordingly.

Decide on the Kubernetes Gateway API version that you want to use.
- For help, review the Upgrade Notes in the Kubernetes Gateway API docs for each version.
- Check if you might need to install the experimental channel for the features that you want to use.

Install the custom resources of the Kubernetes Gateway API version that you want to upgrade to, such as the standard version.

Standard channel:

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

Experimental channel: Note that some CRDs are prefixed with X to indicate that the entire CRD is experimental and subject to change.
```
kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.5.0/experimental-install.yaml
```

Example output:

customresourcedefinition.apiextensions.k8s.io/gatewayclasses.gateway.networking.k8s.io created
customresourcedefinition.apiextensions.k8s.io/gateways.gateway.networking.k8s.io created
customresourcedefinition.apiextensions.k8s.io/httproutes.gateway.networking.k8s.io created
customresourcedefinition.apiextensions.k8s.io/referencegrants.gateway.networking.k8s.io created
customresourcedefinition.apiextensions.k8s.io/grpcroutes.gateway.networking.k8s.io created

Check the Kubernetes Gateway API CRDs. Remove any outdated CRDs.

kubectl get crds -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.versions[*].name}{"\t"}{.metadata.annotations.gateway\.networking\.k8s\.io/bundle-version}{"\t"}{.metadata.annotations.gateway\.networking\.k8s\.io/channel}{"\n"}{end}' | grep gateway.networking.k8s.io

Example output:

gatewayclasses.gateway.networking.k8s.io  v1 v1beta1  v1.2.0	experimental
gateways.gateway.networking.k8s.io        v1 v1beta1  v1.2.0	experimental
grpcroutes.gateway.networking.k8s.io      v1          v1.2.0	experimental
httproutes.gateway.networking.k8s.io      v1 v1beta1  v1.2.0	experimental

For Kubernetes upgrades, consult your cloud infrastructure provider.

For Istio upgrades, consult the docs based on the way that you installed Istio. Example providers:

Upgrade

Set the version you want to upgrade to in an environment variable, such as the latest patch version () .
```
export NEW_VERSION=2026.6.3
```

Apply the new CRDs for the control and data plane by using Helm.

Optional: To check the CRDs locally, download the CRDs to a helm directory.

helm template --version v$NEW_VERSION enterprise-agentgateway-crds oci://us-docker.pkg.dev/solo-public/enterprise-agentgateway/charts/enterprise-agentgateway-crds --output-dir ./helm

Upgrade the CRDs in your cluster:

helm upgrade -i --namespace agentgateway-system --version v$NEW_VERSION enterprise-agentgateway-crds oci://us-docker.pkg.dev/solo-public/enterprise-agentgateway/charts/enterprise-agentgateway-crds

Make any changes to your Helm values.
1. Get the Helm values file for your current version.
  helm get values enterprise-agentgateway -n agentgateway-system -o yaml > values.yaml open values.yaml
2. Compare your current Helm chart values with the version that you want to upgrade to.
  helm show values oci://us-docker.pkg.dev/solo-public/enterprise-agentgateway/charts/enterprise-agentgateway --version v$NEW_VERSION
  helm pull oci://us-docker.pkg.dev/solo-public/enterprise-agentgateway/charts/enterprise-agentgateway --version v$NEW_VERSION tar -xvf enterprise-agentgateway-v$NEW_VERSION.tgz open enterprise-agentgateway/values.yaml
3. Make any changes that you want by editing your values.yaml Helm values file or preparing the --set flags. For development v builds, include the controller.image.pullPolicy=Always setting or refer to the exact image digest to avoid using cached images.
Upgrade the Solo Enterprise for agentgateway control plane Helm installation.
- Make sure to include your Helm values when you upgrade either as a configuration file or with --set flags. Otherwise, any previous custom values that you set might be overwritten.
- When using the development build , add the --set controller.image.pullPolicy=Always option to ensure you get the latest image. Alternatively, you can specify the exact image digest.
```
helm upgrade -i -n agentgateway-system enterprise-agentgateway oci://us-docker.pkg.dev/solo-public/enterprise-agentgateway/charts/enterprise-agentgateway \
  -f values.yaml \
  --version v$NEW_VERSION 
```

Verify that the control plane runs the upgraded version.

kubectl -n agentgateway-system get pod -l app.kubernetes.io/name=enterprise-agentgateway -o jsonpath='{.items[0].spec.containers[0].image}'

Example output:

us-docker.pkg.dev/solo-public/enterprise-agentgateway/enterprise-agentgatewayy-controller:2026.6.3

Confirm that the control plane is up and running.
```
kubectl get pods -n agentgateway-system
```

Upgrade the UI

Upgrade the Solo UI to the latest version.

Save your current values for the Solo UI Helm chart.

helm get values management -n agentgateway-system -o yaml > management-values.yaml

Check for any Helm chart values in the latest Solo UI Helm version that you might want to add to your current values file as part of the upgrade.

helm show values oci://us-docker.pkg.dev/solo-public/solo-enterprise-helm/charts/management --version 0.4.8

helm pull oci://us-docker.pkg.dev/solo-public/solo-enterprise-helm/charts/management --version 0.4.8
tar -xvf management-0.4.8.tgz
open management/values.yaml

Upgrade the Solo UI to the latest version of the UI.

helm upgrade -i management oci://us-docker.pkg.dev/solo-public/solo-enterprise-helm/charts/management \
  --namespace agentgateway-system \
  --create-namespace \
  --version 0.4.8 \
  -f management-values.yaml

Verify that the management and UI pods are up and running.

kubectl get pods -n agentgateway-system

Example output:

NAME                                  READY   STATUS    RESTARTS   AGE
management-clickhouse-shard0-0        1/1     Running   0          3m28s
solo-enterprise-ui-6dd78f9d9b-685ln   5/5     Running   0          3m28s

Inspect agentgateway configuration Uninstall