asmcli Reference
This page describes the available arguments to asmcli
.
Options
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 full path to the kubeconfig file. The environment
variable $PWD
doesn't work here.
--ctx|--context KUBE_CONTEXT
The kubeconfig context to use. If not specified,
asmcli
uses the default context.
-c|--ca {mesh_ca|gcp_cas|citadel}
The certificate authority (CA) to use to manage mutual TLS certificates. Specify
mesh_ca
to use Cloud Service Mesh certificate authority (Cloud Service Mesh certificate authority),gcp_cas
to use Certificate Authority Service, orcitadel
to use the Istio CA. Managed Cloud Service Mesh does not support Istio CA. See the following for additional information:--co|--custom_overlay OVERLAY_FILE
Use
--custom_overly
with the name of a YAML file (referred to as an overlay file) containing theIstioOperator
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 Cloud Service Mesh doesn't support theIstioOperator
API, so you can't use--custom_overlay
to configure the managed control plane.asmcli
must be able to locate the overlay file, so it either needs to be in the same directory asasmcli
, 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.-k|--key_file FILE_PATH
The key file for a service account. Omit this option if you aren't using a service account.
--network_id NETWORK_ID
Use
--network_id
to set thetopology.istio.io/network
label applied to theistio-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) thatasmcli
downloads from theanthos-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 Cloud Service Mesh. Specify the--output-dir
flag to specify a relative path to a directory to use instead. Upon completion, the specified directory contains theasm
and theistio-1.23.2-asm.2
subdirectories. Theasm
directory contains the configuration for the installation. Theistio-1.23.2-asm.2
directory contains the extracted contents of installation file, which containsistioctl
, 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.--platform PLATFORM {gcp|multicloud}
The platform or the provider of the Kubernetes cluster. Defaults to
gcp
(for GKE clusters). For all other platforms use,multicloud
.-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
istio.io/rev
. By default,asmcli
sets the value for the revision label based on the Cloud Service Mesh version, for example:asm-1232-2
. Include this option if you want to override the default value and specify your own. TheREVISION 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 Cloud 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.
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.
-e|--enable_all
- Allow
asmcli
to perform all of the individual enable actions described below. --enable_cluster_roles
- Allow
asmcli
to attempt to bind the Google Cloud user or service account runningasmcli
to thecluster-admin
role on your cluster.asmcli
determines the user account from thegcloud config get core/account
command. If you are runningasmcli
locally with a user account, make sure that you call thegcloud auth login
command before runningasmcli
. If you need to change the user account, run thegcloud config set core/account GCP_EMAIL_ADDRESS
command where GCP_EMAIL_ADDRESS is the account that you use to log in to Google Cloud. --enable_cluster_labels
- Allow
asmcli
to set required cluster labels. --enable_gcp_components
Allow
asmcli
to enable the following required Google Cloud managed services and components:Workload Identity, which lets GKE applications safely access Google Cloud services.
--enable_gcp_apis
Allow
asmcli
to enable all required Google APIs.--enable_gcp_iam_roles
Allow
asmcli
to set the required IAM permissions.--enable_meshconfig_init
Allow the script to initialize the meshconfig endpoint on your behalf. Implied by
--enable_gcp_components
and--managed
.--enable_namespace_creation
Allow
asmcli
to create the rootistio-system
namespace.--enable_registration
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 hub-meshca
) that requires cluster registration. Otherwise, you need to specify this flag separately.
Other flags
--dry_run
- Print commands, but don't execute them.
--fleet_id
- Register a cluster to a fleet using the fleet's host project ID. This flag is
required for non-Google Cloud clusters. When not provided for
Google Cloud clusters, it defaults to the cluster's project ID. You can
run
asmcli install
along with--fleet_id
prior to the installation, or as part of the installation by passing the--enable-registration
and--fleet-id
flags. This setting cannot be changed after it is configured. --managed
- Provision a remote, managed control plane instead of installing one in-cluster.
--offline
- Perform an offline installation using the pre-downloaded package in the output directory. If the directory is not specified or does not contain the required files, the script will exit with error.
--only_enable
- Perform the specified steps to set up the current user/cluster but doesn't install anything.
--only_validate
- Run validation but don't update the project or cluster and don't install
Cloud Service Mesh. This flag is incompatible with the
enablement flags.
asmcli
terminates with an error if you specify--only_validate
with any enablement flag. --print_config
- Instead of installing Cloud 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. --disable_canonical_service
- By default,
asmcli
deploys the Canonical Service controller to your cluster. If you don't wantasmcli
to deploy the controller, specify--disable_canonical_service
. For more information, refer to Enabling and disabling the Canonical Service controller. -h|--help
- Show a help message describing the options and flags and exit.
--use_managed_cni
- Use the managed CNI. If this flag is
not passed,
asmcli
will apply the static CNI manifests. --use_vpcsc
- This flag is no longer required to use VPC Service Controls for your project.
-v|--verbose
- As
asmcli
runs, it prints the command that it will run next. With the--verbose
flag,asmcli
prints the command after execution as well. --version
- Print the version of
asmcli
and exit. If you don't have the most recent version, you can download the most recent version ofasmcli_1.23
.
What's next
Learn about setting up a multi-cluster mesh:
If your mesh consists entirely of GKE clusters, see Set up a multi-cluster mesh on GKE.
If you mesh consists of clusters outside of Google Cloud, see Set up a multi-cluster mesh outside of Google Cloud.