Considerations

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.

Single cluster

Upgrade Istio in your single cluster setup.

Upgrade istioctl

  1. Save the Solo distribution of Istio patch version and tag.

      export ISTIO_VERSION=1.27.8
# 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. 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} \
-f istio-base.yaml

  2. 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 -o yaml > istiod.yaml
open istiod.yaml

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

  4. Upgrade your Helm release with the updated values.

      helm upgrade istiod oci://${HELM_REPO}/istiod \
-n istio-system \
--version ${ISTIO_IMAGE} \
-f istiod.yaml

  5. 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 | 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.

  1. Get the current values for its Helm release in your cluster.

    • Kubernetes:
        helm get values istio-cni -n istio-system -o yaml > cni.yaml
open cni.yaml
    • OpenShift:
        helm get values istio-cni -n kube-system -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 --version ${ISTIO_IMAGE} -f cni.yaml
    • OpenShift:
        helm upgrade istio-cni oci://${HELM_REPO}/cni -n kube-system --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
    • OpenShift:
        kubectl get pods -n kube-system

    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

Multicluster

Upgrade the multicluster sidecar mesh in your multicluster setup.

Upgrade istioctl

  1. Save the Solo distribution of Istio patch version and tag.

      # Change the tags as needed
export ISTIO_IMAGE=1.27.8-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. This script automatically detects your OS and architecture, downloads the appropriate Solo distribution of Istio binary, and verifies the installation.

      bash <(curl -sSfL https://raw.githubusercontent.com/solo-io/gloo-mesh-use-cases/main/gloo-mesh/install-istioctl.sh)
export PATH=${HOME}/.istioctl/bin:${PATH}

  4. Save the names and kubeconfig contexts of each cluster. This guide uses two clusters as an example. To add more clusters to the multicluster setup, include them in the arrays.

      export cluster1=<cluster1_name>
export context1=<cluster1_context>
export cluster2=<cluster2_name>
export context2=<cluster2_context>

Upgrade CRDs and istiod

  1. Upgrade the custom resources of the Kubernetes Gateway API to the latest supported version, 1.3.0.

      kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.3.0/standard-install.yaml --context ${context1}
kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.3.0/standard-install.yaml --context ${context2}

  2. Upgrade the Istio CRDs to the new version.

      function upgrade_base() {
  context=${1:?context}
  cluster=${2:?cluster}
  helm get values --kube-context ${context} istio-base -n istio-system -o yaml > istio-base-${cluster}.yaml
  helm upgrade istio-base oci://${HELM_REPO}/base \
  --namespace istio-system \
  --kube-context ${context} \
  --version ${ISTIO_IMAGE} \
  -f istio-base-${cluster}.yaml
}

upgrade_base ${context1} ${cluster1}
upgrade_base ${context2} ${cluster2}

  3. Get the current values for the istiod Helm release in your cluster.

      helm get values istiod --kube-context ${context1} -n istio-system -o yaml > istiod-${cluster1}.yaml
open istiod-${cluster1}.yaml

helm get values istiod --kube-context ${context2} -n istio-system -o yaml > istiod-${cluster2}.yaml
open istiod-${cluster2}.yaml

  4. Make edits to the istiod Helm values, and save the files. 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 releases with the updated values.

      function upgrade_istiod() {
  context=${1:?context}
  cluster=${2:?cluster}
  helm upgrade istiod oci://${HELM_REPO}/istiod \
  -n istio-system \
  --version ${ISTIO_IMAGE} \
  --kube-context ${context} \
  -f istiod-${cluster}.yaml
}

upgrade_istiod ${context1} ${cluster1}
upgrade_istiod ${context2} ${cluster2}

  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 ${context1} | grep istiod
kubectl get pods -n istio-system --context ${context2} | grep istiod

    Example output:

      istiod-main-b84c55cff-tllfr   1/1     Running   0          58s

Upgrade the CNI and ztunnel

  1. For the component that you want to update, get the current values for its Helm release in your cluster.

      helm get values istio-cni --kube-context ${context1} -n istio-system -o yaml > cni-${cluster1}.yaml
open cni-${cluster1}.yaml

    helm get values ztunnel –kube-context ${context1} -n istio-system -o yaml > ztunnel-${cluster1}.yaml
open ztunnel-${cluster1}.yaml
    

    helm get values istio-cni –kube-context ${context2} -n istio-system -o yaml > cni-${cluster2}.yaml
open cni-${cluster2}.yaml
    

    helm get values ztunnel –kube-context ${context2} -n istio-system -o yaml > ztunnel-${cluster2}.yaml
open ztunnel-${cluster2}.yaml


      helm get values istio-cni --kube-context ${context1} -n kube-system -o yaml > cni-${cluster1}.yaml
open cni-${cluster1}.yaml

    helm get values ztunnel –kube-context ${context1} -n kube-system -o yaml > ztunnel-${cluster1}.yaml
open ztunnel-${cluster1}.yaml
    

    helm get values istio-cni –kube-context ${context2} -n kube-system -o yaml > cni-${cluster2}.yaml
open cni-${cluster2}.yaml
    

    helm get values ztunnel –kube-context ${context2} -n kube-system -o yaml > ztunnel-${cluster2}.yaml
open ztunnel-${cluster2}.yaml

  2. Make edits to the Helm values of the components that you want to upgrade, 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.

      function upgrade_cni_ztunnel() {
  context=${1:?context}
  cluster=${2:?cluster}
  helm upgrade istio-cni oci://${HELM_REPO}/cni --kube-context ${context} -n istio-system --version ${ISTIO_IMAGE} -f cni-${cluster}.yaml
  helm upgrade ztunnel oci://${HELM_REPO}/ztunnel --kube-context ${context} -n istio-system --version ${ISTIO_IMAGE} -f ztunnel-${cluster}.yaml
}

    upgrade_cni_ztunnel ${context1} ${cluster1}
upgrade_cni_ztunnel ${context2} ${cluster2}


      function upgrade_cni_ztunnel() {
  context=${1:?context}
  cluster=${2:?cluster}
  helm upgrade istio-cni oci://${HELM_REPO}/cni --kube-context ${context} -n kube-system --version ${ISTIO_IMAGE} -f cni-${cluster}.yaml
  helm upgrade ztunnel oci://${HELM_REPO}/ztunnel --kube-context ${context} -n kube-system --version ${ISTIO_IMAGE} -f ztunnel-${cluster}.yaml
}

    upgrade_cni_ztunnel ${context1} ${cluster1}
upgrade_cni_ztunnel ${context2} ${cluster2}

  4. Verify that the ztunnel and Istio CNI pods are successfully restarted. Note that it might take a few seconds for the pods to become available.

      kubectl get pods --context ${context1} -n istio-system
kubectl get pods --context ${context2} -n istio-system
  
      kubectl get pods --context ${context1} -n kube-system
kubectl get pods --context ${context2} -n kube-system

    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
ztunnel-tvtzn                      1/1     Running   0             40s
ztunnel-vtpjm                      1/1     Running   0             40s
ztunnel-hllxg                      1/1     Running   0             40s