Preparing for Traffic Director setup

Setting up Traffic Director has these phases:

  1. Granting permissions and enabling the Traffic Director API
  2. Deploying Envoy sidecar proxies alongside your applications and connecting the proxies to Traffic Director
  3. Setting up Traffic Director so that Traffic Director can configure the data plane.

This document describes how to perform the first phase. The second and third phases are covered by platform-specific guides for the following:

Before you read this guide, familiarize yourself with the Traffic Director conceptual overview.


Whether you plan to use Traffic Director to configure Envoy proxies running alongside applications on virtual machines, containers, or a mix of both, you need to first complete the following tasks:

The following sections provide instructions for each task.

Decide how to install Envoy

For both VM- and container-based workloads, Traffic Director offers automated Envoy deployment methods to set up your service mesh.

  • On Compute Engine, you can use a VM template that automatically deploys a supported version of the Envoy binary on your virtual machines. This Envoy is automatically bootstrapped to connect to Traffic Director.

  • On GKE, you can install an Envoy sidecar injector to automatically deploy sidecar proxies alongside newly created pods and connect them to Traffic Director.

If you want to manually deploy Envoy, you can deploy Envoy as a binary (Compute Engine only) or as a container (Compute Engine or GKE). You must also provide an Envoy bootstrap configuration file to connect the proxy to Traffic Director and receive configuration. See Configuring Envoy bootstrap attributes for Traffic Director for more information on bootstrapping.

Finally, you can also use Envoy deployment solutions from third-party providers with Traffic Director. One example of such an offering is GetEnvoy, which provides a package manager-based approach to installing and updating your Envoy proxies.

If you are automatically installing Envoy

Ensure that you enable the Cloud OS Config API. Unless you do this, you cannot install the required components on your VMs.

To do this:


  1. In the Cloud Console, go to APIs & services.
    Go to the API Library page
  2. Select the correct project.
  3. In the search box, enter Cloud OS Config API and press Enter.
  4. Select Cloud OS Config API.
  5. Click Enable.


gcloud services enable

If you are manually installing Envoy

Traffic Director supports Envoy version 1.9.1 or later. We strongly recommend using the most recent Envoy version to ensure that all known security vulnerabilities are mitigated.

The instructions in Traffic Director setup for Compute Engine VMs with manual Envoy deployment explain how to obtain an Envoy binary from a Docker image. If you decide to use the manual setup steps in this guide, you need Docker to unpack the Envoy proxy binary. You also need Docker permissions to pull the image from Docker. If you run the Docker tools as a non-root user, follow Docker's post-installation instructions.

Grant 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 Identity and Access Management (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 GKE node-pool or Compute Engine VMs must have the scope.

Enable the Traffic Director API


  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 services enable

Enable 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 (for example, Envoy proxies) connect to the 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.

In the case of a Compute Engine VM, the xDS client uses the service account assigned to the VM. In the case of GKE, if Workload Identity is not enabled, then the xDS client uses the service account assigned to the underlying GKE node. If Workload Identity is enabled, the xDS client uses the Google service account that is bound to the Kubernetes service account that is assigned to the pod.

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.


  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.


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

Continue the setup process

Now that you've completed the pre-requisite steps, you can deploy your sidecar proxies and configure Traffic Director. The following guides provide platform-specific instructions for Compute Engine and GKE:

Note that, while these guides each focus on deploying Envoy sidecar proxies on a single environment (either Compute Engine or GKE), Traffic Director is flexible and supports deployments that span environments.

You can configure Traffic Director using the Compute Engine load balancing SDK or REST APIs. See the load balancing API and gcloud references.