Skip to content

Upgrade Istio service meshes with Helm

Page as Markdown
Upgrade your Istio service mesh in each workload cluster without downtime.
Overview

Before you upgrade your service mesh components, review the following limitations and recommendations.
Revision and canary upgrade limitations
The upgrade guides in this documentation show you how to perform in-place upgrades for your Istio components, which is the recommended upgrade strategy.
Version and license requirements
  1. Verify that the minor version of the Solo distribution of Istio that you want to upgrade to is tested and supported for your Solo Enterprise for Istio version.To find the available patch versions, you can get the minor version repo URL from the Istio images built by Solo.io support article, and check the patch version builds in that repo.
  2. Check the Istio release notes for the upgrade version to prepare for any breaking changes.
  3. Be sure to review the following known Istio version restrictions.
    • If you use Istio versions 1.27.7, 1.28.4, 1.29.0 or later, and you install the Gloo Mesh (Gloo Platform APIs) management plane (Gloo UI) into a namespace other than gloo-mesh, you must allow that namespace by listing it in the DEBUG_ENDPOINT_AUTH_ALLOWED_NAMESPACES environment variable of your istiod installation. For more information, see the release notes.
    • Patch versions 1.26.0 and 1.26.1 of the Solo distribution of Istio lack support for FIPS-tagged images. When upgrading or installing 1.26, be sure to use patch version 1.26.1-patch0 and later only.
    • In the Solo distribution of Istio 1.25 and later, you can access enterprise-level features by passing your Solo license in the license.value or license.secretRef field of the Solo distribution of the istiod Helm chart. The Solo istiod Helm chart is strongly recommended due to the included safeguards, default settings, and upgrade handling to ensure a reliable and secure Istio deployment. Though it is not recommended, you can pass your license key in the open source istiod Helm chart by using the --set pilot.env.SOLO_LICENSE_KEY field.
    • Istio patch versions 1.25.1 and 1.24.4 contain an upstream certificate rotation bug in which requests with more than one trusted root certificate cannot be validated. If you use Gloo Mesh (Gloo Platform APIs) to manage root certificate rotation and use Istio 1.25 or 1.24, be sure to use 1.25.2 or 1.24.5 and later only.
    • Due to a lack of support for the Istio CNI and iptables for the Istio proxy, you cannot run Istio (and therefore Gloo Mesh (Gloo Platform APIs)) on AWS Fargate. For more information, see the Amazon EKS issue.
Upgrade istioctl

  1. Save the Solo distribution of Istio patch version and tag.
    export ISTIO_VERSION=1.27.9-patch1
# Change the tags as needed
export ISTIO_IMAGE=${ISTIO_VERSION}-solo
  2. Save the repo key for the minor version of the Solo distribution of Istio. This is the 12-character hash at the end of the repo URL us-docker.pkg.dev/gloo-mesh/istio-<repo-key>, which you can find in the Istio images built by Solo.io support article.
    # 12-character hash at the end of the repo URL
export REPO_KEY=<repo_key>
export REPO=us-docker.pkg.dev/gloo-mesh/istio-${REPO_KEY}
export HELM_REPO=us-docker.pkg.dev/gloo-mesh/istio-helm-${REPO_KEY}
  3. Upgrade your istioctl CLI client to the new version.
    curl -L https://istio.io/downloadIstio | ISTIO_VERSION=${ISTIO_VERSION} sh -
cd istio-${ISTIO_VERSION}
export PATH=$PWD/bin:$PATH
Upgrade CRDs and istiod

  1. Save the name and kubeconfig context of a workload cluster in the following environment variables. Each time you repeat the steps in this guide, you change these variables to the next workload cluster’s name and context.
    export CLUSTER_NAME=<cluster-name>
export CLUSTER_CONTEXT=<cluster-context>
  2. Upgrade the Istio CRDs to the new version.
    helm get values istio-base -n istio-system -o yaml > istio-base.yaml
