Version 1.12

Install Anthos Service Mesh

Stay organized with collections Save and categorize content based on your preferences.

This page explains how to install Anthos Service Mesh on GKE and on-premises platforms:

  • Run asmcli to do a new installation of Anthos Service Mesh 1.12.9-asm.3.
  • Optionally, deploy an ingress gateway.
  • Deploy or redeploy your workloads to inject sidecar proxies.

Before you begin

Before you begin, make sure that you:

Install Anthos Service Mesh

The following outlines how to install Anthos Service Mesh:

  1. 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 the output_dir argument so that you can easily locate sample gateways and tools such as istioctl. See the navigation bar on the right for a list of the examples.

  2. Private GKE clusters need an additional firewall configuration step to allow traffic to istiod.

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

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

  5. If you are installing Anthos Service Mesh on more than one cluster, run asmcli install on each cluster. When you run asmcli install, be sure to use the same FLEET_PROJECT_ID for each cluster. After Anthos Service Mesh is installed, see Setting up a multi-cluster mesh.

  6. If 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 control plane with default features and Mesh CA. 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 where asmcli downloads the anthos-service-mesh package and extracts the installation file, which contains istioctl, samples, and manifests. Otherwise asmcli downloads the files to a tmp 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. asmcliconfigures Mesh CA to use fleet workload identity

On-premises

Run the following commands on Anthos clusters on VMware or Anthos on bare metal to install the control plane with default features and Mesh CA. Enter your values in the provided placeholders.

  1. Set the current context to your user cluster:

    kubectl config use-context CLUSTER_NAME
    
  2. Run asmcli install:

    ./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 full path to the kubeconfig file. The environment variable $PWD doesn't work here.
    • --output_dir Include this option to specify a directory where asmcli downloads the anthos-service-mesh package and extracts the installation file, which contains istioctl, samples, and manifests. Otherwise asmcli downloads the files to a tmp directory. You can specify either a relative path or a full path. The environment variable $PWD doesn't work here. Additionally, relative kubeconfig file locations that use a `~` will not work.
    • --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. asmcliconfigures Mesh CA to use fleet workload identity

    To view SLOs and infrastructure metrics in the Anthos Service Mesh UI, you must also perform the first three steps in Enable application logging and monitoring. If logging and monitoring are not enabled and do not receive custom logs and metrics, the Anthos Service Mesh dashboard will not display SLOs, error logs, or CPU and memory metrics.

Install default features and Certificate Authority (CA) Service

This section shows how to run asmcli to install Anthos Service Mesh with the default supported features for your platform and enable CA Service as the certificate authority.

In addition to Mesh CA, you can configure Anthos Service Mesh to use Certificate Authority Service. This guide 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 certificates on different clusters.
  • If you want to use istiod Custom CA plugin certificates.
  • If you need to back your signing keys in a managed HSM.
  • If you are in a highly regulated industry and are subject to compliance.
  • If you want to chain up your Anthos Service Mesh CA to a custom enterprise root certificate to sign workload certificates.

The cost of Mesh CA is included in the Anthos Service Mesh pricing. The CA Service isn't included in the base Anthos Service Mesh price and is charged separately. Additionally, CA Service comes with an explicit SLA, but the Mesh CA does not.

For this integration, all workloads in Anthos Service Mesh are granted IAM roles:

  • privateca.workloadCertificateRequester
  • privateca.auditor
  • privateca.template (required if using a certificate template)

