Traffic Director xDS control plane APIs

Traffic Director and its clients (Envoy proxies or proxyless gRPC libraries) exchange information using the open source xDS API. When you configure Traffic Director (for example, using resources like Forwarding Rules and Backend Services), Traffic Director converts these resources to xDS configuration, which it shares with its clients.

xDS version support

Traffic Director supports xDS v3 (recommended) and xDS v2. See the Envoy and gRPC documentation to see which versions support xDS v3.

Note that open source communities are dropping support for xDS v2. For example, the latest versions of the Envoy proxy no longer support xDS v2. We strongly encourage you to update your Envoy proxies and proxyless gRPC clients to the latest versions, which use xDS v3, so that you can continue to benefit from the latest security releases.

Migrating from xDS v2 to xDS v3

There are two steps in the migration process:

  1. Update the IAM permissions granted to the service account that your clients (Envoy proxies or proxyless gRPC libraries) use when connecting to Traffic Director.
  2. Update and re-deploy your applications. The specific steps vary depending on your deployment and are explained in the following sections.

Update the service account's IAM permissions

Make sure that the service account used by your Traffic Director clients (Envoy, proxyless gRPC) has the trafficdirector.networks.reportMetrics and trafficdirector.networks.getConfigs permissions. These permissions are included in the trafficdirector.client IAM role. If you are using a custom IAM role, you can add these permissions to the custom role. After the permissions have been added, you can remove the compute.networkViewer and/or compute.networkAdmin role(s) from the service account.

Update your applications

After you've updated the IAM permissions on the service account, update your applications.

Envoy on Compute Engine

If you use automatic Envoy deployment with Compute Engine, do a rolling restart or replacement of the managed instance groups. A version of Envoy that supports xDS v3 is automatically added to your VMs.

If you manually deploy Envoy on Compute Engine VMs, follow the setup guide to create a new instance template. The setup guide uses a recent version of Envoy that supports xDS v3. Next, do a rolling update, specifying the new instance template.

Envoy on GKE

If you use automatic Envoy injection with GKE, re-install the sidecar injector on the GKE clusters that you are using with Traffic Director. When a new pod spins up, an Envoy sidecar proxy that supports xDS v3 is automatically injected alongside your workload pod.

If you use manual sidecar injection on GKE, redeploy the sidecar proxy on every one of your GKE clusters.

Proxyless gRPC

There are two steps in the migration process:

  1. Ensure that the version of gRPC that you use supports xDS v3. See xDS features in gRPC.

  2. Update the bootstrap configuration using the following steps:

    1. Add "server_features": ["xds_v3"] in the "xds_servers" field as shown in this example.
    2. The node id must be in the format "projects/{project number}/networks/{network name}/nodes/{id}", as shown in the previous example.

After you've made the above changes to your application, build and re-deploy it.

gRPC versions that do not support xDS v3 are not affected by the above changes to the bootstrap config. Additionally, gRPC versions that support xDS v3 use xDS v2 if the above changes are not present in the bootstrap config.

For your convenience, you can use Traffic Director gRPC bootstrap generator version 0.11.0 or newer to generate xDS v3 compatible bootstrap configuration.

Verifying that Traffic Director clients are using xDS v3

You can use the client status tool to inspect the configuration that Traffic Director generates for its clients. This configuration states whether it is xDS v2 or xDS v3 configuration.