Prepare to set up on service routing APIs with Envoy andproxyless workloads

This document provides information on the prerequisite tasks for setting upCloud Service Mesh using the service routing APIs with Envoy proxies orwith proxyless gRPC as the dataplane.

Setting up Cloud Service Mesh includes several phases. This documentdescribes the first phase: instructions for preparing to configureCloud Service Mesh with VM instances or proxyless gRPC applications.The additional phases are covered by the platform-specific guides listed inContinue the setup process later in this document.

Before you read this guide, familiarize yourself with the following documents,which provide an overview of using Cloud Service Mesh with the servicerouting APIs and Gateway APIs:

• Cloud Service Mesh overview
• Cloud Service Mesh service routing APIs overview

Prerequisites

Prepare your environment by completing the following tasks:

1. Set up projects to suit your business needs.
2. Enable billing.
3. Grant the required permissions.
4. Enable the Traffic Director API and other APIs for your project.
5. Ensure that the service account has sufficient permissions to access theTraffic Director API.
6. Enable the Cloud DNS API and configure Cloud DNS.

The following sections provide instructions for each task.

Set up projects

To set up and manage your projects, seeCreating and managing projectsand related documentation.

Enable billing

Make sure that billing is enabled for your Google Cloud project. For moreinformation, seeEnable, disable, or change billing for a project.

Grant the required IAM permissions

You must have sufficient Identity and Access Management (IAM) permissions to create VMinstances and modify a network to configure Cloud Service Mesh. If you have therole of projectOwner or Editor(roles/owner orroles/editor) in the project where you are enablingCloud Service Mesh, you automatically have the correct permissions.

Otherwise, you must have all of the IAM roles shown in thefollowing table. If you have these roles, you also have their associatedpermissions, as described in theCompute Engine IAM documentation.

The Compute Engine VMs must have thehttps://www.googleapis.com/auth/cloud-platformscope. For more information, seeTroubleshooting deployments that use proxyless gRPC.

Enable the service account to access the Traffic Director API

When you set up your data plane and connect it to Cloud Service Mesh, yourxDS clients, whether Envoy proxies or proxyless gRPC clients, connect to thetrafficdirector.googleapis.com xDS server. ThesexDS clients present a service account identity to the xDS server to ensure thatcommunications between the data plane and the control plane are properlyauthorized.

For a Compute Engine VM, the xDS client uses the service accountassigned to the VM.

Unless you modify the configuration, Google Cloud uses theCompute Engine default service account.

To grant the service account access to the Traffic Director API, use the followinginstructions.

gcloud projects add-iam-policy-bindingPROJECT \    --member serviceAccount:SERVICE_ACCOUNT_EMAIL \    --role=roles/trafficdirector.client

Enable the required APIs

Enable the following required APIs.

• osconfig.googleapis.com
• trafficdirector.googleapis.com
• compute.googleapis.com
• networkservices.googleapis.com

To enable the required APIs, use the following instructions.

gcloud services enable osconfig.googleapis.com \trafficdirector.googleapis.com \compute.googleapis.com \networkservices.googleapis.com

xDS version

The service routing APIs require you to use xDS v3. For information on updatingyour deployment from xDS v2 to xDS v3, seexDS control plane APIs.

Additional requirements with Envoy proxies

This section describes additional requirements for using Cloud Service Mesh withthe service routing APIs and Envoy proxies. If you are deploying with proxylessgRPC, seeAdditional requirements with proxyless gRPC.

How Envoy is installed

During the Cloud Service Mesh deployment process, you create a VMtemplate that automatically installs Envoy on the VMs where your applicationsrun.

About Envoy versions

Envoy must be version 1.20.0 or later to work with Cloud Service Mesh.We recommend always using the most recent Envoy version to ensure that knownsecurity vulnerabilities are mitigated.

If you decide to deploy Envoy by using one of our automated methods, we handlethis task for you as follows:

Automated Envoy deployment with Compute Engine VMs installs the Envoyversion that we have validated to work with Cloud Service Mesh.When a new VM is created by using the instance template, the VM receives thelatest version that we have validated. If you have a long-running VM, you canuse a rolling update to replace your existing VMs and pick up the latest version.

For information about specific Envoy versions, seeVersion history.For information about security vulnerabilities, seeSecurity Advisories.

Additional requirements with proxyless gRPC

This section describes additional requirements for using Cloud Service Mesh withthe service routing APIs and proxyless gRPC. If you are deploying with Envoyproxies, seeAdditional requirements with Envoy proxies.

Overall process with proxyless gRPC

