Google Distributed Cloud 网闸隔离配置 API 概览

Google Distributed Cloud (GDC) 网闸隔离配置应用编程接口 (API) 是 GDC 平台服务的编程接口。Google 使用 Kubernetes 资源模型 (KRM) 在 Kubernetes 之上构建控制平面 API。控制平面负责执行服务的资源管理，例如创建、删除和更新。

特定服务具有这些 API 及其自己的数据平面 API，这些 API 基于 XML、JSON 或 gRPC。本页面将在各自的部分中介绍这些服务。

GDC API 简介

GDC API 有两种类型：基于 Kubernetes 的 API 和非基于 Kubernetes 的 API。许多 GDC API 都是开源 Kubernetes API 的扩展。它们使用 Kubernetes 自定义资源并依赖于 KRM。这些 API（如 Kubernetes API）是基于 HTTP 的 RESTful API，默认接受和返回 JSON 或 Protobuf。API 端点是相关的 Kubernetes 服务器。

其他非基于 Kubernetes 的 GDC API（例如 Vertex 预训练 AI API）有自己的端点。除了支持 HTTP 之外，其中一些 API 还可以通过 gRPC（开源远程过程调用框架）进行访问。如需详细了解特定 API，请参阅垂直导航菜单中的专用文档。

如需访问 GDC API，请使用 gdcloud CLI 工具或 GDC 控制台。

关于 Kubernetes API 和 KRM

由于许多 GDC API 都是 Kubernetes API 的扩展，并且依赖于 KRM，因此了解这些概念有助于您充分利用 GDC API。

Kubernetes API 是完全声明式的，Kubernetes API 中的所有内容都是遵循 KRM 的资源。API 客户端（包括人和机器）对这些资源执行操作，通常是创建、读取、更新和删除 (CRUD) 操作。Kubernetes 数据库会存储资源并表示系统状态。Kubernetes 会持续监控这些资源，并使系统的实际状态与期望状态保持一致。例如，如果您更新 Deployment 资源，以指明您希望容器有五个副本而不是四个，则 Kubernetes 会检测到所需副本数量的变化，并创建一个额外的容器。

对于核心 Kubernetes API，Kubernetes 会自行执行所需状态与实际状态之间的协调。Kubernetes API 扩展是不属于核心 Kubernetes API 的自定义资源。自定义软件会持续监控 Kubernetes API 并与之交互，然后执行协调。

如需详细了解 Kubernetes API 和 Kubernetes 资源模型，请参阅官方 Kubernetes 文档。

• Kubernetes API 概览，网址为 https://kubernetes.io/docs/reference/using-api/
• Kubernetes API 概念，网址为 https://kubernetes.io/docs/reference/using-api/api-concepts/
• Kubernetes 资源模型 (KRM)，网址为 https://github.com/kubernetes/design-proposals-archive/blob/main/architecture/resource-management.md

全球级和可用区级 API

GDC 网闸隔离配置中的资源可以是可用区级资源，也可以是全球性资源。可用区级资源在单个可用区内独立运行，可用区级服务中断可能会影响该可用区内的部分或全部资源。全球级资源在多个可用区中以冗余方式运行，以实现容错。

GDC 网闸隔离配置提供两个级别的管理平面 API，用于创建和管理这两种 GDC 资源类型：全局 API 和可用区级 API。

全球 API 和可用区级 API 都是在不同端点提供的 Kubernetes 声明式 API，GDC 资源在 API 服务器中表示为 Kubernetes 自定义资源。全球 API 服务器共享一个分布在多个可用区的 etcd 集群，以提供具有容错能力的强一致性，但与可用区级 API 服务器相比，延迟时间更长，每秒写入查询次数 (QPS) 更少。在每个组织中，可用区级 Management API 服务器提供可用区级 API，供管理员和开发者管理可用区级资源；全球 API 服务器提供全球 API，用于管理多可用区资源。

GDC API 访问权限

gdcloud CLI 工具和 GDC 控制台都利用 GDC API。Google 建议您使用这些工具来探索 GDC 或执行一次性操作。但是，如果您使用自动化或程序化方式访问 GDC，Google 建议您直接使用 GDC API。

HTTP 和 gRPC 支持

大多数 GDC API 都提供可直接调用的 JSON HTTP 接口。基于 Kubernetes 的 API 使用 Kubernetes 客户端库。一些非 Kubernetes GDC API 具有 gRPC 接口，可提供更高的性能和易用性。Google 还为不基于 Kubernetes 的 GDC API 提供客户端库。 如需详细了解 gRPC，请访问 https://grpc.io/。

TLS 加密

所有 GDC API 都接受使用传输层安全协议 (TLS) 加密的请求。

• 如果您使用的是 Kubernetes 或 GDC 客户端库，该库会为您处理传输中加密。
• 如果您使用的是自己的 HTTP 或 gRPC 客户端，则必须使用 GDC 进行身份验证，这需要 TLS。 对于 gRPC，请按照 gRPC 身份验证指南（网址为 https://grpc.io/docs/guides/auth/）中的说明操作。

