xDS control plane APIs

Traffic Director and its clients (Envoy proxies or proxyless gRPC libraries) use the open source xDS API to exchange information. When you configure Traffic Director—for example, by using resources such as forwarding rules and backend services—Traffic Director converts these resources to an xDS configuration, which it shares with its clients.

xDS version support

Traffic Director supports xDS v3 (strongly recommended) and xDS v2. Support for xDS v2 ends on June 20, 2024. If you are deploying Traffic Director for the first time, we strongly recommend that you use xDS v3.

To determine which Envoy and gRPC versions support xDS v3, see the Envoy and gRPC documentation.

Migrate from xDS v2 to xDS v3

There are two steps in the migration process:

  1. Update the Identity and Access Management (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 redeploy 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 IAM Traffic Director Client role (roles/trafficdirector.client).

If you are using a custom IAM role, you can add these permissions to the custom role. After you add the permissions, you can remove the Compute Network Viewer role (roles/compute.networkViewer) and/or the Compute Network Admin role (roles/compute.networkAdmin) from the service account.

Update your applications

After you update 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 virtual machine (VM) instances.

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 Google Kubernetes Engine (GKE), re-install the sidecar injector on the GKE clusters that you are using with Traffic Director. When a new Pod is created, 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 each 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. For more information, see xDS features in gRPC.

  2. Update the bootstrap configuration by using the following steps:

    1. In the "xds_servers" field, add "server_features": ["xds_v3"] as shown in this bootstrap file example.
    2. The node ID must be in the following format as shown in the previous example:

      "projects/PROJECT_NUMBER/networks/NETWORK_NAME/nodes/ID"
      

After you make the preceding changes to your application, build and redeploy it.

The preceding changes to the bootstrap configuration do not affect gRPC versions that do not support xDS v3. Also, if the preceding changes are not present in the bootstrap configuration, then gRPC versions that support xDS v3 use xDS v2.

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

Verify that Traffic Director clients are using xDS v3

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

What's next