了解 Cloud Service Mesh 客户端状态

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

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

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

了解哪些客户端已连接到 Cloud Service Mesh 或检查 Cloud Service Mesh 为其客户端生成的配置有时会很有帮助。例如，您可能希望调试问题，或者可能想要了解在配置 Cloud Service Mesh 时执行的操作对客户端看到的配置有何影响。

Cloud Service Mesh 支持 Client Status Discovery Service (CSDS) API。您可以使用 CSDS 客户端查询此 API。这样，您就可以查看哪些客户端已连接到 Cloud Service Mesh，并检查 Cloud Service Mesh 为其客户端生成的配置。

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

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

CSDS 客户端会连接到 Cloud Service Mesh，并提供项目编号和网络名称以及一组凭据。然后，Cloud Service Mesh 可以使用有关其所连接的各种 Cloud Service Mesh 客户端的信息进行响应。

如需详细了解 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，则仅返回一项配置，即最近连接到 Cloud Service Mesh 的客户端的配置。

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

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

确定当前哪些客户端已连接到 Cloud Service Mesh

您可以使用 CSDS 客户端确定哪些客户端已连接到您的 Cloud Service Mesh 配置。

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

  • 生成凭据的项目的 ID。

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

  • 如果您使用的是旧版 API，则为您在配置 Cloud Service Mesh 时指定的 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 列显示连接到 Cloud Service Mesh 的客户端的客户端 ID。这些客户端 ID 通过 Envoy 或无代理 gRPC 在连接到 Cloud Service Mesh 时使用的引导文件中的 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 列显示连接到 Cloud Service Mesh 的客户端的客户端 ID。这些客户端 ID 通过 Envoy 或无代理 gRPC 在连接到 Cloud Service Mesh 时使用的引导文件中的 node_id 字段提供。

检查特定 Cloud Service Mesh 客户端的配置

您可以使用在上一部分中获得的客户端 ID 来检查 Cloud Service Mesh 发送到特定客户端的配置。

您可以检查资源 proto 的详细配置，以确定特定客户端正在使用的 xDS API 版本。例如，如果您在配置中看到 envoy.api.v2.Cluster，则表示客户端使用的是 v2 API。如果您在配置中看到 envoy.api.v3.Cluster，则表示客户端使用的是 v3 API。仅支持 xDS v3。要了解如何从 v2 迁移到 v3，请参阅从 xDS v2 迁移到 xDS v3。

服务路由 API

  1. 更新您在确定当前哪些客户端已连接到 Cloud Service Mesh 中创建的 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 文件。此文件包含发送到 Cloud Service Mesh 客户端的配置。

    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 配置。 此输出包含 Cloud Service Mesh 使用聚合 gRPC 流 (ADS) 发送到客户端的各个 xDS 配置的状态。

旧版 API

  1. 更新您在确定当前哪些客户端已连接到 Cloud Service Mesh 中创建的 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 文件。此文件包含发送到 Cloud Service Mesh 客户端的配置。

    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 配置。 此输出包含 Cloud Service Mesh 使用聚合 gRPC 流 (ADS) 发送到客户端的各个 xDS 配置的状态。

状态值

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

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

可视化和监控

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

错误消息

仅在项目中启用 Cloud Service Mesh API 时，您可能会在 CSDS 客户端看到以下错误消息：

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

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

限制

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

后续步骤