Configure CA Service

  1. Create the CA pool in the tier DevOps and in the same region as the cluster that it serves to avoid excessive latency issues or potential cross-region outages. For more information, see Workload-optimized tiers.
  2. Create the CA to have at least one active certificate authority in the CA pool in the same project as the GKE cluster. Use subordinate CA's to sign Anthos Service Mesh workload certificates. Note down the CA pool corresponding to the subordinate CA.
  3. If it is meant to only service certificates for Anthos Service Mesh workloads, set up the following issuance policy for the CA pool:

    policy.yaml

    baselineValues:
      keyUsage:
        baseKeyUsage:
          digitalSignature: true
          keyEncipherment: true
        extendedKeyUsage:
          serverAuth: true
          clientAuth: true
      caOptions:
        isCa: false
    identityConstraints:
      allowSubjectPassthrough: false
      allowSubjectAltNamesPassthrough: true
      celExpression:
        expression: subject_alt_names.all(san, san.type == URI && san.value.startsWith("spiffe://PROJECT_ID.svc.id.goog/ns/") )
    
  4. To update the CA pool's issuance policy, use the following command:

    gcloud privateca pools update CA_POOL --location ca_region --issuance-policy policy.yaml
    

    For information on setting a policy on a pool, see Using a certificate issuance policy.

  5. If you are using a certificate template, then configure it now. For more information, follow the CA 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 certificate template per region.

Configure Anthos Service Mesh to use CA Service

GKE

  1. Install the Anthos Service Mesh control-plane that uses Certificate Authority Service as the CA:

    ./asmcli install \
    --project_id PROJECT_ID \
    --cluster_name CLUSTER_NAME \
    --cluster_location CLUSTER_LOCATION \
    --enable_all \
    --ca gcp_cas \
    --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 the kubeconfig file. The environment variable $PWD doesn't work here.
    • --output_dir Include this option to specify a directory where asmcli downloads the anthos-service-mesh package and extracts the installation file, which contains istioctl, samples, and manifests. Otherwise asmcli downloads the files to a tmp directory. You can specify either a relative path or a full path. The environment variable $PWD doesn't work here. Additionally, relative kubeconfig file locations that use a `~` will not work.
    • --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 gcp_cas Use Certificate Authority Service as the certificate authority. Changing certificate authorities during an upgrade causes downtime. asmcliconfigures Certificate Authority Service to use fleet workload identity
    • --ca_pool The full identifier for the Certificate Authority Service CA Pool. If the certificate template is used, please append the template id separated by :.
      --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
      
  2. Install an ingress gateway to receive incoming or outgoing HTTP/TCP connections. For details, see Install Gateways.

  3. Complete the Anthos Service Mesh installation to enable automatic sidecar proxy injection on your workloads. For details, see Deploy and redeploy workloads.

On-premises

Run the following commands on Anthos clusters on VMware or Anthos on bare metal to install the control plane with default features and Certificate Authority Service. Enter your values in the provided placeholders.

  1. Set the current context to your user cluster:

    kubectl config use-context CLUSTER_NAME
    
  2. Run asmcli install:

    ./asmcli install \
    --kubeconfig KUBECONFIG_FILE \
    --fleet_id FLEET_PROJECT_ID \
    --output_dir DIR_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 the kubeconfig file. The environment variable $PWD doesn't work here.
    • --output_dir Include this option to specify a directory where asmcli downloads the anthos-service-mesh package and extracts the installation file, which contains istioctl, samples, and manifests. Otherwise asmcli downloads the files to a tmp directory. You can specify either a relative path or a full path. The environment variable $PWD doesn't work here. Additionally, relative kubeconfig file locations that use a `~` will not work.
    • --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 gcp_cas Use Certificate Authority Service as the certificate authority. Changing certificate authorities during an upgrade causes downtime. asmcliconfigures Certificate Authority Service to use fleet workload identity
    • --ca_pool The full identifier for the Certificate Authority Service CA Pool. If you are using a certificate 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 Anthos Service Mesh UI, you must also perform the first three steps in Enable application logging and monitoring. If logging and monitoring are not enabled and do not receive custom logs and metrics, the Anthos Service Mesh dashboard will not display SLOs, error logs, or CPU and memory metrics.

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.

The Makefile to generate the certificates is located in the istio-1.12.9-asm.3 subdirectory in the --output_dir directory that you specified in the asmcli validate command. If you didn't run asmcli validate, or you don't have the downloaded directory locally, you can get the Makefile by downloading the Anthos Service Mesh installation file and extracting the contents.

  1. Change to the istio-1.12.9-asm.3 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 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.

  5. Return to the previous directory:

    popd
  6. Run asmcli to install a mesh using Istio CA:

    GKE

    Run the following command to install the control plane with default features and Istio CA. 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 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 where asmcli downloads the anthos-service-mesh package and extracts the installation file, which contains istioctl, samples, and manifests. Otherwise asmcli downloads the files to a tmp 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

    Run the following commands on Anthos clusters on VMware or Anthos on bare metal to install the control plane with default features and Istio CA. Enter your values in the provided placeholders.

    1. Set the current context to your user cluster:

      kubectl config use-context CLUSTER_NAME
      
    2. Run asmcli install:

      ./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 full path to the kubeconfig file. The environment variable $PWD doesn't work here.
      • --output_dir Include this option to specify a directory where asmcli downloads the anthos-service-mesh package and extracts the installation file, which contains istioctl, samples, and manifests. Otherwise asmcli downloads the files to a tmp directory. You can specify either a relative path or a full path. The environment variable $PWD doesn't work here. Additionally, relative kubeconfig file locations that use a `~` will not work.
      • --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

    AWS

    Run the following commands on Anthos clusters on AWS to install the control plane with default features and Istio CA. Enter your values in the provided placeholders. You can choose to enable Ingress for the public subnet or the private subnet.

    Public

    1. Set the current context to your user cluster:

      kubectl config use-context CLUSTER_NAME
      
    2. Run asmcli install:

      ./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 full path to the kubeconfig file. The environment variable $PWD doesn't work here.
      • --output_dir Include this option to specify a directory where asmcli downloads the anthos-service-mesh package and extracts the installation file, which contains istioctl, samples, and manifests. Otherwise asmcli downloads the files to a tmp directory. You can specify either a relative path or a full path. The environment variable $PWD doesn't work here. Additionally, relative kubeconfig file locations that use a `~` will not work.
      • --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.

    Private

    1. Set the current context to your user cluster:

      kubectl config use-context CLUSTER_NAME
      
    2. Save the following YAML to a file called istio-operator-internal-lb.yaml:

      apiVersion: install.istio.io/v1alpha1
      kind: IstioOperator
      spec:
        components:
          ingressGateways:
          - enabled: true
            k8s:
              serviceAnnotations:
                service.beta.kubernetes.io/aws-load-balancer-internal: "true"
            name: istio-ingressgateway
      
    3. Run asmcli install:

      ./asmcli install \
        --fleet_id FLEET_PROJECT_ID \
        --kubeconfig KUBECONFIG_FILE \
        --output_dir DIR_PATH \
        --platform multicloud \
        --enable_all \
        --ca citadel \
        --ca_cert FILE_PATH \
        --ca_key FILE_PATH \
        --root_cert FILE_PATH \
        --cert_chain FILE_PATH
        --custom_overlay istio-operator-internal-lb.yaml \
      
      • --fleet_id The project ID of the fleet host project.
      • --kubeconfig The full path to the kubeconfig file. The environment variable $PWD doesn't work here.
      • --output_dir Include this option to specify a directory where asmcli downloads the anthos-service-mesh package and extracts the installation file, which contains istioctl, samples, and manifests. Otherwise asmcli downloads the files to a tmp directory. You can specify either a relative path or a full path. The environment variable $PWD doesn't work here. Additionally, relative kubeconfig file locations that use a `~` will not work.
      • --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.
      • --custom_overlay stackdriver.yaml By default environments that install Anthos Service Mesh with Istio CA report metrics to Prometheus. If you want to use the Anthos Service Mesh dashboards, you must enable Stackdriver. Note that you can also enable both Stackdriver and Prometheus by using --option prometheus-and-stackdriver.

    Amazon EKS

    Run the following commands on Amazon EKS to install the control plane with default features and Istio CA. Enter your values in the provided placeholders.

    1. Set the current context to your user cluster:

      kubectl config use-context CLUSTER_NAME
      
    2. Run asmcli install:

      ./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 full path to the kubeconfig file. The environment variable $PWD doesn't work here.
      • --output_dir Include this option to specify a directory where asmcli downloads the anthos-service-mesh package and extracts the installation file, which contains istioctl, samples, and manifests. Otherwise asmcli downloads the files to a tmp directory. You can specify either a relative path or a full path. The environment variable $PWD doesn't work here. Additionally, relative kubeconfig file locations that use a `~` will not work.
      • --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

    Microsoft AKS

    Run the following commands on Microsoft AKS to install the control plane with default features and Istio CA. Enter your values in the provided placeholders.

    1. Set the current context to your user cluster:

      kubectl config use-context CLUSTER_NAME
      
    2. Run asmcli install:

      HUB_REGISTRATION_EXTRA_FLAGS=--has-private-issuer ./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
      
      • HUB_REGISTRATION_EXTRA_FLAGS=--has-private-issuer Allows registration with GKE Hub.
      • --fleet_id The project ID of the fleet host project.
      • --kubeconfig The full path to the kubeconfig file. The environment variable $PWD doesn't work here.
      • --output_dir Include this option to specify a directory where asmcli downloads the anthos-service-mesh package and extracts the installation file, which contains istioctl, samples, and manifests. Otherwise asmcli downloads the files to a tmp directory. You can specify either a relative path or a full path. The environment variable $PWD doesn't work here. Additionally, relative kubeconfig file locations that use a `~` will not work.
      • --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 Istio CA with Google Cloud's operations suite enabled

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

