This page provides information to help you plan an Anthos Service Mesh upgrade. We recommend that you also review the Istio upgrade notes.
About canary upgrades
We recommend that you upgrade Anthos Service Mesh by first running a canary deployment
of the new control plane. With a canary upgrade, asmcli
installs a new
revision of the control
plane alongside the old control plane. Both the old and new control planes
are labeled with a revision
label, which serves as an identifier for the
control planes.
You then migrate workloads to the new control plane by setting the same
revision
label on your namespaces and performing a rolling restart. The
restart re-injects the sidecar proxies in the Pods so that the proxies use the
new control plane. With this approach, you can monitor the effect of the
upgrade on a small percentage of your workloads. After testing your
application, you can migrate all traffic to the new control plane or rollback
to the old control plane. This approach is much safer than doing an in-place
upgrade where the new control plane replaces the old control plane.
For this initial preview, asmcli
installs the istio-ingressgateway
with
a revision label by default. This allows you to do a canary upgrade of the
istio-ingressgateway
as well as the control plane.
Customize the control plane
If you customized the previous installation, you need the same customizations
when you upgrade Anthos Service Mesh. If you customized the installation by adding
the --set values
flag to istioctl install
, you must add those settings to
an IstioOperator
YAML file, referred to as an overlay file. You specify the
overlay file by using the --custom_overlay
option with the filename when you
run the script.
The
anthos-service-mesh
package in GitHub contain many overlay files. These files contain common
customizations to the default configuration. You can use these files as they
are, or you can make additional changes to them as needed. Some of the files
are required to
enable optional Anthos Service Mesh features.
The anthos-service-mesh
package is downloaded when you run asmcli
to
validate your project and cluster.
When you install Anthos Service Mesh using asmcli install
, you
can specify one or more overlay files with the --option
or --custom_overlay
.
If you don't need to make any changes to the files in the anthos-service-mesh
repository, you can use --option
, and the script fetches the file from GitHub
for you. Otherwise, you can make changes to the overlay file, and then use the
--custom_overlay
option to pass it to the asmcli
.
Choose a certificate authority
If your current Anthos Service Mesh installation uses Anthos Service Mesh certificate authority (Mesh CA) as the certificate authority (CA) for issuing mutual TLS (mTLS) certificates, we recommend that you continue to use Mesh CA for the following reasons:
- Mesh CA is a highly reliable and scalable service that is optimized for dynamically scaled workloads on Google Cloud.
- With Mesh CA, Google manages the security and availability of the CA backend.
- Mesh CA lets you rely on a single root of trust across clusters.
If your current Anthos Service Mesh installation uses Istio CA (previously called "Citadel"), you can switch to Mesh CA when you upgrade, but you need to schedule downtime. During the upgrade, mTLS traffic is interrupted until all workloads are switched to using the new control plane with Mesh CA.
Certificates from Mesh CA include the following data about your application's services:
- The Google Cloud project ID
- The GKE namespace
- The GKE service account name
Identifying your CA
When you run asmcli install
to upgrade, you specify the CA that asmcli
should enable on the new control plane.
Changing CAs causes downtime when your deploy workloads to the new control plane. If you can't schedule downtime, make sure to specify that same CA for the new control plane that the old control plane uses. If you aren't sure which CA is enabled on your mesh, run the following commands:
Get a list of Pods from one of your namespaces:
kubectl get pods -n NAMESPACE
Replace
POD_NAME
with the name of one of your Pods in the following command:kubectl get pod POD_NAME -n NAMESPACE -o yaml | grep CA_ADDR -A 1
If Mesh CA is enabled on the namespace, your see the following output:
- name: CA_ADDR value: meshca.googleapis.com:443
Prepare gateway configuration
Anthos Service Mesh gives you the option to deploy and manage gateways as part of your service mesh. A gateway describes a load balancer operating at the edge of the mesh receiving incoming or outgoing HTTP/TCP connections. Gateways are Envoy proxies that provide you with fine-grained control over traffic entering and leaving the mesh.
By default, asmcli
doesn't install the istio-ingressgateway
. We
recommend that you deploy and manage the control plane and gateways separately.
For more information, see
Installing and upgrading gateways. If you need the
default istio-ingressgateway
installed with the in-cluster control plane,
include the --option legacy-default-ingressgateway
argument.