本頁面由 Cloud Translation API 翻譯而成。

Google Distributed Cloud 實體隔離方案 API 總覽

Google Distributed Cloud (GDC) 實體隔離應用程式設計介面 (API) 是 GDC 平台服務的程式輔助介面。Google 會使用 Kubernetes Resource Model (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 air-gapped 提供兩個層級的管理平面 API，可建立及管理 GDC 資源類型：全域 API 和區域 API。

全域和區域 API 都是 Kubernetes 宣告式 API，在不同端點提供服務，而 GDC 資源則以 Kubernetes 自訂資源的形式，在 API 伺服器中表示。全球 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

您可以使用 HTTP 用戶端 (例如 curl、wget 或瀏覽器) 直接存取 REST API，方法如下：

在 Proxy 模式下使用 kubectl，讓該工具處理驗證作業。
自行處理驗證。

執行 kubectl proxy

kubectl proxy 指令會在模式中執行 kubectl，做為反向 Proxy。這項指令會連線至 apiserver 並管理驗證。

以 Proxy 模式執行 kubectl 時，會使用儲存的 API 伺服器位置，並透過憑證驗證 API 伺服器的身分。這個方法可防範中間人 (MITM) 攻擊。

下列範例說明如何使用 kubectl proxy 指令：

kubectl proxy --port=8080 &

kubectl Proxy 執行後，您可以使用 curl、wget 或瀏覽器探索 API，如下所示：

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

不使用 kubectl proxy 執行

如果不想以 Proxy 模式執行 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}")

建立密碼，用來保存預設服務帳戶的權杖：

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

等待權杖控制器以權杖填入密鑰：

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"
    }
  ]
}