Gestisci l'accesso alle API Google Cloud per gli agenti

Gli sviluppatori di applicazioni possono richiedere un'identità agente per gli agenti AI che vengono eseguiti su Google Kubernetes Engine (GKE). L'identità dell'agente è un'identità per pod che può essere associata crittograficamente a ogni pod nel workload. Gli agenti possono quindi autenticarsi nelle API Google Cloud utilizzando l'identità dell'agente. Puoi controllare a quali risorse può accedere un agente includendolo come entità nelle policy Identity and Access Management (IAM). Questo documento descrive come gestire l'accesso alle Google Cloud API e ai servizi per gli agenti che utilizzano un'identità agente.

Questo documento è destinato agli amministratori della sicurezza e agli amministratori della piattaforma che gestiscono l'autorizzazione per gli agenti che gli sviluppatori eseguono il deployment nei cluster GKE. Dovresti già avere familiarità con i seguenti argomenti:

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.
  • 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.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per gestire l'accesso alle Google Cloud API per gli agenti, chiedi all'amministratore di concederti i seguenti ruoli IAM nel Google Cloud progetto:

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.

Trovare l'identificatore dell'entità di un agente

Questa sezione descrive come creare l'identificatore dell'entità per un agente. Puoi utilizzare questo identificatore nelle policy IAM per controllare a quali risorse può accedere l'agente.

Qualsiasi workload dell'agente che richiede un'identità dell'agente riceve una stringa di identità SPIFFE univoca per quel workload. Quando l'applicazione chiama le API Google Cloud , le chiamate vengono autenticate utilizzando un token di accesso con identità dell'agente che convalida che il workload abbia un'identità dell'agente. Questo token di accesso include un identificatore dell'entità IAM per il workload dell'agente, che puoi includere nelle policy IAM per controllare a quali risorse ha accesso l'agente.

Quando progetti le policy IAM, puoi creare gli identificatori principal per gli agenti utilizzando le seguenti informazioni:

  • La gerarchia delle risorse del progetto.
  • Il nome del cluster.
  • Lo spazio dei nomi Kubernetes e il service account Kubernetes in questo spazio dei nomi.

Quando gli sviluppatori eseguono il deployment di agenti che ottengono un'identità agente corrispondente all'identificatore principale, l'agente eredita l'accesso specificato nel criterio.

Per trovare l'identificatore principale da utilizzare nelle tue policy:

  1. Identifica il dominio di attendibilità per l'identità. Il dominio di attendibilità dipende dal fatto che il progetto si trovi in un'organizzazione, come segue:

    • Progetti che si trovano in un'organizzazione:

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

      Sostituisci ORGANIZATION_ID con l'ID organizzazione.

    • Progetti che non fanno parte di un'organizzazione:

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

      Sostituisci PROJECT_NUMBER con il numero di progetto del progetto cluster.

  2. Identifica le seguenti informazioni sul cluster:

    • Il nome del cluster GKE.
    • La posizione del control plane del cluster, ad esempio us-central1.
    • Lo spazio dei nomi Kubernetes in cui gli sviluppatori eseguono il deployment dei carichi di lavoro.
    • Il nome del ServiceAccount Kubernetes che gli sviluppatori devono utilizzare per il carico di lavoro dell'agente.

    Se non conosci queste informazioni, chiedi al team della tua piattaforma. Il team della piattaforma deve configurare gli spazi dei nomi, i ServiceAccount e i criteri RBAC nel cluster in modo che gli agenti con requisiti di accesso diversi ottengano identità diverse.

  3. Crea l'identificatore entità:

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

    Sostituisci quanto segue:

    • TRUST_DOMAIN: il dominio di attendibilità per l'identità dell'agente.
    • PROJECT_NUMBER: il numero del progetto cluster.
    • CONTROL_PLANE_LOCATION: la regione o la zona del control plane del cluster.
    • CLUSTER_NAME: il nome del cluster.
    • KUBERNETES_NAMESPACE: il nome dello spazio dei nomi Kubernetes.
    • KUBERNETES_SERVICEACCOUNT: il nome del service account Kubernetes.

Utilizzare le policy per controllare l'accesso

Questa sezione descrive come utilizzare l'identificatore principale di un agente per controllare a quali Google Cloud API e servizi può accedere. Per controllare l'accesso, includi l'identificatore dell'entità in una delle seguenti policy IAM:

Dopo aver creato o aggiornato una policy, qualsiasi agente che richiede un'identità agente e viene eseguito in quello spazio dei nomi e utilizza quel service account ha l'accesso che specifichi nelle tue policy.

Autorizzare gli agenti ad accedere a Auth Manager

Il gestore di autenticazione di Agent Identity è un broker di autenticazione e un vault delle credenziali che gli agenti potrebbero utilizzare per ottenere le credenziali per accedere a strumenti e servizi esterni, come identità dell'agente o per conto di un utente finale. Il gestore dell'autenticazione può avere uno o più fornitori di autenticazione, ognuno dei quali gestisce un flusso specifico di autenticazione e acquisizione delle credenziali per un servizio specifico. Per concedere agli agenti GKE l'accesso a provider di autenticazione specifici:

  1. Trova l'identificatore dell'entità per l'agente.
  2. Ottieni il nome del provider di autenticazione a cui l'agente deve accedere.

  3. Concedi il ruolo Utente identità agente (roles/agentidentity.user) al principal dell'agente nel provider di autenticazione:

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

    Sostituisci quanto segue:

    • AUTH_PROVIDER_NAME: il nome del provider di autenticazione.
    • AUTH_PROVIDER_LOCATION: la regione del provider di autenticazione.
    • PRINCIPAL_IDENTIFIER: l'identificatore dell'entità dell'agente.

    In alternativa, per gli agenti registrati in Agent Registry, puoi gestire l'accesso ai provider di autenticazione creando un binding del provider di autenticazione.

Passaggi successivi