Upgrading to Istio 1.6 with Operator

Starting with version 1.6, the Istio on Google Kubernetes Engine add-on uses the Istio Operator for installation and configuration . The Istio Operator follows the Kubernetes Operator pattern. The Operator lets you configure Istio by defining a Kubernetes custom resource definition (CRD) for the Istio installation. The Operator then uses a controller to make changes to the installation to match the custom resource.

When you upgrade your cluster to 1.17.17-gke.3100+, 1.18.16-gke.1600+, or 1.19.8-gke.1600+, the Istio 1.6 Operator and control plane are installed alongside the existing 1.4.x Istio control plane. The upgrade requires user action and uses revisions to migrate your workloads to the new control plane. With a revision-based upgrade, you migrate to the 1.6 version by setting a label on your workloads to point to the new control plane and performing a rolling restart.

We aren't releasing a 1.5 version of the Istio on Google Kubernetes Engine add-on. Version 1.6 is the version that we release after 1.4.10.

Istio Operator benefits

The Operator allows for greater installation configurability. In versions of the add-on prior to 1.6, the GKE add-on manager reconciles any changes to the Istio manifest and prevents most types of configuration changes. The Istio Operator doesn't have this limitation. The Operator generates an Istio control plane installation manifest based on the IstioOperator custom resource (CR) that you provide during installation. This CR is completely under your control and is never reconciled.

After you have upgraded to Istio 1.6 with the Operator, you can migrate from the Istio on GKE add-on to the open source version of Istio or to Anthos Service Mesh.

Upgrading to Istio 1.6 with Operator

You must do the steps in this section to upgrade to Istio 1.6 with Operator before migrating to Anthos Service Mesh.

You only need to do these steps once to transition to the Operator. Subsequent upgrades follow the dual control plane upgrade process.

  1. Select a GKE version that includes Istio 1.6 (1.17.17-gke.3100+, 1.18.16-gke.1600+, 1.19.8-gke.1600+) and upgrade your cluster.

    Note that the Istio on Google Kubernetes Engine add-on with Istio 1.6 installs two versions of Istio:

    • The static manifest version controlled by the add-on manager (which is active after you upgrade your cluster).

    • The 1.6 version controlled by the Operator (which is inactive until enabled). The inactive 1.6 version doesn't connect to any proxies and consumes negligible cluster resources.

    If the currently installed version of Istio differs from the version in the target static manifest, upgrading the cluster might also perform an in-place upgrade of Istio. For example, if your cluster is currently running Istio 1.4.6-gke.0 and you select GKE cluster version 1.17.7-gke.3100, your Istio control plane is upgraded to 1.4.10-gke.0 (or higher) as part of the upgrade.

    To ensure that your cluster version is recent enough, run the following command:

    kubectl get ns istio-system --show-labels | if [[ $(grep EnsureExists) ]];
    then echo "Version is recent enough"; else echo "Need more recent version"; fi

    The console output indicates whether the cluster version is recent enough.

  2. Download the upgrade-14-16 script:

    curl -LO https://storage.googleapis.com/csm-artifacts/asm/upgrade-14-16

    You can view the script on GitHub.

  3. Make the script executable:

    chmod +x upgrade-14-16
  4. Make sure that kubectl is configured to the cluster that you want to upgrade.

    gcloud container clusters get-credentials cluster-name

    where cluster-name is the name of the cluster.

  5. Run the script:


    The script guides you through the migration process for a single cluster.

  6. To migrate another cluster, run the tool with the --reset flag:

    ./upgrade-14-16 --reset

    Then repeat steps 4 and 5.

Migrating to Anthos Service Mesh

Before migrating to Anthos Service Mesh you need to:

  1. Upgrade to Istio 1.6 with Operator.

  2. Disable the Operator as described below. After migrating, you still configure the service mesh using the same IstioOperator CR format as the Operator, but you do this with the istioctl install command when you want to change the installed state, rather than having the Operator controller continuously watching the IstioOperator CR in the cluster.

To migrate to Anthos Service Mesh, you use a Google-provided script, install_asm, to migrate to Anthos Service Mesh 1.7. The install_asm script handles all the details of preparing your Cloud project and cluster, and then installs Anthos Service Mesh using the Anthos Service Mesh version of istioctl install.


Make sure your cluster meets the following requirements:

  • A machine type that has at least four vCPUs, such as e2-standard-4. If the machine type for your cluster doesn't have at least four vCPUs, change the machine type as described in Migrating workloads to different machine types.

  • The minimum number of nodes depends on your machine type. Anthos Service Mesh requires at least eight vCPUs. If the machine type has four vCPUs, your cluster must have at least two nodes. If the machine type has eight vCPUs, the cluster only needs one node. If you need to add nodes, see Resizing a cluster.

  • The script enables Workload Identity on your cluster. Workload Identity is the recommended method of calling Google APIs. Enabling Workload Identity changes the way calls from your workloads to Google APIs are secured, as described in Workload Identity limitations.

  • To be included in the service mesh, service ports must be named, and the name must include the port's protocol in the following syntax: name: protocol[-suffix] where the square brackets indicate an optional suffix that must start with a dash. For more information, see Naming service ports.

  • If you are installing Anthos Service Mesh on a private cluster, you must open port 15017 in the firewall to get the webhook used with automatic sidecar injection to work properly. For more information, see Opening a port on a private cluster.

  • If you have created a service perimeter in your organization, you might need to add the Mesh CA service to the perimeter. See Adding Mesh CA to a service perimeter for more information.

Plan the migration

To help you plan the migration, review Preparing to migrate from Istio.

Disable the Operator

To prevent the Operator from reconciling the istio-ingressgateway that Anthos Service Mesh installs, you need to disable the Operator.

To disable the Operator:

  1. Get the Operator version:

    kubectl get istiooperators -n istio-system

    The output is similar to the following:

    NAME                        REVISION     STATUS    AGE
    istio-1-6-11-gke-0          istio-1611   HEALTHY   12h

    In the sample output the Operator version is istio-1-6-11-gke-0.

  2. Disable the Operator. In the following command replace VERSION with the Operator version from the previous step:

    kubectl patch -n istio-system istiooperator VERSION -p '{"spec":{"profile":"disabled"}}' --type=merge

    This command blocks the operator from making any changes in the cluster.


If upgrading fails for any reason, you can rollback to the 1.4 version of Istio by running the following command:

./upgrade-14-16 --rollback

Migrate to Anthos Service Mesh

This section describes how to migrate to Anthos Service Mesh 1.7 using the install_asm script.

  1. Choose a certificate authority.

  2. Install the required tools.

  3. Download the install_asm script.

  4. Review the script's options and flags.

    The following examples show how to migrate to Anthos Service Mesh with your chosen certificate authority (CA). and to migrate to Anthos Service Mesh with Mesh CA.


    To continue using Citadel as the CA after migrating to Anthos Service Mesh:

    ./install_asm \
      --project_id PROJECT_ID \
      --cluster_name CLUSTER_NAME\
      --cluster_location CLUSTER_LOCATION \
      --mode migrate \
      --output_dir DIR_PATH  \
      --ca citadel \

    Mesh CA

    To migrate to Mesh CA when you migrate to Anthos Service Mesh:

    ./install_asm \
      --project_id PROJECT_ID \
      --cluster_name CLUSTER_NAME\
      --cluster_location CLUSTER_LOCATION \
      --mode migrate \
      --output_dir DIR_PATH  \
      --ca mesh_ca \

    Anthos Service Mesh 1.7 also provides overlay files available in GitHub for commonly used features such as enabling in egress gateway. For more information, see Enabling optional features.

  5. To complete setting up Anthos Service Mesh, you need to enable automatic sidecar injection and deploy or redeploy workloads.

After migrating

Run the following command, and replace VERSION with the Operator version that you used previously to disable the Operator:

kubectl patch -n istio-system istiooperator VERSION -p '{"spec":{"profile":"empty"}}'

This command re-enables the Operator with an empty profile, which causes it to remove the resources it previously installed from the cluster. This doesn't include the gateways or control plane elements installed by the install_asm script.