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 型和非 Kubernetes 型。許多 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 都是 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 伺服器之間建立 Proxy 伺服器：

   kubectl proxy --kubeconfig MANAGEMENT_API_SERVER
   

   將 MANAGEMENT_API_SERVER 替換為管理 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

您可以透過 curl、wget 等 HTTP 用戶端或瀏覽器，直接存取 REST API，方法如下：

• 在 Proxy 模式下使用 kubectl 處理驗證。
• 自行處理驗證。

執行 kubectl proxy

kubectl proxy 指令會以反向 Proxy 模式執行 kubectl。這個指令會連線至 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 伺服器。

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