Upgrade

You can use this guide to upgrade the agentgateway control plane and data plane components, or to apply changes to the components’ configuration settings.

Upgrade

1. Set the version you want to upgrade to in an environment variable, such as the latest patch version (2.2.1) .

   export NEW_VERSION=2.2.1

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

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

      helm template --version v$NEW_VERSION agentgateway-crds oci://ghcr.io/kgateway-dev/charts/agentgateway-crds  --output-dir ./helm

   2. Upgrade the CRDs in your cluster:

      helm upgrade -i --namespace agentgateway-system --version v$NEW_VERSION agentgateway-crds oci://ghcr.io/kgateway-dev/charts/agentgateway-crds

3. Make any changes to your Helm values.

   1. Get the Helm values file for your current version.

      helm get values 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.

      • Show all values:

        helm show values oci://ghcr.io/kgateway-dev/charts/agentgateway --version v$NEW_VERSION

      • Get a file with all values: You can get a agentgateway/values.yaml file for the upgrade version by pulling and inspecting the Helm chart locally.

        helm pull oci://ghcr.io/kgateway-dev/charts/agentgateway --version v$NEW_VERSION
        tar -xvf agentgateway-v$NEW_VERSION.tgz
        open 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 v1.0.0-alpha.3 builds, include the controller.image.pullPolicy=Always setting or refer to the exact image digest to avoid using cached images.

4. Upgrade the 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 v1.0.0-alpha.3, add the --set controller.image.pullPolicy=Always option to ensure you get the latest image. Alternatively, you can specify the exact image digest.
   • To use experimental Gateway API features, include the experimental feature gate, --set controller.extraEnv.KGW_ENABLE_GATEWAY_API_EXPERIMENTAL_FEATURES=true.

   helm upgrade -i -n agentgateway-system agentgateway oci://ghcr.io/kgateway-dev/charts/agentgateway \
     -f values.yaml \
     --version v$NEW_VERSION 

5. Verify that the control plane runs the upgraded version.

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

   Example output:

   cr.agentgateway.dev/controller:2.2.1

6. Confirm that the control plane is up and running.

   kubectl get pods -n agentgateway-system