此页面由 Cloud Translation API 翻译。

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

Google Distributed Cloud (GDC) 网闸隔离应用编程接口 (API) 是 GDC 平台服务的编程接口。 Google 基于 Kubernetes 使用 Kubernetes 资源模型 (KRM) 构建控制平面 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 资源以指示您希望容器有 5 个副本而不是 4 个，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 和地区 API

GDC 气隙中的资源可以是可用区级资源，也可以是全球资源。地区资源在单个地区内独立运作，地区服务中断可能会影响该地区中的部分或全部资源。全局资源可在多个可用区中以冗余方式运行，以实现容错。

GDC air-gapped 提供两个级别的管理平面 API，用于创建和管理两种 GDC 资源类型：全局 API 和区域 API。

全局 API 和区域 API 都是在不同端点提供的 Kubernetes 声明性 API，而 GDC 资源在 API 服务器中表示为 Kubernetes 自定义资源。全球 API 服务器共享一个分布在各个可用区中的 etcd 集群，以提供具有容错功能的强一致性，但与可用区 API 服务器相比，延迟更高，每秒写入查询次数 (QPS) 更少。在每个组织中，区域管理 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/。

访问 Kubernetes API 和基于 Kubernetes 的 API

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

使用 kubectl 进行访问

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

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

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

kubectl config view

使用 HTTP 客户端直接访问 API

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

依靠 kubectl 在代理模式下处理身份验证。
自行处理身份验证。

运行 kubectl 代理

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 服务器。

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

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

从上一个输出中导出您要与之互动的 Kubernetes 集群的名称：
```
export CLUSTER_NAME="CLUSTER_NAME"
```

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

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

创建一个 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

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

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

设置令牌值：

TOKEN=$(kubectl get secret $(kubectl get secrets | grep default | cut -f1 -d ' ')  \
    -o jsonpath='{.data.token}' | base64 --decode)

如需访问该 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"
    }
  ]
}