了解 Traffic Director 客户端状态

使用 Traffic Director 处理应用网络时，请考虑以下两个主要组件：

  • 基础架构层。基础架构层（例如 Envoy Sidecar 代理或无代理 gRPC 库）配置为代表您的应用处理网络。
  • 控制层面 Traffic Director。控制层面生成配置并将配置分发给基础架构层。

Envoy 代理或 gRPC 库初始化后，会使用 xDS API 连接到 Traffic Director。代理或库充当 Traffic Director 的客户端。在客户端和 Traffic Director 之间建立连接后，Traffic Director 会将配置信息发送回客户端，并根据需要更新配置。

有时，了解哪些客户端连接到 Traffic Director 或检查 Traffic Director 为其客户端生成的配置会有所帮助。例如，您可能想调试问题，或者可能想要了解配置 Traffic Director 时所执行的操作如何影响客户端看到的配置。

Traffic Director 支持客户端状态发现服务 (CSDS) API。您可以使用 CSDS 客户端查询此 API。这使您可以查看哪些客户端连接到 Traffic Director 并检查 Traffic Director 为其客户端生成的配置。

CSDS 客户端是一种开源工具，可以从 Envoy 代码库中获取。下图说明了 CSDS 客户端如何向 Traffic Director 查询有关 Traffic Director 的CSDS API 的信息。

使用 CSDS API 获取有关 Traffic Director 客户端的配置信息。
使用 CSDS API 获取有关 Traffic Director 客户端的配置信息（点击可放大）

CSDS 客户端连接到 Traffic Director，并显示项目编号和网络名称以及一组凭据。然后，Traffic Director 可以响应有关其所连接的各种 Traffic Director 客户端的信息。

如需详细了解 CSDS 客户端，请参阅自述文件。

前提条件

如需连接到 CSDS API，您需要一个 CSDS 客户端。您可以通过以下两种方式之一获取客户端：

  1. 您可以使用 Cloud Shell 构建客户端。
  2. 您可以在本地开发机器上构建客户端。

使用 Cloud Shell 构建 CSDS 客户端

如需使用 Cloud Shell 构建 CSDS 客户端，请执行以下操作：

  1. 按照停用或重置 Cloud Shell 中的说明重置 Cloud Shell。这可确保现有配置不会干扰您的构建。
  2. 在 Google Cloud 控制台中，打开新的 Cloud Shell 会话。

  3. 运行以下命令，获取用于构建 CSDS 客户端的源代码：

    git clone https://github.com/envoyproxy/envoy-tools.git

  4. 导航到 CSDS 客户端目录并运行以下命令：

    cd envoy-tools/csds-client/
make init
make build

  5. 构建完成后，使用以下命令对其进行测试：

    csds-client -help

如果构建成功，您会看到客户端的帮助文本。

在本地开发机器上构建 CSDS 客户端

您可以按照开源代码库的 README 文件中的说明，在本地机器上下载和构建 CSDS 客户端。为此，您还必须在环境中设置 Go 和 make 工具。如果您不想执行此操作，请使用 Cloud Shell 的上述说明（其中提供了 Go 和 make 工具）。

其他前提条件

  1. 确保每个客户端的节点 ID 在服务网格中是唯一的。如果多个客户端共享同一节点 ID，则仅返回一个配置，即最近连接到 Traffic Director 的客户端的配置。

    如果您使用 Google 的参考软件包，则无需在引导文件中手动设置节点 ID，系统会为您生成节点 ID。如果您不使用参考软件包，则必须在每个引导文件中手动设置节点 ID。

  2. 确保您有权访问具有配置 Traffic Director 所需的 Identity and Access Management (IAM) 权限的用户账号。以下说明使用 Google Cloud CLI 生成并自动提供 CSDS 客户端所需的凭据。或者，您可以使用 CSDS 客户端并直接提供凭据。

确定哪些客户端当前已连接到 Traffic Director

您可以使用 CSDS 客户端来确定哪些客户端已连接到您的 Traffic Director 配置。

如需获取此信息，您需要以下详细信息：

  • 生成凭据的项目的 ID。

  • 如果您使用的是服务路由 API，则为以下其中一项，具体取决于 xDS 客户端提取的资源：

  • 如果您使用的是旧版 API，则为在配置 Traffic Director 时指定的 VPC 网络的名称。此网络是路由规则映射的转发规则指定的网络。

