為 GKE 代理要求代理身分

您在 Google Kubernetes Engine (GKE) 叢集上部署的代理程式工作負載，通常需要以代理程式本身的身分或代表使用者存取外部工具和服務。安全管理員和平台管理員也想瞭解已部署的代理程式在各項服務中執行的作業。 Google Cloud本文說明如何為 Pod 要求 Agent Identity，藉此設定代理程式工作負載的驗證。有了這個代理程式身分，您就能設定驗證，不必手動管理不同工作流程的憑證，還能將 GKE 代理程式與 Gemini Enterprise Agent Platform 整合。本文適用於在 GKE 叢集上建構及執行代理程式工作負載的應用程式開發人員。

您應該已熟悉下列主題：

定價

在 GKE 中，代理程式身分識別功能無須額外付費。

限制

  • 您只能在 Agent Registry 中自動註冊 Deployment。 其他工作負載控制器和靜態 Pod 不支援自動註冊。雖然您可以為所有工作負載類型要求代理程式身分，但透過代理程式登錄服務註冊，即可將這些身分與 Agent Platform 整合。
  • 繫結的代理程式身分存取權杖只會使用 https://www.googleapis.com/auth/cloud-platform OAuth 範圍。您無法為繫結的存取權杖指定其他範圍。

事前準備

開始之前，請務必先完成下列工作：

  • 啟用 Google Kubernetes Engine API。
    • 啟用 Google Kubernetes Engine API
  • 如要使用 Google Cloud CLI 執行這項工作，請安裝並初始化 gcloud CLI。如果您先前已安裝 gcloud CLI，請執行 gcloud components update 指令，取得最新版本。較舊的 gcloud CLI 版本可能不支援執行本文件中的指令。

  • 如果尚未啟用，請啟用 Agent Registry API：

    啟用 API 時所需的角色

    如要啟用 API，您必須具備 serviceusage.services.enable 權限。如果您建立了專案，可能已透過「擁有者」角色 (roles/owner) 取得這項權限。否則，您可以透過「服務使用管理員」角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。

    gcloud services enable agentregistry.googleapis.com

  • 確認您有現有的 Autopilot 叢集或 Standard 叢集，且已啟用 Workload Identity Federation for GKE，並執行 GKE 1.37.0-gke.3503000 以上版本。

  • 確認您有足夠的權杖交換作業配額。這項配額的名稱為「各區域每分鐘的 Exchange Workload Identity 權杖要求數量」。詳情請參閱「配額與限制」。

必要的角色

如要取得要求代理程式身分和部署工作負載所需的權限，請要求管理員授予您 Google Cloud 專案的 Kubernetes Engine 開發人員 (roles/container.developer) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

為工作負載要求代理程式身分

如要取得 Pod 的代理程式身分，請在 Pod 規格中新增註解，為工作負載要求 SPIFFE ID，並將 X.509 憑證組合注入每個 Pod。如果是由 Deployment 管理的 Pod，您也應新增註解和標籤，在 Agent Registry 中註冊代理程式。雖然註冊是選用程序，但只有註冊的代理程式才能使用 Agent Gateway 等 Agent Platform 服務。如要進一步瞭解特定註解和標籤，請參閱「工作負載層級設定」。

下列步驟說明如何建立範例 Deployment，要求代理程式身分：

  1. 找出組織 ID。如果專案不屬於任何機構，請略過這個步驟，改為找出專案編號。

    gcloud projects get-ancestors PROJECT_ID

    將 PROJECT_ID 替換為叢集專案 ID。

    輸出結果會與下列內容相似：

    ID: my-project
TYPE: project
ID: 811159889184
TYPE: folder
ID: 301928500920
TYPE: organization

    請記下 organization 資源的 ID 欄位值。

  2. 連線至叢集：

    gcloud container clusters get-credentials CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION

    更改下列內容：

    • CLUSTER_NAME：叢集名稱。
    • CONTROL_PLANE_LOCATION：叢集控制層的區域或可用區。

  3. 建立命名空間，執行範例 Deployment：

    kubectl create namespace NAMESPACE_NAME

    將 NAMESPACE_NAME 替換為命名空間的名稱。

  4. 為 Deployment 建立 Kubernetes ServiceAccount：

    kubectl create serviceaccount SERVICEACCOUNT_NAME \
    --namespace=NAMESPACE_NAME

    將 SERVICEACCOUNT_NAME 替換為 ServiceAccount 的名稱。

  5. 將下列部署資訊清單儲存為 agent-identity-deployment.yaml：

    apiVersion: apps/v1
kind: Deployment
metadata:
  name: agent-identity-deployment
  namespace: NAMESPACE_NAME
  # Add the agent to Agent Registry
  labels:
    registry.gke.io/functional-type: "AGENT"
  annotations:
    # A2A protocol metadata annotation for automated Agent Card discovery
    a2a-protocol.org/agent-card: |
      card:
        endpoint: /.well-known/agent-card.json
        protocol: HTTP
        port: 8080
