Cloud Service Mesh control plane revisions

This page applies to the in-cluster and managedISTIODcontrol plane implementations.This page does not apply to theTRAFFIC_DIRECTOR control plane implementation,which is a multi-tenant, global control plane, without individual revisions.

This page describes how control planerevisions work and the value ofusing them for safe service mesh upgrades (and rollbacks).

Service mesh installation fundamentals

At a high level, Cloud Service Mesh installation consists of two major phases:

1. First you use theasmcli tool to install anin-cluster control planeor configure themanaged control plane.The control plane consists of a set of system services that are responsiblefor managing mesh configuration.

2. Next, you deploy a specialsidecar proxy throughout your environment thatintercepts network communication to and from each workload. The proxiescommunicate with the control plane to get their configuration, which allowsyou to direct and control traffic (data plane traffic) around your meshwithout making any changes to your workloads.

   To deploy the proxies, you use a process calledautomatic sidecar injection (auto-injection)to run a proxy as an additional sidecar container in each ofyour workload Pods. You don't need to modify the Kubernetes manifests thatyou use to deploy your workloads, but you do need to add a label to yournamespaces and restart the Pods.

Use revisions to upgrade your mesh safely

The ability to control traffic is one of the principal benefits of using aservice mesh. For example, you can gradually shift traffic to a new version ofan application when you first deploy it to production. If you detect problemsduring the upgrade, you can shift traffic back to the original version,providing a simple and low risk means of rolling back. This procedure is knownas acanary release, and it greatly reduces the risk associated with newdeployments.

Auto-injection uses a Kubernetes feature calledadmission control.A mutating admission webhook is registered to watch for newly created Pods. Thewebhook is configured with a namespace selector so that it only matches Podsthat are being deployed to namespaces that have a particular label. When a Podmatches, the webhook consults an injection service provided by the controlplane to obtain a new, mutated configuration for the Pod, which contains thecontainers and volumes needed to run the sidecar.

1. A webhook configuration is created during installation. The webhook isregistered with the Kubernetes API server.
2. The Kubernetes API server watches for Pod deployments in namespaces thatmatch the webhooknamespaceSelector.
3. A namespace is labeled so that it will be matched by thenamespaceSelector.
4. Pods deployed to the namespace trigger the webhook.
5. Theinject service provided by the control plane mutates the Podspecifications to auto-inject the sidecar.

What is a revision?

The label used for auto-injection is like any other user-defined Kuberneteslabel. A label is essentially a key-value pair which can be used to support theconcept of labelling. Labels are widely used for tagging and forrevisions. For example, Git tags, Docker tags, andKnative revisions.

The current Cloud Service Mesh installation process lets you label the installedcontrol plane with a revision string. The installer labels every control planeobject with the revision. The key in the key-value pair isistio.io/rev, butthe value of the revision label differs for the managed control plane and thein-cluster control planes.

• For in-cluster control planes, theistiod Service and Deployment typicallyhave a revision label similar toistio.io/rev=asm-1236-11, whereasm-1236-11 identifies the Cloud Service Mesh version. The revisionbecomes part of the service name, for example:istiod-asm-1236-11.istio-system

• For the managed control plane, the revision label corresponds to arelease channel:

  Revision label	Channel
  istio.io/rev=asm-managed	Regular
  istio.io/rev=asm-managed-rapid	Rapid
  istio.io/rev=asm-managed-stable	Stable

Additionally, you have the option of usingdefault injection labels(for example,istio-injection=enabled).

To enable auto-injection, you add a revision label to your namespaces thatmatches the revision label on the control plane. For example, a control planewith revisionistio.io/rev=asm-1236-11 selects Pods in namespaces withthe labelistio.io/rev=asm-1236-11 and injects sidecars.

The canary upgrade process

Revision labels make it possible to perform canary upgrades and easy rollbacksof the in-cluster control plane. The managed control uses a similar process,but your cluster is automatically upgraded to the latest version within thatchannel.

The following steps describe how the process works:

1. Start with an existing Cloud Service Mesh or open source Istioinstallation. It doesn't matter whether the namespaces are using a revisionlabel or theistio-injection=enabled label.
2. Use a revision string when you install the new version of the controlplane. Because of the revision string, the new control plane is installedalongside the existing version. The new installation includes a new webhookconfiguration with anamespaceSelector configured to watch for namespaceswith that specific revision label.
3. You migrate sidecar proxies to the new control plane by removing the oldlabel from the namespace, adding the new revision label, and thenrestarting the Pods. If you use revisions with Cloud Service Mesh, youmust stop using theistio-injection=enabled label. A control plane with arevision does not select Pods in namespaces with anistio-injectionlabel, even if there is a revision label. The webhook for the new controlplane injects sidecars into the Pods.
4. Carefully test the workloads associated with the upgraded control planeand either continue to roll out the upgrade or roll back to the originalcontrol plane.

After associating Pods with the new control plane, the existing control planeand webhook are still installed. The old webhook has no effect for Pods innamespaces that have been migrated to the new control plane. You can roll backthe Pods in a namespace to the original control plane by removing the newrevision label, adding back the original label and restarting the Pods. When youare certain that the upgrade is complete, you can remove the old controlplane.

For detailed steps on upgrading using revisions, see theUpgrade guide.

A closer look at a mutating webhook configuration

To better understand the mutating webhook for automatic sidecar injection,inspect the configuration yourself. Use the following command:

kubectl -n istio-system get mutatingwebhookconfiguration -l app=sidecar-injector -o yaml

You should see a separate configuration for each control plane that you haveinstalled. A namespace selector for a revision-based control plane looks likethis:

 namespaceSelector:    matchExpressions:    - key: istio-injection      operator: DoesNotExist    - key: istio.io/rev      operator: In      values:      - asm-1236-11

The selector may vary depending on the version of Cloud Service Mesh or Istio thatyou are running. This selector matches namespaces with a specific revision labelas long as they do not also have anistio-injection label.

When a Pod is deployed to a namespace matching the selector, its Podspecification is submitted to the injector service for mutation. The injectorservice to be called is specified as follows:

     service:        name: istiod-asm-1236-11        namespace: istio-system        path: /inject        port: 443

   rules:- apiGroups:- ""      apiVersions:- v1      operations:- CREATE      resources:- pods      scope: '*'

• Upgrade Cloud Service Mesh
• Injecting sidecar proxies