Isolare l'esecuzione del codice AI con Agent Sandbox

Questo documento fornisce istruzioni per il deployment di un ambiente di sviluppo e l'utilizzo del client Python di Agent Sandbox su un cluster Google Kubernetes Engine (GKE).

Per una panoramica di come la funzionalità Agent Sandbox isola il codice non attendibile generato con l'AI, consulta Informazioni su GKE Agent Sandbox.

Costi

Agent Sandbox è offerto senza costi aggiuntivi in GKE. I prezzi di GKE si applicano alle risorse che crei.

Prima di iniziare

  1. Nella Google Cloud console, nella pagina di selezione del progetto, seleziona o crea un Google Cloud progetto.

    Ruoli richiesti per selezionare o creare un progetto

    • Seleziona un progetto: la selezione di un progetto non richiede un ruolo IAM specifico. Puoi selezionare qualsiasi progetto su cui ti è stato concesso un ruolo.
    • Crea un progetto: per creare un progetto, devi disporre del ruolo Autore progetto (roles/resourcemanager.projectCreator), che contiene l' resourcemanager.projects.create autorizzazione. Scopri come concedere i ruoli.

    Vai al selettore di progetti

  2. Verifica che la fatturazione sia attivata per il tuo Google Cloud progetto.

  3. Abilita le API Artifact Registry e Kubernetes Engine.

    Ruoli richiesti per abilitare le API

    Per abilitare le API, devi disporre del ruolo IAM Service Usage Admin (roles/serviceusage.serviceUsageAdmin), che contiene l'autorizzazione serviceusage.services.enable. Scopri come concedere i ruoli.

    Abilita le API

  4. Nella Google Cloud console, attiva Cloud Shell.

    Attiva Cloud Shell

  5. Verifica di disporre delle autorizzazioni necessarie per completare questa guida.
  6. Devi disporre di un cluster GKE con la funzionalità Agent Sandbox abilitata. Se non ne hai uno, segui le istruzioni riportate in Abilitare Agent Sandbox su GKE per creare un nuovo cluster o aggiornarne uno esistente.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per creare e gestire le sandbox, chiedi all'amministratore di concederti il ruolo IAM Amministratore di Kubernetes Engine (roles/container.admin) nel 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.

Definisci le variabili di ambiente

Per semplificare i comandi che esegui in questo documento, puoi impostare le variabili di ambiente in Cloud Shell. In Cloud Shell, definisci le seguenti variabili di ambiente utili eseguendo i comandi seguenti:

export PROJECT_ID=$(gcloud config get project)
export CLUSTER_NAME="agent-sandbox-cluster"
export LOCATION="us-central1"
export NODE_POOL_NAME="agent-sandbox-node-pool"
export MACHINE_TYPE="e2-standard-2"

Di seguito è riportata una spiegazione di queste variabili di ambiente:

  • PROJECT_ID: l'ID del tuo progetto corrente. Google Cloud La definizione di questa variabile consente di assicurarti che tutte le risorse, come il cluster GKE, vengano create nel progetto corretto.
  • CLUSTER_NAME: il nome del cluster GKE, ad esempio agent-sandbox-cluster.
  • LOCATION: la Google Cloud regione o la zona in cui si trova il cluster GKE. Imposta questo valore sulla regione (ad esempio, us-central1) se utilizzi un cluster Autopilot o sulla zona (ad esempio, us-central1-a) se utilizzi un cluster Standard.
  • NODE_POOL_NAME: il nome del pool di nodi che eseguirà i carichi di lavoro in sandbox, ad esempio agent-sandbox-node-pool.
  • MACHINE_TYPE: il tipo di macchina dei nodi nel pool di nodi, ad esempio e2-standard-2. Per informazioni dettagliate sulle diverse serie di macchine e sulla scelta tra le diverse opzioni, consulta la guida alle risorse e al confronto per le famiglie di macchine.

Esegui il deployment di un ambiente in sandbox

