Isola l'esecuzione di codice AI con Agent Sandbox su GKE

Questo documento mostra come eseguire il codice generato dall'AI in una sandbox isolata su un cluster Google Kubernetes Engine (GKE). Puoi creare un template della sandbox e un pool di sandbox pronte nel cluster. Poi, esegui uno script Python che richiede una sandbox dal pool ed esegue un comando nella sandbox. Lo script utilizza il client Python di Agent Sandbox, una libreria per la creazione e la gestione delle sandbox.

L'esecuzione di codice non attendibile in una sandbox aiuta a proteggere il sistema da potenziali vulnerabilità nel codice generato dall'AI, ad aumentare la velocità di sviluppo e a migliorare la sicurezza dei deployment. Per una panoramica di come Agent Sandbox su GKE isola il codice non attendibile generato dall'AI, consulta Informazioni su Agent Sandbox su GKE.

Costi

Agent Sandbox su GKE è un software open source che puoi utilizzare senza costi aggiuntivi. I prezzi di GKE si applicano alle risorse che crei, incluse le risorse di computing utilizzate dal controller di Agent Sandbox.

Prima di iniziare

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

    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 per 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'autorizzazione resourcemanager.projects.create. Scopri come concedere i ruoli.

    Vai al selettore di progetti

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

  3. Abilita l'API Kubernetes Engine, 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 hai già questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore Service Usage (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.

    Abilitare l'API

  4. Nella console Google Cloud , attiva Cloud Shell.

    Attiva Cloud Shell

  5. Verifica di disporre delle autorizzazioni necessarie per completare questo documento.
  6. Assicurati di avere un cluster GKE in cui sia installato il controller Agent Sandbox e sia stato eseguito il deployment del router sandbox. In caso contrario, completa solo le seguenti sezioni di Installa Agent Sandbox su GKE, quindi torna a questo documento:
    1. Definisci le variabili di ambiente
    2. Crea un cluster GKE
    3. Installa Agent Sandbox
    4. Esegui il deployment del router della sandbox
    Non è necessario completare le altre sezioni del documento, ad esempio Esegui il deployment di un ambiente in modalità sandbox. Più avanti in questo documento, creerai le tue risorse SandboxTemplate e SandboxWarmPool.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per creare e gestire le sandbox, chiedi all'amministratore di concederti il ruolo IAM Kubernetes Engine Admin (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 questi comandi:

export CLUSTER_NAME="agent-sandbox-cluster"
export LOCATION="us-central1"

Ecco una spiegazione di queste variabili di ambiente:

  • CLUSTER_NAME: il nome del tuo cluster GKE, ad esempio agent-sandbox-cluster.
  • LOCATION: la regione o la zona Google Cloud in cui si trova il tuo cluster GKE. Se utilizzi un cluster Autopilot, imposta questo valore sulla regione (ad esempio, us-central1). Se utilizzi un cluster Standard, imposta questo valore sulla zona (ad esempio, us-central1-a).

Esegui il deployment di un ambiente sandbox

Questa sezione mostra come creare il progetto della sandbox (una risorsa SandboxTemplate), verificare il router di networking 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 Agentic Sandbox. Questo client fornisce un'interfaccia che semplifica l'intero ciclo di vita di una sandbox, dalla creazione alla pulizia. Si tratta di 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 accesso centrale per tutto il traffico. Nell'esempio descritto in questo documento, il client crea un tunnel verso 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 risorse SandboxTemplate e SandboxWarmPool

Ora definisci la configurazione della sandbox creando una risorsa SandboxTemplate e una risorsa SandboxWarmPool. La risorsa SandboxTemplate funge da blueprint riutilizzabile che il controller Agent Sandbox utilizza per creare ambienti sandbox coerenti e preconfigurati. La risorsa SandboxWarmPool aiuta a garantire che un numero specificato di pod pre-warm sia sempre in esecuzione e pronto per essere richiesto. Una sandbox preinizializzata è un pod in esecuzione che è già stato inizializzato. Questa pre-inizializzazione consente di creare nuove sandbox in meno di un secondo ed evita la latenza di avvio di una sandbox normale:

  1. In Cloud Shell, crea un file denominato sandbox-template-and-pool.yaml con i seguenti contenuti:

    apiVersion: extensions.agents.x-k8s.io/v1beta1
