Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

Richiedi un'identità dell'agente per un agente GKE

Autopilot Standard

I carichi di lavoro degli agenti che esegui il deployment nei cluster Google Kubernetes Engine (GKE) spesso devono accedere a strumenti e servizi esterni, con l'identità dell'agente o per conto degli utenti finali. Gli amministratori della sicurezza e gli amministratori della piattaforma vogliono anche sapere cosa fanno gli agenti di cui è stato eseguito il deployment nei vari Google Cloud servizi. Questo documento mostra come configurare l'autenticazione per i carichi di lavoro degli agenti richiedendo un'identità agente per i tuoi pod. Questa identità dell'agente ti consente di configurare l'autenticazione senza dover gestire manualmente le credenziali per diversi workflow e integra gli agenti GKE con Gemini Enterprise Agent Platform. Questo documento è destinato agli sviluppatori di applicazioni che creano ed eseguono carichi di lavoro degli agenti sui cluster GKE.

Dovresti già avere familiarità con i seguenti argomenti:

Prezzi

L'identità dell'agente è fornita senza costi aggiuntivi in GKE.

Limitazioni

Puoi registrare automaticamente solo i deployment in Agent Registry. Altri controller dei carichi di lavoro e pod statici non supportano la registrazione automatica. Sebbene tu possa richiedere identità agente per tutti i tipi di workload, la registrazione in Agent Registry ti consente di integrare queste identità con Agent Platform.
I token di accesso con identità dell'agente vincolata utilizzano solo l'ambito OAuth https://www.googleapis.com/auth/cloud-platform. Non puoi specificare un ambito diverso per i token di accesso vincolati.

Prima di iniziare

Prima di iniziare, assicurati di aver eseguito le seguenti operazioni:

Abilita l'API Google Kubernetes Engine.

Abilita l'API Google Kubernetes Engine

Per utilizzare Google Cloud CLI per questa attività, installala e poi inizializza gcloud CLI. Se hai già installato gcloud CLI, scarica l'ultima versione eseguendo il comando gcloud components update. Le versioni precedenti di gcloud CLI potrebbero non supportare l'esecuzione dei comandi in questo documento.
Nota: per le installazioni esistenti di gcloud CLI, assicurati di impostare la proprietà compute/region. Se utilizzi principalmente cluster zonali, imposta invece compute/zone. Se imposti una località predefinita, puoi evitare errori in gcloud CLI come il seguente: One of [--zone, --region] must be supplied: Please specify location. Potresti dover specificare la posizione in determinati comandi se la posizione del cluster è diversa da quella predefinita che hai impostato.

