Zugriff auf Google Cloud-APIs für KI-Agenten verwalten

Anwendungsentwickler können eine Agent-Identität für KI-Agents anfordern, die in Google Kubernetes Engine (GKE) ausgeführt werden. Die Agent-Identität ist eine Identität pro Pod, die kryptografisch an jeden Pod in der Arbeitslast gebunden werden kann. KI-Agenten können sich dann mit der KI-Agentenidentität bei Google Cloud APIs authentifizieren. Sie können steuern, auf welche Ressourcen ein Agent zugreifen kann, indem Sie den Agenten als Prinzipal in IAM-Richtlinien (Identity and Access Management) angeben. In diesem Dokument wird beschrieben, wie Sie den Zugriff auf Google Cloud APIs und -Dienste für Agents verwalten, die eine Agent-Identität verwenden.

Dieses Dokument richtet sich an Sicherheitsadministratoren und Plattformadministratoren, die die Autorisierung für Agents verwalten, die Entwickler in GKE-Clustern bereitstellen. Sie sollten bereits mit den folgenden Themen vertraut sein:

Hinweis

Führen Sie die folgenden Aufgaben aus, bevor Sie beginnen:

  • Aktivieren Sie die Google Kubernetes Engine API.
    • Google Kubernetes Engine API aktivieren
  • Wenn Sie die Google Cloud CLI für diese Aufgabe verwenden möchten, müssen Sie die gcloud CLI installieren und dann initialisieren. Wenn Sie die gcloud CLI bereits installiert haben, rufen Sie die neueste Version mit dem Befehl gcloud components update ab. In früheren gcloud CLI-Versionen werden die Befehle in diesem Dokument möglicherweise nicht unterstützt.
  • Prüfen Sie, ob Sie einen Autopilot-Cluster oder einen Standardcluster mit aktivierter Workload Identity Federation for GKE haben, auf dem GKE-Version 1.37.0-gke.3503000 oder höher ausgeführt wird.

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für das Google Cloud Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Verwalten des Zugriffs auf Google Cloud APIs für Agents benötigen:

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

Prinzipal-ID eines KI-Agenten ermitteln

In diesem Abschnitt wird beschrieben, wie Sie die Prinzipal-ID für einen Agent erstellen. Sie können diese Kennung in IAM-Richtlinien verwenden, um zu steuern, auf welche Ressourcen der Agent zugreifen kann.

Jede Agent-Arbeitslast, die eine Agent-Identität anfordert, erhält einen SPIFFE-Identitätsstring, der für diese Arbeitslast eindeutig ist. Wenn die Anwendung Google Cloud APIs aufruft, werden die Aufrufe mit einem Zugriffstoken für die KI-Agentenidentität authentifiziert, das bestätigt, dass die Arbeitslast eine KI-Agentenidentität hat. Dieses Zugriffstoken enthält eine IAM-Hauptkonto-ID für die Agent-Arbeitslast, die Sie in IAM-Richtlinien einfügen können, um zu steuern, auf welche Ressourcen der Agent Zugriff hat.

Beim Entwerfen Ihrer IAM-Richtlinien können Sie die Hauptkonto-IDs für Agents mit den folgenden Informationen erstellen:

  • Die Ressourcenhierarchie des Projekts.
  • Der Name des Clusters.
  • Der Kubernetes-Namespace und das Kubernetes-ServiceAccount in diesem Namespace.

Wenn Entwickler Agenten bereitstellen, die eine Agentenidentität erhalten, die mit der Prinzipal-ID übereinstimmt, erbt der Agent den Zugriff, den Sie in Ihrer Richtlinie angegeben haben.