kind: SandboxTemplate
metadata:
  name: python-sandbox-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/v1beta1
kind: SandboxWarmPool
metadata:
  name: python-sandbox-warmpool
  namespace: default
spec:
  replicas: 2
  sandboxTemplateRef:
    name: python-sandbox-template

  2. Applica il manifest SandboxTemplate e SandboxWarmPool:

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

  3. Attendi che le sandbox del pool caldo siano pronte:

    kubectl wait sandboxwarmpool python-sandbox-warmpool \
    --for=jsonpath='{.status.readyReplicas}'=2 \
    --timeout=600s

    Più avanti in questo documento, il client Python crea una risorsa SandboxClaim. Se il client crea la richiesta prima che le sandbox del pool siano pronte, il controller potrebbe creare una nuova sandbox per la richiesta anziché assegnarne una dal pool. In un cluster Autopilot, le sandbox possono richiedere diversi minuti per essere pronte, perché GKE potrebbe dover creare nodi per loro.

Verifica il router sandbox

Il client Python che utilizzerai per creare e interagire con gli ambienti in sandbox utilizza un componente chiamato router della 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 tua macchina locale al servizio router della sandbox in esecuzione nel cluster. Questo approccio di tunneling evita la necessità di un indirizzo IP pubblico o di una configurazione complessa del traffico in entrata e semplifica l'interazione con le sandbox dal tuo ambiente locale.

Verifica che il router della sandbox sia in esecuzione nello spazio dei nomi agent-sandbox-system:

kubectl get deployment sandbox-router --namespace=agent-sandbox-system

Quando il router è in esecuzione, la colonna READY mostra che tutte le repliche sono pronte, ad esempio 2/2. Se il comando restituisce un errore NotFound, esegui il deployment del router seguendo i passaggi descritti in Esegui il deployment del router della sandbox.

Installa il client Python

Ora che i componenti in-cluster come il router della sandbox sono stati sottoposti a deployment, il passaggio preparatorio finale consiste nell'installare il client Python di Agentic Sandbox sulla tua 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. Utilizza la stessa versione del controller Agent Sandbox:

    pip install k8s-agent-sandbox==1.0.6

Testa la sandbox

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

  1. Crea uno script Python denominato test_sandbox.py con i seguenti contenuti:

    from k8s_agent_sandbox import SandboxClient
from k8s_agent_sandbox.models import SandboxLocalTunnelConnectionConfig

# Tunnels to svc/sandbox-router-svc in the agent-sandbox-system namespace.
# cleanup=True deletes the sandbox when the script exits.
client = SandboxClient(
    connection_config=SandboxLocalTunnelConnectionConfig(),
    cleanup=True,
)

