Esecuzione del codice in Cloud Run

Anteprima : sandbox di Cloud Run

Questa funzionalità è soggetta ai "Termini dell'offerta pre-GA" nella sezione dei Termini di servizio generali dei Termini specifici dei servizi. Le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni della fase di lancio.

Cloud Run è già in sandbox e isolato, il che lo rende ideale per l'hosting di agenti AI. Quando abiliti le sandbox di Cloud Run, lo strumento a riga di comando sandbox diventa disponibile nel container. Utilizza questo strumento a riga di comando per eseguire codice non attendibile scritto in qualsiasi linguaggio, in un ambiente sandbox altamente ottimizzato, isolato dal resto del container.

Gli agenti AI possono sfruttare le sandbox per eseguire in sicurezza i sotto-agenti, eseguire attività di calcolo o aprire browser in un ambiente veloce e isolato senza rischiare il sistema host.

Le sandbox di Cloud Run offrono i seguenti vantaggi principali:

• Creazione rapida: le sandbox sono interattive e pronte a eseguire i comandi quasi immediatamente. Creando sandbox all'interno di una risorsa Cloud Run esistente in cui viene eseguito l'agente, riduci i tempi di creazione rispetto alla creazione di una nuova risorsa Cloud Run per ogni attività. Questa efficienza contribuisce a garantire che l'agente rimanga reattivo.

• Sicurezza: le sandbox isolano l'esecuzione dei processi. Per impostazione predefinita, le sandbox non hanno accesso al carico di lavoro principale, alle variabili di ambiente, ai secret o al Google Cloud server di metadati. Tutte le sandbox sono completamente isolate l'una dall'altra.

• Controllo dell'accesso e ambiente: i processi vengono eseguiti con privilegi sudo come utente non root, il che ti consente di installare gli strumenti utilizzando i gestori di pacchetti come apt, pip o npm durante l'esecuzione. Sebbene l'ambiente sandbox sia temporaneo e venga eliminato al termine, puoi utilizzare directory permanenti o snapshot per salvare spazi di lavoro specifici o mappare i dati a un bucket Cloud Storage.

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.
   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

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

3. Installa e inizializza gcloud CLI.
4. Esegui il deployment di una risorsa Cloud Run, ad esempio un servizio , un job, un pool di worker o un'istanza di seconda generazione.

Abilita le sandbox

Per utilizzare le sandbox, devi prima abilitarle nella risorsa Cloud Run utilizzando il flag --sandbox-launcher o l'attributo YAML sandboxLauncher. Per i passaggi di configurazione dettagliati, scegli tra i seguenti tipi di risorse:

• Servizi
• Job
• Pool di worker
• Istanze (anteprima)

Avvia le sandbox

Dopo aver abilitato le sandbox, puoi avviarle dall'ambiente di esecuzione del container. Il file binario della sandbox si trova in /usr/local/gcp/bin/sandbox.

Gli esempi riportati in questa guida utilizzano il comando sandbox anziché il percorso assoluto /usr/local/gcp/bin/sandbox.

Puoi eseguire il file binario facendo riferimento al suo percorso assoluto nel codice sorgente. Ad esempio, per stampare Hello all'interno della sandbox isolata, scegli una delle seguenti opzioni:

Node.js

Per eseguire il comando sandbox da un'applicazione Node.js, includi il seguente codice:

exec(`sandbox do -- /bin/echo "Hello"`, (e, stdout, stderr) => {
    res.send({ stdout, stderr });
});

Python

Per eseguire il comando sandbox da un'applicazione Python, includi il seguente codice:

import subprocess
result = subprocess.run(
    ["sandbox", "do", "--", "/bin/echo", "Hello"],
    capture_output=True,
    text=True,
)
return {"stdout": result.stdout, "stderr": result.stderr}

Vai

Per eseguire il comando sandbox da un'applicazione Go, includi il seguente codice:

cmd := exec.Command("sandbox", "do", "--", "/bin/echo", "Hello")
out, err := cmd.CombinedOutput()

Interfaccia a riga di comando della sandbox

Per eseguire il comando sandbox direttamente dalla riga di comando, esegui il seguente comando:

sandbox do -- /bin/echo "Hello"