服务路由 API

  1. 从具有正确权限的帐号中运行以下命令：

    gcloud auth application-default login \
 --billing-project=BILLING_PROJECT_ID

  2. 使用以下内容创建一个 YAML 格式的新文件。

    node_matchers:
  - node_metadatas:
      - path:
          - key: TRAFFICDIRECTOR_GCP_PROJECT_NUMBER
        value:
          string_match:
            exact: "PROJECT_NUMBER"
      - path:
          - key: TRAFFICDIRECTOR_MESH_SCOPE_NAME
        value:
          string_match:
            exact: "MESH_OR_SCOPE"

    替换以下值：

    • PROJECT_NUMBER：项目的 ID
    • MESH_OR_SCOPE：如果 xDS 客户端提取网格资源，请使用前缀 mesh:，后跟实际网格名称；如果 xDS 客户端提取网关资源，请使用前缀 scope:，后跟 scope 参数的名称

  1. 运行 CSDS 客户端，该客户端使用 gcloud CLI 生成的凭据。将 PATH_TO_CSDS_REQUEST_YAML_FILE 替换为您在上一步中创建的 YAML 文件的路径。

    csds-client \
  -service_uri trafficdirector.googleapis.com:443 \
  -platform gcp \
  -authn_mode auto \
  -api_version v3 \
  -request_file PATH_TO_CSDS_REQUEST_YAML_FILE

    您将看到如下所示的输出：

    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 列显示连接到 Traffic Director 的客户端的客户端 ID。这些客户端 ID 是使用 Envoy 或无代理 gRPC 连接到 Traffic Director 时使用的引导文件中的 node_id 字段提供的。

旧版 API

  1. 从具有正确权限的帐号中运行以下命令：

    gcloud auth application-default login \
 --billing-project=BILLING_PROJECT_ID

  2. 使用以下内容创建一个 YAML 格式的新文件。

    node_matchers:
  - node_metadatas:
      - path:
          - key: TRAFFICDIRECTOR_GCP_PROJECT_NUMBER
        value:
          string_match:
            exact: "PROJECT_NUMBER"
      - path:
          - key: TRAFFICDIRECTOR_NETWORK_NAME
        value:
          string_match:
            exact: "NETWORK_NAME"

    替换以下值：

    • PROJECT_NUMBER：Google Cloud 项目的唯一 ID
    • NETWORK_NAME：路由规则映射的转发规则指定的 VPC 网络

  3. 运行 CSDS 客户端，该客户端使用 gcloud CLI 生成的凭据。将 PATH_TO_CSDS_REQUEST_YAML_FILE 替换为您在上一步中创建的 YAML 文件的路径。

    csds-client \
  -service_uri trafficdirector.googleapis.com:443 \
  -platform gcp \
  -authn_mode auto \
  -api_version v3 \
  -request_file PATH_TO_CSDS_REQUEST_YAML_FILE

    您将看到如下所示的输出：

    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 列显示连接到 Traffic Director 的客户端的客户端 ID。这些客户端 ID 是使用 Envoy 或无代理 gRPC 连接到 Traffic Director 时使用的引导文件中的 node_id 字段提供的。

检查特定 Traffic Director 客户端的配置

您可以使用在上一部分中获取的客户端 ID 检查 Traffic Director 发送到特定客户端的配置。

您可以检查资源 proto 的详细配置，以确定特定客户端正在使用的 xDS API 版本。例如，如果您在配置中看到 envoy.api.v2.Cluster，则表示客户端使用的是 v2 API。如果您在配置中看到 envoy.api.v3.Cluster，则表示客户端使用的是 v3 API。

服务路由 API

  1. 更新您在确定哪些客户端当前已连接到 Traffic Director 中创建的 YAML 文件。 添加一个使用客户端 ID 作为值的 node-id 字段。

    node_matchers:
  - node_id:
      exact: "CLIENT_ID"
    node_metadatas:
      - path:
          - key: TRAFFICDIRECTOR_GCP_PROJECT_NUMBER
        value:
          string_match:
            exact: "PROJECT_NUMBER"
      - path:
          - key: TRAFFICDIRECTOR_MESH_SCOPE_NAME
        value:
          string_match:
            exact: "MESH_OR_SCOPE_NAME"

    替换以下值：

    • CLIENT_ID：您要检查其配置的客户端的 ID，例如 projects/000000/networks/mesh:mesh1/nodes/00000000-0000-0000-0000-00000000~127.0.0.1
    • PROJECT_NUMBER：Google Cloud 项目的唯一 ID
    • MESH_OR_SCOPE：如果 xDS 客户端提取网格资源，请使用前缀 mesh:，后跟实际网格名称；如果 xDS 客户端提取网关资源，请使用前缀 scope:，后跟 scope 参数的名称

  2. 运行 CSDS 客户端。运行客户端会生成 JSON 文件。此文件包含发送到 Traffic Director 客户端的配置。

    csds-client \
 -service_uri trafficdirector.googleapis.com:443 \
 -platform gcp \
 -authn_mode auto \
 -api_version v3 \
 -request_file PATH_TO_CSDS_REQUEST_YAML_FILE \
 -output_file FILENAME.JSON

    替换以下值：

    • PATH_TO_CSDS_REQUEST_YAML_FILE：YAML 文件的路径
    • FILENAME.JSON：保存 CSDS 客户端输出的文件的名称

    您将看到如下所示的输出：

    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

    您可以通过查看 JSON 文件来检查详细的 xDS 配置。 此输出包含 Traffic Director 使用汇总 gRPC 数据流 (ADS) 发送到客户端的各个 xDS 配置的状态。

