Upgrading Istio on GKE

Stay organized with collections Save and categorize content based on your preferences.

This guide contains upgrade notes for any releases that have specific upgrade instructions. You don't need to do anything for upgrades that aren't mentioned in this guide.

Upgrading operator based 1.6 Istio to the latest patch release

Please make sure you are using a GKE cluster running:

  • 1.17.17-gke.3100 or higher.
  • 1.18.16-gke.1600 or higher.
  • 1.19.8-gke.1600 or higher.

If not, please follow the upgrade instructions to upgrade your cluster.

To patch your istio-operator 1.6 deployment image, run the following commands on a workstation that is configured to connect to the Istio on GKE cluster.

  1. Back up your current operator image version:

    kubectl -n istio-operator get deployment/istio-operator -o \
jsonpath={.spec.template.spec.containers..image} > operator-image-backup

    more operator-image-backup

  2. Identify the version you want to update to. For example, if you want to upgrade Istio on GKE to 1.6.14-gke.5, run the following command:

    kubectl -n istio-operator set image deployment/istio-operator \
istio-operator=gcr.io/gke-release/istio/operator:1.6.14-gke.5

    Note that the control plane and istio-ingressgateway will be upgraded automatically.

  3. Restart your workloads to re-inject the new Envoy proxies.

If you experience issues and want to rollback, run:

kubectl -n istio-operator set image deployment/istio-operator \
istio-operator=$(cat operator-image-backup)

Upgrading 1.4 Istio to the latest patch release

To upgrade your Istio 1.4, run the following commands on a workstation that is configured to connect to the Istio on GKE cluster.

  1. Back up your current deployment image:

    export ORIGINAL_ISTIO_VERSION=$(kubectl -n  istio-system get deployment/istio-pilot -o \
jsonpath={.spec.template.spec.containers[0].image} | sed 's/.*://')

echo $ORIGINAL_ISTIO_VERSION

  2. Set an env variable to the Istio version you want to upgrade to, for example, run the following command to set it to 1.4.10-gke.17:

    export ISTIO_VERSION=1.4.10-gke.17

  3. Update Istio addon deployment image version:

    kubectl set image -n istio-system deployment/istio-ingressgateway istio-proxy=gke.gcr.io/istio/proxyv2:${ISTIO_VERSION}

kubectl set image -n istio-system deployment/istio-citadel citadel=gke.gcr.io/istio/citadel:${ISTIO_VERSION}

kubectl set image -n istio-system deployment/istio-galley galley=gke.gcr.io/istio/galley:${ISTIO_VERSION}

kubectl set image -n istio-system deployment/istio-sidecar-injector sidecar-injector-webhook=gke.gcr.io/istio/sidecar_injector:${ISTIO_VERSION}

kubectl set image -n istio-system deployment/istio-pilot discovery=gke.gcr.io/istio/pilot:${ISTIO_VERSION} istio-proxy=gke.gcr.io/istio/proxyv2:${ISTIO_VERSION}

kubectl set image -n istio-system deployment/istio-policy mixer=gke.gcr.io/istio/mixer:${ISTIO_VERSION} istio-proxy=gke.gcr.io/istio/proxyv2:${ISTIO_VERSION}

kubectl set image -n istio-system deployment/istio-telemetry mixer=gke.gcr.io/istio/mixer:${ISTIO_VERSION} istio-proxy=gke.gcr.io/istio/proxyv2:${ISTIO_VERSION}

  4. Get the sidecar injector configuration map:

    kubectl get configmap -n istio-system istio-sidecar-injector -oyaml > sidecar-injector.yaml

  5. Replace all presence of original image version with the target istio version:

    sed -i -- "s/${ORIGINAL_ISTIO_VERSION}/${ISTIO_VERSION}/g" sidecar-injector.yaml

  6. Apply the updated configmap:

    kubectl apply -f sidecar-injector.yaml

  7. Restart your workloads to re-inject the new Envoy proxies.

If you experience issues and want to roll back, you can run the same steps with ISTIO_VERSION set to the previous version.

Upgrading from Istio 1.1.3

The Istio on GKE add-on version 1.1.3-gke.0 has PodDisruptionBudget (PDB) definitions that require the minimum number of available replicas to be at least 1. As of version 1.1.7-gke.0, the add-on no longer has this requirement. However, once this PDB is installed, it prevents upgrading to any other version if it violates the PDB. This means that to upgrade from 1.1.3-gke.0 to any higher version 1.1.x (such as 1.1.7-gke.0), it's necessary to first increase the minReplicas value for all Istio HorizontalPodAutoscaler resources to at least 2, otherwise the upgrade will fail due to PodDisruptionBudget violation.

Upgrading to Istio 1.1

Before upgrading a GKE cluster from 1.0.x to 1.1.x, you should ensure that your configuration is compatible with 1.1. The following changes in Istio 1.1 are potentially backwards incompatible and might require you to update your configuration to avoid breaking or unexpected behavior. We recommend you run our upgrade script to help you check your configuration.

TLS behavior override via annotations

In 1.0, you modify TLS policy through annotations. In 1.1 these annotations don't work and require that you configure a Policy and DestinationRule instead. See the Istio doc for details.

Upgrade process

Replace the annotations with a Policy and DestinationRule, according to the Istio docs. This change doesn't break your 1.0 configuration. After you upgrade to 1.1, the old annotations won't have any effect, so you can delete the old annotations or leave them in place.

RbacConfig to ClusterRbacConfig renaming

RbacConfig CRD is renamed to ClusterRbacConfig. The schema is unchanged.

Upgrade process

Create an identical ClusterRbacConfig CR for every RbacConfig CR.

Destination rule precedence

During sidecar routing to a service, destination rules for the target service in the same namespace as the sidecar take precedence, followed by destination rules in the service's namespace, and finally followed by destination rules in other namespaces, if applicable.

Upgrade process

Check your DestinationRules to see if they have rules in multiple namespaces for the same target service. If so, examine the rules closely to see how they overlap, and make sure that the correct precedence applies for your desired behavior.