asmcli reference

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.

Overview

Theasmcli is a Google-provided tool that you can use to install orupgrade Cloud Service Mesh. If you let it,asmcli will configure yourproject and cluster as follows:

• Grant you the required Identity and Access Management (IAM) permissions on yourGoogle Cloud project.
• Enable the required Google APIs on your Google Cloud project.
• Set a label on the cluster that identifies the mesh.
• Create a service account that lets data plane components, suchas the sidecar proxy, securely access your project's data and resources.
• Register the clusterto the fleet if it isn't already registered.

Just include the--enable_all flag when you runasmcli to let it configureyour project and cluster. For more information aboutasmcli options and flags,see theasmcli reference.

Next,asmcli configures YAML files with your project and cluster information.These configuration files are needed to install the Cloud Service Meshcontrol plane.

If you are new to Cloud Service Mesh and Istio, skip ahead toSupported platforms. The next section is intended tohelp existing Cloud Service Mesh upgrade to 1.23.

Transitioning toasmcli

Theasmcli takes the place ofistioctl install andinstall_asm. Althoughyou can still use the legacy tools in Cloud Service Mesh 1.11, we are deprecatingthem and they will no longer be supported in Cloud Service Mesh 1.12 and later.Please update your scripts and tools to useasmcli.

All clusters must be registered to afleet. SeeFleet requirementsfor details.

Transitioning frominstall_asm

If you are familiar withinstall_asm,asmcli is similar but with thefollowing notable differences:

• You useasmcli install for new installations and upgrades.There isn't a--mode option like withinstall_asm. When you runasmcli install, it checks to see ifthere's an existing control plane on the cluster. If there isn't an existingcontrol plane,asmcli installs Cloud Service Mesh. If the cluster has anexisting control plane (either a Cloud Service Mesh control plane or an open sourceIstio control plane):

  • If therevision label on the existingcontrol plane doesn't match the revision label for the new control plane,asmcli does acanary upgrade.

  • If the control plane revision labels are the same,asmcli does anin-place upgrade.

• Most of theasmclioptions and flags behave the sameas the ones forinstall_asm.

Transitioning fromistioctl install

If you are familiar withistioctl install, if you normally pass anIstioOperator YAML file via the-f command-line argument to configure thecontrol plane, you can pass the file toasmcli using the--custom_overlayoption. In the Cloud Service Mesh documentation, we refer to these files asoverlay files.

Note: By default,asmcli doesn't install an ingress gateway with the controlplane. For production deployments, we recommend that you install gatewaysseparately. For more information and best practices, seeInstall and upgrade gateways.We have provided sample Deployment, Service, ServiceAccount, and Roleconfiguration files in theanthos-service-mesh repository for both ingress and egress gateways to get you started. You candeploy them as they are or customize them as needed.

Supported platforms

Deprecated: Configuring Cloud Service Mesh with asmcli for Managed controlplane for GKE on Google Cloud is deprecated. For more information, see theCloud Service Mesh release notes.To configure Managed Cloud Service Mesh for GKE follow thisguide.

Cloud Service Mesh installations on the list ofSupported platforms can be configuredor upgraded byasmcli.

However, not all features are available on the platforms outside of Google Cloud.For details, seeIn-cluster control plane supported features.

asmcli reference

This section describes the available arguments toasmcli.

Note: Run the command./asmcli -h -v to view a full list of available flagsand options along with their descriptions.

Options

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

-c|--ca {mesh_ca|gcp_cas|citadel}

The certificate authority (CA) to use to managemutual TLS certificates. Specifymesh_ca to use Cloud Service Mesh certificate authority (Cloud Service Mesh certificate authority),gcp_casto useCertificate Authority Service, orcitadel to use the Istio CA. Managed Cloud Service Mesh does not support IstioCA.See the following for additional information:

• Choose a certificate authority
• Options for Istio CA custom certificate
• Configure Cloud Service Mesh to use CA Service

--channelCLOUD_SERVICE_MESH_CHANNEL

Use--channel with a specificCloud Service Mesh release channelto provision the Control Plane revision associated with that release channel.For example,--channel rapid,--channel regular, and--channel stable.This flag is required when configuring certain Cloud Service Mesh features onGKE Autopilot clusters.

--channel option is no longer supported for Managed Cloud Service Mesh asmentioned inCSM Release Notes.Release channel is determined based on your GKE cluster release channel.For more information, seeManaged Cloud Service Mesh release channels.

--co|--custom_overlayOVERLAY_FILE

Use--custom_overly with the name of a YAML file (referred to as anoverlay file) containing theIstioOperator custom resource to configurethe in-cluster control plane. You specify an overlay file toenable a featurethat isn't enabled by default. Managed Cloud Service Mesh doesn't support theIstioOperator API, so you can't use--custom_overlay to configure themanaged control plane.asmcli must be able to locate the overlay file, so iteither needs to be in the same directory asasmcli, or you can specify arelative 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-flagsHUB_REGISTRATION_EXTRA_FLAGS

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

-k|--key_fileFILE_PATH

The key file for a service account. Omit this option if you aren't usinga service account.

--network_idNETWORK_ID

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

-o|--optionOVERLAY_FILE

The name of the overlay file (without the.yaml extension) thatasmclidownloads from theanthos-service-mesh repository to enable anoptional feature. You need internet connectivity to use--option. The--option and--custom_overlay options are similar, but they have slightlydifferent behavior:

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

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

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

