xDS control plane APIs

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

xDS version support

Cloud Service Mesh supports xDS v3 (strongly recommended) and xDS v2. Support for xDS v2 ends on June 20, 2024. If you are deploying Cloud Service Mesh 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 Cloud Service Mesh.
  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 Cloud Service Mesh clients (Envoy, proxyless gRPC) has the trafficdirector.networks.reportMetrics and trafficdirector.networks.getConfigs permissions. These permissions are included in the IAM Cloud Service Mesh 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), the Compute Network Admin role (roles/compute.networkAdmin), or both from the service account.

We recommend that you use the Cloud Service Mesh Client role instead of the Compute Network Viewer role (roles/compute.networkViewer) or the Compute Network Admin role (roles/compute.networkAdmin). Using the Cloud Service Mesh Client role restricts the permissions granted to the service account and avoids granting overly broad permissions.

Update your applications

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

Envoy on Compute Engine

To update your applications on Envoy 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.

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 Cloud Service Mesh. 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 don't affect gRPC versions that don't 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 Cloud Service Mesh gRPC bootstrap generator version 0.11.0 or later to generate an xDS v3-compatible bootstrap configuration.

Verify that Cloud Service Mesh clients are using xDS v3

To inspect the configuration that Cloud Service Mesh 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