Reference

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}
Enter install if you are doing a new installation of Anthos Service Mesh. Enter migrate if you are migrating from Istio. Enter upgrade to upgrade an existing Anthos Service Mesh installation to a new version.
-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 or mesh_ca. If you can schedule downtime for the migration, we recommend that you use mesh_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 the IstioOperator CR to enable an optional feature. When including one of these files, you don't need to download the anthos-service-mesh package first, and you don't specify the .yaml extension. If you need to modify any of the files, download the anthos-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
-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.
-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 designate a directory to use instead. Upon completion, the specified directory contains the asm and the istio-1.9.8-asm.6 subdirectories. The asm directory contains the configuration for the installation. The istio-1.9.8-asm.6 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, the script uses those files instead of downloading them again.

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 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 the gcloud config get-value core/account command. If you are running the script locally with a user account, make sure that you call the gcloud auth login command before running the script. 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.
--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:

--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 of install_asm_1.9.

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.9.8, you use the version of the install_asm script on the release-1.9-asm branch. For an explanation of the versioning and release process, see Versioning/Release.

Validation

scripts/asm-installer/install_asm 
validate_dependencies() {
  validate_node_pool
  validate_k8s
  validate_expected_control_plane

  if [[ "${MODE}" = "migrate" ]]; then
    validate_istio_version
  elif [[ "${MODE}" = "upgrade" ]]; then
    validate_asm_version
    validate_ca_consistency
  fi
}

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.

scripts/asm-installer/install_asm 
required_iam_roles() {
  # meshconfig.admin - required for init, stackdriver, UI elements, etc.
  # servicemanagement.admin/serviceusage.serviceUsageAdmin - enables APIs
  if can_modify_gcp_components || \
     can_modify_cluster_labels || \
     can_modify_cluster_roles; then
    echo roles/container.admin
  fi
  if can_modify_gcp_components; then
    echo roles/meshconfig.admin
  fi
  if can_modify_gcp_apis; then
    echo roles/servicemanagement.admin
    echo roles/serviceusage.serviceUsageAdmin
  fi
  if can_modify_gcp_iam_roles; then
    echo roles/resourcemanager.projectIamAdmin
  fi
  if is_sa; then
    echo roles/iam.serviceAccountAdmin
  fi
  if can_register_cluster; then
    echo roles/gkehub.admin
  fi
  if [[ "${CA}" = "gcp_cas" ]]; then
    echo roles/privateca.admin
  fi
  if [[ "${_CI_I_AM_A_TEST_ROBOT}" -eq 1 ]]; then
    echo roles/compute.admin
    echo roles/iam.serviceAccountKeyAdmin
  fi
}

Required Google APIs

If you included the --enable_all or --enable_apis flag, the script enables the required APIS:

scripts/asm-installer/install_asm 
required_apis() {
    cat << EOF
container.googleapis.com
monitoring.googleapis.com
logging.googleapis.com
cloudtrace.googleapis.com
meshtelemetry.googleapis.com
meshconfig.googleapis.com
iamcredentials.googleapis.com
gkeconnect.googleapis.com
gkehub.googleapis.com
cloudresourcemanager.googleapis.com
stackdriver.googleapis.com
EOF
  case "${CA}" in
   mesh_ca)
     echo meshca.googleapis.com
     ;;
   gcp_cas)
     echo privateca.googleapis.com
     ;;
    *);;
  esac

  if [[ "${_CI_I_AM_A_TEST_ROBOT}" -eq 1 ]]; then
    echo compute.googleapis.com
  fi
}

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_idlabel 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-198-6 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

What's next