Isolare l'esecuzione del codice AI con Agent Sandbox

Questo documento fornisce istruzioni per l'installazione e l'esecuzione del controller Agent Sandbox su un cluster Google Kubernetes Engine (GKE). Spiega anche come eseguire il deployment di un ambiente sandbox sul cluster in cui puoi testare comandi shell non attendibili.

Il controller Agent Sandbox fornisce un framework per la creazione e la gestione di ambienti di runtime effimeri. Questo approccio ti consente di definire un modello per l'ambiente della tua app e poi creare istanze su richiesta.

Agent Sandbox fornisce un ambiente sicuro e isolato per l'esecuzione di codice non attendibile, ad esempio codice generato da modelli linguistici di grandi dimensioni (LLM). L'esecuzione di questo tipo di codice direttamente in un cluster comporta rischi per la sicurezza, perché il codice non attendibile potrebbe potenzialmente accedere o interferire con altre app o con il nodo del cluster sottostante stesso.

Agent Sandbox mitiga questi rischi fornendo un forte isolamento di processi, archiviazione e rete per il codice che esegue. Questo isolamento viene ottenuto utilizzando gVisor, una tecnologia che crea una barriera sicura tra l'applicazione e il sistema operativo del nodo del cluster. Possono essere utilizzate altre tecnologie di sandboxing, ad esempio Kata Containers; tuttavia, l'esempio in questo documento utilizza solo gVisor.

Questo documento fornisce istruzioni per l'esecuzione di Agent Sandbox su un cluster GKE Autopilot o Standard.

Agent Sandbox è un progetto open source. Per saperne di più su come contribuire al progetto o trovare dettagli tecnici più approfonditi, consulta il progetto open source Agent Sandbox.

Costi

Se segui i passaggi descritti in questo documento, al tuo account Google Cloud verranno addebitati costi. I costi iniziano quando crei un cluster GKE. Questi costi includono gli addebiti per cluster per GKE, come descritto nella pagina dei prezzi, e gli addebiti per l'esecuzione di VM Compute Engine.

Per evitare addebiti non necessari, assicurati di disabilitare GKE o eliminare il progetto dopo aver completato questo documento.

Prima di iniziare

  1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  2. Verify that billing is enabled for your Google Cloud project.

  3. Enable the Artifact Registry, Google Kubernetes Engine APIs.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the APIs

  4. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    Definisci le variabili di ambiente

    Per semplificare i comandi eseguiti 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 PROJECT_ID=$(gcloud config get project)
export CLUSTER_NAME="agent-sandbox-cluster"
export GKE_LOCATION="us-central1"
export AGENT_SANDBOX_VERSION="v0.1.0"
export NODE_POOL_NAME="agent-sandbox-node-pool"
export MACHINE_TYPE="e2-standard-2"
export PYTHON_CLIENT_VERSION="main"

    Ecco una spiegazione di queste variabili di ambiente:

    • PROJECT_ID: l'ID del tuo progetto Google Cloud corrente. La definizione di questa variabile consente di garantire 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.
    • GKE_LOCATION: la regione Google Cloud in cui verranno creati il cluster GKE e il repository Artifact Registry, ad esempio us-central1. Ti consigliamo di collocarli insieme perché ciò riduce la latenza di pull delle immagini.
    • AGENT_SANDBOX_VERSION: la versione del controller Agent Sandbox da distribuire al cluster.
    • 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.
    • PYTHON_CLIENT_VERSION: la versione del client Python di Agentic Sandbox da installare.

    Esegui il deployment della sandbox dell'agente

    Ora che hai configurato il progetto Google Cloud e l'ambiente Cloud Shell, puoi eseguire il provisioning dell'infrastruttura necessaria ed eseguire il deployment di Agent Sandbox.

    Crea un cluster GKE

    Successivamente, crea un cluster GKE con gVisor abilitato. Questo cluster fornisce l'ambiente Kubernetes in cui verrà eseguito il deployment e l'esecuzione del controller Agent Sandbox e dell'app sandbox di esempio. gVisor fornisce la tecnologia di limitazione tramite sandbox per eseguire in modo sicuro codice non attendibile.

    Puoi creare un cluster Autopilot o Standard. Autopilot abilita automaticamente gVisor, mentre i cluster Standard richiedono la creazione manuale di un pool di nodi abilitato per gVisor:

    Autopilot

    Per creare un cluster Autopilot utilizzando gcloud CLI, esegui questo comando:

    gcloud container clusters create-auto ${CLUSTER_NAME} \
    --location=${GKE_LOCATION} \
    --project=${PROJECT_ID}

    Standard

    Per creare un cluster Standard utilizzando gcloud CLI, segui questi passaggi:

    1. Crea il cluster:

      gcloud container clusters create ${CLUSTER_NAME} \
    --location=${GKE_LOCATION}

    2. Crea un pool di nodi separato con gVisor abilitato:

      gcloud container node-pools create ${NODE_POOL_NAME} \
  --cluster=${CLUSTER_NAME} \
  --location=${GKE_LOCATION} \
  --machine-type=${MACHINE_TYPE} \
  --image-type=cos_containerd \
  --sandbox type=gvisor

    Recupera le credenziali del cluster in modo che la CLI kubectl possa connettersi al cluster. Questo comando aggiorna il file di configurazione Kubernetes, archiviato per impostazione predefinita nella directory ~/.kube/config. Questo file di configurazione contiene le credenziali richieste da kubectl per interagire con il tuo cluster GKE:

    gcloud container clusters get-credentials ${CLUSTER_NAME} \
    --location=${GKE_LOCATION}

    Esegui il deployment del controller Agent Sandbox nel cluster

    Puoi eseguire il deployment del controller Agent Sandbox e dei relativi componenti richiesti applicando i manifest di rilascio ufficiali al cluster. Questi manifest sono file di configurazione che indicano a Kubernetes di scaricare tutti i componenti necessari per eseguire il deployment e l'esecuzione del controller sandbox dell'agente sul cluster.

    Esegui questi comandi per eseguire il deployment del controller Agent Sandbox nel tuo cluster GKE:

    kubectl apply \