So finden Sie die Prinzipal-ID, die Sie in Ihren Richtlinien verwenden können:

  1. Identifizieren Sie die Vertrauensdomäne für die Identität. Die Vertrauensdomäne hängt davon ab, ob sich das Projekt in einer Organisation befindet:

    • Projekte in einer Organisation:

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

      Ersetzen Sie ORGANIZATION_ID durch die Organisations-ID.

    • Projekte, die nicht in einer Organisation sind:

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

      Ersetzen Sie PROJECT_NUMBER durch die Projektnummer des Clusterprojekts.

  2. Ermitteln Sie die folgenden Informationen zum Cluster:

    • Der Name des GKE-Clusters.
    • Der Standort der Cluster-Steuerungsebene, z. B. us-central1.
    • Der Kubernetes-Namespace, in dem Entwickler die Arbeitslasten bereitstellen.
    • Der Name des Kubernetes-Dienstkontos, das Entwickler für die Agent-Arbeitslast verwenden müssen.

    Wenn Sie diese Informationen nicht kennen, fragen Sie Ihr Plattformteam. Das Plattformteam sollte die Namespaces, ServiceAccounts und RBAC-Richtlinien im Cluster so einrichten, dass Agents mit unterschiedlichen Zugriffsanforderungen unterschiedliche Identitäten erhalten.

  3. Hauptkonto-ID erstellen:

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

    Ersetzen Sie Folgendes:

    • TRUST_DOMAIN: die Vertrauensdomäne für die Agent Identity.
    • PROJECT_NUMBER: die Projektnummer des Clusterprojekts.
    • CONTROL_PLANE_LOCATION: Die Region oder Zone der Cluster-Steuerungsebene.
    • CLUSTER_NAME ist der Name des Clusters.
    • KUBERNETES_NAMESPACE: der Name des Kubernetes-Namespace.
    • KUBERNETES_SERVICEACCOUNT ist der Name des Kubernetes-Dienstkontos.

Zugriff mit Richtlinien steuern

In diesem Abschnitt wird beschrieben, wie Sie mit der Prinzipal-ID eines Agents steuern, auf welche Google Cloud APIs und -Dienste der Agent zugreifen kann. Um den Zugriff zu steuern, fügen Sie die Hauptkonto-ID in eine der folgenden IAM-Richtlinien ein:

Nachdem Sie eine Richtlinie erstellt oder aktualisiert haben, hat jeder Agent, der eine Agent-Identität anfordert, in diesem Namespace ausgeführt wird und dieses Dienstkonto verwendet, den Zugriff, den Sie in Ihren Richtlinien angeben.

KI‑Agents den Zugriff auf den Authentifizierungsmanager autorisieren

Der Authentifizierungsmanager für die Identität von KI-Agenten ist ein Authentifizierungsbroker und Anmeldedatenspeicher, den Agenten verwenden können, um Anmeldedaten für den Zugriff auf externe Tools und Dienste zu erhalten, entweder als eigene Identität des Agenten oder im Namen eines Endnutzers. Der Auth-Manager kann einen oder mehrere Auth-Anbieter haben, von denen jeder einen bestimmten Authentifizierungs- und Anmeldedatenabrufablauf für einen bestimmten Dienst übernimmt. So gewähren Sie GKE-Agents Zugriff auf bestimmte Authentifizierungsanbieter:

  1. Prinzipal-ID für den Agenten ermitteln
  2. Rufen Sie den Namen des Authentifizierungsanbieters ab, auf den der KI-Agent zugreifen muss.

  3. Weisen Sie dem Agent-Prinzipal die Rolle „Agent Identity User“ (roles/agentidentity.user) für den Auth-Anbieter zu:

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

    Ersetzen Sie Folgendes:

    • AUTH_PROVIDER_NAME: der Name des Authentifizierungsanbieters.
    • AUTH_PROVIDER_LOCATION: die Region des Authentifizierungsanbieters.
    • PRINCIPAL_IDENTIFIER: die Hauptkonto-ID des Agenten.

    Alternativ können Sie für Agenten, die in der Agent Registry registriert sind, den Zugriff auf Authentifizierungsanbieter verwalten, indem Sie eine Bindung für den Authentifizierungsanbieter erstellen.

Nächste Schritte