Per visualizzare l'elenco completo dei comandi disponibili, esegui il sandbox -h comando.

Utilizza le funzionalità della riga di comando della sandbox

Lo strumento a riga di comando sandbox contiene comandi per eseguire, configurare e gestire le sandbox.

Esegui un comando nella sandbox

Puoi eseguire un'istruzione in una nuova sandbox temporanea utilizzando il comando sandbox do. Il comando sandbox do esegue le seguenti attività:

1. Avvia un ambiente sandbox (sandbox run).
2. Esegue il comando specificato (sandbox exec).
3. Elimina la sandbox dopo l'esecuzione riuscita (sandbox delete).

Ad esempio, per eseguire un calcolo matematico all'interno della sandbox, esegui i seguenti snippet di codice per la lingua che preferisci. Assicurati che tutti i comandi o gli strumenti che esegui, ad esempio python3, siano installati nell'immagine container:

Node.js

Per eseguire il comando sandbox da un'applicazione Node.js:

exec(`sandbox do -- /usr/bin/python3 -c "print(1+2)"`, (e, stdout, stderr) => {
    res.send({ stdout, stderr });
});

Python

Per eseguire il comando sandbox da un'applicazione Python:

import subprocess
result = subprocess.run(
    ["sandbox", "do", "--", "/usr/bin/python3", "-c", "print(1+2)"],
    capture_output=True,
    text=True,
)
return {"stdout": result.stdout, "stderr": result.stderr}

Vai

Per eseguire il comando sandbox da un'applicazione Go:

cmd := exec.Command("sandbox", "do", "--", "/usr/bin/python3", "-c", "print(1+2)")
out, err := cmd.CombinedOutput()

Interfaccia a riga di comando della sandbox

Per eseguire il comando sandbox direttamente dalla riga di comando:

sandbox do -- /usr/bin/python3 -c "print(1+2)"

Se esegui un comando per nome senza il relativo percorso assoluto, ad esempio python3 anziché /usr/bin/python3, configura in modo esplicito la variabile di ambiente PATH nella sandbox utilizzando il flag --env.

Persisti i dati tra le diverse esecuzioni

Per impostazione predefinita, le sandbox sono temporanee. Per rendere persistenti i dati tra le diverse esecuzioni della sandbox all'interno della stessa istanza Cloud Run, puoi importare ed esportare lo stato del file system dello spazio di lavoro utilizzando i file di archivio tar standard. In alternativa, puoi configurare i montaggi di binding per condividere le directory direttamente tra il container host e gli ambienti sandbox.

Utilizza i seguenti flag quando esegui il comando sandbox do:

• --export-tar: acquisisce i file di overlay modificati in un file di archivio tar al termine.
• --import-tar: estrae i file da un file di archivio tar nella sandbox prima dell'esecuzione.
• --sync-tar: esegue una sincronizzazione bidirezionale importando prima dell'esecuzione ed esportando al termine.

Ad esempio, per passare i dati tra due chiamate sandbox utilizzando i file di archivio, esegui i seguenti comandi:

1. Scrivi i dati all'interno di una sandbox ed esporta lo stato in un file di archivio:

   sandbox do --write --export-tar=/tmp/work.tar \
     -- /usr/bin/bash -c "mkdir -p /tmp/work && echo 'task-complete' > /tmp/work/status.txt"
   

2. Importa il file di archivio in una chiamata successiva per recuperare i dati:

   sandbox do --write --import-tar=/tmp/work.tar \
     -- /usr/bin/bash -c "cat /tmp/work/status.txt"
   

In alternativa, per importare automaticamente lo stato dell'archivio esistente ed esportare le nuove modifiche in un unico comando, utilizza --sync-tar=/tmp/work.tar. Quando un processo sandbox termina, Cloud Run elimina definitivamente i file di overlay temporanei che non sono stati esportati in un file di archivio.

Esegui un comando in background

Per eseguire processi a lunga esecuzione, browser headless o server in background, ad esempio un loop dell'agente in background che ascolta continuamente le richieste in entrata, utilizza il flag --detach.

Ad esempio, esegui il seguente comando per avviare una sandbox scollegata con un programma inattivo o in background:

