# xDS control plane APIs

Cloud Service Mesh and its clients (Envoy proxies or proxyless gRPC
libraries) use the [open source xDS
API](https://www.envoyproxy.io/docs/envoy/latest/api/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.

> [!NOTE]
> **Note:** This guide only supports Cloud Service Mesh with Google Cloud APIs and does not support Istio APIs. For more information see, [Cloud Service Mesh overview](https://docs.cloud.google.com/service-mesh/docs/overview.md.txt).

## xDS version support

Cloud Service Mesh supports xDS v3 only.

To determine which Envoy and gRPC versions support xDS v3, see the
[Envoy](https://www.envoyproxy.io/docs/envoy/latest/api/api_supported_versions)
and
[gRPC](https://github.com/grpc/grpc/blob/master/doc/grpc_xds_features.md) documentation.

If you are still using xDS v2, use the following instructions to migrate to
xDS v3.

## 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
[Traffic Director Client role](https://docs.cloud.google.com/iam/docs/roles-permissions/anthosservicemesh.md.txt#trafficdirector.client)
(`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](https://docs.cloud.google.com/compute/docs/instance-groups/rolling-out-updates-to-managed-instance-groups.md.txt#starting_a_basic_rolling_update)
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](https://docs.cloud.google.com/service-mesh/docs/set-up-gke-pods-auto#installing_the_sidecar_injector_to_your_cluster)
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](https://docs.cloud.google.com/service-mesh/docs/set-up-gke-pods#injecting_a_sidecar_proxy_into_kubernetes_pods)
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](https://github.com/grpc/grpc/blob/master/doc/grpc_xds_features.md).

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](https://docs.cloud.google.com/service-mesh/docs/onboarding/prepare-service-routing-envoy-proxyless.md.txt#bootstrap_file).
   2. The node ID must be in the following format as shown in the previous
      example:

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

> [!NOTE]
> **Note:** Per policy, we encourage users to check for updates of the TD gRPC bootstrap generator yearly.

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.19.0](https://github.com/GoogleCloudPlatform/traffic-director-grpc-bootstrap/releases/tag/v0.19.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](https://docs.cloud.google.com/service-mesh/docs/service-routing/client-status.md.txt).
This tool states whether the configuration is xDS v2 or xDS v3.

## What's next

- To find general Cloud Service Mesh troubleshooting information, see [Troubleshoot Envoy deployments](https://docs.cloud.google.com/service-mesh/docs/service-routing/troubleshooting.md.txt).
- To resolve configuration issues when you deploy proxyless gRPC services, see [Troubleshoot proxyless gRPC deployments](https://docs.cloud.google.com/service-mesh/docs/service-routing/troubleshooting-proxyless.md.txt).