Version 1.12

asmcli Reference

This page describes the available arguments to asmcli.


Identify the cluster You have the following options to identify the cluster:

GKE only

-p|--project_id CLUSTER_PROJECT_ID
The project ID that the cluster was created in.
-n|--cluster_name CLUSTER_NAME
The name of the cluster.
-l|--cluster_location CLUSTER_LOCATION
Either the zone (for single-zone clusters) or region (for regional clusters) that the cluster was created in.

All platforms

--kubeconfig KUBECONFIG_FILE The path to the kubeconfig file

--ctx|--context KUBE_CONTEXT The kubeconfig context to use. If not specified, asmcli uses the default context.

-c|--ca {mesh_ca|citadel}

The certificate authority (CA) to use to manage mutual TLS certificates. Specify either mesh_ca to use Anthos Service Mesh certificate authority (Mesh CA) or citadel to use the Istio CA. Managed Anthos Service Mesh only supports Mesh CA, so you don't need to specify the --ca option when deploying the Google-managed control plane. See the following for additional information:


Use --channel with a specific Anthos Service Mesh release channel to provision the Control Plane revision associated with that release channel. For example, --channel rapid, --channel regular, and --channel stable.

--co|--custom_overlay OVERLAY_FILE

Use --custom_overly with the name of a YAML file (referred to as an overlay file) containing the IstioOperator custom resource to configure the in-cluster control plane. You specify an overlay file to enable a feature that isn't enabled by default. Managed Anthos Service Mesh doesn't support the IstioOperator API, so you can't use --custom_overlay to configure the Google-managed control plane. asmcli must be able to locate the overlay file, so it either needs to be in the same directory as asmcli, or you can specify a relative path. To add multiple files, specify --co|--custom_overlay and the filename, for example: --co overlay_file1.yaml --co overlay_file2.yaml --co overlay_file3.yaml

--hub-registration-extra-flags HUB_REGISTRATION_EXTRA_FLAGS

If using attached Amazon EKS clusters, use --hub-registration-extra-flags to register the cluster to the fleet if it isn't already registered.

--network_id NETWORK_ID

Use --network_id to set the label applied to the istio-system namespace. For GKE, --network_id defaults to the network name for the cluster. For other environments, default will be used.

-o|--option OVERLAY_FILE

The name of the overlay file (without the .yaml extension) that asmcli downloads from the anthos-service-mesh repository to enable an optional feature. You need internet connectivity to use --option. The --option and --custom_overlay options are similar, but they have slightly different behavior:

  • Use --custom_overlay when you need to change the settings in the overlay file.

  • Use --option to enable a feature that doesn't require changes to the overlay file, for example, to configure audit policies for your services.

To add multiple files, specify -o|--option and the filename, for example: -o option_file1 -o option_file2 -o option_file3

-D|--output_dir DIR_PATH

If not specified, asmcli creates a temporary directory where it downloads files and configurations necessary for installing Anthos Service Mesh. Specify the --output-dir flag to specify a relative path to a directory to use instead. Upon completion, the specified directory contains the asm and the istio-1.12.0-asm.4 subdirectories. The asm directory contains the configuration for the installation. The istio-1.12.0-asm.4 directory contains the extracted contents of installation file, which contains istioctl, samples, and manifests. If you specify --output-dir and the directory already contains the necessary files, asmcli uses those files instead of downloading them again.

-r|--revision_name REVISION NAME

A revision label is a key-value pair that is set on the control plane. The revision label key is always By default, asmcli sets the value for the revision label based on the Anthos Service Mesh version, for example: asm-1120-4. Include this option if you want to override the default value and specify your own. The REVISION NAME argument must be a DNS-1035 label. This means the name must:

  • contain at most 63 characters
  • contain only lowercase alphanumeric characters or '-'
  • start with an alphabetic character
  • end with an alphanumeric character

The regex used for validation is: '[a-z]([-a-z0-9]*[a-z0-9])?')

-s|--service_account ACCOUNT
The name of a service account used to install Anthos Service Mesh. If not specified, the active user account in the current gcloud configuration is used. If you need to change the active user account, run gcloud auth login.
-k|--key_file FILE_PATH
The key file for a service account. Omit this option if you aren't using a service account.

Options for Istio CA custom certificate

If you specified --ca citadel and you are using a custom CA, include the following options:

  • --ca_cert FILE_PATH: The intermediate certificate
  • --ca_key FILE_PATH: The key for the intermediate certificate
  • --root_cert FILE_PATH: The root certificate
  • --cert_chain FILE_PATH: The certificate chain

For more information, see Plugging in existing CA Certificates.

Enablement flags

The flags that start with --enable let asmcli enable the required Google APIs, set required Identity and Access Management (IAM) permissions, and update your cluster. If you prefer, you can update your project and cluster yourself before running asmcli. All of the enablement flags are incompatible with asmcli validate. If you specify an enablement flag when you run asmcli validate, the command terminates with an error.

Allow asmcli to perform all of the individual enable actions described below.
Allow asmcli to attempt to bind the GCP user or service account running asmcli to the cluster-admin role on your cluster. asmcli determines the user account from the gcloud config get-value core/account command. If you are running asmcli locally with a user account, make sure that you call the gcloud auth login command before running asmcli. If you need to change the user account, run the gcloud config set core/account GCP_EMAIL_ADDRESS command where GCP_EMAIL_ADDRESS is the account that you use to log in to Google Cloud.
Allow asmcli to set required cluster labels.

Allow asmcli to enable the following required Google Cloud managed services and components:


Allow asmcli to enable all required Google APIs.


Allow asmcli to set the required IAM permissions.


Allow asmcli to register the cluster to the project that the cluster is in. If you don't include this flag, follow the steps in Registering a cluster to manually register the cluster. Note that unlike the other enablement flags, --enable_registration is only included in --enable_all when you specify an option (such as --option vm or --option hub-meshca) that requires cluster registration. Otherwise, you need to specify this flag separately.

Other flags

Print commands, but don't execute them.
Run validation but don't update the project or cluster and don't install Anthos Service Mesh. This flag is incompatible with the enablement flags. asmcli terminates with an error if you specify --only_validate with any enablement flag.
Instead of installing Anthos Service Mesh, print all of the compiled YAML to standard output (stdout). All other output is written to standard error (stderr), even if it would normally go to stdout. asmcli skips all validations and setup when you specify this flag.
By default, asmcli deploys the Canonical Service controller to your cluster. If you don't want asmcli to deploy the controller, specify --disable_canonical_service. For more information, refer to Enabling and disabling the Canonical Service controller.
Show a help message describing the options and flags and exit.
As asmcli runs, it prints the command that it will run next. With the --verbose flag, asmcli prints the command after execution as well.
Print the version of asmcli and exit. If you don't have the most recent version, you can download the most recent version of asmcli_1.12.

What's next