This page explains how to run the script to install Anthos Service Mesh version 1.8.6 on a GKE cluster for a mesh containing one or more clusters that are in the same Cloud project.
For a multi-cluster mesh where the clusters are in different projects, see Multi-cluster/multi-project installation and migration for GKE.
This page is for installations of Anthos Service Mesh: either new installations or reinstalling the same version with another configuration.
Although running the script for new installs is similar for reinstallations of the same version, upgrades and migrations from Istio, those use cases involve additional planning. For information see the following:
Before you begin
Before you begin the installation, make sure that you have:
- Reviewed the requirements
- Chosen a certificate authority (CA)
- Registered your cluster
- Installed the required tools
- Downloaded the script
The script requires that you have the
required permissions, or that you
include either the --enable_all
or --enable_gcp_iam_roles
flags
to allow the script to enable the permission for you. Similarly, to allow the
script to enable the
required APIs
and update your cluster,
specify the --enable_all
flag or the more granular
enablement flags.
Installing Anthos Service Mesh
Set the options and specify the flags to run the script. You always include the following options:
--project_id
,--cluster_name
,--cluster_location
, and--mode install
. If you want to use Citadel as the CA, you need to specify the--ca
option and some other options, as described in Installation with Citadel as the CA. For a complete description of the script's arguments, see Option and flags.To complete setting up Anthos Service Mesh, you need to enable automatic sidecar injection and deploy or redeploy workloads.
The following section provides typical examples for running the script. See the navigation bar on the right for a list of the examples.
Examples
This section shows examples of running the script for an installation with some additional arguments that you might find useful. See the navigation bar on the right for a list of the examples.
Only validate
The following example shows running the script with the --only_validate
option. With this option, the script doesn't make any changes to your project or
cluster, and it doesn't install Anthos Service Mesh. When you specify
--only_validate
,the script fails if you include any of the
--enable_*
flags.
The script validates that:
- Your environment has the required tools.
- You have the required permission on the specified project.
- The cluster meets the minimum requirements.
- The project has all the required Google APIs enabled.
By default, the script downloads and extracts the installation file and
downloads the
asm
configuration package from GitHub to a temp directory. Before exiting,
the script outputs a message that provides the name of the temp directory.
You can specify an existing directory for the downloads with the
--output_dir DIR_PATH
option. The --output_dir
option makes it convenient for you to use the istioctl
command-line tool
if you need it. Additionally, the configuration files to enable optional
features are included in the asm/istio/options
directory.
Run the following command to validate your configuration and download the
installation file and asm
package to the OUTPUT_DIR
directory:
./install_asm \ --project_id PROJECT_ID \ --cluster_name CLUSTER_NAME \ --cluster_location CLUSTER_LOCATION \ --mode install \ --output_dir DIR_PATH \ --only_validate
On success, the script outputs the following:
./install_asm \ install_asm: Setting up necessary files... install_asm: Creating temp directory... install_asm: Generating a new kubeconfig... install_asm: Checking installation tool dependencies... install_asm: Downloading ASM.. % Total % Received % Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed 100 57.0M 100 57.0M 0 0 30.6M 0 0:00:01 0:00:01 --:--:-- 30.6M install_asm: Downloading ASM kpt package... fetching package /asm from https://github.com/GoogleCloudPlatform/anthos-service-mesh-packages to asm install_asm: Checking for project PROJECT_ID... install_asm: Confirming cluster information... install_asm: Confirming node pool requirements... install_asm: Fetching/writing GCP credentials to kubeconfig file... Fetching cluster endpoint and auth data. kubeconfig entry generated for cluster-1. install_asm: Checking Istio installations... install_asm: Checking required APIs... install_asm: Successfully validated all requirements to install ASM from this computer.
If one of the tests fails the validation, the script outputs an error message. For example, if your project doesn't have all of the required Google APIs enabled, you see the following error:
ERROR: One or more APIs are not enabled. Please enable them and retry, or run the script with the '--enable_gcp_apis' flag to allow the script to enable them on your behalf.
If you got an error message about needing to run the script with an
enablement flag,
you can include the specific flag from the error message or the --enable_all
flag when running the script without --only_validate
. 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.
Installation
The following command runs the script for a new installation, enables
Mesh CA, which is the default CA for installs, so you
don't need the --ca
option in this case. The
--enable_all
flag
allows the script to enable the required Google APIs, set Identity and Access Management
permissions, and make the required updates to your cluster, which includes
enabling
GKE Workload Identity.
If you plan to use Mesh CA, you can use the fleet workload identity pool as an alternative to GKE workload identity. For an example, see Enable Mesh CA with the fleet workload identity pool.
./install_asm \ --project_id PROJECT_ID \ --cluster_name CLUSTER_NAME \ --cluster_location CLUSTER_LOCATION \ --mode install \ --enable_all
You might also want to include the following:
--output_dir DIR_PATH
If you didn't run the only validate example, include this option to specify an existing directory where the script downloads theasm
package and the Anthos Service Mesh installation file, which containsistioctl
, samples, and manifests. Otherwise the script downloads theasm
package and installation file to a temp directory.--enable-registration
This flag allows 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 your cluster.
Installation with Citadel as the CA
This section explains how to:
- Generate certificates and keys that Anthos Service Mesh uses to sign your workloads.
- Run the script for an installation and enable Citadel as the CA.
We recommend that you use Citadel as the CA only when you need a custom CA.
For the best security, we highly recommend maintaining an offline root CA and using the subordinate CAs to issue CAs for each cluster. For more information, see Plug in CA Certificates. In this configuration, all workloads in the service mesh use the same root CA. Each Anthos Service Mesh CA uses an intermediate CA signing key and certificate, signed by the root CA. When multiple CAs exist within a mesh, this establishes a hierarchy of trust among the CAs. You can repeat these steps to provision certificates and keys for any number of certificate authorities.
Create a directory for the certificates and keys:
mkdir -p certs && \ pushd certs
Generate a root certificate and key:
make -f ../tools/certs/Makefile.selfsigned.mk root-ca
This generates these files:
- root-cert.pem: the root certificate
- root-key.pem: the root key
- root-ca.conf: the configuration for openssl to generate the root certificate
- root-cert.csr: the CSR for the root certificate
Generate an intermediate certificate and key:
make -f ../tools/certs/Makefile.selfsigned.mk cluster1-cacerts
This generates these files in a directory named
cluster1
:- ca-cert.pem: the intermediate certificates
- ca-key.pem: the intermediate key
- cert-chain.pem: the certificate chain which istiod uses
- root-cert.pem: the root certificate
If you perform these steps using an offline computer, copy the generated directory to the computer where you are running the script.
Run the script and include the files that you generated previously for the certificates and key.
./install_asm \ --project_id PROJECT_ID \ --cluster_name CLUSTER_NAME \ --cluster_location CLUSTER_LOCATION \ --mode install \ --ca citadel \ --ca_cert FILE_PATH \ --ca_key FILE_PATH \ --root_cert FILE_PATH \ --cert_chain FILE_PATH \ --enable_all
Installation with an overlay file
An overlay file is a YAML file containing an IstioOperator
custom resource
(CR) that you pass to install_asm
to configure the control plane. You can
override the default control plane configuration and
enable an optional feature by passing
the YAML file to install_asm
. You can layer on more overlays, and each overlay
file overrides the configuration on the previous layers.
If you specify more than one CR in a YAML file, install_asm
splits the file
into multiple temporary YAML files, one for each CR. The script splits the
CRs into separate files because istioctl install
only applies the first CR in
a YAML file containing more than one CR.
The following example does an installation and includes an overlay file to
customize the control plane configuration. In the following command, change
OVERLAY_FILE
to the name of the YAML file.
./install_asm \ --project_id PROJECT_ID \ --cluster_name CLUSTER_NAME \ --cluster_location CLUSTER_LOCATION \ --mode install \ --enable_all \ --custom_overlay OVERLAY_FILE
Installation with an option
The following example does an installation and includes the
egressgateways.yaml
file from the
asm
package, which enables an egress gateway. Note that you don't include the
.yaml
extension. The script fetches the file for you so you don't have to
download the asm
package first.
./install_asm \ --project_id PROJECT_ID \ --cluster_name CLUSTER_NAME \ --cluster_location CLUSTER_LOCATION \ --mode install \ --enable_all \ --option egressgateways
You can use --option
to
enable an optional feature. If you
need to make modifications to any of the files in the asm/istio/options
directory in the asm
package, download the asm
package, make your changes,
and include the file using --custom_overlay
.
To download the asm
package to the current working directory so you can
make modifications to the files:
kpt pkg get \
https://github.com/GoogleCloudPlatform/anthos-service-mesh-packages.git/asm@release-1.8-asm asm
If you ran the Only validate example where you specified
the --output_dir
option, then the configuration files are in the specified
output directory under asm/istio/options
.
Enable Mesh CA with fleet
The preview of Mesh CA with fleet is limited to new installations of Anthos Service Mesh on GKE. Upgrades and migrations aren't supported during the preview.
This example shows you how to enable Mesh CA to use the fleet workload identity pool. Mesh CA with fleet lets you join clusters in separate Google Cloud projects to a single trust domain corresponding to the fleet.
To enable Mesh CA with fleet:
If you haven't already
registered your cluster,
be sure to include the --enable-registration
flag as shown in the following
example:
./install_asm \
--project_id PROJECT_ID \
--cluster_name CLUSTER_NAME \
--cluster_location CLUSTER_LOCATION \
--mode install \
--enable_all \
--enable-registration \
--option hub-meshca
This command runs the script for a new installation, configures your project and cluster with the options required by Anthos Service Mesh, registers the cluster to the project that the cluster is in, and configures Mesh CA to use the fleet workload identity pool.
Deploying and redeploying workloads
Anthos Service Mesh uses sidecar proxies to enhance network security, reliability, and observability. With Anthos Service Mesh, these functions are abstracted away from the application's primary container and implemented in a common out-of-process proxy delivered as a separate container in the same Pod.
Your installation isn't complete until you enable automatic sidecar proxy injection (auto-injection) and restart the Pods for any workloads that were running on your cluster before you installed Anthos Service Mesh.
To enable auto-injection, you label your namespaces with the revision label
that was set on istiod
when you installed Anthos Service Mesh. The revision label is
used by the sidecar injector webhook to associate injected sidecars with a
particular istiod
revision. After adding the label, any existing Pods in the
namespace must be restarted for sidecars to be injected.
Before you deploy new workloads in a new namespace, make sure to configure auto-injection so that Anthos Service Mesh can monitor and secure traffic.
To enable auto-injection:
Use the following command to locate the revision label on
istiod
:kubectl -n istio-system get pods -l app=istiod --show-labels
The output looks similar to the following:
NAME READY STATUS RESTARTS AGE LABELS istiod-asm-186-8-5788d57586-bljj4 1/1 Running 0 23h app=istiod,istio.io/rev=asm-186-8,istio=istiod,pod-template-hash=5788d57586 istiod-asm-186-8-5788d57586-vsklm 1/1 Running 1 23h app=istiod,istio.io/rev=asm-186-8,istio=istiod,pod-template-hash=5788d57586
In the output, under the
LABELS
column, note the value of theistiod
revision label, which follows the prefixistio.io/rev=
. In this example, the value isasm-186-8
.Apply the revision label and remove the
istio-injection
label if it exists. In the following command,NAMESPACE
is the name of the namespace where you want to enable auto-injection, andREVISION
is the revision label you noted in the previous step.kubectl label namespace NAMESPACE istio-injection- istio.io/rev=REVISION --overwrite
You can ignore the message
"istio-injection not found"
in the output. That means that the namespace didn't previously have theistio-injection
label, which you should expect in new installations of Anthos Service Mesh or new deployments. Because auto-injection fails if a namespace has both theistio-injection
and the revision label, allkubectl label
commands in the Anthos Service Mesh documentation include removing theistio-injection
label.If workloads were running on your cluster before you installed Anthos Service Mesh, restart the Pods to trigger re-injection.
How you restart Pods depends on your application and the environment the cluster is in. For example, in your staging environment, you might simply delete all the Pods, which causes them to restart. But in your production environment, you might have a process that implements a blue-green deployment so that you can safely restart Pods to avoid traffic interruption.
You can use
kubectl
to perform a rolling restart:kubectl rollout restart deployment -n NAMESPACE
Verify that your Pods are configured to point to the new version of
istiod
.kubectl get pods -n NAMESPACE -l istio.io/rev=REVISION
Viewing the Anthos Service Mesh dashboards
After you have workloads deployed on your cluster with the sidecar proxies injected, you can explore the Anthos Service Mesh pages in the Google Cloud console to see all of the observability features that Anthos Service Mesh offers. Note that it takes about one or two minutes for telemetry data to be displayed in the Google Cloud console after you deploy workloads.
Access to Anthos Service Mesh in the Google Cloud console is controlled by Identity and Access Management (IAM). To access the Anthos Service Mesh pages, a Project Owner must grant users the Project Editor or Viewer role, or the more restrictive roles described in Controlling access to Anthos Service Mesh in the Google Cloud console.
In the Google Cloud console, go to Anthos Service Mesh.
Select the Cloud project from the drop-down list on the menu bar.
If you have more than one service mesh, select the mesh from the Service Mesh drop-down list.
To learn more, see Exploring Anthos Service Mesh in the Google Cloud console.
In addition to the Anthos Service Mesh pages, metrics related to your services (such as the number of requests received by a particular service) are sent to Cloud Monitoring, where they appear in the Metrics Explorer.
To view metrics:
In the Google Cloud console, go to the Monitoring page:
Select Resources > Metrics Explorer.
For a full list of metrics, see Istio metrics in the Cloud Monitoring documentation.