Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

Agentenidentität für einen GKE-Agenten anfordern

Autopilot Standard

Agent-Arbeitslasten, die Sie in Google Kubernetes Engine-Clustern (GKE) bereitstellen, müssen häufig auf externe Tools und Dienste zugreifen, entweder mit der eigenen Identität des Agents oder im Namen von Endnutzern. Sicherheits- und Plattformadministratoren möchten auch wissen, was bereitgestellte Agents in den Google Cloud-Diensten tun. In diesem Dokument wird beschrieben, wie Sie die Authentifizierung für Agent-Arbeitslasten konfigurieren, indem Sie eine Agent-Identität für Ihre Pods anfordern. Mit dieser Agent-Identität können Sie die Authentifizierung konfigurieren, ohne Anmeldedaten für verschiedene Workflows manuell verwalten zu müssen. Außerdem werden Ihre GKE-Agents in die Gemini Enterprise Agent Platform eingebunden. Dieses Dokument richtet sich an Anwendungsentwickler, die Agent-Arbeitslasten in GKE-Clustern erstellen und ausführen.

Sie sollten bereits mit den folgenden Themen vertraut sein:

Preise

Die Agent-Identität wird in GKE ohne zusätzliche Kosten bereitgestellt.

Beschränkungen

Sie können nur Bereitstellungen automatisch in der Agent Registry registrieren. Andere Workload-Controller und statische Pods unterstützen keine automatische Registrierung. Sie können zwar Agent-Identitäten für alle Arbeitslasttypen anfordern, aber durch die Registrierung in der Agent Registry können Sie diese Identitäten in die Agent Platform einbinden.
Für Zugriffstokens für gebundene Agentenidentitäten wird nur der OAuth-Bereich https://www.googleapis.com/auth/cloud-platform verwendet. Sie können keinen anderen Bereich für die gebundenen Zugriffstokens angeben.

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.
Hinweis: Legen Sie für vorhandene Installationen der gcloud CLI das compute/region-Attribut fest. Wenn Sie hauptsächlich zonale Cluster verwenden, legen Sie stattdessen compute/zone fest. Wenn Sie einen standardmäßigen Speicherort festlegen, können Sie in der gcloud CLI Fehler wie diesen vermeiden: One of [--zone, --region] must be supplied: Please specify location. Bei bestimmten Befehlen müssen Sie möglicherweise den Speicherort angeben, wenn er sich von dem von Ihnen festgelegten Standard unterscheidet.

Aktivieren Sie die Agent Registry API, falls sie noch nicht aktiviert ist:
Rollen, die zum Aktivieren von APIs erforderlich sind
Zum Aktivieren von APIs benötigen Sie die Berechtigung serviceusage.services.enable. Wenn Sie das Projekt erstellt haben, haben Sie diese Berechtigung wahrscheinlich bereits über die Rolle „Inhaber“ (roles/owner). Andernfalls können Sie diese Berechtigung über die Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin) erhalten. Informationen zum Zuweisen von Rollen
```
gcloud services enable agentregistry.googleapis.com
```
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.
Prüfen Sie, ob Ihr Kontingent für den Tausch von Tokens ausreicht. Dieses Kontingent hat den Namen Workload Identity-Tokenanfragen pro Minute und Region austauschen. Weitere Informationen finden Sie unter Kontingente und Limits.

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die IAM-Rolle Kubernetes Engine Developer (roles/container.developer) für Ihr Google Cloud Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Anfordern einer Agent-Identität und zum Bereitstellen von Arbeitslasten 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.

Agent-Identität für eine Arbeitslast anfordern

Wenn Sie eine Agent-Identität für Pods abrufen möchten, fügen Sie Ihrer Pod-Spezifikation Annotationen hinzu, um eine SPIFFE-ID für die Arbeitslast anzufordern und das X.509-Zertifikatbündel in jeden Pod einzufügen. Für Pods, die von Deployments verwaltet werden, sollten Sie auch eine Annotation und ein Label hinzufügen, um den Agenten in Agent Registry zu registrieren. Die Registrierung ist zwar optional, aber nur registrierte Agenten können Agent Platform-Dienste wie Agent Gateway nutzen. Weitere Informationen zu den spezifischen Anmerkungen und Labels finden Sie unter Konfiguration auf Arbeitslastebene.

In den folgenden Schritten wird gezeigt, wie Sie eine Beispielbereitstellung erstellen, die Agent-Identitäten anfordert:

Ermitteln Sie Ihre Organisations-ID. Wenn sich Ihr Projekt nicht in einer Organisation befindet, überspringen Sie diesen Schritt und suchen Sie stattdessen nach Ihrer Projektnummer.
```
gcloud projects get-ancestors PROJECT_ID
```
Ersetzen Sie PROJECT_ID durch die Clusterprojekt-ID.

