This page describes the available arguments to the script and provides details on the changes that the script makes to your project and GKE cluster.
Options
-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.
-m|--mode {install|migrate|upgrade}
You can use
--mode install
for a new installation, upgrade, or migration from Istio. When you use--mode install
for upgrades or migrations,install_asm
allows the upgrade/migration no matter what version of the control plane is on the cluster. Themigrate
andupgrade
flags only allow upgrades or migrations from the previous minor version or an earlier patch version.If you use
--mode install
for upgrades or migrations, make sure to specify the same certificate authority (CA) that is currently enabled on the cluster. Changing the CA will result in downtime. The--upgrade
flag doesn't allow you to change the CA, which prevents inadvertent downtime.If you are migrating from Istio, you can change the CA and enable Anthos Service Mesh certificate authority (Mesh CA). If you can't schedule downtime for the migration to Mesh CA, there is still a migration path to Mesh CA, but it requires additional steps. For details, see Migrating to Mesh CA.
-c|--ca {mesh_ca|citadel}
For new installations, if you want to use Mesh CA, you don't have to include this option because the script defaults to Mesh CA. For upgrades, you don't need to include this option because the script doesn't allow you to change the CA. For migrations, you specify
citadel
ormesh_ca
. If you can schedule downtime for the migration, we recommend that you usemesh_ca
. For more information about which CA to use, see Choosing a certificate authority. For additional options that you must specify when using Istio CA, see Options for Istio CA custom certificate.--co|--custom_overlay YAML_FILE
The name of the
IstioOperator
custom resource (CR) YAML file to enable a feature that isn't enabled by default. The script must be able to locate the YAML file, so the file either needs to be in the same directory as the script, 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
-o|--option OPTION_FILE
The name of a YAML file from the
anthos-service-mesh
package that contains theIstioOperator
CR to enable an optional feature. When including one of these files, you don't need to download theanthos-service-mesh
package first, and you don't specify the.yaml
extension. If you need to modify any of the files, download theanthos-service-mesh
package, make your changes, and use the--custom_overlay
option. 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, the script 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 theasm
and theistio-1.11.8-asm.4
subdirectories. Theasm
directory contains the configuration for the installation. Theistio-1.11.8-asm.4
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, the script 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
istio.io/rev
. By default, the script sets the value for the revision label based on the Anthos Service Mesh version, for example:asm-1118-4
. Include this option if you want to override the default value and specify your own. TheREVISION NAME
argument must be a DNS-1035 label, and it must consist of lower case alphanumeric characters or-
, start with an alphabetic character, and end with an alphanumeric character (such asmy-name'
, orabc-123
). 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 Citadel 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 the script 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 the script as described
in the Setting up your project and
Setting up your cluster sections of the
Multi-project installation guide. All of these flags are are incompatible with
--only_validate
, and the script terminates with an error in this case.
-e|--enable_all
- Allow the script to perform all of the individual enable actions described below.
--enable_cluster_roles
- Allow the script to attempt to bind the GCP user or service account
running the script to the
cluster-admin
role on your cluster. The script determines the user account from thegcloud config get core/account
command. If you are running the script locally with a user account, make sure that you call thegcloud auth login
command before running the script. 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 the script to set required cluster labels.
--enable_gcp_components
Allow the script 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 the script to enable all required Google APIs.
--enable_gcp_iam_roles
Allow the script to set the required IAM permissions.
--enable_registration
Allow the script 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
--dry_run
- Print commands, but don't execute them.
--only_validate
- 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. The script terminates with an
error if you specify
--only_validate
with any enablement flag. --print_config
- 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. The script skips all validations and setup when you specify this flag.
--disable_canonical_service
- By default, the script deploys the
Canonical Service controller
to your cluster. If you don't want the script 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.
-v|--verbose
- As the script runs, if prints the command that it will run next. With the
--verbose
flag, the script prints the command after execution as well. --version
- Print the version of
install_asm
and exit. If the command doesn't output a version, download the most recent version ofinstall_asm_1.11
.
Understanding the script
Although you download the script from a secure Cloud Source Repositories location,
the script is also available on GitHub so that you can see what it does
before you download it. The script validates that your project and cluster meet
the Anthos Service Mesh requirements, and it automates all the steps that you would do
manually to configure your project and cluster and then install Anthos Service Mesh
using the istioctl install
command.
With Anthos Service Mesh 1.11.8, you use the version of the
install_asm
script on the release-1.11
branch. For an explanation
of the versioning and release process, see
Versioning/Release.
Validation
The install_asm
script verifies that:
- The project ID, cluster name, and cluster location that you entered as parameter values are valid.
- The cluster meets the minimum required machine type and number of nodes.
Setting up your project
Required roles
If you included the --enable_all
or --enable_gcp_iam_roles
flag, the
script sets the required
IAM permissions.
Required Google APIs
If you included the --enable_all
or --enable_apis
flag, the script enables
the required APIS:
Setting up your cluster
The script does the following updates to your cluster if you have included the
--enable_all
flag, or one of the more granular
enablement flags listed below:
Cluster update | Flag |
---|---|
Enables Workload Identity, which lets GKE applications safely access Google Cloud services. | --enable_gcp_components |
Enables Cloud Monitoring and Cloud Logging on GKE. | --enable_gcp_components |
Sets the mesh_id label on the cluster, which is required for
metrics to get displayed on the Anthos Service Mesh pages in the
Google Cloud console.
|
--enable_cluster_labels |
Sets a label like asmv=asm-1118-4 so that you can
tell that the cluster was modified by the script.
|
--enable_cluster_labels |
Binds the GCP user or service account running the script to the `cluster-admin` role on your cluster. | --enable_cluster_roles |