注意：GDC 建议您使用现有客户端（尤其是 Google 提供的客户端）与 GDC API 进行交互。创建自己的 API 客户端是一项艰巨的软件工程任务，如果操作不当，可能会导致系统出现难以诊断的意外行为。

访问 Kubernetes API 和基于 Kubernetes 的 API

kubectl Kubernetes CLI 是直接使用 Kubernetes API 和任何基于 Kubernetes 的 API 的主要方式。

使用 kubectl 访问

首次访问 Kubernetes API 时，请使用 Kubernetes 命令行工具 kubectl。

如需访问集群，您需要集群位置信息和访问集群所需的凭据。请参阅登录部分，了解如何获取这些凭证。

检查当前的 kubectl 配置，并查看您有权访问的集群：

kubectl config view

生成 API 端点说明

如需查看 GDC 网闸隔离配置中所有服务 API 的可用 API 端点列表，您可以按照 OpenAPI 规范生成 JSON 格式的 API 说明。您可以在 Swagger 等工具中查看为 API 端点生成的 JSON。

完成以下步骤，以 JSON 格式生成管理和数据平面 API 端点说明：

1. 在您的环境与 Management API 服务器之间创建代理服务器：

   kubectl proxy --kubeconfig MANAGEMENT_API_SERVER
   

   将 MANAGEMENT_API_SERVER 替换为 Management API 服务器的 kubeconfig 文件的路径。如需了解详情，请参阅可用区级 Management API 服务器资源。

2. 下载 JSON 格式的 API 端点说明列表：

   curl -s http://127.0.0.1:8001/openapi/v2 | jq 'if .paths then .paths = (.paths
       | with_entries(select(.key | contains(".private") | not))) else . end' > k8s_swagger.json
   

3. 在 Swagger 等工具中打开生成的 k8s_swagger.json 文件，以查看 API 端点说明。

使用 HTTP 客户端直接访问 API

以下是使用 HTTP 客户端（例如 curl、wget 或浏览器）直接访问 REST API 的方法：

• 在代理模式下使用 kubectl，让其处理身份验证。
• 自行处理身份验证。

运行 kubectl proxy

kubectl proxy 命令在 kubectl 充当反向代理的模式下运行。此命令会连接到 apiserver 并管理身份验证。

在代理模式下运行 kubectl 会使用存储的 API 服务器位置，并使用证书验证 API 服务器的身份。此方法可防范中间人 (MITM) 攻击。

以下示例展示了如何使用 kubectl proxy 命令：

kubectl proxy --port=8080 &

kubectl 代理运行后，您可以使用 curl、wget 或浏览器探索 API，如下所示：

$ curl http://localhost:8080/api/
{
  "versions": [
    "v1"
  ],
  "serverAddressByClientCIDRs": [
    {
      "clientCIDR": "0.0.0.0/0",
      "serverAddress": "10.0.1.149:443"
    }
  ]
}

在不使用 kubectl 代理的情况下运行

如果您不想在代理模式下运行 kubectl，则可以直接将身份验证令牌传递给 API 服务器。

1. 列出您有权访问的所有可能的 Kubernetes 集群，因为您的 kubeconfig 文件可能有多个上下文：

   kubectl config view \
       -o jsonpath='{"Cluster name\tServer\n"}{range.clusters[*]}{.name}{"\t"}{.cluster.server}{"\n"}{end}'
   

2. 从上一个输出中导出要与之交互的 Kubernetes 集群的名称：

   export CLUSTER_NAME="CLUSTER_NAME"
   

3. 设置引用 Kubernetes 集群名称的 API 服务器：

   APISERVER=$(kubectl config view -o jsonpath="{.clusters[?(@.name==\"$CLUSTER_NAME\")].cluster.server}")
   

4. 创建一个 Secret 来存储默认服务账号的令牌：

   kubectl apply -n NAMESPACE -f - <<EOF
   apiVersion: v1
   kind: Secret
   metadata:
     name: default-token
     annotations:
       kubernetes.io/service-account.name: default
   type: kubernetes.io/service-account-token
   EOF
   

5. 等待令牌控制器使用令牌填充 Secret：

   while ! kubectl describe secret default-token -n NAMESPACE | grep -E '^token' >/dev/null; do
     echo "waiting for token..." >&2
     sleep 1
   done
   

6. 设置令牌值：

   TOKEN=$(kubectl get secret default-token -n NAMESPACE \
       -o jsonpath='{.data.token}' | base64 --decode)
   

7. 如需访问 API，请将该令牌与 curl 等工具搭配使用，方法是添加 HTTP 标头 Authorization: Bearer $TOKEN，如以下示例所示：

   curl -k $APISERVER/api --header "Authorization: Bearer $TOKEN"
   

   输出类似于以下内容：

   {
     "kind": "APIVersions",
     "versions": [
       "v1"
     ],
     "serverAddressByClientCIDRs": [
       {
         "clientCIDR": "0.0.0.0/0",
         "serverAddress": "10.0.1.149:443"
       }
     ]
   }