spec:
  replicas: 2
  selector:
    matchLabels:
      workload-type: agent
  template:
    metadata:
      name: agent-identity-pod
      annotations:
        iam.gke.io/identity: "spiffe://TRUST_DOMAIN/*" # The trust domain from which to assign SPIFFE IDs.
        iam.gke.io/inject-podcertificates: "true" # Inject X.509 certificates and per-Pod private key into each Pod.
        iam.gke.io/spiffe-identity-type: "agent-identity" # Required for Agent Registry registration.
      labels:
        workload-type: agent
    spec:
      serviceAccountName: SERVICEACCOUNT_NAME
      containers:
      - name: agent
        image: python:3.11-slim
        command: ["sleep","infinity"]

    將 TRUST_DOMAIN 替換為信任網域，該網域會為專案中的代理程式核發身分。視專案是否隸屬於機構，這個值必須使用下列其中一種語法：

    • 機構中的專案： agents.global.org-ORGANIZATION_ID.system.id.goog， 其中 ORGANIZATION_ID 是機構的 ID。
    • 不屬於機構的專案： agents.global.proj-PROJECT_NUMBER.system.id.goog，其中 PROJECT_NUMBER 是叢集專案的專案編號。

    這項部署作業會為工作負載要求代理程式身分，將每個 Pod 的 X.509 憑證新增至 Pod，並在代理程式登錄中註冊代理程式。

  6. 建立 Deployment：

    kubectl apply -f agent-identity-deployment.yaml

  7. 確認 Pod 正在執行：

    kubectl get pods -l workload-type=agent -n NAMESPACE_NAME

檢查指派的代理程式身分

部署要求代理程式身分的工作負載後，您可以檢查 X.509 憑證來驗證身分。如果停用憑證插入功能，您可以從 GKE 中繼資料伺服器取得未繫結的身分識別權杖，並檢查主體欄位，如「向 API 進行驗證 Google Cloud 」一文所述。

如要在 Pod 中讀取 X.509 憑證，請按照下列步驟操作：

  1. 檢查 Pod 是否可存取 X.509 憑證和私密金鑰：

    kubectl get pod POD_NAME -n NAMESPACE_NAME \
    -o=jsonpath='{range .spec.volumes[*]}{.name}{"\n"}{end}'

    將 POD_NAME 替換為使用代理程式身分的 Pod 名稱。

    輸出結果會與下列內容相似：

    kube-api-access-bx86g
gke-workload-spiffe-credentials

    在這個輸出內容中，gke-workload-spiffe-credentials volume 是注入憑證的位置。如果沒有看到這個磁碟區，請確認 iam.gke.io/inject-podcertificates 註解在 Pod 規格中設為 true 值。

  2. 在 Pod 中建立互動式殼層工作階段：

    kubectl exec -n NAMESPACE_NAME -it POD_NAME -- /bin/bash

  3. 在殼層工作階段中，列出 gke-workload-spiffe-credentials 磁碟區中的憑證：

    ls -1 /var/run/secrets/workload-spiffe-credentials/

    輸出結果會與下列內容相似：

    x509.credential-bundle.private-key.pem
TRUST_DOMAIN.spiffe-trust-bundle.pem

    輸出內容會顯示下列檔案：

    • x509.credential-bundle.private-key.pem：代理程式身分憑證套件，內含 X.509 憑證鏈結和 Pod 專屬的私密金鑰。這個憑證組合可用於要求存取權杖和 ID 權杖，以及使用 mTLS 向 Google CloudAPI 進行驗證。
    • TRUST_DOMAIN.spiffe-trust-bundle.pem：根 CA 信任套件，內含構成代理程式身分憑證信任錨點的自行簽署憑證。這個信任套件主要用於在 mTLS 握手期間，驗證其他工作負載的 TLS 憑證。

  4. 如要取得與 Pod 相關聯的 SPIFFE ID，請讀取 X.509 憑證：

    openssl x509 -in /var/run/secrets/workload-spiffe-credentials/x509.credential-bundle.private-key.pem -text -noout

    輸出結果會與下列內容相似：

    Certificate:
    Data:
    # Multiple lines are omitted here
        X509v3 extensions:
            # Multiple lines are omitted here
            X509v3 Subject Alternative Name: critical
                URI:spiffe://agents.global.org-301928500920.system.id.goog/resources/container/projects/729788050015/locations/us-central1/clusters/cluster-2/ns/agent-identity-ns/sa/agent-identity-sa
    # Multiple lines are omitted here

    在這個輸出內容中，URI 欄位的值 (位於 X509v3 Subject Alternative Name 欄位) 是代理程式的 SPIFFE ID。

如果代理程式 Pod 已獲派 SPIFFE ID，表示您已成功要求代理程式身分。您可以使用指派的身分，向各種工具和服務進行驗證。

後續步驟