sandbox run my-web-server --detach -- /usr/bin/long_running_or_idle_program

Puoi utilizzare il flag detach per riutilizzare la stessa sandbox per più test. Per interagire con una sandbox scollegata in esecuzione o eseguire comandi aggiuntivi al suo interno, utilizza il comando sandbox exec e scegli come target la sandbox in base al suo nome.

Ad esempio, per eseguire un comando di test all'interno della sandbox in background my-web-server esistente, esegui il seguente comando:

sandbox exec my-web-server -- /usr/bin/python3 -c "print('test-complete')"

Configura le variabili di ambiente

Configura le variabili di ambiente nelle sandbox come faresti con qualsiasi altro container. Le sandbox non ereditano le variabili di ambiente dal container host. Devi fornirle in modo esplicito utilizzando il flag --env quando esegui il comando sandbox.

Ad esempio, per passare una variabile di configurazione a una sandbox, esegui il seguente comando:

sandbox do --env AGENT_MODE="test" -- /usr/bin/bash -c "echo \$AGENT_MODE"

Evita di passare i secret utilizzando il flag env, perché potrebbero essere visibili ai processi sandbox.

Crea snapshot del file system

Esegui il deployment di una sandbox denominata in background per gestire attività continue come server web o workflow di agenti a esecuzione continua, esegui comandi sulla sandbox in modo dinamico e acquisisci lo stato del file system modificato in un file di archivio tar.

Suggerimento: se esegui molti comandi ripetutamente su una singola sandbox, valuta la possibilità di avviare una sandbox una sola volta, con un punto di ingresso inattivo, ad esempio sleep 12m, e poi eseguire il comando sandbox exec che ha come target questa sandbox per un'esecuzione dei comandi molto rapida.

Ad esempio, per eseguire il deployment di una sandbox in background, scrivere un file nel relativo overlay e creare uno snapshot del relativo stato per verificare che i dati siano stati acquisiti, esegui i seguenti comandi:

1. Esegui il deployment di una sandbox denominata in background con l'accesso in scrittura abilitato, creando un file all'interno del relativo spazio di lavoro:

   sandbox run --write my-sandbox --detach -- /usr/bin/bash -c "echo 'hi' > /tmp/hello.txt && sleep 1h"
   

2. Crea uno snapshot del file system modificato della sandbox in esecuzione utilizzando il comando sandbox tar:

   sandbox tar my-sandbox --file=/tmp/foo.tar
   

3. Estrai e verifica che il file di archivio dello snapshot contenga i dati scritti all'interno della sandbox:

   tar -xvf /tmp/foo.tar
   

   Dovresti vedere i seguenti risultati:

   ./
   ./tmp/
   ./tmp/hello.txt
   

Configura il networking

Per impostazione predefinita, tutto il traffico in uscita dalla sandbox viene bloccato. Per consentire l'accesso alla rete in uscita, utilizza il flag --allow-egress:

Ad esempio, per recuperare i dati da un endpoint esterno, esegui il seguente comando:

sandbox do --allow-egress -- /usr/bin/python3 -c 'import urllib.request; print(urllib.request.urlopen("https://google.com").getcode())'

Questo comando restituisce il codice di stato HTTP standard 200, che indica una connessione riuscita.

Accedi al file system

Per impostazione predefinita, i processi eseguiti all'interno della sandbox hanno accesso in sola lettura al file system root del container host. Puoi utilizzare il flag --write per abilitare la scrittura in un overlay del file system temporaneo (tmpfs). Tuttavia, le scritture andranno perse quando la sandbox viene eliminata. Per abilitare la scrittura persistente nel container host, puoi configurare i montaggi di binding.

Accesso in sola lettura predefinito

All'interno della sandbox, i processi possono leggere i file dal container host e non possono scrivere nel file system root.

I seguenti esempi presuppongono che tu stia eseguendo i comandi dalla directory root (/) del container host.

Per verificare l'accesso in sola lettura predefinito, esegui i seguenti comandi:

1. Crea uno script Python nel container host:

   mkdir -p /tmp/my-scripts
   echo "print('hi')" > /tmp/my-scripts/task.py
   

2. Verifica che il file esista in locale:

   cat /tmp/my-scripts/task.py
   

3. Esegui il file all'interno della sandbox:

   sandbox do -- /usr/bin/python3 /tmp/my-scripts/task.py
   

   Questo comando restituisce hi, confermando che la sandbox ha accesso in lettura.

   Se tenti di scrivere i dati direttamente nel file system root della sandbox senza configurazione aggiuntiva, l'esecuzione non riesce. Ad esempio, se tenti di scrivere in /tmp all'interno della sandbox predefinita, viene restituito un errore del file system di sola lettura:

   Esegui il seguente comando per scrivere nel file system root:

   sandbox do -- /usr/bin/bash -c "echo 'hi' > /tmp/testfile.txt"
   

   Il comando non riesce e viene visualizzato il seguente errore:

   /usr/bin/bash: line 1: /tmp/testfile.txt: Read-only file system
   Error: failed to exec in container: cmd.Wait(exec) failed: exit status 1
   

Condividi i dati utilizzando i montaggi di binding

Per consentire ai processi all'interno della sandbox di scrivere dati persistenti, collega un volume condiviso utilizzando il flag --mount:

1. Crea una directory di volumi condivisi nel container host e inserisci un file iniziale:

   mkdir -p /tmp/my-volume
   echo 'read' > /tmp/my-volume/readwrite.txt
   

2. Esegui la sandbox per leggere il file dal percorso di montaggio del binding:

   sandbox do --mount type=bind,source=/tmp/my-volume,destination=/mnt/my-mount -- /usr/bin/bash -c "cat /mnt/my-mount/readwrite.txt"
   

   Questo comando restituisce read.

3. Esegui la sandbox per scrivere nuovi dati nell'host dall'interno del montaggio:

   sandbox do --mount type=bind,source=/tmp/my-volume,destination=/mnt/my-mount -- /usr/bin/bash -c "echo 'write' > /mnt/my-mount/readwrite.txt"
   

4. Verifica nel container host che la sandbox abbia modificato correttamente il file:

   cat /tmp/my-volume/readwrite.txt
   

   Questo comando restituisce write.

Configura i montaggi di sola lettura

Per concedere alla sandbox l'accesso a una directory host impedendo esplicitamente la modifica dei file, aggiungi l'attributo readonly alla specifica di montaggio.

Ad esempio, esegui il seguente comando per testare le restrizioni di scrittura su un montaggio di binding di sola lettura:

sandbox do --mount type=bind,source=/tmp/my-volume,destination=/mnt/my-mount,readonly -- /usr/bin/bash -c "echo 'fails' > /mnt/my-mount/hello.txt"

Il tentativo di scrittura non riesce e viene visualizzato il seguente errore:

/usr/bin/bash: line 1: /mnt/my-mount/hello.txt: Read-only file system
Error: failed to exec in container: cmd.Wait(exec) failed: exit status 1

Visualizza i log

Cloud Run acquisisce automaticamente gli eventi del ciclo di vita della sandbox, come gli avvii e le uscite dell'esecuzione, in Cloud Logging.

L'interfaccia a riga di comando sandbox scrive l'output standard (stdout) e l'errore standard (stderr) dei comandi in sandbox direttamente nei flussi standard del processo di chiamata. Per visualizzare questi log in Cloud Logging, indirizza i flussi all'output standard e all'errore standard del container:

Node.js

const { exec } = require('child_process');
const child = exec('sandbox do -- /usr/bin/python3 -c "print(1+2)"');
child.stdout.pipe(process.stdout);
child.stderr.pipe(process.stderr);

Python

subprocess.run(
    ["sandbox", "do", "--", "/usr/bin/python3", "-c", "print(1+2)"],
    stdout=sys.stdout,
    stderr=sys.stderr,
)

Vai

cmd := exec.Command("sandbox", "do", "--", "/usr/bin/python3", "-c", "print(1+2)")
cmd.Stdout = os.Stdout
cmd.Stderr = os.Stderr
cmd.Run()

Passaggi successivi

• Scopri di più su hosting di agenti AI su Cloud Run.
• Esplora l'automazione di browser e sistemi operativi in Cloud Run.
• Esamina il contratto di runtime del container.