Prepare to set up Cloud Service Mesh with proxyless gRPC services

Setting up Cloud Service Mesh includes several phases. This document describes thefirst phase: instructions for preparing to configure Cloud Service Meshwith proxyless gRPC applications. This document applies when you are using theload balancing APIs. However, we strongly recommend that you use theservice routing APIs. The other phases are covered by the platform-specificguides listed inContinue the setup process later in thisdocument.

Before you read this guide, familiarize yourself with the following documents,which provide an overview of using Cloud Service Mesh with proxyless gRPCapplications:

• Cloud Service Mesh overview
• Cloud Service Mesh with proxyless gRPC services overview
• Cloud Service Mesh new service routing APIs overview

Prerequisites

Prepare your environment by completing the following tasks:

1. Enable billing.
2. Grant the required permissions.
3. Enable the Traffic Director API for your project.
4. Ensure that the service account has sufficientpermissions to access the Traffic Director API.

The following sections provide instructions for each task.

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 youare enabling Cloud Service Mesh, you automatically have the correct permissions.

Otherwise, you must have all of the IAMroles shown in the following table. If you have these roles, you also have theirassociated permissions, 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.

With xDS v3, grant the service account used by Cloud Service Mesh gRPC clientsthe roleroles/trafficdirector.client.

Enable the Traffic Director API

gcloud services enable trafficdirector.googleapis.com

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 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.

You need the following permissions. The xDS protocol version is specified inthebootstrap file. Only xDS v3 is supported.

If you are using xDS v2, you must migrate to xDS v3. For informationabout how to migrate, seeMigrate from xDS v2 to xDS v3.

When you use xDS v3, the service account used by your gRPC applications musthave thetrafficdirector.networks.reportMetrics andtrafficdirector.networks.getConfigs permissions. You can use theIAMTraffic Director Client role(roles/trafficdirector.client), which wraps both permissions.

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

Next, 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 gRPC bootstrap 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:

• Continue with theCloud Service Mesh Set up GKE and proxyless gRPC services
• Continue with theCloud Service Mesh Set up Compute Engine and proxyless gRPC services
• Continue with theCloud Service Mesh GKE Kubernetes Gateway API setup guides. Note that the Gateway API feature is in Preview.