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 inoltre 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"

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.

Esegui il deployment della sandbox dell'agente

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

Crea un cluster GKE

Poi, crea un cluster GKE con gVisor abilitato. Questo cluster fornisce l'ambiente Kubernetes in cui eseguire 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 a 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 di 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 base 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 router sandbox 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 i 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: 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 utilizzi 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

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 vedere il messaggio "Hello from the sandboxed environment!" (Ciao dall'ambiente sandbox!), che è l'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 flusso di lavoro 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 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.

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

Per verificare se una sandbox specifica è rivendicata o disponibile, controlla il 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 rivendicato.

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