This page explains how to:
- Run
asmcli
to do a new installation of Anthos Service Mesh 1.10.6-asm.2. - Deploy or redeploy your workloads to inject sidecar proxies.
Before you begin
Before you begin, make sure that you:
- Review the prerequisites.
- Review the information in Plan the install.
- Install the required tools
- Download
asmcli
- Grant cluster admin permissions
- Validate project and cluster
Install Anthos Service Mesh
The following outlines how to install Anthos Service Mesh:
Run
asmcli install
to install the in-cluster control plane on a single cluster. See the following sections for command line examples. The examples contain both required arguments and optional arguments that you might find useful. We recommend that you always specify theoutput_dir
argument so that you can easily locate sample gateways and tools such asistioctl
. See the navigation bar on the right for a list of the examples.Optionally, install an ingress gateway.
To complete setting up Anthos Service Mesh, you need to enable automatic sidecar injection and deploy or redeploy workloads.
If you are installing Anthos Service Mesh on more than one cluster, run
asmcli install
on each cluster. After Anthos Service Mesh is installed on all clusters, see Setting up a multi-cluster mesh on-premisesIf your clusters are on different networks (as they are in island mode) then you should pass a unique network name to
asmcli
using the--network_id
flag.
Install default features and Mesh CA
This section shows how to run asmcli
to install Anthos Service Mesh with the default
supported features for your platform and
enable Anthos Service Mesh certificate authority (Mesh CA) as the certificate authority.
GKE
Run the following command to install the new control plane with default features. Enter your values in the provided placeholders.
./asmcli install \
--project_id PROJECT_ID \
--cluster_name CLUSTER_NAME \
--cluster_location CLUSTER_LOCATION \
--fleet_id FLEET_PROJECT_ID \
--output_dir DIR_PATH \
--enable_all \
--ca mesh_ca
--project_id
,--cluster_name
, and--cluster_location
Specify the project ID that the cluster is in, the cluster name, and either the cluster zone or region.--fleet_id
The project ID of the fleet host project. If you don't include this option,asmcli
uses the project that the cluster was created in when registering the cluster.--output_dir
Include this option to specify a directory whereasmcli
downloads theanthos-service-mesh
package and extracts the installation file, which containsistioctl
, samples, and manifests. Otherwiseasmcli
downloads the files to atmp
directory. You can specify either a relative path or a full path. The environment variable$PWD
doesn't work here.-
--enable_all
Allows the script to:- Grant required IAM permissions.
- Enable the required Google APIs.
- Set a label on the cluster that identifies the mesh.
- Register the cluster to the fleet if it isn't already registered.
--ca mesh_ca
Use Mesh CA as the certificate authority.asmcli
configures Mesh CA to use fleet workload identity
On-premises
Set the current context to your user cluster:
kubectl config use-context CLUSTER_NAME
Run the following command to install the new control plane with default features. Enter your values in the provided placeholders.
./asmcli install \ --fleet_id FLEET_PROJECT_ID \ --kubeconfig KUBECONFIG_FILE \ --output_dir DIR_PATH \ --platform multicloud \ --enable_all \ --ca mesh_ca
--fleet_id
The project ID of the fleet host project.--kubeconfig
The path to thekubeconfig
file You can specify either a relative path or a full path. The environment variable$PWD
doesn't work here.--output_dir
Include this option to specify a directory whereasmcli
downloads theanthos-service-mesh
package and extracts the installation file, which containsistioctl
, samples, and manifests. Otherwiseasmcli
downloads the files to atmp
directory. You can specify either a relative path or a full path. The environment variable$PWD
doesn't work here.--platform multicloud
Specifies that on-premises is the platform.-
--enable_all
Allows the script to:- Grant required IAM permissions.
- Enable the required Google APIs.
- Set a label on the cluster that identifies the mesh.
- Register the cluster to the fleet if it isn't already registered.
--ca mesh_ca
Use Mesh CA as the certificate authority.asmcli
configures Mesh CA to use fleet workload identity
Install default features with Istio CA
This section explains how to:
- Generate certificates and keys for the Istio CA that Anthos Service Mesh uses to sign your workloads.
- Run
asmcli
to install Anthos Service Mesh with default features and enable Istio CA.
For the best security, we highly recommend maintaining an offline root CA and using the subordinate CAs to issue certificates for each cluster. For more information, see Plug in CA Certificates. In this configuration, all workloads in the service mesh use the same root certificate authority (CA). Each Anthos Service Mesh CA uses an intermediate CA signing key and certificate, signed by the root CA. When multiple CAs exist within a mesh, this establishes a hierarchy of trust among the CAs. You can repeat these steps to provision certificates and keys for any number of certificate authorities.
Create a directory for the certificates and keys:
mkdir -p certs && \ pushd certs
Generate a root certificate and key:
make -f ../tools/certs/Makefile.selfsigned.mk root-ca
This generates these files:
- root-cert.pem: the root certificate
- root-key.pem: the root key
- root-ca.conf: the configuration for openssl to generate the root certificate
- root-cert.csr: the CSR for the root certificate
Generate an intermediate certificate and key:
make -f ../tools/certs/Makefile.selfsigned.mk cluster1-cacerts
This generates these files in a directory named
cluster1
:- ca-cert.pem: the intermediate certificates
- ca-key.pem: the intermediate key
- cert-chain.pem: the certificate chain which istiod uses
- root-cert.pem: the root certificate
If you perform these steps using an offline computer, copy the generated directory to a computer with access to the clusters.
Return to the previous directory:
popd
Run
asmcli
to install a mesh using Istio CA:GKE
./asmcli install \ --project_id PROJECT_ID \ --cluster_name CLUSTER_NAME \ --cluster_location CLUSTER_LOCATION \ --fleet_id FLEET_PROJECT_ID \ --output_dir DIR_PATH \ --enable_all \ --ca citadel \ --ca_cert CA_CERT_FILE_PATH \ --ca_key CA_KEY_FILE_PATH \ --root_cert ROOT_CERT_FILE_PATH \ --cert_chain CERT_CHAIN_FILE_PATH
--project_id
,--cluster_name
, and--cluster_location
Specify the project ID that the cluster is in, the cluster name, and either the cluster zone or region.--fleet_id
The project ID of the fleet host project. If you don't include this option,asmcli
uses the project that the cluster was created in when registering the cluster.--output_dir
Include this option to specify a directory whereasmcli
downloads theanthos-service-mesh
package and extracts the installation file, which containsistioctl
, samples, and manifests. Otherwiseasmcli
downloads the files to atmp
directory. You can specify either a relative path or a full path. The environment variable$PWD
doesn't work here.-
--enable_all
Allows the script to:- Grant required IAM permissions.
- Enable the required Google APIs.
- Set a label on the cluster that identifies the mesh.
- Register the cluster to the fleet if it isn't already registered.
-ca citadel
Use Istio CA as the certificate authority.--ca_cert
The intermediate certificate--ca_key
The key for the intermediate certificate--root_cert
The root certificate--cert_chain
The certificate chain
On-premises
Set the current context to your user cluster:
kubectl config use-context CLUSTER_NAME
Run the following command to install Anthos Service Mesh with default features and Istio CA:
./asmcli install \ --fleet_id FLEET_PROJECT_ID \ --kubeconfig KUBECONFIG_FILE \ --output_dir DIR_PATH \ --platform multicloud \ --enable_all \ --ca citadel \ --ca_cert CA_CERT_FILE_PATH \ --ca_key CA_KEY_FILE_PATH \ --root_cert ROOT_CERT_FILE_PATH \ --cert_chain CERT_CHAIN_FILE_PATH
--fleet_id
The project ID of the fleet host project.--kubeconfig
The path to thekubeconfig
file You can specify either a relative path or a full path. The environment variable$PWD
doesn't work here.--output_dir
Include this option to specify a directory whereasmcli
downloads theanthos-service-mesh
package and extracts the installation file, which containsistioctl
, samples, and manifests. Otherwiseasmcli
downloads the files to atmp
directory. You can specify either a relative path or a full path. The environment variable$PWD
doesn't work here.--platform multicloud
Specifies that on-premises is the platform.-
--enable_all
Allows the script to:- Grant required IAM permissions.
- Enable the required Google APIs.
- Set a label on the cluster that identifies the mesh.
- Register the cluster to the fleet if it isn't already registered.
-ca citadel
Use Istio CA as the certificate authority.--ca_cert
The intermediate certificate--ca_key
The key for the intermediate certificate--root_cert
The root certificate--cert_chain
The certificate chain
Install with optional features
An overlay file is a YAML file containing an IstioOperator
custom resource
(CR) that you pass to asmcli
to configure the control plane. You can
override the default control plane configuration and
enable an optional feature by passing
the YAML file to asmcli
. You can layer on more overlays, and each overlay
file overrides the configuration on the previous layers.
GKE
Run the following command to install the new control plane with default features. Enter your values in the provided placeholders.
./asmcli install \
--project_id PROJECT_ID \
--cluster_name CLUSTER_NAME \
--cluster_location CLUSTER_LOCATION \
--fleet_id FLEET_PROJECT_ID \
--output_dir DIR_PATH \
--enable_all \
--ca mesh_ca \
--custom_overlay OVERLAY_FILE
--project_id
,--cluster_name
, and--cluster_location
Specify the project ID that the cluster is in, the cluster name, and either the cluster zone or region.--fleet_id
The project ID of the fleet host project. If you don't include this option,asmcli
uses the project that the cluster was created in when registering the cluster.--output_dir
Include this option to specify a directory whereasmcli
downloads theanthos-service-mesh
package and extracts the installation file, which containsistioctl
, samples, and manifests. Otherwiseasmcli
downloads the files to atmp
directory. You can specify either a relative path or a full path. The environment variable$PWD
doesn't work here.-
--enable_all
Allows the script to:- Grant required IAM permissions.
- Enable the required Google APIs.
- Set a label on the cluster that identifies the mesh.
- Register the cluster to the fleet if it isn't already registered.
--ca mesh_ca
Use Mesh CA as the certificate authority. Note thatasmcli
configures Mesh CA to use fleet workload identity--custom_overlay
Specify the name of the overlay file.
On-premises
Set the current context to your user cluster:
kubectl config use-context CLUSTER_NAME
Run the following command to install the new control plane with default features. Enter your values in the provided placeholders.
./asmcli install \ --fleet_id FLEET_PROJECT_ID \ --kubeconfig KUBECONFIG_FILE \ --output_dir DIR_PATH \ --platform multicloud \ --enable_all \ --ca mesh_ca \ --custom_overlay OVERLAY_FILE
--fleet_id
The project ID of the fleet host project.--kubeconfig
The path to thekubeconfig
file You can specify either a relative path or a full path. The environment variable$PWD
doesn't work here.--output_dir
Include this option to specify a directory whereasmcli
downloads theanthos-service-mesh
package and extracts the installation file, which containsistioctl
, samples, and manifests. Otherwiseasmcli
downloads the files to atmp
directory. You can specify either a relative path or a full path. The environment variable$PWD
doesn't work here.--platform multicloud
Specifies that on-premises is the platform.-
--enable_all
Allows the script to:- Grant required IAM permissions.
- Enable the required Google APIs.
- Set a label on the cluster that identifies the mesh.
- Register the cluster to the fleet if it isn't already registered.
--ca mesh_ca
Use Mesh CA as the certificate authority. Note thatasmcli
configures Mesh CA to use fleet workload identity--custom_overlay
Specify the name of the overlay file.
Install gateways
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.
Create a namespace for the ingress gateway if you don't already have one. Gateways are user workloads, and as a best practice, they shouldn't be deployed in the control plane namespace. Replace
GATEWAY_NAMESPACE
with the name of your namespace.kubectl create namespace GATEWAY_NAMESPACE
Enable auto-injection on the gateway by applying a a revision label on the gateway namespace. The revision label is used by the sidecar injector webhook to associate injected proxies with a particular control plane revision. The revision label that you use depends on whether you deployed managed Anthos Service Mesh or the in-cluster control plane.
Use the following command to locate the revision label on
istiod
:kubectl -n istio-system get pods -l app=istiod --show-labels
The output looks similar to the following:
NAME READY STATUS RESTARTS AGE LABELS istiod-asm-1106-2-5788d57586-bljj4 1/1 Running 0 23h app=istiod,istio.io/rev=asm-1106-2,istio=istiod,pod-template-hash=5788d57586 istiod-asm-1106-2-5788d57586-vsklm 1/1 Running 1 23h app=istiod,istio.io/rev=asm-1106-2,istio=istiod,pod-template-hash=5788d57586
In the output, under the
LABELS
column, note the value of theistiod
revision label, which follows the prefixistio.io/rev=
. In this example, the value isasm-1106-2
.Apply the revision label to the namespace. In the following command,
REVISION
is the value of theistiod
revision label that you noted in the previous step.kubectl label namespace GATEWAY_NAMESPACE istio-injection- istio.io/rev=REVISION --overwrite
You can ignore the message
"istio-injection not found"
in the output. That means that the namespace didn't previously have theistio-injection
label, which you should expect in new installations of Anthos Service Mesh or new deployments. Because auto-injection fails if a namespace has both theistio-injection
and the revision label, allkubectl label
commands in the Anthos Service Mesh documentation include removing theistio-injection
label.Change to the directory that you specified in
--output_dir
.You can deploy the example ingress gateway configuration located in the
samples/gateways/istio-ingressgateway/
directory as is, or modify it as needed.kubectl apply -n GATEWAY_NAMESPACE -f samples/gateways/istio-ingressgateway
Learn more about best practices for gateways.
Deploy and redeploy workloads
Anthos Service Mesh uses sidecar proxies to enhance network security, reliability, and observability. With Anthos Service Mesh, these functions are abstracted away from the application's primary container and implemented in a common out-of-process proxy delivered as a separate container in the same Pod.
Your installation isn't complete until you enable automatic sidecar proxy injection (auto-injection) and restart the Pods for any workloads that were running on your cluster before you installed Anthos Service Mesh.
To enable auto-injection, you label your namespaces with the revision label
that was set on istiod
when you installed Anthos Service Mesh. The revision label is
used by the sidecar injector webhook to associate injected sidecars with a
particular istiod
revision. After adding the label, any existing Pods in the
namespace must be restarted for sidecars to be injected.
Before you deploy new workloads in a new namespace, make sure to configure auto-injection so that Anthos Service Mesh can monitor and secure traffic.
To enable auto-injection:
Use the following command to locate the revision label on
istiod
:kubectl -n istio-system get pods -l app=istiod --show-labels
The output looks similar to the following:
NAME READY STATUS RESTARTS AGE LABELS istiod-asm-1106-2-5788d57586-bljj4 1/1 Running 0 23h app=istiod,istio.io/rev=asm-1106-2,istio=istiod,pod-template-hash=5788d57586 istiod-asm-1106-2-5788d57586-vsklm 1/1 Running 1 23h app=istiod,istio.io/rev=asm-1106-2,istio=istiod,pod-template-hash=5788d57586
In the output, under the
LABELS
column, note the value of theistiod
revision label, which follows the prefixistio.io/rev=
. In this example, the value isasm-1106-2
.Apply the revision label and remove the
istio-injection
label if it exists. In the following command,NAMESPACE
is the name of the namespace where you want to enable auto-injection, andREVISION
is the revision label you noted in the previous step.kubectl label namespace NAMESPACE istio-injection- istio.io/rev=REVISION --overwrite
You can ignore the message
"istio-injection not found"
in the output. That means that the namespace didn't previously have theistio-injection
label, which you should expect in new installations of Anthos Service Mesh or new deployments. Because auto-injection fails if a namespace has both theistio-injection
and the revision label, allkubectl label
commands in the Anthos Service Mesh documentation include removing theistio-injection
label.If workloads were running on your cluster before you installed Anthos Service Mesh, restart the Pods to trigger re-injection.
How you restart Pods depends on your application and the environment the cluster is in. For example, in your staging environment, you might simply delete all the Pods, which causes them to restart. But in your production environment, you might have a process that implements a blue-green deployment so that you can safely restart Pods to avoid traffic interruption.
You can use
kubectl
to perform a rolling restart:kubectl rollout restart deployment -n NAMESPACE
Verify that your Pods are configured to point to the new version of
istiod
.kubectl get pods -n NAMESPACE -l istio.io/rev=REVISION
What's next?
GKE: Set up a multi-mesh
On-premises: