When you use Traffic Director to handle your application networking, there are two primary components to keep in mind:
- The infrastructure layer. The infrastructure layer, such as Envoy sidecar proxies or proxyless gRPC libraries, is configured to handle networking on behalf of your applications.
- The control plane, Traffic Director. The control plane generates configuration for, and distributes it to, the infrastructure layer.
When a proxy or the gRPC library is initialized, it connects to Traffic Director using xDS APIs. The proxy or the library acts as a client to Traffic Director. After a connection is established between the client and Traffic Director, Traffic Director sends configuration information back to the client and updates the configuration as needed.
Sometimes, it is helpful to understand which clients are connected to Traffic Director or to inspect the configuration that Traffic Director generates for its clients. For example, you might want to debug an issue, or you might want to better understand how the actions that you took when configuring Traffic Director affect the configuration that your clients see.
Traffic Director supports the Client Status Discovery Service (CSDS) API. You query this API using a CSDS client. This enables you to see which clients are connected to Traffic Director and to inspect the configuration that Traffic Director generates for its clients.
The CSDS client is an open source tool that you can obtain from the Envoy repository. The following diagram illustrates how the CSDS client queries Traffic Director for information about Traffic Director's CSDS API.
The CSDS client connects to Traffic Director and presents a project number and network name, along with a set of credentials. Traffic Director can then respond with information about the various Traffic Director clients to which it is connected.
To connect to the CSDS API, you need a CSDS client. There are two ways to obtain the client.
- You can build the client using Cloud Shell.
- You can build the client on a local development machine.
The next two sections provide details for both ways to obtain the CSDS client.
Building the CSDS client using Cloud Shell
To use Cloud Shell to build the CSDS client, do the following:
- Use the instructions in Disabling or resetting Cloud Shell to reset Cloud Shell. This ensures that existing configurations do not interfere with your build.
- From the Google Cloud Console, open a new Cloud Shell session.
Run this command to obtain the source code that you use to build the CSDS client:
git clone https://github.com/envoyproxy/envoy-tools.git
Navigate to the CSDS client directory and issue these commands:
cd envoy-tools/csds-client/ make init make build
After the build is complete, test it with this command:
If the build succeeded, you see the help text for the client.
Building the CSDS client on a local development machine
You can download and build a CSDS client on a local machine by following the
instructions in the README file in the open source repository. To do this
you must also have Go and the
make tool set up in your environment. If you
prefer not to do this, use the above instructions for the Cloud Shell,
in which Go and the
make tool are provided for you.
- Make sure the node ID of each client is unique within the service mesh. If multiple clients share the same node ID, only one configuration is returned. That is the configuration for the client that mostly recently connected to Traffic Director. You do not need to manually set the node ID in your bootstrap files if you use Google's reference packages. A node ID is generated for you. If you do not use the reference packages, you must manually set the node ID in each of your bootstrap files.
- Ensure that you have access to a user account that has the IAM permissions required to
configure Traffic Director.
The instructions below use the
gcloudcommand-line tool to generate and automatically supply the credentials needed by the CSDS client. Alternatively, you can use the CSDS client and supply the credentials directly.
Determining which clients are currently connected to Traffic Director
You need the following information before you follow these steps:
- The project number of the project from which the credentials were generated.
- The network name that you specified when you configured Traffic Director. This is the network name from the forwarding rule of the routing rule map.
To determine which clients are connected to Traffic Director, follow these instructions:
From an account that has the correct permissions, run this command:
gcloud auth application-default login --billing-project BILLING_PROJECT_ID
Create a new file in the YAML format with the following content, replacing
NETWORK_NAMEwith the correct values for your deployment:
node_matchers: - node_metadatas: - path: - key: TRAFFICDIRECTOR_GCP_PROJECT_NUMBER value: string_match: exact: "PROJECT_NUMBER" # e.g.,: "314053285323" - path: - key: TRAFFICDIRECTOR_NETWORK_NAME value: string_match: exact: "NETWORK_NAME" # e.g.,: "default"
Run the CSDS client, which uses the credentials generated by the
gcloudcommand-line tool. Substitute the path to the YAML file you created in the previous step for PATH_TO_CSDS_REQUEST_YAML_FILE.
csds-client \ -service_uri trafficdirector.googleapis.com:443 \ -platform gcp \ -authn_mode auto \ -api_version v2 \ -request_file PATH_TO_CSDS_REQUEST_YAML_FILE
You should see output similar to the following:
Client ID xDS stream type Config Status 603e3524-d1d6-4a9e-9b26-39bcd633a7cb~10.128.0.5 ADS N/A 603e3524-d1d6-4a9e-9b26-39bcd633a7cb~10.128.0.5 LRS N/A 8576d4bf-8f10-40b2-920b-bb6a7cf9f34a~10.168.0.3 ADS N/A 8576d4bf-8f10-40b2-920b-bb6a7cf9f34a~10.168.0.3 LRS N/A d9577b61-fa3a-41d6-90bd-11c4fdd2f8c0~10.128.0.4 ADS N/A d9577b61-fa3a-41d6-90bd-11c4fdd2f8c0~10.128.0.4 LRS N/A f38a59c1-4428-42f1-be81-e02eb994f9dd~10.128.0.6 ADS N/A f38a59c1-4428-42f1-be81-e02eb994f9dd~10.128.0.6 LRS N/A
Client ID column displays the client IDs of the clients that are connected
to Traffic Director. These are provided using the
node id field in the
bootstrap file used by Envoy or proxyless gRPC when they connect to
Inspecting the configuration for a specific Traffic Director client
You can inspect the configuration that Traffic Director sends to a particular client by using the client's ID, which you obtained in the previous section.
To inspect the configuration, follow these instructions:
Update the YAML file that you previously created and set the value of
node_idto the client ID:
node_matchers: - node_id: exact: "CLIENT_ID" # e.g.,: "f38a59c1-4428-42f1-be81-e02eb994f9dd~10.128.0.6" node_metadatas: - path: - key: TRAFFICDIRECTOR_GCP_PROJECT_NUMBER value: string_match: exact: "PROJECT_NUMBER" # e.g.,: "314053285323" - path: - key: TRAFFICDIRECTOR_NETWORK_NAME value: string_match: exact: "NETWORK_NAME" # e.g.,: "default"
Run the CSDS client. This generates a JSON file containing the configuration that is sent to the Traffic Director client.
csds-client \ -service_uri trafficdirector.googleapis.com:443 \ -platform gcp \ -authn_mode auto \ -api_version v2 \ -request_file PATH_TO_CSDS_REQUEST_YAML_FILE \ -output_file FILENAME.json
You should see output similar to the following:
Client ID xDS stream type Config Status 8576d4bf-8f10-40b2-920b-bb6a7cf9f34a~10.168.0.3 ADS LDS SYNCED RDS SYNCED CDS STALE Config has been saved to FILENAME.json
You can inspect detailed xDS configuration by looking at the
.json file. This
output contains the status of individual xDS configurations sent by
Traffic Director to the client using an aggregated gRPC stream (ADS).
These are the xDS configuration status values that you might see:
UNKNOWN: (DEFAULT) Status info is not available/unknown.
SYNCED: Traffic Director sent the configuration to the client and received an
ACKfrom the client.
ERROR: Traffic Director sent the config to client and received a
NACKfrom the client.
STALE: Traffic Director sent the configuration to the client, but did not received an
NACKfrom the client.
NOT_SENT: Config is not sent.
N/A: The CSDS client did not include the node ID. All of the connected streams are returned but configuration status is not available.
Visualization and monitoring
The CSDS client open source tool has additional features that you might want to use, such as visualization and continued monitoring. The README file in the open source repository has more information about these features.
You might see the following error message from the CSDS client when you only enable the Traffic Director API in your project:
rpc error: code = NotFound desc = Requested entity was not found.
This is expected behavior. Traffic Director configuration is scoped per network. If you haven't created a network yet and you run the CSDS client, you see this error message.
- Traffic Director only supports the CSDS v2 API.
- Endpoint information is not included in the CSDS response, because this information is not available in the CSDS v2 API.
- If yodu are operating in a Shared VPC environment, you must specify the host project number and receive appropriate permissions on the host project to use the tool.
- The node ID of each client must be unique within the service mesh. If multiple clients share the same node ID, only one configuration is returned. That is the configuration for the client that mostly recently connected to Traffic Director.
- You might sometimes see a backslash (\) in the node ID field in the yaml file. If this happens, escape the backslash using an additional backslash when you query the CSDS API for configuration information. This is a known issue.
For more information on the CSDS client, see the following: