Prepare to set up Traffic Director with proxyless gRPC services

This guide contains instructions for preparing to configure Traffic Director with proxyless gRPC applications.

Before you begin

Make sure that you are familiar with general Traffic Director concepts. Read the following documents:

• Traffic Director overview
• Traffic Director with proxyless gRPC applications overview

These documents provide an overview of using Traffic Director with proxyless gRPC applications.

General preparation

First, prepare your environment by performing the tasks described in the following sections.

Enable billing

Make sure that billing is enabled for your Google Cloud project. For more information, see Enable, disable, or change billing for a project.

Granting the required IAM permissions

You must have sufficient permissions to create VM instances and modify a network to configure Traffic Director. If you have the role of project owner or editor in the project where you are enabling Traffic Director, you automatically have the correct permissions.

Otherwise, you must have all of the following Compute Engine IAM roles. If you have these roles, you also have their associated permissions, as described in the Compute Engine IAM documentation.

Task	Required role
Set IAM policy for a service account	Service Account Admin
Obtain the global forwarding rule resource	Compute Network Viewer
Enable Traffic Director	Service Usage Admin
Create networks, subnets, and load balancer components	Network Admin
Add and remove firewall rules	Security Admin
Create instances	Compute Instance Admin

In addition, the Compute Engine VMs must have the https://www.googleapis.com/auth/cloud-platform scope.

Enabling the Traffic Director API

Console

1. In the Cloud Console, go to APIs & services for your project.
   Go to the API Library page
2. To find the Traffic Director API, use the search field. If you don't see the Traffic Director API listed, that means you don't have the necessary permissions to enable the Traffic Director API.
3. Click the Traffic Director API.
4. In the page that displays information about the API, click Enable.

gcloud

gcloud services enable trafficdirector.googleapis.com

Enabling the service account to access the Traffic Director API

When you set up your data plane and connect it to Traffic Director, your xDS clients connect to the trafficdirector.googleapis.com xDS server. These xDS clients present a service account identity to the xDS server to ensure that communications between the data plane and control plane are properly authorized.

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

Note: Unless you modify the configuration, Google Cloud uses the Compute Engine default service account.

The service account used by your xDS clients must have the compute.globalForwardingRules.get project-level IAM permission. You can also grant this permission by assigning the compute.networkViewer role to the service account.

Console

1. Open the IAM & Admin page in the Cloud Console.

   Open the IAM & Admin page

2. Select your project.

3. Identify the service account to which you want to add a role.

   • If the service account isn't already on the members list, it doesn't have any roles assigned to it. Click Add and enter the email address of the service account.
   • If the service account is already on the members list, it has existing roles. Select the service account and click the Roles tab.

4. Click the Edit button for the service account that you want to edit.

5. Select the Compute Engine > Compute Network Viewer role.

6. Click Save to apply the role to the service account.

gcloud

Replace the ${SERVICE_ACCOUNT_EMAIL} variable with the correct value.

PROJECT=`gcloud config get-value project`
gcloud projects add-iam-policy-binding ${PROJECT} \
   --member serviceAccount:${SERVICE_ACCOUNT_EMAIL} \
   --role roles/compute.networkViewer

Next, follow this overall procedure for setting up proxyless gRPC applications in a mesh:

1. Update your gRPC clients to the latest version of gRPC, with the most recent patch.
2. Update your clients' gRPC name resolver scheme when you create a channel and specify a Traffic Director bootstrap file.
3. Configure Traffic Director and Cloud Load Balancing resources.

This guide provides information for completing the first two steps. The configuration process you use for step 3 depends on whether your deployment uses Compute Engine VMs or Google Kubernetes Engine NEGs.

Supported gRPC versions and languages

gRPC is an open source project and its release support is described here. We strongly recommend using the most recent version of gRPC to ensure that known security vulnerabilities are mitigated. This also ensures that your applications have access to the latest features supported by Traffic Director. The service mesh features supported in various implementations and versions of gRPC are listed here. gRPC languages and features supported with Traffic Director and proxyless gRPC services are listed here.

Traffic Director maintains compatibility with current and supported versions of gRPC and endeavors to be compatible with gRPC versions less than one year old, subject to the Google Cloud Platform Terms of Service.

Updating your gRPC clients

First, you must update the gRPC library in your application to the version that supports the features you require. See the previous section for details. Add the xDS name-resolver as a dependency to your gRPC applications. Requirements per language for Java and Go are shown below. Other languages do not have any additional requirements.

Java requirements

In Java, if you're using Gradle, add the snapshot repository and grpc-xds dependency to your build.gradle file. Replace the version shown below with the latest version of gRPC.

repositories {
    mavenLocal()
}
dependencies {
  runtimeOnly 'io.grpc:grpc-xds:1.30.0-SNAPSHOT'
}

If you're using Maven, add the following to the <dependencies> section of pom.xml. Replace the version shown below with the latest version of gRPC.

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

Go requirements

If you're using Go, you must import the xds Go package.

gRPC name resolver must be xds

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

You must also include the service name used in the target URI in the Traffic Director configuration. For example, in Java, you create the channel using this structure, in which the service name is helloworld:

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

Bootstrap file

The xds resolver scheme tells the gRPC application to connect to Traffic Director to obtain configuration information for the target service. Therefore, do the following:

• Create a bootstrap file, as shown below. This file tells gRPC to connect to an xDS server (Traffic Director) to get configuration for specific services.
• Define an environment variable named GRPC_XDS_BOOTSTRAP, with the bootstrap filename 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 of Traffic Director gRPC bootstrap generator.

A bootstrap file containing the information needed to connect to Traffic Director must be included alongside the application. A sample bootstrap 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.

Field	Value and Description
xds_servers	A list of xDS servers. gRPC uses only the first one in the list.
server_uri	Specify at least one. gRPC tries to connect to only the first xDS server in the list of `xds_servers`. The default value is trafficdirector.googleapis.com:443
channel_creds	Credentials to use with the xDS server.
server_features	A list of features supported by the server, such as xDS v3 support. The default value is empty.
type	Use the value google_default. For more information on how credentials are obtained, see Getting Started with Authentication.
node	Information about the client connecting to the xDS server.
id	The id must be in the format "projects/{project number}/networks/{network name}/nodes/{id}" as shown in the example above. Provide a unique string as the value of {id}. This helps identify the gRPC client that is connecting to Traffic Director.
metadata	Information specific to xDS server.
TRAFFICDIRECTOR_NETWORK_NAME	If the field is empty or not specified, then the value is set to default.
locality	The GCP zone in which the gRPC client is running

What's next

After you complete the preparation described in this document, continue with the instructions in one of these documents:

• Setting up VM-based proxyless gRPC services
• Setting up GKE proxyless gRPC services