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

Prepare to upgrade

Before you upgrade Gloo Gateway, 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 Gloo Gateway that you are upgrading to requires a different version of Kubernetes, the Kubernetes Gateway API, or Istio, upgrade those technologies accordingly.

    1. Decide on the Kubernetes Gateway API version that you want to use.

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

      • Standard channel:

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

    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:

Upgrade

  1. Set the version to upgrade Gloo Gateway in an environment variable, such as the latest patch version (2.0.1) .

      export NEW_VERSION=2.0.1

  2. Apply the Gloo Gateway CRDs for the upgrade version by using Helm.

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

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

    2. Upgrade the CRDs in your cluster:

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

  3. Make any changes to your Helm values.

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

        helm get values gloo-gateway -n gloo-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://us-docker.pkg.dev/solo-public/gloo-gateway/charts/gloo-gateway --version $NEW_VERSION

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

          helm pull oci://us-docker.pkg.dev/solo-public/gloo-gateway/charts/gloo-gateway --version $NEW_VERSION
tar -xvf gloo-gateway-$NEW_VERSION.tgz
open gloo-gateway/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.0.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 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.0.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 gloo-system gloo-gateway oci://us-docker.pkg.dev/solo-public/gloo-gateway/charts/gloo-gateway \
  -f values.yaml \
  --version $NEW_VERSION

  5. Verify that Gloo Gateway runs the upgraded version.

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

    Example output:

      us-docker.pkg.dev/solo-public/gloo-gateway/gloo-gateway:2.0.1

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

      kubectl get pods -n gloo-system