This guide explains how to do a clean installation of Anthos Service Mesh version 1.5.10-asm.2 on an existing Google Cloud GKE cluster using the GKE Enterprise command-line interface (CLI). Note the following limitations with this beta version of the GKE Enterprise CLI:
- Upgrades aren't supported. If you have a previous version of Anthos Service Mesh installed on your cluster, refer to Upgrading Anthos Service Mesh on GKE.
- Installations on GKE on VMware aren't supported. To install Anthos Service Mesh on an existing GKE on VMware cluster, refer to Installing Anthos Service Mesh on premises.
The installation enables the following features:
- Mesh telemetry.
- Mesh security, including Anthos Service Mesh certificate authority (Mesh CA).
- The Supported default features listed on the Supported features page.
This guide also explains how to register your cluster in the fleet that is in the same Google Cloud project as the cluster. A fleet lets you organize clusters to make multi-cluster management easier. By registering your clusters in a fleet, you can group services and other infrastructure as needed to apply consistent policies.
Before you begin
Before you start the installation:
- Set up your environment.
- Install the GKE Enterprise CLI.
- Review the following requirements and restrictions.
Requirements
You must have an GKE Enterprise trial license or subscription. See the GKE Enterprise Pricing guide for details.
Your GKE cluster must meet the following requirements:
- At least four nodes.
- The minimum machine type
is
e2-standard-4
, which has four vCPUs. - Use a release channel rather than a static version of GKE
To be included in the service mesh, service ports must be named, and the name must include the port's protocol in the following syntax:
name: protocol[-suffix]
where the square brackets indicate an optional suffix that must start with a dash. For more information, Naming service ports.If you are installing Anthos Service Mesh on a private cluster, you must add a firewall rule to open port 15017 if you want to use automatic sidecar injection. If you don't add the firewall rule and automatic sidecar injection is enabled, you get an error when you deploy workloads. For details on adding a firewall rule, see Adding firewall rules for specific use cases.
If you have created a service perimeter in your organization, you might need to add the Mesh CA service to the perimeter. See Adding Mesh CA to a service perimeter for more information.
Restrictions
Only one installation of Anthos Service Mesh per Google Cloud project is supported. Multiple mesh deployments in a single project aren't supported.
Certificate data
Certificates from Mesh CA include the following data about your application's services:
- The Google Cloud project ID
- The GKE namespace
- The GKE service account name
Setting project and cluster defaults
Get the project ID of the project that the cluster was created in:
gcloud
gcloud projects list
Console
In the Google Cloud console, go to the Dashboard page:
Click the Select from drop-down list at the top of the page. In the Select from window that appears, select your project. The project ID is displayed on the project Dashboard Project info card.
Create an environment variable for the project ID:
export PROJECT_ID=
YOUR_PROJECT_ID
Set the default project ID for the Google Cloud CLI:
gcloud config set project ${PROJECT_ID}
Create the following environment variables:
Set the cluster name:
export CLUSTER_NAME=YOUR_CLUSTER_NAME
Set the
CLUSTER_LOCATION
to either your cluster zone or cluster region:export CLUSTER_LOCATION=YOUR_ZONE_OR_REGION
Set the default zone or region for the Google Cloud CLI.
If you have a single-zone cluster, set the default zone:
gcloud config set compute/zone ${CLUSTER_LOCATION}
If you have a regional cluster, set the default region:
gcloud config set compute/region ${CLUSTER_LOCATION}
Preparing resource configuration files
You use the GKE Enterprise CLI and kustomize
to export and patch
Config Connector resource files that
you will use to update an existing cluster with the options required by
Anthos Service Mesh. The Config Connector resource is the Kubernetes representation of
Google Cloud resources.
Export resource configuration files
You use the gcloud beta anthos export
command to output resource configuration files
for an existing cluster.
Create a directory for the Anthos Service Mesh resources. For convenience, the following steps refer to the directory you create as ASM_RESOURCES.
Change to the ASM_RESOURCES directory.
Download the
asm-patch
package to the current working directory:kpt pkg get \ https://github.com/GoogleCloudPlatform/anthos-service-mesh-packages.git/asm-patch@release-1.5-asm .
The command creates a subdirectory called
asm-patch/
.Add a directory name in an environment variable called
BASE_DIR
. When you run thegcloud beta anthos export
command against an existing cluster, the GKE Enterprise CLI creates a directory with the name specified inBASE_DIR
and outputs the Config Connector resource files to the directory.export BASE_DIR=YOUR_BASE_DIR
If you will be setting up more than one cluster, we recommend that you use the cluster name as the directory name. For example, if you are preparing resource configuration files for two clusters, after you run the
gcloud beta anthos export
command forcluster-1
andcluster-2
, your directory structure should be similar to the following:In the diagram,
cluster-1
andcluster-2
are directories that contain the Config Connector resource configuration files for the clusters namedcluster-1
andcluster-2
.Export the Config Connector resource configuration files:
gcloud beta anthos export ${CLUSTER_NAME} --output-directory ${BASE_DIR}
The
export
command populates the project ID and your cluster zone/region in the resource configuration files for your cluster to match your currentgcloud config
settings. If you want to export resource configuration files for a cluster that doesn't match your currentgcloud config
settings, you can specify the following command-line options:-p PROJECT_ID
-l YOUR_ZONE_OR_REGION
Check
gcloud beta anthos export --help
for more details.
Patch the resource configuration files
You use the GKE Enterprise kpt
setters and kustomize
to update
the resource configuration files.
List the available configuration setters in the
asm-patch
package:kpt cfg list-setters asm-patch/
The output is similar to the following:
NAME VALUE SET BY DESCRIPTION COUNT base-dir base 1 gcloud.compute.location your_zone_or_region 1 gcloud.container.cluster your_cluster_name 3 gcloud.core.project your_project_id kpt 11 gcloud.project.projectNumber your_project_number kpt 1
Set the relative path between the
${BASE_DIR}
and theasm-patch
directories:kpt cfg set asm-patch/ base-dir ../${BASE_DIR}
Set the cluster name:
kpt cfg set asm-patch/ gcloud.container.cluster ${CLUSTER_NAME}
If you haven't set the
gcloud config
defaults, or if you want to change the values, run the following setters:kpt cfg set asm-patch/ gcloud.compute.location ${CLUSTER_LOCATION}
kpt cfg set asm-patch/ gcloud.core.project ${PROJECT_ID}
Apply the Anthos Service Mesh patches to the cluster resource configuration files:
pushd ${BASE_DIR} && kustomize create --autodetect \ --namespace ${PROJECT_ID} && popd
pushd asm-patch && kustomize build -o ../${BASE_DIR}/all.yaml && popd
Validate the final resource configurations:
kpt fn source ${BASE_DIR} | kpt fn run --image gcr.io/kustomize-functions/validate-asm:v0.1.0
If there are any errors, fix them and validate the resource configurations again.
Optionally, you can check in the resource configuration files to your own source control system, such as Cloud Source Repositories, so that you can track changes to the files.
Updating your cluster and installing Anthos Service Mesh
The GKE Enterprise CLI updates your cluster with the following options, which are required by Anthos Service Mesh:
Adds a
mesh_id
label to the cluster in the formatproj-PROJECT_NUMBER
, wherePROJECT_NUMBER
is the project number of the project that the cluster was created in. Themesh_id
label is required for metrics to get displayed on the Anthos Service Mesh dashboard in the Google Cloud console. If your cluster has existing labels, the GKE Enterprise CLI preserves them.Enables Workload Identity.
Enables Kubernetes Engine Monitoring.
Enrolls the cluster in a release channel overview.
Run the following command to update the cluster and install Anthos Service Mesh:
gcloud beta anthos apply ${BASE_DIR}
The command updates your cluster with the required options and then deploys Anthos Service Mesh. This process takes about 30 minutes to complete.
Checking the control plane components
Check that the control plane pods in istio-system
are up:
kubectl get pod -n istio-system
Expected output is similar to the following:
NAME READY STATUS RESTARTS AGE istio-ingressgateway-74cc894bfd-786rg 1/1 Running 0 7m19s istiod-78cdbbbdb-d7tps 1/1 Running 0 7m36s promsd-576b8db4d6-lqf64 2/2 Running 1 7m19s
Registering your cluster
You must register your cluster with the project's fleet to gain access to the unified user interface in the Google Cloud console. A fleet provides a unified way to view and manage the clusters and their workloads, including clusters outside Google Cloud.
Create a Google Cloud service account and key file
A JSON file containing service account credentials is required to register a cluster. To follow the principle of least privilege, we recommend that you create a distinct service account for each cluster that you register.
To create a service account and key file:
Select a name for the service account and create an environment variable for it:
export SERVICE_ACCOUNT_NAME=SERVICE_ACCOUNT_NAME
Create the service account:
gcloud iam service-accounts create ${SERVICE_ACCOUNT_NAME}
List all of a project's service accounts to confirm the service account was created:
gcloud iam service-accounts list
Bind the gkehub.connect IAM role to the service account:
gcloud projects add-iam-policy-binding ${PROJECT_ID} \ --member="serviceAccount:${SERVICE_ACCOUNT_NAME}@${PROJECT_ID}.iam.gserviceaccount.com" \ --role="roles/gkehub.connect"
Create an environment variable for the local filepath where you want to save the JSON file. We recommend that you name the file using the service account name and your project ID, such as:
/tmp/creds/${SERVICE_ACCOUNT_NAME}-${PROJECT_ID}.json
export SERVICE_ACCOUNT_KEY_PATH=LOCAL_KEY_PATH
Download the service account's private key JSON file:
gcloud iam service-accounts keys create ${SERVICE_ACCOUNT_KEY_PATH} \ --iam-account=${SERVICE_ACCOUNT_NAME}@${PROJECT_ID}.iam.gserviceaccount.com
Register the cluster
In the following command, replace MEMBERSHIP_NAME
with a name that uniquely represents the cluster being registered on the Hub.
gcloud container hub memberships register MEMBERSHIP_NAME \ --gke-cluster=${CLUSTER_LOCATION}/${CLUSTER_NAME} \ --service-account-key-file=${SERVICE_ACCOUNT_KEY_PATH}
The command responds with output similar to the following:
kubeconfig entry generated for CLUSTER_NAME. Waiting for membership to be created...done. Created a new membership [projects/PROJECT_ID/locations/global/memberships/MEMBERSHIP_NAME] for the cluster [MEMBERSHIP_NAME] Generating the Connect Agent manifest... Deploying the Connect Agent on cluster [MEMBERSHIP_NAME] in namespace [gke-connect]... Deployed the Connect Agent on cluster [MEMBERSHIP_NAME] in namespace [gke-connect]. Finished registering the cluster [MEMBERSHIP_NAME] with the Hub.
This service account key is stored as a secret named creds-gcp
in the
gke-connect
namespace.
For more information about cluster registration, see Registering a cluster in the Connect documentation.
Injecting sidecar proxies
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.
Any workloads that were running on your cluster before you installed Anthos Service Mesh need to have the sidecar proxy injected or updated so they have the current Anthos Service Mesh version. Before you deploy new workloads, make sure to configure sidecar proxy injection so that Anthos Service Mesh can monitor and secure traffic.You can enable automatic sidecar injection with one command, for example:
kubectl label namespace NAMESPACE istio-injection=enabled --overwrite
where NAMESPACE
is the name of the
namespace
for your application's services or default
if you didn't explicitly create
a namespace.
For more information, see Injecting sidecar proxies.
Viewing the Anthos Service Mesh pages
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 Google 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.
Installing a sample using kpt
Optionally, you can use kpt
to install the Hipster sample into the cluster.
Download the sample:
kpt pkg get \ https://github.com/GoogleCloudPlatform/microservices-demo.git/release \ hipster-demo
Enable automatic sidecar injection:
kubectl label namespace default istio-injection=enabled
Deploy the sample to the cluster:
kubectl apply -f hipster-demo
Find the external IP address of your application:
kubectl get service frontend-external
Visit the application on your browser to confirm installation:
http://EXTERNAL_IP/
Now that you have a sample running, you can explore the Anthos Service Mesh observability features in the Google Cloud console. Note that it can take up to 10 minutes for the topology graph to display the services in your mesh.
When you're finished exploring, remove the Hipster sample:
kubectl delete -f hipster-demo
What's next
Learn more about the configuration resources used by the GKE Enterprise CLI: