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

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 version 1.30.0 or later, 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.

Updating your gRPC clients

First, you must update your gRPC clients to version 1.30.0 or later, with the most recent patch. Most gRPC server versions can interoperate with gRPC clients that use 1.30.0 or later, with the most recent patch, so you don't need to update all of your gRPC servers simultaneously.

Supported languages and gRPC versions

Your gRPC clients must use gRPC version 1.30.0, or later, with the most recent patch. The languages C++, Java, Go, Python, PHP, Ruby, and C# have xDSv2 support and all are supported with Traffic Director. 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:

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:

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

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"
        }
      ]
    }
  ],
  "node": {
    "id": "b7f9c818-fb46-43ca-8662-d3bdbcf7ec18~10.0.0.1",
    "metadata": {
      "TRAFFICDIRECTOR_GCP_PROJECT_NUMBER": "123456789012",
      "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.
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	Provide a unique string in the id field. This helps identify the gRPC client that is connecting to Traffic Director.
metadata	Information specific to xDS server.
TRAFFICDIRECTOR_GCP_PROJECT_NUMBER	The project number where Traffic Director is running.
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