Install Cloud Service Mesh for Kubernetes workloads off Google Cloud

Note: This guide only supports Cloud Service Mesh with Istio APIs and doesnot support Google Cloud APIs. For more information see,Cloud Service Mesh overview.

This page explains how to install unmanaged, in-cluster Cloud Service Mesh forKubernetes workloads off Google Cloud:

• Runasmcli to do a new installation of Cloud Service Mesh 1.28.2-asm.4.
• Optionally, deploy an ingress gateway.
• Deploy or redeploy your workloads to inject sidecar proxies.

If you need to install unmanaged, in-cluster Cloud Service Mesh with anistiod control plane on GKE, seeInstall in-cluster Cloud Service Mesh on Google Cloud. Note that for Kubernetes workloads onGoogle Cloud, we recommendprovisioning a managed control plane

For instructions to prepare an offline installation of Cloud Service Mesh,seePrepare an offline installation of Cloud Service MeshYou will need to specify the--offline and--output_dir options when runningasmcli install.

Limitations

Note the following limitations:

• All Cloud Service Mesh clusters for one mesh must be registered to the samefleet at all times to use Cloud Service Mesh. Other clusters in theproject of a Cloud Service Mesh cluster must not be registered to adifferent fleet.

• Theasmcli tool must have access to the Google Kubernetes Engine (GKE)endpoint. You can configure access through a"jump" server, such as aCompute Engine VM within the Virtual Private Cloud (VPC) giving specificaccess.

Before you begin

Before you begin, make sure that you:

• Reviewthe prerequisites.
• Review the information inPlan the install.
• Install the required tools.
• Downloadasmcli.
• Grant cluster admin permissions.
• Validate project and cluster.

Warning: For Cloud Service Mesh to function correctly, deployistiod andcanonical-service-controller-manager to your cluster. These tools haveelevatedrole-based access control (RBAC) permissions,such as the ability to modify all deployments and to modify all cluster secrets.These permissions are required for Cloud Service Mesh functions such asinjecting sidecars, discovering services, securing traffic, managing ingressgateways, and presenting services dashboards.Note: If you need to install Cloud Service Mesh from a private or customcontainer registry, seeUse a custom overlay for custom registry.

Roles required to install in-cluster Cloud Service Mesh

The following table describes the roles that are required to install in-clusterCloud Service Mesh.

Role name	Role ID	Grant location	Description
GKE Hub Admin	roles/gkehub.admin	Fleet project	Full access to GKE Hubs and related resources.
Kubernetes Engine Admin	roles/container.admin	Cluster project. Note that this role must be granted in both Fleet and cluster project for cross-project bindings.	Provides access to full management of Container Clusters and their Kubernetes API objects.
Mesh Config Admin	roles/meshconfig.admin	Fleet and cluster project	Provides permissions required to initialize managed components of Cloud Service Mesh, such as managed control plane and backend permission that allows workloads to talk to Stackdriver without each being individually authorized (for both managed and in-cluster control planes).
Project IAM Admin	roles/resourcemanager.projectIamAdmin	Cluster project	Provides permissions to administer IAM policies on projects.
Service Account Admin	roles/iam.serviceAccountAdmin	Fleet project	Authenticate as a service account.
Service Management Admin	roles/servicemanagement.admin	Fleet project	Full control of Google Service Management resources.
Service Usage Admin	roles/serviceusage.serviceUsageAdmin	Fleet project	Ability to enable, disable, and inspect service states, inspect operations, and consume quota and billing for a consumer project.(Note 1)
CA Service AdminBeta	roles/privateca.admin	Fleet project	Full access to all CA Service resources.(Note 2)

Notes:

1. Service Usage Admin - This role is necessaryas a prerequisite to enable themesh.googleapis.com API wheninitially provisioning managed Cloud Service Mesh.
2. CA Service Admin - This role is only required if youare integrating with CA Service.

Install Cloud Service Mesh