GKE

Run the following command to install the control plane with default features and Istio CA. 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 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 where asmcli downloads the anthos-service-mesh package and extracts the installation file, which contains istioctl, samples, and manifests. Otherwise asmcli downloads the files to a tmp 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
  • --option stackdriver Enables Stackdriver option. Note that you can also enable both Stackdriver and Prometheus by using --option prometheus-and-stackdriver.

On-premises

Run the following commands on Anthos clusters on VMware or Anthos on bare metal to install the control plane with Stackdriver and other optional features features and Istio CA. Enter your values in the provided placeholders.

  1. Set the current context to your user cluster:

    kubectl config use-context CLUSTER_NAME
    
  2. Run asmcli install:

    ./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 full path to the kubeconfig file. The environment variable $PWD doesn't work here. Additionally, relative kubeconfig file locations that use a `~` will not work.
    • --output_dir Include this option to specify a directory where asmcli downloads the anthos-service-mesh package and extracts the installation file, which contains istioctl, samples, and manifests. Otherwise asmcli downloads the files to a tmp 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 something other 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
    • --option stackdriver Enables Stackdriver option. Note that you can also enable both Stackdriver and Prometheus by using --option prometheus-and-stackdriver.

    To view SLOs and infrastructure metrics in the Anthos Service Mesh UI, you must also perform the first three steps in Enable application logging and monitoring. If logging and monitoring are not enabled and do not receive custom logs and metrics, the Anthos Service Mesh dashboard will not display SLOs, error logs, or CPU and memory metrics.

AWS

Run the following commands on Anthos clusters on AWS to install the control plane with Stackdriver and other optional features and Istio CA. Enter your values in the provided placeholders. You can choose to enable Ingress for the public subnet or the private subnet.

Public

  1. Set the current context to your user cluster:

    kubectl config use-context CLUSTER_NAME
    
  2. Run asmcli install:

    ./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 \
      --option stackdriver
    
    • --fleet_id The project ID of the fleet host project.
    • --kubeconfig The full path to the kubeconfig file. The environment variable $PWD doesn't work here. Additionally, relative kubeconfig file locations that use a `~` will not work.
    • --output_dir Include this option to specify a directory where asmcli downloads the anthos-service-mesh package and extracts the installation file, which contains istioctl, samples, and manifests. Otherwise asmcli downloads the files to a tmp 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 something other 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.
    • --option stackdriver Enables Stackdriver option. Note that you can also enable both Stackdriver and Prometheus by using --option prometheus-and-stackdriver.

Private

  1. Set the current context to your user cluster:

    kubectl config use-context CLUSTER_NAME
    
  2. Save the following YAML to a file called istio-operator-internal-lb.yaml:

    apiVersion: install.istio.io/v1alpha1
    kind: IstioOperator
    spec:
      components:
        ingressGateways:
        - enabled: true
          k8s:
            serviceAnnotations:
              service.beta.kubernetes.io/aws-load-balancer-internal: "true"
          name: istio-ingressgateway
    
  3. Run asmcli install:

    ./asmcli install \
      --fleet_id FLEET_PROJECT_ID \
      --kubeconfig KUBECONFIG_FILE \
      --output_dir DIR_PATH \
      --platform multicloud \
      --enable_all \
      --ca citadel \
      --ca_cert FILE_PATH \
      --ca_key FILE_PATH \
      --root_cert FILE_PATH \
      --cert_chain FILE_PATH
      --custom_overlay istio-operator-internal-lb.yaml \
      --option stackdriver
    
    • --fleet_id The project ID of the fleet host project.
    • --kubeconfig The full path to the kubeconfig file. The environment variable $PWD doesn't work here. Additionally, relative kubeconfig file locations that use a `~` will not work.
    • --output_dir Include this option to specify a directory where asmcli downloads the anthos-service-mesh package and extracts the installation file, which contains istioctl, samples, and manifests. Otherwise asmcli downloads the files to a tmp 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 something other 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 information about overlay files, see Enabling optional features on the in-cluster control plane
    • --option stackdriver Enables Stackdriver option. Note that you can also enable both Stackdriver and Prometheus by using --option prometheus-and-stackdriver. Alternatively, you can enable Stackdriver using --custom_overlay stackdriver.yaml. You must either Download the anthos-service-mesh-package or create stackdriver.yaml from the provided manifest.

Amazon EKS

Run the following commands on Amazon EKS to install the control plane with Stackdriver and other optional features and Istio CA. Enter your values in the provided placeholders.

  1. Set the current context to your user cluster:

    kubectl config use-context CLUSTER_NAME
    
  2. Run asmcli install:

    ./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 \
      --option stackdriver
    
    • --fleet_id The project ID of the fleet host project.
    • --kubeconfig The full path to the kubeconfig file. The environment variable $PWD doesn't work here. Additionally, relative kubeconfig file locations that use a `~` will not work.
    • --output_dir Include this option to specify a directory where asmcli downloads the anthos-service-mesh package and extracts the installation file, which contains istioctl, samples, and manifests. Otherwise asmcli downloads the files to a tmp 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 something other 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
    • --option stackdriver Enables Stackdriver option. Note that you can also enable both Stackdriver and Prometheus by using --option prometheus-and-stackdriver.

Microsoft AKS

Run the following commands on Microsoft AKS to install the control plane with default features and Istio CA. Enter your values in the provided placeholders.

  1. Set the current context to your user cluster:

    kubectl config use-context CLUSTER_NAME
    
  2. Run asmcli install:

    HUB_REGISTRATION_EXTRA_FLAGS=--has-private-issuer ./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 \
      --option stackdriver
    
    • HUB_REGISTRATION_EXTRA_FLAGS=--has-private-issuer Allows registration with GKE Hub.
    • --fleet_id The project ID of the fleet host project.
    • --kubeconfig The full path to the kubeconfig file. The environment variable $PWD doesn't work here. Additionally, relative kubeconfig file locations that use a `~` will not work.
    • --output_dir Include this option to specify a directory where asmcli downloads the anthos-service-mesh package and extracts the installation file, which contains istioctl, samples, and manifests. Otherwise asmcli downloads the files to a tmp 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 something other 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
    • --option stackdriver Enables Stackdriver option. Note that you can also enable both Stackdriver and Prometheus by using --option prometheus-and-stackdriver.

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. As a best practice, we recommend that you save the overlay files in your version control system.

GKE

Run the following command to install the control plane with an optional feature. To add multiple files, specify --custom_overlay and the filename, for example: --custom_overlay overlay_file1.yaml --custom_overlay overlay_file2.yaml --custom_overlay overlay_file3.yaml 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 where asmcli downloads the anthos-service-mesh package and extracts the installation file, which contains istioctl, samples, and manifests. Otherwise asmcli downloads the files to a tmp 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 that asmcliconfigures Mesh CA to use fleet workload identity
  • --custom_overlay Specify the name of the overlay file.

Outside Google Cloud

Run the following commands on Anthos clusters on VMware, Anthos on bare metal, Anthos clusters on AWS, Amazon EKS, or Microsoft AKS. Enter your values in the provided placeholders.

  1. Set the current context to your user cluster:

    kubectl config use-context CLUSTER_NAME
    
  2. Run asmcli install to install the control plane with an optional feature. To add multiple files, specify --custom_overlay and the filename, for example: --custom_overlayoverlay_file1.yaml --custom_overlay overlay_file2.yaml --custom_overlay overlay_file3.yaml

    ./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 full path to the kubeconfig file. The environment variable $PWD doesn't work here.
    • --output_dir Include this option to specify a directory where asmcli downloads the anthos-service-mesh package and extracts the installation file, which contains istioctl, samples, and manifests. Otherwise asmcli downloads the files to a tmp directory. You can specify either a relative path or a full path. The environment variable $PWD doesn't work here. Additionally, relative kubeconfig file locations that use a `~` will not work.
    • --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 that asmcliconfigures 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.

  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 be deployed in the control plane namespace. Replace GATEWAY_NAMESPACE with the name of your namespace.

    kubectl create namespace GATEWAY_NAMESPACE
    

    Expected output:

    namespace/GATEWAY_NAMESPACE created
    
  2. Enable auto-injection on the gateway. The steps required depend on whether you want to use default injection labels (for example, istio-injection=enabled) or the revision label on the gateway namespace. The default revision tag and revision label are used by the sidecar injector webhook to associate injected proxies with a particular control plane revision.

    Default injection labels

    Apply the default injection labels to the namespace.

    kubectl label namespace GATEWAY_NAMESPACE istio-injection=enabled istio.io/rev-
    

    Revision label

    1. Use the following command to locate the revision label on istiod:

      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 the Anthos Service Mesh version, for example: asm-1129-3

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

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

      Expected output:

      namespace/GATEWAY_NAMESPACE labeled
      
  3. 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 DIR_PATH/samples/gateways/istio-ingressgateway
    

    Expected output:

    deployment.apps/istio-ingressgateway created
    poddisruptionbudget.policy/istio-ingressgateway created
    horizontalpodautoscaler.autoscaling/istio-ingressgateway created
    role.rbac.authorization.k8s.io/istio-ingressgateway created
    rolebinding.rbac.authorization.k8s.io/istio-ingressgateway created
    service/istio-ingressgateway created
    serviceaccount/istio-ingressgateway created
    

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 default injection labels if the default tag is set up, or a revision label that was set on istiod when you installed Anthos Service Mesh. The default revision tag and revision label are used by the sidecar injector webhook to associate injected sidecars with an 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.

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

    Default injection labels

    In the following command, NAMESPACE is the name of the namespace where you want to enable auto-injection.

    kubectl label namespace NAMESPACE istio-injection=enabled istio.io/rev-
    

    Since the default injection labels will inject the revision the default tag is pointing to, there is no need to relabel namespaces.

    Revision label

    1. 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-1129-3-5788d57586-bljj4   1/1     Running   0          23h   app=istiod,istio.io/rev=asm-1129-3,istio=istiod,pod-template-hash=5788d57586
      istiod-asm-1129-3-5788d57586-vsklm   1/1     Running   1          23h   app=istiod,istio.io/rev=asm-1129-3,istio=istiod,pod-template-hash=5788d57586

      In the output, under the LABELS column, note the value of the istiod revision label, which follows the prefix istio.io/rev=. In this example, the value is asm-1129-3.

    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, and REVISION 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 the istio-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 the istio-injection and the revision label, all kubectl label commands in the Anthos Service Mesh documentation include removing the istio-injection label.

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

What's next?