-f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/${AGENT_SANDBOX_VERSION}/manifest.yaml \
-f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/${AGENT_SANDBOX_VERSION}/extensions.yaml

    Verifica il controller della sandbox dell'agente

    Dopo aver applicato i manifest, verifica che il pod del controller Agent Sandbox venga eseguito correttamente nello spazio dei nomi agent-sandbox-system:

    kubectl get pods -n agent-sandbox-system

    Attendi che il pod mostri "Running" (In esecuzione) nella colonna STATUS e "1/1" nella colonna READY. Quando il pod è in esecuzione correttamente, l'output è simile a questo:

    NAME                         READY   STATUS    RESTARTS   AGE
agent-sandbox-controller-0   1/1     Running   0          44d

    Ora che il controller Agent Sandbox è in esecuzione, può creare e gestire automaticamente ambienti sandbox per qualsiasi risorsa Sandbox creata nel cluster.

    Esegui il deployment di un ambiente sandbox

    Ora che il controller Agent Sandbox è in esecuzione nel cluster GKE, devi eseguire il deployment dei componenti per l'ambiente sandbox di esempio. 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 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 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 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 del sandbox creando una risorsa SandboxTemplate e una risorsa SandboxWarmPool. SandboxTemplate funge da progetto riutilizzabile che il controller di Agent Sandbox utilizza per creare ambienti sandbox coerenti e preconfigurati. La risorsa SandboxWarmPool garantisce che un numero specificato di pod pre-riscaldati siano sempre in esecuzione e pronti per essere rivendicati. 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 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
      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"
            ephemeral-storage: "512Mi"
      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 sandbox utilizza un componente chiamato Sandbox Router per comunicare con le sandbox.

    Per questo esempio, utilizzi la modalità sviluppatore del client per i test. Questa modalità è pensata per lo sviluppo locale e utilizza il comando kubectl port-forward per stabilire un tunnel diretto dalla tua macchina locale al servizio Sandbox Router in esecuzione nel cluster. Questo approccio di tunneling evita la necessità di un indirizzo IP pubblico o di una configurazione di ingresso complessa e semplifica l'interazione con le sandbox dal tuo 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: 2 # Run at least two replicas for high availability
  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:v20251124-v0.1.0-10-ge26ddb2
        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: "250m"
            memory: "512Mi"
          limits:
            cpu: "1000m"
            memory: "1Gi"
      securityContext:
        runAsUser: 1000
        runAsGroup: 1000

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

      kubectl apply -f sandbox-router.yaml

    Installa il client Python

    Ora che i componenti in-cluster come il router sandbox sono stati implementati, l'ultimo passaggio preparatorio consiste nell'installare il client Python sandbox agentico sulla tua macchina locale. Ricorda che questo client è una libreria Python che ti consente di creare, utilizzare ed eliminare 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 dal repository agent-sandbox:

      pip install "git+https://github.com/kubernetes-sigs/agent-sandbox.git@${PYTHON_CLIENT_VERSION}#subdirectory=clients/python/agentic-sandbox-client"

    Testare la sandbox

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

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

      from agentic_sandbox import SandboxClient

# Automatically tunnels to svc/sandbox-router-svc
with SandboxClient(
    template_name="python-runtime-template",
    namespace="default"
) as sandbox:
    print(sandbox.run("echo 'Hello from the sandboxed environment!'").stdout
)

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

      python3 test_sandbox.py

    Dovresti visualizzare il messaggio "Hello from the sandboxed environment!" (Ciao dall'ambiente sandbox), output della 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 la sandbox dell'agente 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 workflow 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 il stdout da questo comando. La sandbox viene eliminata automaticamente dopo l'esecuzione del programma.

    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=$GKE_LOCATION --quiet

    Passaggi successivi

    • Scopri di più sul progetto open source Agent Sandbox su GitHub.
    • Per comprendere la tecnologia sottostante che fornisce l'isolamento della sicurezza per i tuoi carichi di lavoro, consulta GKE Sandbox.
    • Per saperne di più su come migliorare la sicurezza dei cluster e dei workload, consulta la Panoramica della sicurezza di GKE.