Die Ausgabe sieht etwa so aus:
```
ID: my-project
TYPE: project
ID: 811159889184
TYPE: folder
ID: 301928500920
TYPE: organization
```
Notieren Sie sich den Wert im Feld ID für die organization-Ressource.
Stellen Sie eine Verbindung zu Ihrem Cluster her:
```
gcloud container clusters get-credentials CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION
```
Ersetzen Sie Folgendes:
- CLUSTER_NAME: Der Name Ihres Clusters.
- CONTROL_PLANE_LOCATION: die Region oder Zone der Steuerungsebene Ihres Clusters.
Erstellen Sie einen Namespace, in dem Sie das Beispiel-Deployment ausführen können:
```
kubectl create namespace NAMESPACE_NAME
```
Ersetzen Sie NAMESPACE_NAME durch einen Namen für den Namespace.
Erstellen Sie ein Kubernetes-ServiceAccount für das Deployment:
```
kubectl create serviceaccount SERVICEACCOUNT_NAME \
    --namespace=NAMESPACE_NAME
```
Ersetzen Sie SERVICEACCOUNT_NAME durch einen Namen für das Dienstkonto.

Speichern Sie das folgende Deployment-Manifest als 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"]

Ersetzen Sie TRUST_DOMAIN durch die Vertrauensdomäne, die Identitäten für Agents in Ihrem Projekt ausstellt. Für diesen Wert muss eine der folgenden Syntaxen verwendet werden, je nachdem, ob sich Ihr Projekt in einer Organisation befindet:

Projekte in einer Organisation: agents.global.org-ORGANIZATION_ID.system.id.goog, wobei ORGANIZATION_ID die ID der Organisation ist.
Projekte, die sich nicht in einer Organisation befinden: agents.global.proj-PROJECT_NUMBER.system.id.goog, wobei PROJECT_NUMBER die Projektnummer des Clusterprojekts ist.

Bei dieser Bereitstellung wird eine Agent-Identität für die Arbeitslast angefordert, die X.509-Zertifikate pro Pod werden den Pods hinzugefügt und der Agent wird in der Agent Registry registriert.

Erstellen Sie das Deployment:

kubectl apply -f agent-identity-deployment.yaml

Prüfen Sie, ob die Pods ausgeführt werden:

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

Zugewiesene Agentenidentität prüfen

Nachdem Sie eine Arbeitslast bereitgestellt haben, die eine Agent-Identität anfordert, können Sie die Identität anhand der X.509-Zertifikate überprüfen. Wenn Sie die Zertifikateinfügung deaktivieren, können Sie ein nicht gebundenes Identitätstoken vom GKE-Metadatenserver abrufen, um das Betrefffeld zu prüfen, wie unter Bei Google Cloud -APIs authentifizieren beschrieben.

So lesen Sie das X.509-Zertifikat in einem Pod:

Prüfen, ob ein Pod Zugriff auf das X.509-Zertifikat und den privaten Schlüssel hat:
```
kubectl get pod POD_NAME -n NAMESPACE_NAME \
    -o=jsonpath='{range .spec.volumes[*]}{.name}{"\n"}{end}'
```
Ersetzen Sie POD_NAME durch den Namen eines Pods, der die Agent-Identität verwendet.

Die Ausgabe sieht etwa so aus:
```
kube-api-access-bx86g
gke-workload-spiffe-credentials
```
In dieser Ausgabe ist das gke-workload-spiffe-credentials-Volume der Speicherort der eingefügten Zertifikate. Wenn dieses Volume nicht angezeigt wird, prüfen Sie, ob die Annotation iam.gke.io/inject-podcertificates in der Pod-Spezifikation auf den Wert true festgelegt ist.

Erstellen Sie eine interaktive Shell-Sitzung im Pod:

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

Listen Sie in der Shell-Sitzung die Anmeldedaten im gke-workload-spiffe-credentials-Volume auf:
```
ls -1 /var/run/secrets/workload-spiffe-credentials/
```
Die Ausgabe sieht etwa so aus:
```
x509.credential-bundle.private-key.pem
TRUST_DOMAIN.spiffe-trust-bundle.pem
```
Die Ausgabe zeigt die folgenden Dateien:
- x509.credential-bundle.private-key.pem: Das Bündel mit den Berechtigungsnachweisen für die Identität des Agenten, das die X.509-Zertifikatskette und einen privaten Schlüssel enthält, der für den Pod eindeutig ist. Dieses Anmeldedatenpaket wird verwendet, um Zugriffstokens und ID-Tokens anzufordern und sich über mTLS bei Google Cloud-APIs zu authentifizieren.
- TRUST_DOMAIN.spiffe-trust-bundle.pem: das Root-CA-Trust-Bundle, das die selbst signierten Zertifikate enthält, die den Trust-Anchor für die Anmeldedaten der Agent-Identität bilden. Dieses Vertrauensbündel wird hauptsächlich verwendet, um TLS-Zertifikate von anderen Arbeitslasten während mTLS-Handshakes zu validieren.

So rufen Sie die SPIFFE-ID ab, die dem Pod zugeordnet ist: Lesen Sie das X.509-Zertifikat.

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

Die Ausgabe sieht etwa so aus:

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

In dieser Ausgabe ist der Wert, der sich im Feld URI für das Feld X509v3 Subject Alternative Name befindet, die SPIFFE-ID des Agenten.

Wenn Ihrem Agent-Pod eine SPIFFE-ID zugewiesen ist, war Ihre Anfrage nach einer Agent-Identität erfolgreich. Sie können die zugewiesene Identität verwenden, um sich bei verschiedenen Tools und Diensten zu authentifizieren.