Warning: GitOps tools (including Config Sync, Argo CD, Terraform,and Jenkins) may interfere with your Cloud Service Mesh installation,migration, or upgrade processes. For best results, disable your GitOps toolsbefore you install, migrate, or upgrade Cloud Service Mesh.

The following outlines how to install Cloud Service Mesh:

1. Runasmcli install to install the in-cluster control plane on a singlecluster. See the following sections for command line examples. The examplescontain both required arguments and optional arguments that you might finduseful. We recommend that you always specify theoutput_dir argument sothat you can locate sample gateways and tools such asistioctl. See thenavigation bar on the right for a list of the examples.

2. Optionally,install an ingress gateway. By default,asmcli doesn't install theistio-ingressgateway. We recommend that youdeploy and manage the control plane and gateways separately. If you need thedefaultistio-ingressgateway installed with the in-cluster control plane,include the--option legacy-default-ingressgateway argument.

3. To complete setting up Cloud Service Mesh, you need to enable automaticsidecar injection anddeploy or redeploy workloads.

4. If you are installing Cloud Service Mesh on more than one cluster, runasmcli install on each cluster. When you runasmcli install, besure to use the sameFLEET_PROJECT_ID for eachcluster. After Cloud Service Mesh is installed, see the instructions toset up a multi-cluster meshoff Google Cloud.