旧版 API

  1. 更新您在确定哪些客户端当前已连接到 Traffic Director 中创建的 YAML 文件。 添加一个使用客户端 ID 作为值的 node-id 字段。

    node_matchers:
  - node_id:
      exact: "CLIENT_ID"
    node_metadatas:
      - path:
          - key: TRAFFICDIRECTOR_GCP_PROJECT_NUMBER
        value:
          string_match:
            exact: "PROJECT_NUMBER"
      - path:
          - key: TRAFFICDIRECTOR_NETWORK_NAME
        value:
          string_match:
            exact: "NETWORK_NAME"

    替换以下值：

    • CLIENT_ID：您要检查其配置的客户端的 ID，例如 f38a59c1-4428-42f1-be81-e02eb994f9dd~10.128.0.6
    • PROJECT_NUMBER：Google Cloud 项目的唯一 ID
    • NETWORK_NAME：路由规则映射的转发规则指定的 VPC 网络

  2. 运行 CSDS 客户端。运行客户端会生成 JSON 文件。此文件包含发送到 Traffic Director 客户端的配置。

    csds-client \
 -service_uri trafficdirector.googleapis.com:443 \
 -platform gcp \
 -authn_mode auto \
 -api_version v3 \
 -request_file PATH_TO_CSDS_REQUEST_YAML_FILE \
 -output_file FILENAME.JSON

    替换以下值：

    • PATH_TO_CSDS_REQUEST_YAML_FILE：YAML 文件的路径
    • FILENAME.JSON：保存 CSDS 客户端输出的文件的名称

    您将看到如下所示的输出：

    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

    您可以通过查看 JSON 文件来检查详细的 xDS 配置。 此输出包含 Traffic Director 使用汇总 gRPC 数据流 (ADS) 发送到客户端的各个 xDS 配置的状态。

状态值

下表列出了您可能会看到的 xDS 配置状态值。

值 说明
UNKNOWN （默认）⁣状态信息不可用或未知。
SYNCED Traffic Director 将配置发送给客户端，并从客户端收到 ACK。
ERROR Traffic Director 将配置发送给客户端，并从客户端收到 NACK。
STALE Traffic Director 将配置发送到客户端，但未从客户端收到 ACK 或 NACK。
NOT_SENT 配置未发送。
N/A CSDS 客户端不包含节点 ID。将会返回所有已连接的数据流，但配置状态将不可用。

可视化和监控

CSDS 客户端开源工具具有您可能需要使用的其他功能，例如可视化和持续监控。如需详细了解这些功能，请参阅开源代码库中的自述文件。

错误消息

只有仅在您的项目中启用 Traffic Director API 时，才可能会看到来自 CSDS 客户端的以下错误消息：

rpc error: code = NotFound desc = Requested entity was not found.

这是预期行为。Traffic Director 配置按网络确定范围。如果您尚未创建网络并运行 CSDS 客户端，则会看到此错误消息。

限制

  • CSDS 响应中不包含端点信息，因为 CSDS v3 API 中不提供该信息。
  • 每个客户端的节点 ID 在服务网格中必须是唯一的。如果多个客户端共享同一节点 ID，则仅返回一个配置，即最近连接到 Traffic Director 的客户端的配置。
  • 有时，您可能会在 YAML 文件的节点 ID 字段中看到反斜杠 (\)。如果发生这种情况，请在查询 CSDS API 以获取配置信息时，使用其他另一个反斜杠转义这个反斜杠。这是一个已知问题。

后续步骤