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:
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
- In the Cloud Console, go to APIs & services for your
project.
Go to the API Library page - 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.
- Click the Traffic Director API.
- 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.
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
Open the IAM & Admin page in the Cloud Console.
Select your project.
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.
Click the Edit
button for the service account that you want to edit.Select the Compute Engine > Compute Network Viewer role.
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:
- Update your gRPC clients to the latest version of gRPC, with the most recent patch.
- Update your clients' gRPC name resolver scheme when you create a channel and specify a Traffic Director bootstrap file.
- 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: