For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.

Upgrade

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

Considerations

Consider the following rules before you plan your kgateway upgrade.

Testing upgrades

During the upgrade, pods that run the new version of the control plane and proxies are created. Then, the old pods are terminated. Because zero downtime is not guaranteed, try testing the upgrade in a staging environment before upgrading your production environment.

Patch version upgrades

You can skip patch versions within the same minor release. For example, you can upgrade from version 2.3.0 to 2.3.6 directly, and skip the patch versions in between.

Minor version upgrades

• Before you upgrade the minor version, always upgrade your current minor version to the latest patch. This ensures that your current environment is up-to-date with any bug fixes or security patches before you begin the minor version upgrade process.
• Always upgrade to the latest patch version of the target minor release. Do not upgrade to a lower patch version, such as 2.3.0, 2.3.1, and so on.
• Do not skip minor versions during your upgrade. Upgrade minor release versions one at a time.

Prepare to upgrade

Before you upgrade kgateway, review the following information.

1. Review the kgateway release notes for any breaking changes or new features that you need to be aware of.

2. Check the supported version compatibility matrix. If the version of kgateway that you are upgrading to requires a different version of Kubernetes, the Kubernetes Gateway API, or Istio, upgrade those technologies accordingly.

Upgrade

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

   export NEW_VERSION=2.3.6

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 kgateway-crds oci://cr.kgateway.dev/kgateway-dev/charts/kgateway-crds --output-dir ./helm

   2. Upgrade the CRDs in your cluster:

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

3. Make any changes to your Helm values.

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

      helm get values kgateway -n kgateway-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://cr.kgateway.dev/kgateway-dev/charts/kgateway --version v$NEW_VERSION

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

        helm pull oci://cr.kgateway.dev/kgateway-dev/charts/kgateway --version v$NEW_VERSION
        tar -xvf kgateway-v$NEW_VERSION.tgz
        open kgateway/values.yaml

   3. Make any changes that you want by editing your values.yaml Helm values file or preparing the --set flags. For development v2.4.0-main builds, include the controller.image.pullPolicy=Always setting or refer to the exact image digest to avoid using cached images.

4. Upgrade the kgateway 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 v2.4.0-main, 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 kgateway-system kgateway oci://cr.kgateway.dev/kgateway-dev/charts/kgateway \
     -f values.yaml \
     --version v$NEW_VERSION 

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

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

   Example output:

   cr.kgateway.dev/controller:2.3.6

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

   kubectl get pods -n kgateway-system