Abilita l'API Agent Registry, se non è già abilitata:
Ruoli richiesti per abilitare le API
Per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente disponi già di questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore utilizzo servizi (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.
```
gcloud services enable agentregistry.googleapis.com
```
Verifica di avere un cluster Autopilot esistente o un cluster Standard con la Workload Identity Federation for GKE abilitata e che esegue GKE versione 1.37.0-gke.3503000 o successive.
Verifica di disporre di una quota sufficiente per le operazioni di scambio di token. Questa quota ha il nome Richieste di token di identità del workload di Exchange al minuto per regione. Per saperne di più, consulta Quote e limiti.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per richiedere un'identità agente ed eseguire il deployment dei carichi di lavoro, chiedi all'amministratore di concederti il ruolo IAM Kubernetes Engine Developer (roles/container.developer) nel progetto Google Cloud . Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Richiedere un'identità agente per un workload

Per ottenere un'identità agente per i pod, aggiungi annotazioni alla specifica del pod per richiedere un ID SPIFFE per il workload e per inserire il bundle di certificati X.509 in ogni pod. Per i pod gestiti dai deployment, devi anche aggiungere un'annotazione e un'etichetta per registrare l'agente in Agent Registry. Sebbene la registrazione sia facoltativa, solo gli agenti registrati possono utilizzare i servizi di Agent Platform come Agent Gateway. Per ulteriori informazioni sulle annotazioni e sulle etichette specifiche, consulta Configurazione a livello di workload.

I seguenti passaggi mostrano come creare un esempio di Deployment che richiede identità agent:

Trova il tuo ID organizzazione. Se il tuo progetto non fa parte di un'organizzazione, salta questo passaggio e trova il numero del progetto.
```
gcloud projects get-ancestors PROJECT_ID
```
Sostituisci PROJECT_ID con l'ID progetto del cluster.

L'output è simile al seguente:
```
ID: my-project
TYPE: project
ID: 811159889184
TYPE: folder
ID: 301928500920
TYPE: organization
```
Prendi nota del valore nel campo ID per la risorsa organization.
Connettiti al cluster:
```
gcloud container clusters get-credentials CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION
```
Sostituisci quanto segue:
- CLUSTER_NAME: il nome del tuo cluster.
- CONTROL_PLANE_LOCATION: la regione o la zona del control plane del cluster.
Crea uno spazio dei nomi per eseguire il deployment di esempio:
```
kubectl create namespace NAMESPACE_NAME
```
Sostituisci NAMESPACE_NAME con un nome per lo spazio dei nomi.
Crea un service account Kubernetes per il deployment:
```
kubectl create serviceaccount SERVICEACCOUNT_NAME \
    --namespace=NAMESPACE_NAME
```
Sostituisci SERVICEACCOUNT_NAME con un nome per il service account.

Salva il seguente manifest di deployment come 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"]

Sostituisci TRUST_DOMAIN con il dominio di attendibilità che emette identità per gli agenti nel tuo progetto. Questo valore deve utilizzare una delle seguenti sintassi, a seconda che il progetto si trovi in un'organizzazione:

Progetti che si trovano in un'organizzazione: agents.global.org-ORGANIZATION_ID.system.id.goog, dove ORGANIZATION_ID è l'ID dell'organizzazione.
Progetti che non si trovano in un'organizzazione: agents.global.proj-PROJECT_NUMBER.system.id.goog, dove PROJECT_NUMBER è il numero di progetto del progetto cluster.

Questo deployment richiede un'identità agente per il workload, aggiunge i certificati X.509 per pod ai pod e registra l'agente nel registro degli agenti.

Crea il deployment:

kubectl apply -f agent-identity-deployment.yaml

Verifica che i pod siano in esecuzione:

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

Controllare l'identità dell'agente assegnato

Dopo aver eseguito il deployment di un workload che richiede un'identità agente, puoi verificare l'identità controllando i certificati X.509. Se disattivi l'inserimento del certificato, puoi ottenere un token di identità non associato dal server di metadati GKE per controllare il campo Subject, come descritto in Autenticarsi alle API Google Cloud .

Per leggere il certificato X.509 in un pod:

Controlla se un pod ha accesso al certificato X.509 e alla chiave privata:
```
kubectl get pod POD_NAME -n NAMESPACE_NAME \
    -o=jsonpath='{range .spec.volumes[*]}{.name}{"\n"}{end}'
```
Sostituisci POD_NAME con il nome di un pod che utilizza l'identità dell'agente.

L'output è simile al seguente:
```
kube-api-access-bx86g
gke-workload-spiffe-credentials
```
In questo output, il volume gke-workload-spiffe-credentials è la posizione dei certificati inseriti. Se non vedi questo volume, verifica che l'annotazione iam.gke.io/inject-podcertificates sia impostata sul valore true nella specifica del pod.

Crea una sessione shell interattiva nel pod:

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

Nella sessione della shell, elenca le credenziali nel volume gke-workload-spiffe-credentials:
```
ls -1 /var/run/secrets/workload-spiffe-credentials/
```
L'output è simile al seguente:
```
x509.credential-bundle.private-key.pem
TRUST_DOMAIN.spiffe-trust-bundle.pem
```
L'output mostra i seguenti file:
- x509.credential-bundle.private-key.pem: il pacchetto di credenziali di identità dell'agente, che include la catena di certificati X.509 e una chiave privata univoca per il pod. Questo bundle di credenziali viene utilizzato per richiedere token di accesso e token ID e per autenticarsi alle API Google Cloud utilizzando mTLS.
- TRUST_DOMAIN.spiffe-trust-bundle.pem: il bundle di attendibilità della CA radice, che contiene i certificati autofirmati che formano il trust anchor per le credenziali dell'identità dell'agente. Questo bundle di attendibilità viene utilizzato principalmente per convalidare i certificati TLS di altri workload durante gli handshake mTLS.

Per ottenere l'ID SPIFFE associato al pod, leggi il certificato X.509:

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

L'output è simile al seguente:

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 questo output, il valore nel campo URI per il campo X509v3 Subject Alternative Name è l'ID SPIFFE dell'agente.

Se il pod dell'agente ha un ID SPIFFE assegnato, la tua richiesta di identità dell'agente è andata a buon fine. Puoi utilizzare l'identità assegnata per l'autenticazione a vari strumenti e servizi.