-D|--output_dirDIR_PATH

If not specified,asmcli creates a temporary directory where itdownloads files and configurations necessary for installing Cloud Service Mesh.Specify the--output-dir flag to specify a relative path to a directory to useinstead. Upon completion, the specified directory contains theasm andtheistio-1.23.6-asm.11 subdirectories. Theasm directorycontains the configuration for the installation. Theistio-1.23.6-asm.11 directory contains the extracted contents ofinstallation file, which containsistioctl, samples, and manifests. If youspecify--output-dir and the directory already contains the necessaryfiles,asmcli uses those files instead of downloading them again.

--platformPLATFORM {gcp|multicloud}

The platform or the provider of the Kubernetes cluster. Defaults togcp (for GKE clusters). For all otherplatforms use,multicloud.

-r|--revision_nameREVISION NAME

Arevision label is a key-value pair thatis set on the control plane. The revision label key is alwaysistio.io/rev. Bydefault,asmcli sets the value for the revision label based on theCloud Service Mesh version, for example:asm-1236-11. Include thisoption if you want to override the default value and specify your own. TheREVISION NAME argument must be aDNS-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_accountACCOUNT

The name of a service account used to install Cloud Service Mesh. If notspecified, the active user account in the currentgcloud configuration isused. If you need to change the active user account, rungcloud auth login.

Options for Istio CA custom certificate

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

• --ca_certFILE_PATH: The intermediate certificate
• --ca_keyFILE_PATH: The key for the intermediate certificate
• --root_certFILE_PATH: The root certificate
• --cert_chainFILE_PATH: The certificate chain

For more information, seePlugging in existing CA Certificates.

Enablement flags

The flags that start with--enable letasmcli enable the required GoogleAPIs, setrequired Identity and Access Management (IAM) permissions,and update your cluster. If you prefer, you canupdate your project and cluster yourselfbefore runningasmcli. All of the enablement flags are incompatible withasmcli validate. If you specify an enablement flag when you runasmcli validate, the command terminates with an error.

-e|--enable_all

Allowasmcli to perform all of the individual enable actions describedbelow.

--enable_cluster_roles

Allowasmcli to attempt to bind the Google Cloud user or serviceaccount runningasmcli to thecluster-adminrole on your cluster.asmcli determines the user account from thegcloud config get core/accountcommand. If you are runningasmcli locally with a user account, make surethat you call thegcloud auth logincommand before runningasmcli. If you need to change the user account,run thegcloud config set core/accountGCP_EMAIL_ADDRESScommand whereGCP_EMAIL_ADDRESS is the account that you useto log in to Google Cloud.

--enable_cluster_labels

Allowasmcli to set requiredcluster labels.

--enable_gcp_components

Allowasmcli to enable the following required Google Cloud managedservices and components:

• Workload Identity,which lets GKE applications safely access Google Cloudservices.

• Cloud Monitoring and Cloud Logging onGKE.

--enable_gcp_apis

Allowasmcli to enable allrequired Google APIs.

--enable_gcp_iam_roles

Allowasmcli to set the requiredIAM permissions.

--enable_meshconfig_init

Allow the script to initialize the meshconfig endpoint on your behalf. Impliedby--enable_gcp_components and--managed.

--enable_namespace_creation

Allowasmcli to create the rootistio-system namespace.

--enable_registration

Allowasmcli to register the cluster to the project that the cluster isin. If you don't include this flag, follow the steps inRegistering a clusterto manually register the cluster. Note that unlike the other enablement flags,--enable_registration is only included in--enable_all when you specifyan 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 isrequired for non-Google Cloud clusters. When not provided forGoogle Cloud clusters, it defaults to the cluster's project ID. You canrunasmcli install along with--fleet_id prior to the installation, or aspart of the installation by passing the--enable-registration and--fleet-idflags. This setting cannot be changed after it is configured.

--managed

Deprecated. Provision a remote, managed control plane instead of installingone in-cluster.

--offline

Perform anoffline installationusing the pre-downloaded package in the output directory. If the directory isnot specified or does not contain the required files, the script will exitwith error.

--only_enable

Perform the specified steps to set up the current user/cluster but doesn'tinstall anything.

--only_validate

Run validation but don't update the project or cluster and don't installCloud Service Mesh. This flag is incompatible with theenablement flags.asmcli terminates with anerror if you specify--only_validate with any enablement flag.

--print_config

Instead of installing Cloud Service Mesh, print all of the compiled YAML tostandard output (stdout). All other output is written to standard error(stderr), even if it would normally go to stdout.asmcli skips allvalidations and setup when you specify this flag.

--disable_canonical_service

By default,asmcli deploys theCanonical Service controller to your cluster. If you don't wantasmcli to deploy the controller,specify--disable_canonical_service. For more information, refer toEnabling 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 isnot passed,asmcli will apply the static CNI manifests.

--use_vpcsc

If your organization enforcesVPC Service Controls for your project, you mustconfigure managed Cloud Service Mesh with the--use_vpcsc flag. Otherwise theinstallation will fail security controls.

-v|--verbose

Asasmcli 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 ofasmcli and exit. If you don't have the most recentversion, you candownloadthe most recent version ofasmcli_1.23.