Prepare to set up Traffic Director with Envoy

Setting up Traffic Director includes the following phases:

  1. Granting permissions, enabling the Traffic Director API, and—if you are using Compute Engine—configuring Cloud DNS.
  2. Deploying your applications with Envoy proxies.
  3. Creating services and routing rules that determine how traffic travels through your service mesh.

This document describes the first phase, and applies whether you are using the older APIs or the new service routing APIs, which are in preview. The second and third phases are covered by the platform-specific guides listed in Continue the setup process later in this document.

Before you read this guide, familiarize yourself with the Traffic Director overview. If you are using the new APIs, review the new service routing APIs overview.

Prerequisites

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

  1. Enable billing.
  2. Decide how you want to install Envoy.
  3. Grant the required permissions.
  4. Enable the Traffic Director API for your project.
  5. If you are using Compute Engine, enable the Cloud DNS API and configure Cloud DNS.
  6. Ensure that the service account used by the Envoy proxies has sufficient permissions 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 more information, see Enable, disable, or change billing for a project.

Decide how to install Envoy

Traffic Director makes it easy to install Envoy proxies and manage this infrastructure layer:

  • On Compute Engine, you can automatically add Envoy to applications running on your VMs. You use a VM template that installs Envoy, connects it to Traffic Director, and configures your VM's networking.

  • On Google Kubernetes Engine (GKE), you can automatically add Envoy sidecar proxies to your services' Pods. You install an Envoy sidecar injector to your cluster, which adds Envoy sidecar proxies, connects them to Traffic Director, and configures your container's networking.

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.

About Envoy versioning

Envoy must be version 1.9.1 or later to work with Traffic Director. We recommend always using the most recent Envoy version to ensure that known security vulnerabilities are mitigated.

If you decide to deploy Envoy by using one of our automated methods, we handle this task for you as follows:

  • When you use automated Envoy deployment with Compute Engine VMs, the Envoy version installed is one that we have validated to work with Traffic Director. When a new VM is created by using the instance template, the VM receives the latest version that we have validated. If you have a long-running VM, you can use a rolling update to replace your existing VMs and pick up the latest version.

  • When you use the Envoy sidecar injector with GKE, the injector is configured to use a recent version of Envoy that we have validated to work with Traffic Director. When a sidecar is injected alongside your workload Pod, it receives this version of Envoy. If you want to pick up a more recent version of Envoy, update the Envoy sidecar injector.

For information about specific Envoy versions, see Version history. For information about security vulnerabilities, see Security Advisories.

Grant the required IAM permissions

You must have sufficient Identity and Access Management (IAM) permissions to create VM instances and modify a network to configure Traffic Director. If you have the role of project Owner or Editor (roles/owner or roles/editor) in the project where you are enabling Traffic Director, you automatically have the correct permissions.

Otherwise, you must have all of the Compute Engine IAM roles shown in the following table. 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
(roles/iam.serviceAccountAdmin)
Enable Traffic Director. Service Usage Admin
(roles/serviceusage.serviceUsageAdmin)
Create networks, subnets, and load balancer components. Compute Network Admin
(roles/compute.networkAdmin)
Add and remove firewall rules. Compute Security Admin
(roles/compute.securityAdmin)
Create instances. Compute Instance Admin
(roles/compute.instanceAdmin)

The GKE node pool or Compute Engine VMs must have the https://www.googleapis.com/auth/cloud-platform scope. For more information, see Troubleshooting deployments that use Envoy.

With xDS v3, grant the service account used by Traffic Director Envoy clients the role roles/trafficdirector.client.

Enable the Traffic Director API

Console

  1. In the Google Cloud console, go to the API Library page for your project.

    Go to the API Library

  2. In the Search for APIs & Services field, enter Traffic Director.

  3. In the search results list, click Traffic Director API. If you don't see the Traffic Director API listed, that means that you don't have the necessary permissions to enable the Traffic Director API.

  4. On the Traffic Director API page, click Enable.

gcloud

Run the following command:

gcloud services enable trafficdirector.googleapis.com

Enable the Cloud DNS API and configure Cloud DNS

Use these instructions if you are configuring Traffic Director on Compute Engine. You must enable the Cloud DNS API and configure Cloud DNS for DNS name resolution.

For background information about Traffic Director and DNS resolution, see Traffic Director and DNS name resolution.

First, use the following instructions to enable the Cloud DNS API.

Console

  1. In the Google Cloud console, go to the API Library page for your project.

    Go to the API Library

  2. In the Search for APIs & Services field, enter DNS.

  3. In the search results list, click Cloud DNS API. If you don't see the Cloud DNS API listed, that means that you don't have the necessary permissions to enable the Cloud DNS API.

  4. On the Cloud DNS API page, click Enable.

gcloud

Run the following command:

gcloud services enable dns.googleapis.com

Next, configure a Cloud DNS managed private zone. Use the instructions in Create a private zone.

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 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 the control plane are properly authorized:

  • For a Compute Engine VM, the xDS client uses the service account assigned to the VM.
  • For GKE, if Workload Identity is not enabled, 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.

You need the following permissions, depending on the version of the xDS client that you use to configure Envoy. We strongly recommend that you configure your new Envoy deployments with xDS v3, or migrate to xDS v3 if you have an existing deployment that uses xDS v2.

  • When you use xDS v3, the service account used by your clients must have the trafficdirector.networks.reportMetrics and trafficdirector.networks.getConfigs permissions. You can use the IAM Traffic Director Client role (roles/trafficdirector.client), which wraps both permissions.

  • When you use xDS v2, the service account used by your clients must have the project-level IAM compute.globalForwardingRules.get permission. You can also grant this permission by assigning the Compute Network Viewer role (roles/compute.networkViewer) to the service account.

Console

  1. In the Google Cloud console, go to the IAM & Admin page.

    Go to IAM & Admin

  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 then click the Roles tab.
  4. Expand the role. For the service account that you want to edit, click Edit.

  5. Select the Other > Traffic Director Client role.

  6. To apply the role to the service account, click Save.

gcloud

Run the following command:

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

Replace the following:

  • PROJECT: enter gcloud config get-value project
  • SERVICE_ACCOUNT_EMAIL: the email associated with the service account

Continue the setup process

Now that you completed the prerequisite steps, you can start to set up your service mesh.