Upgrade

You can use this guide to upgrade the version of your kgateway components, or to apply changes to the components’ configuration settings.

Prepare to upgrade

Before you upgrade kgateway, review the following information.

1. Review the 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.

   Kubernetes Gateway API Kubernetes Istio

   1. Decide on the Kubernetes Gateway API version that you want to use. For help, review the Upgrade Notes in the Kubernetes Gateway API docs. In particular, check if you need to install the experimental channel. The following Kubernetes Gateway API features require experimental.

      • TCPRoutes to set up a TCP listener on your Gateway.

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

      • Standard channel:

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

      • Experimental channel:

        kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.2.1/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

   3. 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:

   • Upstream Istio
   • Gloo Mesh Enterprise

Upgrade kgateway

1. Set the version to upgrade kgateway in an environment variable, such as the latest patch version (2.0.0-main) .

   export NEW_VERSION=2.0.0-main

2. Apply the kgateway CRDs for the upgrade version by using Helm.

   helm upgrade -i --namespace kgateway-system --version v2.0.0-main 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 > kgateway.yaml
      open kgateway.yaml

   2. Compare your current Helm chart values with the version that you want to upgrade to. You can get a values 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 kgateway.yaml Helm values file or preparing the --set flags.

4. Upgrade the kgateway 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.

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

5. Verify that kgateway runs the upgraded version.

   kubectl -n kgateway-system get pod -l kgateway=kgateway -ojsonpath='{.items[0].spec.containers[0].image}'

   Example output:

   cr.kgateway.dev/kgateway-dev/kgateway:2.0.0-main

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

   kubectl get pods -n kgateway-system