helm upgrade istio-base oci://${HELM_REPO}/base \
--namespace istio-system \
--version ${ISTIO_IMAGE} \
--kube-context ${CLUSTER_CONTEXT} \
-f istio-base.yaml
    If you see an error such as Error: UPGRADE FAILED: Rendered manifests contain a resource that already exists, see the community Istio docs.
  3. Get the current values for the istiod Helm release in your cluster. Your release might have a different name.
    helm get values istiod -n istio-system --kube-context ${CLUSTER_CONTEXT} -o yaml > istiod.yaml
open istiod.yaml
  4. Make edits to the istiod Helm values, and save the file. If you update the Istio minor version, such as in the global.tag field, be sure to also update the value of the hub field to the repo for the correct version of the Solo distribution of Istio.
  5. Upgrade your Helm release with the updated values.
    helm upgrade istiod oci://${HELM_REPO}/istiod \
-n istio-system \
--version ${ISTIO_IMAGE} \
--kube-context ${CLUSTER_CONTEXT} \
-f istiod.yaml
  6. Verify that the istiod pods are successfully restarted. Note that it might take a few seconds for the pods to become available.
    kubectl get pods -n istio-system --context ${CLUSTER_CONTEXT} | grep istiod
    Example output:
    istiod-main-bb86b959f-msrg7   1/1     Running   0          2m45s
istiod-main-bb86b959f-w29cm   1/1     Running   0          3m
Optional: Upgrade the CNI

If you installed the Istio CNI, such as in OpenShift setups, follow the steps to upgrade this component.
If your changes include upgrading the Istio version of the components, be sure to upgrade the istiod control plane before you upgrade the CNI component. Otherwise, these components might have an outdated image.
  1. Get the current values for its Helm release in your cluster.
    • Kubernetes:
      helm get values istio-cni -n istio-system --kube-context ${CLUSTER_CONTEXT} -o yaml > cni.yaml
open cni.yaml
    • OpenShift:
      helm get values istio-cni -n kube-system --kube-context ${CLUSTER_CONTEXT} -o yaml > cni.yaml
open cni.yaml
  2. Make edits to the Helm values, and save the files. If you update the Istio minor version, such as in tag fields, be sure to also update the value of the hub field to the repo for the correct version of the Solo distribution of Istio.
  3. Upgrade your Helm releases with the updated values.
    • Kubernetes:
      helm upgrade istio-cni oci://${HELM_REPO}/cni -n istio-system --kube-context ${CLUSTER_CONTEXT} --version ${ISTIO_IMAGE} -f cni.yaml
    • OpenShift:
      helm upgrade istio-cni oci://${HELM_REPO}/cni -n kube-system --kube-context ${CLUSTER_CONTEXT} --version ${ISTIO_IMAGE} -f cni.yaml
  4. Verify that the Istio CNI pods are successfully restarted. Note that it might take a few seconds for the pods to become available.
    • Kubernetes:
      kubectl get pods -n istio-system --context ${CLUSTER_CONTEXT}
    • OpenShift:
      kubectl get pods -n kube-system --context ${CLUSTER_CONTEXT}
    Example output:
    istiod-main-85c4dfd97f-mncj5       1/1     Running   0             42s
istio-cni-node-pr5rl               1/1     Running   0             42s
istio-cni-node-pvmx2               1/1     Running   0             42s
istio-cni-node-lcrcd               1/1     Running   0             42s
```<h2>Repeat for each cluster<span class="hx:absolute hx:-mt-20" id="repeat-for-each-cluster"></span>&#10;    <a href="#repeat-for-each-cluster" class="subheading-anchor" aria-label="Permalink for this section"></a></h2><p><strong>Multicluster setups</strong>: Repeat the steps to <a href="#base-istiod-single">upgrade CRDs and istiod</a> and optionally <a href="#cni-single">upgrade the CNI</a> for each cluster where you want to upgrade Istio. Be sure to change the values of the <code>$CLUSTER_NAME</code> and <code>$CLUSTER_CONTEXT</code> environment variables for each cluster.</p>
Install Istio service meshes with Helm