管理代理程式的 Google Cloud API 存取權

應用程式開發人員可以為在 Google Kubernetes Engine (GKE) 上執行的 AI 代理程式要求代理程式身分。代理程式身分是每個 Pod 的身分，可加密繫結至工作負載中的每個 Pod。代理程式隨後即可使用代理程式身分向 Google Cloud API 驗證身分。您可以將代理程式納入 Identity and Access Management (IAM) 政策，藉此控管代理程式可存取的資源。本文說明如何管理代理程式的 API 和服務存取權，這些代理程式使用代理程式身分。 Google Cloud

本文適用於安全管理員和平台管理員，他們負責管理開發人員部署至 GKE 叢集的代理授權。您應已熟悉下列主題：

事前準備

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

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

必要的角色

如要取得管理代理程式 Google Cloud API 存取權所需的權限，請要求管理員在 Google Cloud 專案中授予您下列 IAM 角色：

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

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

找出代理的主體 ID

本節說明如何建構代理程式的主體 ID。您可以在 IAM 政策中使用這個 ID，控管代理程式可存取的資源。

任何要求代理身分的代理工作負載，都會取得該工作負載專屬的 SPIFFE 身分字串。應用程式呼叫 Google Cloud API 時，系統會使用代理身分存取權杖驗證呼叫，確認工作負載具有代理身分。這個存取權杖包含代理程式工作負載的 IAM 主體 ID，您可以在 IAM 政策中加入這個 ID，控管代理程式可存取的資源。

設計 IAM 政策時，您可以使用下列資訊，為代理建構主體 ID：

  • 專案的資源階層。
  • 叢集名稱。
  • Kubernetes 命名空間和該命名空間中的 Kubernetes ServiceAccount。

開發人員部署代理程式時，如果代理程式取得的代理程式身分與主體 ID 相符，代理程式就會沿用您在政策中指定的存取權。

如要找出要在政策中使用的主要 ID，請按照下列步驟操作：

  1. 找出身分識別的信任網域。信任網域取決於專案是否屬於機構，如下所示：

    • 組織中的專案：

      agents.global.org-ORGANIZATION_ID.system.id.goog

      將 ORGANIZATION_ID 替換為組織 ID。

    • 不屬於任何機構的專案：

      agents.global.proj-PROJECT_NUMBER.system.id.goog

      將 PROJECT_NUMBER 替換為叢集專案的專案編號。

  2. 找出叢集的下列資訊：

    • GKE 叢集的名稱。
    • 叢集控制層的位置，例如 us-central1。
    • 開發人員用來部署工作負載的 Kubernetes 命名空間。
    • 開發人員必須用於代理程式工作負載的 Kubernetes ServiceAccount 名稱。

    如果不知道這項資訊，請洽詢平台團隊。平台團隊應在叢集中設定命名空間、ServiceAccount 和 RBAC 政策，讓存取需求不同的代理程式取得不同的身分。

  3. 建構主體 ID：

    principal://TRUST_DOMAIN/resources/container/projects/PROJECT_NUMBER/locations/CONTROL_PLANE_LOCATION/clusters/CLUSTER_NAME/ns/KUBERNETES_NAMESPACE/sa/KUBERNETES_SERVICEACCOUNT

    更改下列內容：

    • TRUST_DOMAIN：代理程式身分識別的信任網域。
    • PROJECT_NUMBER：叢集專案的專案編號。
    • CONTROL_PLANE_LOCATION：叢集控制層的區域或可用區。
    • CLUSTER_NAME：叢集名稱。
    • KUBERNETES_NAMESPACE：Kubernetes 命名空間的名稱。
    • KUBERNETES_SERVICEACCOUNT：Kubernetes ServiceAccount 的名稱。

使用政策控管存取權

本節說明如何使用代理程式的主體 ID，控管代理程式可存取的 Google Cloud API 和服務。如要控管存取權，請在下列任一 IAM 政策中加入主體 ID：

建立或更新政策後，任何要求代理程式身分並在該命名空間中執行，以及使用該 ServiceAccount 的代理程式，都會擁有您在政策中指定的存取權。

授權代理存取驗證管理工具

代理身分驗證管理員是驗證中介服務和憑證保管庫，代理可能會使用這些服務取得憑證，以代理身分或代表使用者存取外部工具和服務。驗證管理員可以有一或多個驗證供應商，每個供應商都會處理特定服務的特定驗證和憑證取得流程。如要授予 GKE 代理程式特定驗證提供者存取權，請按照下列步驟操作：

  1. 找出代理的主體 ID。
  2. 取得代理程式需要存取的驗證供應商名稱。

  3. 在授權供應商上，將 Agent Identity 使用者 (roles/agentidentity.user) 角色授予代理主體：

    gcloud agent-identity auth-providers add-iam-policy-binding AUTH_PROVIDER_NAME \
    --location=AUTH_PROVIDER_LOCATION \
    --member=PRINCIPAL_IDENTIFIER \
    --role=roles/agentidentity.user

    更改下列內容：

    • AUTH_PROVIDER_NAME：授權供應商的名稱。
    • AUTH_PROVIDER_LOCATION：授權供應商的區域。
    • PRINCIPAL_IDENTIFIER：代理程式的主體 ID。

    或者，對於在 Agent Registry 中註冊的代理程式，您可以建立驗證提供者繫結，管理驗證提供者的存取權。

後續步驟