Questa sezione mostra come creare il blueprint della sandbox (SandboxTemplate), eseguire il deployment del router di rete necessario e installare il client Python che utilizzerai per interagire con la sandbox.

Il modo consigliato per creare e interagire con la sandbox è utilizzare il client Python di Agentic Sandbox. Questo client fornisce un'interfaccia che semplifica l'intero ciclo di vita di una sandbox, dalla creazione alla pulizia. È una libreria Python che puoi utilizzare per creare, utilizzare ed eliminare le sandbox in modo programmatico.

Il client utilizza un router sandbox come punto di ingresso centrale per tutto il traffico. Nell'esempio descritto in questo documento, il client crea un tunnel a questo router utilizzando il comando kubectl port-forward, in modo da non dover esporre indirizzi IP pubblici. Tieni presente che l'utilizzo di kubectl port-forward non è una soluzione sicura e il suo utilizzo deve essere limitato agli ambienti di sviluppo.

Crea un SandboxTemplate e un SandboxWarmPool

Ora definisci la configurazione della sandbox creando una risorsa SandboxTemplate e una risorsa SandboxWarmPool. SandboxTemplate funge da blueprint riutilizzabile che il controller Agent Sandbox utilizza per creare ambienti sandbox preconfigurati e coerenti. La risorsa SandboxWarmPool contribuisce a garantire che un numero specificato di pod pre-riscaldati siano sempre in esecuzione e pronti per essere richiesti. Una sandbox pre-riscaldata è un pod in esecuzione già inizializzato. Questa pre-inizializzazione consente di creare nuove sandbox in meno di un secondo ed evita la latenza di avvio del lancio di una sandbox normale:

  1. In Cloud Shell, crea un file denominato sandbox-template-and-pool.yaml con il seguente contenuto:

    apiVersion: extensions.agents.x-k8s.io/v1alpha1
kind: SandboxTemplate
metadata:
  name: python-runtime-template
  namespace: default
spec:
  podTemplate:
    metadata:
      labels:
        sandbox: python-sandbox-example
    spec:
      runtimeClassName: gvisor
      automountServiceAccountToken: false # Required
      securityContext:
        runAsNonRoot: true # Required
      nodeSelector:
        sandbox.gke.io/runtime: gvisor # Required
      tolerations:
      - key: "sandbox.gke.io/runtime"
        value: "gvisor"
        effect: "NoSchedule" # Required
      containers:
      - name: python-runtime
        image: registry.k8s.io/agent-sandbox/python-runtime-sandbox:v0.1.0
        ports:
        - containerPort: 8888
        readinessProbe:
          httpGet:
            path: "/"
            port: 8888
          initialDelaySeconds: 0
          periodSeconds: 1
        resources:
          requests:
            cpu: "250m"
            memory: "512Mi"
          limits:
            cpu: "500m"
            memory: "1Gi" # Required
        securityContext:
          capabilities:
            drop: ["ALL"] # Required
      restartPolicy: "OnFailure"
---
apiVersion: extensions.agents.x-k8s.io/v1alpha1
kind: SandboxWarmPool
metadata:
  name: python-sandbox-warmpool
  namespace: default
spec:
  replicas: 2
  sandboxTemplateRef:
    name: python-runtime-template

  2. Applica il manifest SandboxTemplate e SandboxWarmPool:

    kubectl apply -f sandbox-template-and-pool.yaml

Esegui il deployment del router sandbox

Il client Python che utilizzerai per creare e interagire con gli ambienti in sandbox utilizza un componente chiamato router sandbox per comunicare con le sandbox.

Per questo esempio, utilizzerai la modalità sviluppatore del client per i test. Questa modalità è destinata allo sviluppo locale e utilizza il comando kubectl port-forward per stabilire un tunnel diretto dalla macchina locale al servizio del router sandbox in esecuzione nel cluster. Questo approccio di tunneling evita la necessità di un indirizzo IP pubblico o di una configurazione di Ingress complessa e semplifica l'interazione con le sandbox dall'ambiente locale.

Per eseguire il deployment del router sandbox:

  1. In Cloud Shell, crea un file denominato sandbox-router.yaml con il seguente contenuto:

    # A ClusterIP Service to provide a stable endpoint for the router pods.
apiVersion: v1
kind: Service
metadata:
  name: sandbox-router-svc
  namespace: default
spec:
  type: ClusterIP
  selector:
    app: sandbox-router
  ports:
  - name: http
    protocol: TCP
    port: 8080 # The port the service will listen on
    targetPort: 8080 # The port the router container listens on (from the sandbox_router/Dockerfile)
---
# The Deployment to manage and run the router pods.
apiVersion: apps/v1
kind: Deployment
metadata:
  name: sandbox-router-deployment
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: sandbox-router
  template:
    metadata:
      labels:
        app: sandbox-router
    spec:
      # Ensure pods are spread across different zones for HA
      topologySpreadConstraints:
        - maxSkew: 1
          topologyKey: topology.kubernetes.io/zone
          whenUnsatisfiable: ScheduleAnyway
          labelSelector:
            matchLabels:
              app: sandbox-router
      containers:
      - name: router
        image: us-central1-docker.pkg.dev/k8s-staging-images/agent-sandbox/sandbox-router:latest-main
        ports:
        - containerPort: 8080
        readinessProbe:
          httpGet:
            path: /healthz
            port: 8080
          initialDelaySeconds: 5
          periodSeconds: 5
        livenessProbe:
          httpGet:
            path: /healthz
            port: 8080
          initialDelaySeconds: 10
          periodSeconds: 10
        resources:
          requests:
            cpu: "100m"
            memory: "512Mi"
          limits:
            cpu: "1000m"
            memory: "1Gi"
      securityContext:
        runAsUser: 1000
        runAsGroup: 1000

  2. Applica il manifest per eseguire il deployment del router nel cluster:

    kubectl apply -f sandbox-router.yaml

  3. Verifica che il deployment del router sandbox sia in esecuzione correttamente:

    kubectl get deployment sandbox-router-deployment

    Attendi che il deployment mostri 2/2 o 1/1 nella colonna READY.

Installa il client Python

Ora che i componenti in-cluster come il router sandbox sono stati sottoposti a deployment, l'ultimo passaggio preparatorio consiste nell'installare il client Python di Agentic Sandbox sulla macchina locale. Ricorda che questo client è una libreria Python che ti consente di creare, utilizzare ed eliminare le sandbox in modo programmatico. Lo utilizzerai nella sezione successiva per testare l'ambiente:

  1. Crea e attiva un ambiente virtuale Python:

    python3 -m venv .venv
source .venv/bin/activate

  2. Installa il pacchetto client:

    pip install k8s-agent-sandbox

Testa la sandbox

Ora che tutti i componenti di configurazione sono in posizione, puoi creare e interagire con una sandbox utilizzando il client Python di Agentic Sandbox.

  1. Nella directory agent-sandbox, crea uno script Python denominato test_sandbox.py con il seguente contenuto:

    from k8s_agent_sandbox import SandboxClient
from k8s_agent_sandbox.models import SandboxLocalTunnelConnectionConfig

# Automatically tunnels to svc/sandbox-router-svc
client = SandboxClient(
    connection_config=SandboxLocalTunnelConnectionConfig()
)

sandbox = client.create_sandbox(template="python-runtime-template", namespace="default")
try:
    print(sandbox.commands.run("echo 'Hello from the sandboxed environment!'").stdout)
except Exception as e:
    print(f"An error occurred: {e}")

  2. Dal terminale (con l'ambiente virtuale ancora attivo), esegui lo script di test:

    python3 test_sandbox.py

Dovresti vedere il messaggio "Hello from the sandboxed environment!", che viene generato dalla sandbox.

Complimenti! Hai eseguito correttamente un comando shell all'interno di una sandbox sicura. Utilizzando il metodo sandbox.run(), puoi eseguire qualsiasi comando shell e Agent Sandbox esegue il comando all'interno di una barriera sicura che protegge i nodi del cluster e altri carichi di lavoro da codice non attendibile. In questo modo, un agente AI o qualsiasi flusso di lavoro automatizzato può eseguire le attività in modo sicuro e affidabile.

Quando esegui lo script, SandboxClient gestisce tutti i passaggi. Crea la risorsa SandboxClaim per avviare la sandbox, attende che sia pronta e poi utilizza il metodo sandbox.run() per eseguire i comandi della shell bash all'interno del container sicuro. Il client acquisisce e stampa quindi stdout da questo comando. La sandbox viene eliminata automaticamente dopo l'esecuzione del programma.

Quando viene creata una risorsa SandboxClaim, un pod disponibile viene assegnato dal pool di riscaldamento all'oggetto Sandbox e la richiesta viene contrassegnata come pronta. SandboxWarmPool si riempie automaticamente per mantenere il numero configurato di repliche.

Per verificare se una sandbox specifica è stata richiesta o è disponibile, controlla ownerReferences nei metadati del pod sandbox. Se il valore del campo kind è Sandbox, il pod è in uso. Se il valore del campo kind è SandboxWarmPool, il pod è inattivo e in attesa di essere richiesto.

Esegui le sandbox in produzione

In questo documento, interagisci con le sandbox dall'esterno del cluster utilizzando Cloud Shell. Il client Python utilizza le tue credenziali utente per l'autenticazione al server API del cluster e per gestire le risorse sandbox e utilizza il comando kubectl port-forward per stabilire una connessione con le sandbox. Questi passaggi sono adatti agli scenari di sviluppo.

In uno scenario di produzione, un'applicazione controller (come un orchestratore AI) è responsabile della creazione e della gestione delle risorse sandbox. Per utilizzare Agent Sandbox in produzione, tieni presente quanto segue:

  • Autenticazione: l'applicazione controller deve eseguire l'autenticazione al server API del cluster per eseguire le sandbox. La configurazione dell'autenticazione dipende dalla posizione in cui viene eseguita l'applicazione controller, come indicato di seguito:

    • Se l'applicazione controller viene eseguita come pod nello stesso cluster, utilizza RBAC Kubernetes o Workload Identity Federation for GKE con le policy IAM per concedere all'account di servizio Kubernetes del pod le autorizzazioni necessarie per monitorare le sandbox o scoprire gli endpoint di rete.
    • Se l'applicazione controller viene eseguita all'esterno del cluster, utilizza la federazione delle identità per i workload, o gli account di servizio IAM per assegnare all'applicazione un'identità a cui puoi fare riferimento nelle policy di autorizzazione.

  • Routing: le richieste del client Python nell'applicazione controller devono raggiungere il router sandbox nel cluster. In produzione, utilizza uno dei seguenti metodi per stabilire una connessione di rete:

    • Se l'applicazione controller viene eseguita nello stesso cluster, utilizza la funzione SandboxDirectConnectionConfig per indirizzare l'URL e la porta utilizzati dal servizio del router sandbox.
    • Se l'applicazione controller viene eseguita all'esterno del cluster, utilizza l' API GKE Gateway per creare un bilanciatore del carico interno o esterno. Nel codice client, utilizza la funzione SandboxGatewayConnectionConfig per fare riferimento al gateway.

    Per ulteriori informazioni su questi metodi di routing, consulta gli esempi di utilizzo su GitHub e i passaggi di deployment del gateway per il router.

  • Accesso sandbox alle Google Cloud risorse: se il codice sandbox deve inviare richieste alle Google Cloud API, ad esempio Cloud Storage, utilizza una policy IAM con Workload Identity Federation for GKE per concedere all'account di servizio Kubernetes utilizzato dal pod sandbox le autorizzazioni necessarie per questo accesso.

Libera spazio

Per evitare addebiti sul tuo Google Cloud account, devi eliminare il cluster GKE che hai creato:

gcloud container clusters delete $CLUSTER_NAME --location=$LOCATION --quiet

Passaggi successivi