5. If your clusters are on different networks (as they are inisland modethen you should pass a unique network name toasmcli using the--network_id flag.

Install default features and Mesh CA

This section shows how to runasmcli to install Cloud Service Mesh with thedefaultsupported features for your platform and enableCloud Service Mesh certificate authority as the certificate authority.

Install default features and Certificate Authority (CA) Service

This section shows how to runasmcli to install Cloud Service Mesh with the defaultsupported features for your platform andenable CA Service as the certificate authority.

Platform note: CA Service is only supported on the following platforms: GKE clusters on Google Cloud, Google Distributed Cloud (software only) for VMware, and Distributed Cloud. If you runasmcli install and specify--ca gcp_cas on other platforms, the installation appears successful, but your workloads will fail to start.

In addition toCloud Service Mesh certificate authority,you can configure Cloud Service Mesh to useCertificate Authority Service. Thisguide provides you an opportunity to integrate with CA Service,which is recommended for the following use cases:

• If you need different certificate authorities to sign workload certificateson different clusters.
• If you need to back your signing keys in aCloud HSM.
• If you are in a highly regulated industry and are subject to compliance.
• If you want to chain up your Cloud Service Mesh CA to a custom enterprise rootcertificate to sign workload certificates.

The cost of Cloud Service Mesh certificate authority is included in theCloud Service Mesh pricing. TheCA Service isn't included in the base Cloud Service Mesh price and ischarged separately. Additionally,CA Service comes with anexplicit SLA, but the Cloud Service Mesh certificate authority does not.

Configure CA Service

1. Create theCA poolin the tierDevOps and in the same region as thecluster that it serves to avoid excessive latency issues or potentialcross-region outages. For more information, seeWorkload-optimized tiers.
2. Create the CAto have at least one active certificate authority in the CA pool in thesame project as the GKE cluster. Use subordinate CA's to signCloud Service Mesh workload certificates. Note down theCA poolcorresponding to the subordinate CA.

3. If it is meant to only service certificates for Cloud Service Mesh workloads, setup the following issuance policy for the CA pool:

   policy.yaml

   baselineValues:  keyUsage:    baseKeyUsage:      digitalSignature: true      keyEncipherment: true    extendedKeyUsage:      serverAuth: true      clientAuth: true  caOptions:    isCa: falseidentityConstraints:  allowSubjectPassthrough: false  allowSubjectAltNamesPassthrough: true  celExpression:    expression: subject_alt_names.all(san, san.type == URI && san.value.startsWith("spiffe://PROJECT_ID.svc.id.goog/ns/") )

   Note: As a best practice for multi-cluster meshes, set one subordinateCA pool per unique cluster region. All the subordinate CA pools should chainto the same root CA pool.

4. To update the CA pool's issuance policy, use the following command:

   gcloud privateca pools updateCA_POOL --locationca_region --issuance-policy policy.yaml

   For information on setting a policy on a pool, seeUsing a certificate issuance policy.

5. If you are using acertificate template, then configure it now. For more information,follow theCA Service guide for workload identity certificates.Ensure the certificate template is created in the same region as the CA pool. If there are multiple regions for CA pools, then create a certificatetemplate per region.

Configure Cloud Service Mesh to use CA Service

Run the following commands on Google Distributed Cloud (software only) for VMware orGoogle Distributed Cloud (software only) for bare metal to install the control plane with default featuresand Certificate Authority Service. Enter your values in the provided placeholders.

1. Set the current context to your user cluster:

   kubectl config use-contextCLUSTER_NAME

2. Runasmcli install:

   ./asmcli install \  --kubeconfigKUBECONFIG_FILE \  --fleet_idFLEET_PROJECT_ID \  --output_dirDIR_PATH \  --enable_all \  --ca gcp_cas \  --platform multicloud \  --ca_pool  projects/CA_POOL_PROJECT_ID/locations/ca_region/caPools/CA_POOL

   • --fleet_id The project ID of the fleet host project.
   • --kubeconfig The full path to thekubeconfig file. The environment variable$PWD doesn't work here. Additionally, relativekubeconfig file locations that use a `~` will not work.
   • --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 the platform is somethingother than Google Cloud, such as on-premises or multi-cloud.
   • --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 gcp_cas Use Certificate Authority Service as the certificate authority. Changing certificate authorities during an upgrade causes downtime.asmcliconfigures Certificate Authority Service to usefleet workload identity
   • --ca_pool The full identifier for the Certificate Authority ServiceCA Pool. If you are using acertificate template, then append the template id separated by:. For example:

       --ca_pool projects/CA_POOL_PROJECT_ID/locations/ca_region/caPools/CA_POOL:projects/CA_POOL_PROJECT_ID/locations/ca_region/certificateTemplates/CERT_TEMPLATE_ID

   To view SLOs and infrastructure metrics in the Cloud Service Mesh UI, you mustalso perform the first three steps inEnable application logging and monitoring.If logging and monitoring are not enabled and do not receive custom logs andmetrics, the Cloud Service Mesh dashboard will not display SLOs, error logs, or CPUand memory metrics.

Install default features with Istio CA

This section explains how to:

• Generate certificates and keys for the Istio CA that Cloud Service Mesh uses tosign your workloads.
• Runasmcli to install Cloud Service Mesh with default features and enableIstio CA.

By default environments that install Cloud Service Mesh with Istio CA report metricsto Prometheus. If you want to use the Cloud Service Mesh dashboards, you must enableStackdriver. For more information, seeInstall with optional features.

For the best security, we highly recommend maintaining an offline root CA andusing the subordinate CAs to issue certificates for each cluster. For moreinformation, seePlug in CA Certificates.In this configuration, all workloads in the service mesh use the same rootcertificate authority (CA). Each Cloud Service Mesh CA uses an intermediate CAsigning key and certificate, signed by the root CA. When multiple CAs existwithin a mesh, this establishes a hierarchy of trust among the CAs. You canrepeat these steps to provision certificates and keys for any number ofcertificate authorities.

Important: These steps create certificates and keys using amake command thatwe provide for illustrative purposes only. For the best security, use an offlinesecure computer and production-ready tools, for example usingHashiCorpVault to securely generate and protect the CAsigning key.

The Makefile to generate the certificates is located in theistio-1.28.2-asm.4 subdirectory in the--output_dir directory that youspecified in theasmcli validate command. If you didn't runasmcli validate,or you don't have the downloaded directory locally, you can get the Makefile bydownloading the Cloud Service Mesh installation fileand extracting the contents.

1. Change to theistio-1.28.2-asm.4 directory.

2. Create a directory for the certificates and keys:

   mkdir -p certs && \pushd certs

3. 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

4. Generate an intermediate certificate and key:

   make -f ../tools/certs/Makefile.selfsigned.mk cluster1-cacerts

   This generates these files in a directory namedcluster1:

   • ca-cert.pem: the intermediate certificates
   • ca-key.pem: the intermediate key
   • cert-chain.pem: the certificate chain whichistiod uses
   • root-cert.pem: the root certificate
   Note: You can replacecluster1 with a different name. For example,makemycluster-cacerts creates a directory namedmycluster.

   If you perform these steps using an offline computer, copy the generateddirectory to a computer with access to the clusters.

5. Return to the previous directory:

   popd

6. Runasmcli to install a mesh using Istio CA:

   On-premises

   Run the following commands on Google Distributed Cloud (software only) for VMware orGoogle Distributed Cloud (software only) for bare metal to install the control plane withdefault features and Istio CA. Enter your values in the providedplaceholders.

   1. Set the current context to your user cluster:

      kubectl config use-contextCLUSTER_NAME

   2. Runasmcli install:

      ./asmcli install \  --fleet_idFLEET_PROJECT_ID \  --kubeconfigKUBECONFIG_FILE \  --output_dirDIR_PATH \  --platform multicloud \  --enable_all \  --ca citadel \  --ca_certCA_CERT_FILE_PATH \  --ca_keyCA_KEY_FILE_PATH \  --root_certROOT_CERT_FILE_PATH \  --cert_chainCERT_CHAIN_FILE_PATH

      • --fleet_id The project ID of the fleet host project.
      • --kubeconfig The full path to thekubeconfig file. The environment variable$PWD doesn't work here. Additionally, relativekubeconfig file locations that use a `~` will not work.
      • --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 the platform is somethingother than Google Cloud, such as on-premises or multi-cloud.
      • --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

   AWS

   Caution:GKE on AzureandGKE on AWSare deprecated and will shut down on March 17, 2027.Cloud Service Mesh support forattached clusters, including Amazon EKS clusters and Microsoft AKS clusters,is deprecated and will shut down March 17, 2027.

   Run the following commands on GKE on AWS to install the controlplane with default features and Istio CA. Enter your values in theprovided placeholders. You can choose to enable Ingress for the publicsubnet or the private subnet.

   Public

   1. Set the current context to your user cluster:

      kubectl config use-contextCLUSTER_NAME

   2. Runasmcli install:

      ./asmcli install \  --fleet_idFLEET_PROJECT_ID \  --kubeconfigKUBECONFIG_FILE \  --output_dirDIR_PATH \  --platform multicloud \  --enable_all \  --ca citadel \  --ca_certCA_CERT_FILE_PATH \  --ca_keyCA_KEY_FILE_PATH \  --root_certROOT_CERT_FILE_PATH \  --cert_chainCERT_CHAIN_FILE_PATH

      • --fleet_id The project ID of the fleet host project.
      • --kubeconfig The full path to thekubeconfig file. The environment variable$PWD doesn't work here. Additionally, relativekubeconfig file locations that use a `~` will not work.
      • --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 the platform is somethingother than Google Cloud, such as on-premises or multi-cloud.
      • --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.

   Private

   1. Set the current context to your user cluster:

      kubectl config use-contextCLUSTER_NAME

   2. Save the following YAML to a file calledistio-operator-internal-lb.yaml:

      apiVersion:install.istio.io/v1alpha1kind:IstioOperatorspec:components:ingressGateways:-enabled:truek8s:serviceAnnotations:service.beta.kubernetes.io/aws-load-balancer-internal:"true"name:istio-ingressgateway

   3. Runasmcli install:

      ./asmcli install \  --fleet_idFLEET_PROJECT_ID \  --kubeconfigKUBECONFIG_FILE \  --output_dirDIR_PATH \  --platform multicloud \  --enable_all \  --ca citadel \  --ca_certFILE_PATH \  --ca_keyFILE_PATH \  --root_certFILE_PATH \  --cert_chainFILE_PATH \  --custom_overlay istio-operator-internal-lb.yaml

      • --fleet_id The project ID of the fleet host project.
      • --kubeconfig The full path to thekubeconfig file. The environment variable$PWD doesn't work here. Additionally, relativekubeconfig file locations that use a `~` will not work.
      • --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 the platform is somethingother than Google Cloud, such as on-premises or multi-cloud.
      • --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.
      • --custom_overlay The name of the overlay file created. For more informationabout overlay files, seeEnabling optionalfeatures on the in-cluster control plane

   Azure

   Caution:GKE on AzureandGKE on AWSare deprecated and will shut down on March 17, 2027.Cloud Service Mesh support forattached clusters, including Amazon EKS clusters and Microsoft AKS clusters,is deprecated and will shut down March 17, 2027.

   Run the following commands on GKE on Azure toinstall the control plane with default features and Istio CA. Enter yourvalues in the provided placeholders. You can choose to enable Ingress forthe public subnet or the private subnet.

   Public

   1. Set the current context to your user cluster:

      kubectl config use-contextCLUSTER_NAME

   2. Runasmcli install:

      ./asmcli install \  --fleet_idFLEET_PROJECT_ID \  --kubeconfigKUBECONFIG_FILE \  --output_dirDIR_PATH \  --platform multicloud \  --enable_all \  --ca citadel \  --ca_certCA_CERT_FILE_PATH \  --ca_keyCA_KEY_FILE_PATH \  --root_certROOT_CERT_FILE_PATH \  --cert_chainCERT_CHAIN_FILE_PATH

      • --fleet_id The project ID of the fleet host project.
      • --kubeconfig The full path to thekubeconfig file. The environment variable$PWD doesn't work here. Additionally, relativekubeconfig file locations that use a `~` will not work.
      • --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 the platform is somethingother than Google Cloud, such as on-premises or multi-cloud.
      • --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.

   Private

   1. Set the current context to your user cluster:

      kubectl config use-contextCLUSTER_NAME

   2. Save the following YAML to a file calledistio-operator-internal-lb.yaml:

      apiVersion:install.istio.io/v1alpha1kind:IstioOperatorspec:components:ingressGateways:-enabled:truek8s:serviceAnnotations:service.beta.kubernetes.io/aws-load-balancer-internal:"true"name:istio-ingressgateway

   3. Runasmcli install:

      ./asmcli install \  --fleet_idFLEET_PROJECT_ID \  --kubeconfigKUBECONFIG_FILE \  --output_dirDIR_PATH \  --platform multicloud \  --enable_all \  --ca citadel \  --ca_certFILE_PATH \  --ca_keyFILE_PATH \  --root_certFILE_PATH \  --cert_chainFILE_PATH \  --custom_overlay istio-operator-internal-lb.yaml

      • --fleet_id The project ID of the fleet host project.
      • --kubeconfig The full path to thekubeconfig file. The environment variable$PWD doesn't work here. Additionally, relativekubeconfig file locations that use a `~` will not work.
      • --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 the platform is somethingother than Google Cloud, such as on-premises or multi-cloud.
      • --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.
      • --custom_overlay The name of the overlay file created. For more informationabout overlay files, seeEnabling optionalfeatures on the in-cluster control plane

   Amazon EKS

   Caution:GKE on AzureandGKE on AWSare deprecated and will shut down on March 17, 2027.Cloud Service Mesh support forattached clusters, including Amazon EKS clusters and Microsoft AKS clusters,is deprecated and will shut down March 17, 2027.

   Run the following commands on Amazon EKS to install the control plane withdefault features and Istio CA. Enter your values in the providedplaceholders.

   1. Set the current context to your user cluster:

      kubectl config use-contextCLUSTER_NAME

   2. Runasmcli install:

      ./asmcli install \  --fleet_idFLEET_PROJECT_ID \  --kubeconfigKUBECONFIG_FILE \  --output_dirDIR_PATH \  --platform multicloud \  --enable_all \  --option attached-cluster \  --ca citadel \  --ca_certCA_CERT_FILE_PATH \  --ca_keyCA_KEY_FILE_PATH \  --root_certROOT_CERT_FILE_PATH \  --cert_chainCERT_CHAIN_FILE_PATH \  --network_iddefault

      • --fleet_id The project ID of the fleet host project.
      • --kubeconfig The full path to thekubeconfig file. The environment variable$PWD doesn't work here. Additionally, relativekubeconfig file locations that use a `~` will not work.
      • --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 the platform is somethingother than Google Cloud, such as on-premises or multi-cloud.
      • --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.
      • --option attached-cluster Changes the default signingutility to be istiod.
      • -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
      • --network_id If you are setting up a multi-networkmesh, then set the--network_id to a unique value for eachcluster in the mesh.

   Microsoft AKS

   Caution:GKE on AzureandGKE on AWSare deprecated and will shut down on March 17, 2027.Cloud Service Mesh support forattached clusters, including Amazon EKS clusters and Microsoft AKS clusters,is deprecated and will shut down March 17, 2027.

   Run the following commands on Microsoft AKS to install the control planewith default features and Istio CA. Enter your values in the providedplaceholders.

   1. Set the current context to your user cluster:

      kubectl config use-contextCLUSTER_NAME

   2. Runasmcli install:

      HUB_REGISTRATION_EXTRA_FLAGS=--has-private-issuer ./asmcli install \  --fleet_idFLEET_PROJECT_ID \  --kubeconfigKUBECONFIG_FILE \  --output_dirDIR_PATH \  --platform multicloud \  --enable_all \  --option attached-cluster \  --ca citadel \  --ca_certCA_CERT_FILE_PATH \  --ca_keyCA_KEY_FILE_PATH \  --root_certROOT_CERT_FILE_PATH \  --cert_chainCERT_CHAIN_FILE_PATH \  --network_iddefault

      • HUB_REGISTRATION_EXTRA_FLAGS=--has-private-issuerAllows registration with GKE Hub.
      Note: To allow registration with GKE Hub, you must usethis flag because AKS clusters do not have a publicly-routable OIDCdiscovery endpoint for the Kubernetes service account token.
      • --fleet_id The project ID of the fleet host project.
      • --kubeconfig The full path to thekubeconfig file. The environment variable$PWD doesn't work here. Additionally, relativekubeconfig file locations that use a `~` will not work.
      • --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 the platform is somethingother than Google Cloud, such as on-premises or multi-cloud.
      • --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.
      • --option attached-cluster Changes the default signingutility to be istiod.
      • -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
      • --network_id If you are setting up a multi-networkmesh, then set the--network_id to a unique value for eachcluster in the mesh.

Install with Istio CA with Google Cloud Observability enabled

If you want to use Cloud Service Mesh dashboards, you must enable Stackdriver.

Install with optional features

An overlay file is a YAML file containing anIstioOperator custom resource(CR) that you pass toasmcli to configure the control plane. You canoverride the default control plane configuration andenable an optional feature by passingthe YAML file toasmcli. You can layer on more overlays, and each overlayfile overrides the configuration on the previous layers. As a best practice,we recommend that you save the overlay files in your version control system.

There are two options to enable optional features:--option and--custom_overlay.

Use--option to if you don't need to change the overlayfile. With this methodasmclifetches the file from theGitHub repository for you.

Use--custom_overlay when you need to customize the overlay file.

For more information, seeEnabling optional features on the in-cluster control plane.

Run the following commands on Google Distributed Cloud (software only) for VMware,Google Distributed Cloud (software only) for bare metal, GKE on AWS, GKE on Azure,Amazon EKS, or Microsoft AKS. Enter your values in the provided placeholders.

1. Set the current context to your user cluster:

   kubectl config use-contextCLUSTER_NAME

2. Runasmcli install to install the control plane with an optionalfeature. To add multiple files, specify--custom_overlay and thefilename, for example:--custom_overlayoverlay_file1.yaml--custom_overlay overlay_file2.yaml --custom_overlay overlay_file3.yaml

   ./asmcli install \--fleet_idFLEET_PROJECT_ID \--kubeconfigKUBECONFIG_FILE \--output_dirDIR_PATH \--platform multicloud \--enable_all \--ca mesh_ca \--custom_overlayOVERLAY_FILE

   • --fleet_id The project ID of the fleet host project.
   • --kubeconfig The full path to thekubeconfig file. The environment variable$PWD doesn't work here. Additionally, relativekubeconfig file locations that use a `~` will not work.
   • --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 the platform is somethingother than Google Cloud, such as on-premises or multi-cloud.
   • --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 Cloud Service Mesh certificate authority as thecertificate authority. Note thatasmcliconfiguresCloud Service Mesh certificate authority to usefleetworkload identity
   • --custom_overlay Specify the name of the overlay file.

Install gateways

Cloud Service Mesh gives you the option to deploy and manage gateways as part of yourservice mesh. A gateway describes a load balancer operating at the edge of themesh receiving incoming or outgoing HTTP/TCP connections. Gateways are Envoyproxies that provide you with fine-grained control over traffic entering andleaving the mesh.

1. 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 bedeployed in the control plane namespace. ReplaceGATEWAY_NAMESPACE with the name of your namespace.

   kubectlcreatenamespaceGATEWAY_NAMESPACE

   Expected output:

   namespace/GATEWAY_NAMESPACE created

2. Enable auto-injection on the gateway. The steps required depend on whetheryou want to usedefault injection labels (for example,istio-injection=enabled) or therevision label on the gatewaynamespace. The default revision tag and revision label are used by thesidecar injector webhook to associate injected proxies with a particularcontrol plane revision.

   Default (recommended)

   1. If you used a default tag revision to enable auto-injection on thegateway, verify that the default tag exists in the directory that youspecified in--output_dir and that it is pointing to the newly installedrevision.

      DIR_PATH/istioctl tag list

   2. Apply the default injection labels to the namespace.

      kubectl label namespaceGATEWAY_NAMESPACE istio-injection=enabled istio.io/rev-

   Revision label

   1. Use the following command to locate the revision label onistiod:

      kubectl get deploy -n istio-system -l app=istiod -o \  "jsonpath={.items[*].metadata.labels['istio\.io/rev']}{'\n'}"

      The command outputs the revision label that corresponds to theCloud Service Mesh version, for example:asm-1282-4

   2. Apply the revision label to the namespace. In the following command,REVISION is the value of theistiod revisionlabel that you noted in the previous step.

      kubectl label namespaceGATEWAY_NAMESPACE \  istio.io/rev=REVISION --overwrite

      Expected output:

      namespace/GATEWAY_NAMESPACE labeled

   You can ignore the message"istio.io/rev" not found in theoutput. That means that the namespace didn't previously have theistio.io/rev label, which you should expect in new installations ofCloud Service Mesh or new deployments. Because auto-injection fails if a namespacehas both theistio.io/rev and theistio-injectionlabel, allkubectl label commands in the Cloud Service Meshdocumentation explicitly specify both labels.

   If the gateway namespace is not labelled, theistio-ingressgateway podswill fail with anImagePullBackOff error when the gateway attempts to pulland theauto image. This image should be replaced by the webhook.

3. Download the example ingress gateway .yaml configuration file from theanthos-service-mesh-packages repository.

4. Apply the example ingress gateway .yaml configuration as is, or modify asneeded.

   kubectlapply-nGATEWAY_NAMESPACE\-fCONFIG_PATH/istio-ingressgateway

   Expected output:

   deployment.apps/istio-ingressgateway createdpoddisruptionbudget.policy/istio-ingressgateway createdhorizontalpodautoscaler.autoscaling/istio-ingressgateway createdrole.rbac.authorization.k8s.io/istio-ingressgateway createdrolebinding.rbac.authorization.k8s.io/istio-ingressgateway createdservice/istio-ingressgateway createdserviceaccount/istio-ingressgateway created

Learn more aboutbest practices for gateways.

Deploy and redeploy workloads

Warning: If you are installing sidecars in application pods where CA connectivity through a direct connection is not available (for example, due to firewalls or other restrictive features), then you mustConfigure CA connectivity through a proxy after installing the in-cluster control plane and before redeploying workloads.

Cloud Service Mesh uses sidecar proxies to enhance network security, reliability, andobservability. With Cloud Service Mesh, these functions are abstracted away from theapplication's primary container and implemented in a common out-of-process proxydelivered as a separate container in the same Pod.

Your installation isn't complete until you enable automatic sidecar proxyinjection (auto-injection) and restart the Pods for any workloads thatwere running on your cluster before you installed Cloud Service Mesh.

To enable auto-injection, you label your namespaces with thedefault injection labelsif the default tag is set up, or arevision labelthat was set onistiod when you installed Cloud Service Mesh. The default revisiontag and revision label are used by the sidecar injector webhook to associateinjected sidecars with anistiod revision. After adding the label, anyexisting Pods in the namespace must be restarted for sidecars to be injected.

Before you deploy new workloads in a new namespace, make sure to configureauto-injection so that Cloud Service Mesh can monitor and secure traffic.

1. The steps required to enable auto-injection depend on whether you want to usedefault injection labels or the revision label:

   Default (Recommended)

   1. If you used a default tag revision to enable auto-injection on thegateway, verify that the default tag exists in the directory that youspecified in--output_dir and that it is pointing to the newly installedrevision.

      DIR_PATH/istioctl tag list

   2. Run the following command.NAMESPACE is the name of thenamespace where you want to enable auto-injection.

      kubectl label namespaceNAMESPACE istio-injection=enabled istio.io/rev-

   The default injection labels inject the revisionthe default tag is pointing to.

   Revision label

   1. Use the following command to locate the revision label onistiod:

      kubectl -n istio-system get pods -l app=istiod --show-labels

      The output looks similar to the following:

      NAMEREADYSTATUSRESTARTSAGELABELSistiod-asm-1282-4-5788d57586-bljj41/1Running023happ=istiod,istio.io/rev=asm-1282-4,istio=istiod,pod-template-hash=5788d57586istiod-asm-1282-4-5788d57586-vsklm1/1Running123happ=istiod,istio.io/rev=asm-1282-4,istio=istiod,pod-template-hash=5788d57586

      In the output, under theLABELS column, note the value of theistiodrevision label, which follows the prefixistio.io/rev=. In this example,the value isasm-1282-4.

   2. Apply the revision label and remove theistio-injection label if itexists. In the following command,NAMESPACE isthe name of the namespace where you want to enable auto-injection, andREVISION is the revision label you noted in theprevious step.

      kubectl label namespaceNAMESPACE istio-injection- istio.io/rev=REVISION --overwrite

      You can ignore the message"istio-injection not found" in theoutput. That means that the namespace didn't previously have theistio-injection label, which you should expect in newinstallations of Cloud Service Mesh or new deployments. Because auto-injectionbehavior is undefined when a namespace has both theistio-injectionand the revision label, allkubectl label commands in theCloud Service Mesh documentation explicitly ensure that only one is set.

2. If workloads were running on your cluster before you installedCloud Service Mesh, restart the Pods to trigger re-injection.

   How you restart Pods depends on your application and the environment thecluster is in. For example, in your staging environment, you might simplydelete all the Pods, which causes them to restart. But in your productionenvironment, you might have a process that implements ablue-green deployment so that you can safely restart Pods to avoid traffic interruption.

   You can usekubectl to perform a rolling restart:

   kubectl rollout restart deployment -nNAMESPACE

What's next?

• If you mesh consists of clusters outside of Google Cloud, seeSet up a multi-cluster mesh outside of Google Cloud.

• Configure an external IP address on-premises.

• Deploy the Online Boutique sample application.