Upgrade sidecar service meshes with Helm
Upgrade your service mesh control and data plane components in your Gloo Mesh Core cluster.
Version requirements
Verify that the minor version of the Solo distribution of Istio that you want to upgrade to is tested and supported for your Gloo Mesh 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.
Check the Istio release notes for the upgrade version to prepare for any breaking changes.
Be sure to review the following known Istio version restrictions.
In Gloo Mesh Core version 2.6 and later, ambient mode requires the Solo distribution of Istio version 1.22.3 or later (
1.22.3-solo
). In Gloo Mesh version 2.7 and later, multicluster ambient setups require the Solo distribution of Istio version 1.24.3 or later (1.24.3-solo
), including the Solo distribution ofistioctl
.
In Istio 1.22.0-1.22.3, theISTIO_DELTA_XDS
environment variable must be set tofalse
. For more information, see this upstream Istio issue. Note that this issue is resolved in Istio 1.22.4.
Istio 1.20 is supported only as patch version1.20.1-patch1
and later. Do not use patch versions 1.20.0 and 1.20.1, which contain bugs that impact several Gloo Mesh Core features that rely on Istio ServiceEntries.
Before you begin
Set up the following tools and environment variables.
Set environment variables for the Solo distribution of Istio that you want to upgrade to.
# Solo distrubution of Istio patch version # in the format 1.x.x, with no tags export ISTIO_VERSION=1.24.2 # 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>' export REPO_KEY=<repo_key> # Solo distrubution of Istio patch version and Solo tag # Optionally append other Solo tags as needed export ISTIO_IMAGE=${ISTIO_VERSION}-solo # Solo distribution of Istio image repo export REPO=us-docker.pkg.dev/gloo-mesh/istio-${REPO_KEY}
Be sure to review the following known Istio version restrictions.
In Gloo Mesh Core version 2.6 and later, ambient mode requires the Solo distribution of Istio version 1.22.3 or later (
1.22.3-solo
). In Gloo Mesh version 2.7 and later, multicluster ambient setups require the Solo distribution of Istio version 1.24.3 or later (1.24.3-solo
), including the Solo distribution ofistioctl
.
In Istio 1.22.0-1.22.3, theISTIO_DELTA_XDS
environment variable must be set tofalse
. For more information, see this upstream Istio issue. Note that this issue is resolved in Istio 1.22.4.
Istio 1.20 is supported only as patch version1.20.1-patch1
and later. Do not use patch versions 1.20.0 and 1.20.1, which contain bugs that impact several Gloo Mesh Core features that rely on Istio ServiceEntries.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
Add and update the Helm repository for Istio.
helm repo add istio https://istio-release.storage.googleapis.com/charts helm repo update
Upgrade service meshes
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>
Upgrade the Istio CRDs to the new version.
helm get values istio-base -n istio-system --kube-context ${CLUSTER_CONTEXT} -o yaml > istio-base.yaml helm upgrade istio-base istio/base \ --namespace istio-system \ --kube-context ${CLUSTER_CONTEXT} \ --version ${ISTIO_VERSION} \ -f istio-base.yaml
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
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 thehub
field to the repo for the correct version of the Solo distribution of Istio.Upgrade your Helm release with the updated values.
helm upgrade istiod istio/istiod \ -n istio-system \ --kube-context ${CLUSTER_CONTEXT} \ --version ${ISTIO_VERSION} \ -f istiod.yaml
Verify that the istiod pods are successfully restarted. Note that it might take a few seconds for the pods to become available.
kubectl --kube-context ${CLUSTER_CONTEXT} get pods -n istio-system | grep istiod
Example output:
istiod-main-bb86b959f-msrg7 1/1 Running 0 2m45s istiod-main-bb86b959f-w29cm 1/1 Running 0 3m
Optional: If you installed the Istio CNI, upgrade its Helm release.
Get the current values for the CNI Helm release in your cluster.
Make edits to the Helm values, and save the file. If you update the Istio minor version, such as in
tag
fields, be sure to also update the value of thehub
field to the repo for the correct version of the Solo distribution of Istio.Upgrade your Helm release with the updated values.
Verify that the Istio CNI pods are successfully restarted. Note that it might take a few seconds for the pods to become available.
Example output:
... 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
Multicluster setups: Repeat steps 1 - 7 for each cluster where you want to upgrade Istio. Be sure to change the values of the
$CLUSTER_NAME
and$CLUSTER_CONTEXT
environment variables for each cluster.