Follow this overall procedure for setting up proxyless gRPC applicationsin a service mesh:

1. Update your gRPC clients to the latest version of gRPC, with the most recentpatch.
2. Update your clients' gRPC name resolver scheme when you create a channel andspecify a Cloud Service Mesh bootstrap file.
3. Configure Cloud Service Mesh and Cloud Load Balancing resources.

This document provides information for completing the first two steps. Theconfiguration process that you use for step 3 depends on whether yourdeployment usesCompute Engine VMs orGKE network endpoint groups (NEGs).

Supported gRPC versions and languages

gRPC is an open source project and its release support is described on thegRPC FAQ.We recommend that you use the most recent version of gRPC to ensure that knownsecurity vulnerabilities are mitigated. This also ensures that your applicationshave access to the latest features supported by Cloud Service Mesh. Theservice mesh features supported in various implementations and versions ofgRPC are listed onGitHub.For a list of gRPC languages and features supported with Cloud Service Mesh andproxyless gRPC services, seeCloud Service Mesh features.

Cloud Service Mesh maintains compatibility with current and supported versions ofgRPC and endeavors to be compatible with gRPC versions less than one yearold, subject to theGoogle Cloud Platform Terms of Service.

Update your gRPC clients

Update the gRPC library in your application to the version that supports thefeatures that you require. For details, see the previous section.

Add the xDS name-resolver as a dependency to your gRPC applications.Requirements per language for Java and Go are shown in the following sections.Other languages don't have any additional requirements.

Java requirements

In Java, if you're using Gradle, add thegrpc-xds dependency to yourbuild.gradle file. ReplaceLATEST_GRPC_VERSION with thelatest version ofgRPC.

dependencies {  runtimeOnly 'io.grpc:grpc-xds:LATEST_GRPC_VERSION'}

If you're using Maven, add the following to the<dependencies> sectionof pom.xml. ReplaceLATEST_GRPC_VERSION with thelatest version of gRPC.

    <dependency>      <groupId>io.grpc</groupId>      <artifactId>grpc-xds</artifactId>      <version>LATEST_GRPC_VERSION</version>      <scope>runtime</scope>    </dependency>

Go requirements

If you're using Go, import thexds Go package.

Set gRPC name resolver to usexds

Set or change your gRPC applications to use thexds name resolution scheme inthe target URI, rather than DNS or any other resolver scheme. You do this byusing the prefixxds:/// in the target name when you create a gRPC channel.Load balancing for gRPC clients is on a per-channel basis.

Include the service name used in the target URI in theCloud Service Mesh configuration. For example, in Java, you create thechannel by using this structure, in which the service name ishelloworld:

ManagedChannelBuilder.forTarget("xds:///helloworld[:PORT_NUMBER]")

Create and configure a bootstrap file

Thexds resolver scheme tells the gRPC application to connect toCloud Service Mesh to obtain configuration information for the targetservice. Therefore, do the following:

• Create a bootstrap file, as shown in the following sample. This file tellsgRPC to connect to an xDS server (Cloud Service Mesh) to get the configurationfor specific services.
• Define an environment variable namedGRPC_XDS_BOOTSTRAP, with the bootstrapfilename as the value of the environment variable.

The setup instructions have examples that show how to generate the bootstrap file.For your convenience, you can use the latest version ofCloud Service Mesh gRPCbootstrap generator.

A bootstrap file containing the information needed to connect toCloud Service Mesh must be included alongside the application. A samplebootstrap file looks like this:

{  "xds_servers": [    {      "server_uri": "trafficdirector.googleapis.com:443",      "channel_creds": [        {          "type": "google_default"        }      ],      "server_features": ["xds_v3"]    }  ],  "node": {    "id": "projects/123456789012/networks/default/nodes/b7f9c818-fb46-43ca-8662-d3bdbcf7ec18",    "metadata": {      "TRAFFICDIRECTOR_NETWORK_NAME": "default"    },    "locality": {      "zone": "us-central1-a"    }  }}

The following table explains the fields in the bootstrap file.

projects/PROJECT_NUMBER/networks/NETWORK_NAME/nodes/ID

Continue the setup process

After you complete the prerequisites described in this document, continuewith one of these documents if you are configuring Cloud Service Meshwith the service routing APIs:

• Set up proxyless gRPC services with aMesh resource
• Set up Envoy proxies with HTTP services
• Set up an ingress gateway
• Set up TCP services with aTCPRoute resource
• Set up cross-project references withMesh andRoute resources
• Set up Gateway TLS routing