sandbox = client.create_sandbox(warmpool="python-sandbox-warmpool", 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!" (Ciao dall'ambiente in sandbox!), che è l'output della sandbox.

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

Quando esegui lo script, SandboxClient gestisce tutti i passaggi per te. Crea la risorsa SandboxClaim per avviare la sandbox, attende che la sandbox sia pronta e poi utilizza il metodo sandbox.commands.run() per eseguire i comandi della shell bash all'interno del container sicuro. Il client acquisisce e stampa il stdout da quel comando. Poiché lo script imposta il parametro cleanup su True, il client elimina la sandbox quando il programma viene chiuso.

Quando viene creata una risorsa SandboxClaim, una sandbox disponibile del pool caldo viene assegnata alla richiesta e quest'ultima viene contrassegnata come pronta. La risorsa SandboxWarmPool si reintegra automaticamente per mantenere il numero di repliche configurato.

Per verificare se una sandbox specifica è rivendicata o disponibile, controlla ownerReferences nei metadati della risorsa Sandbox. Se il valore del campo kind è SandboxClaim, la sandbox è in uso. Se il valore del campo kind è SandboxWarmPool, la sandbox è inattiva e in attesa di essere rivendicata.

Esegui le sandbox in produzione

In questo documento, interagirai con le sandbox dall'esterno del cluster utilizzando Cloud Shell. Il client Python utilizza le tue credenziali utente per autenticarsi nel cluster e gestire le risorse della sandbox, nonché il comando kubectl port-forward per stabilire una connessione con le sandbox. Questi passaggi sono ideali per gli scenari di sviluppo.

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

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

    • Se l'applicazione controller viene eseguita come pod nello stesso cluster, utilizza RBAC di Kubernetes o Workload Identity Federation for GKE con policy IAM per concedere al ServiceAccount Kubernetes del pod le autorizzazioni necessarie per monitorare le sandbox o rilevare gli endpoint di rete.
    • Se l'applicazione controller viene eseguita all'esterno del cluster, utilizza la federazione delle identità per i workload o i service account 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 della 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 scegliere come target l'URL e la porta utilizzati dal servizio router della sandbox.
    • Se l'applicazione controller viene eseguita all'esterno del cluster, utilizza l'API gateway GKE per creare un bilanciatore del carico interno o esterno. Nel codice client, utilizza la funzione SandboxGatewayConnectionConfig per fare riferimento al gateway.

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

  • Accesso della sandbox alle risorse Google Cloud : se il codice della sandbox deve inviare richieste alle API Google Cloud , ad esempio Cloud Storage, utilizza una policy IAM con Workload Identity Federation for GKE per concedere al ServiceAccount Kubernetes utilizzato dal pod della sandbox le autorizzazioni necessarie per l'accesso. Poiché la policy di rete predefinita blocca l'accesso al server di metadati Google Cloud (169.254.169.254), devi personalizzare la policy di rete per consentire questo traffico.

  • Limitazioni delle policy di rete: per impostazione predefinita, Agent Sandbox su GKE applica una postura di rete sicura di default (networkPolicyManagement: Managed). In questa postura si applicano le seguenti limitazioni:

    • Il traffico ingress è bloccato da tutte le origini, ad eccezione del router sandbox designato (pod con l'etichetta app: sandbox-router nello spazio dei nomi agent-sandbox-system).
    • Il traffico in uscita è consentito verso l'internet pubblico, ma il traffico in uscita verso intervalli LAN privati (RFC 1918), DNS del cluster interno (CoreDNS) e il server dei metadati del provider cloud (169.254.0.0/16) è esplicitamente bloccato.

    Per utilizzare Workload Identity Federation for GKE o accedere ad altre risorse private, devi definire policy di rete personalizzate nella risorsa SandboxTemplate. Per informazioni dettagliate sulla configurazione e sui modelli personalizzabili (come sandbox air-gapped o l'integrazione di Workload Identity Federation for GKE), consulta Gestione delle policy di rete di Agent Sandbox.

Policy di sicurezza della sandbox

Per impostazione predefinita, Agent Sandbox su GKE non applica policy di sicurezza alle sandbox. Per applicare le impostazioni di isolamento per le sandbox, applica la policy di ammissione di convalida (VAP) di Kubernetes secure-sandbox-policy consigliata dal repository GitHub di Agent Sandbox. Per istruzioni, consulta Applica la policy di sicurezza consigliata.

La policy applica i requisiti di isolamento, ad esempio richiedendo gVisor, disattivando hostNetwork e bloccando i volumi hostPath. La policy applica anche i requisiti di protezione, come l'eliminazione di tutte le funzionalità, la prevenzione dell'aggiunta di nuove funzionalità e la richiesta di eseguire i container come non root e di impostare i limiti delle risorse. Per l'elenco completo dei requisiti, consulta Requisiti di deployment di Agent Sandbox su GKE.

Modifica o rimuovi i vincoli delle policy

Poiché sei tu ad applicare la policy, puoi modificarla in base ai tuoi workload. Se i tuoi workload richiedono esenzioni da alcune regole, puoi modificare la policy per rimuovere vincoli specifici o eliminare completamente l'associazione della policy. La rimozione di un vincolo riduce l'isolamento fornito dalla policy, quindi rimuovi solo i vincoli richiesti dai tuoi workload.

Per modificare la policy e rimuovere un vincolo specifico (ad esempio, per consentire ai container di essere eseguiti come root o omettere i limiti delle risorse), modifica la risorsa ValidatingAdmissionPolicy:

kubectl edit validatingadmissionpolicy secure-sandbox-policy

Nell'editor di testo che si apre, individua la sezione validations e rimuovi o modifica l'espressione del vincolo che blocca il workload.

In alternativa, se vuoi interrompere l'applicazione della policy nel cluster, elimina l'associazione della policy:

kubectl delete validatingadmissionpolicybinding secure-sandbox-binding

Problemi noti

Questa sezione descrive i problemi noti relativi all'utilizzo di Agent Sandbox su GKE e come risolverli o aggirarli.

La policy di sicurezza blocca le funzionalità quando si utilizza un mesh di servizi

Se hai applicato la policy di sicurezza consigliata e provi a eseguire il deployment di una sandbox che si integra con un sidecar del mesh di servizi (ad esempio Envoy o Istio), la creazione della sandbox potrebbe essere bloccata dalla policy con un errore simile al seguente:

sandbox create error: sandboxes.agents.x-k8s.io "claude-cli-claim-managed" is forbidden:
ValidatingAdmissionPolicy 'secure-sandbox-policy' with binding 'secure-sandbox-binding'
denied request: Security Violation: Capabilities.add must be empty. You cannot add capabilities.
  • Causa: i sidecar del mesh di servizi spesso utilizzano un container init, come istio-init o proxy-init. Questi container init richiedono funzionalità come NET_ADMIN o NET_RAW per configurare le regole iptables per il routing del traffico in uscita trasparente. La risorsa ValidatingAdmissionPolicy secure-sandbox-policy blocca tutte le aggiunte di funzionalità in tutti i tipi di container.
  • Soluzione: poiché gestisci questa policy nel tuo cluster, puoi modificare ValidatingAdmissionPolicy per consentire a container init attendibili specifici di richiedere le funzionalità NET_ADMIN e NET_RAW. Per istruzioni su come modificare o rimuovere i vincoli delle policy, consulta Modifica o rimuovi i vincoli delle policy. Ad esempio, puoi aggiornare le espressioni o le variabili di convalida della policy per esentare i nomi dei container attendibili dalla regola delle funzionalità.

Latenza o timeout in uscita durante la connessione alle API di Google tramite IPv6

I workload all'interno della sandbox potrebbero riscontrare timeout di connessione o latenza elevata, fino a due minuti, quando tentano di connettersi a risorse esterne o API di Google (come Vertex AI o Cloud Storage).

  • Causa: se nel cluster GKE è abilitato IPv6 a doppio stack, la risoluzione DNS per le API di Google restituisce sia indirizzi IPv4 (A) che IPv6 (AAAA). Alcuni algoritmi nei motori di runtime, come Node.js, tentano di connettersi prima tramite IPv6. Se il VPC GKE non ha una route in uscita IPv6 valida, ad esempio un Cloud NAT o un gateway internet per IPv6, la connessione TCP smette di rispondere fino alla scadenza del timeout TCP SYN. In questo caso, la connessione TCP torna a IPv4.

  • Soluzione: per risolvere questo problema, esegui una delle seguenti operazioni:

    • Configura il traffico in uscita IPv6: per consentire al traffico IPv6 in uscita di tornare al cluster, configura un gateway Cloud NAT o internet IPv6 valido nella tua rete VPC.

    • Preferisci IPv4 nel workload: per preferire la risoluzione DNS IPv4, configura il runtime del workload. Ad esempio, in un'applicazione Node.js, puoi impostare le seguenti variabili di ambiente nella definizione di SandboxTemplate:

      env:
- name: NODE_OPTIONS
  value: "--dns-result-order=ipv4first --no-network-family-autoselection"

Esegui la pulizia delle risorse

Per evitare che al tuo account Google Cloud vengano addebitati costi, devi eliminare il cluster GKE che hai creato:

gcloud container clusters delete ${CLUSTER_NAME} \
    --location=${LOCATION} \
    --quiet

Passaggi successivi