Le sandbox di Cloud Run forniscono un ambiente rapido, sicuro e isolato per eseguire il codice dell'agente, eseguire trasformazioni dei dati ed eseguire script in sicurezza all'interno del job esistente. Le sandbox sono altamente ottimizzate per la latenza e vengono eseguite nella stessa istanza del container, condividendo la CPU e la memoria allocate.
Questa pagina descrive come configurare le sandbox sul container. Per informazioni dettagliate sulla scrittura di codice per interagire con la sandbox utilizzando l'interfaccia a riga di comando, consulta Esecuzione di codice in Cloud Run.
Prima di iniziare
- Accedi al tuo account Google Cloud . Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti senza costi per l'esecuzione, il test e il deployment di workload.
-
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 theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
-
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 theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
- Installa e inizializza gcloud CLI.
- Crea un job Cloud Run.
Ruoli obbligatori
Per ottenere le autorizzazioni necessarie per configurare i job Cloud Run, chiedi all'amministratore di concederti i seguenti ruoli IAM:
- Cloud Run Developer (
roles/run.developer) sul job Cloud Run - Utente dell'account di servizio (
roles/iam.serviceAccountUser) sull'identità di servizio
Per un elenco di ruoli e autorizzazioni IAM associati a Cloud Run, consulta Ruoli IAM di Cloud Run e Autorizzazioni IAM di Cloud Run. Se il tuo job Cloud Run interagisce con le APIGoogle Cloud , come le librerie client Cloud, consulta la guida alla configurazione dell'identità del servizio. Per saperne di più sulla concessione dei ruoli, consulta Autorizzazioni di deployment e Gestisci l'accesso.
Abilita le sandbox
Per abilitare le sandbox nei job Cloud Run, utilizza Google Cloud CLI, una configurazione YAML o Terraform:
gcloud
Per creare o aggiornare il job, specifica il flag --sandbox-launcher:
Per creare un job, esegui questo comando:
gcloud beta run jobs create JOB --image IMAGE_URL --sandbox-launcher
Sostituisci quanto segue:
- JOB: il nome del job Cloud Run.
IMAGE_URL: un riferimento all'immagine container, ad esempious-docker.pkg.dev/cloudrun/container/job:latest
Per aggiornare un job esistente, esegui questo comando:
gcloud beta run jobs update JOB --sandbox-launcher
YAML
Se stai creando un nuovo job, salta questo passaggio. Se stai aggiornando un job esistente, scarica la relativa configurazione YAML:
gcloud run jobs describe JOB --format export > job.yaml
Aggiorna il file YAML in modo da includere l'attributo
sandboxLauncherimpostato sutrueall'interno della configurazione del container:apiVersion: run.googleapis.com/v1 kind: Job metadata: name: JOB annotations: run.googleapis.com/launch-stage: BETA spec: template: spec: template: spec: containers: - name: CONTAINER image: IMAGE_URL sandboxLauncher: trueSostituisci quanto segue:
- JOB: il nome del job Cloud Run.
- CONTAINER: il nome del container.
IMAGE_URL: un riferimento all'immagine container, ad esempious-docker.pkg.dev/cloudrun/container/job:latest
Crea o aggiorna il job utilizzando il seguente comando:
gcloud run jobs replace job.yaml
Per impostazione predefinita, il comando
gcloud run jobs replaceutilizza il filejob.yaml, se presente.
Terraform
Per scoprire come applicare o rimuovere una configurazione Terraform, consulta Comandi Terraform di base.
Aggiungi quanto segue a una risorsagoogle_cloud_run_v2_job nella configurazione Terraform:resource "google_cloud_run_v2_job" "default" {
name = "JOB"
location = "REGION"
template {
template {
containers {
image = "IMAGE_URL"
sandbox_launcher = true
}
}
}
}
Sostituisci quanto segue:
- JOB: il nome del job Cloud Run.
- REGION: la regione Google Cloud . Ad esempio:
europe-west1. IMAGE_URL: un riferimento all'immagine container, ad esempious-docker.pkg.dev/cloudrun/container/job:latest
Le sandbox condividono la CPU e l'allocazione della memoria allocate al container host. Assicurati che i limiti di CPU e memoria del container principale possano supportare sia l'applicazione sia le sandbox attive eseguite contemporaneamente.
Disattiva le sandbox
Per disabilitare la possibilità di avviare una sandbox nel job, utilizza Google Cloud CLI o una configurazione YAML:
gcloud
Aggiorna il job utilizzando il flag --no-sandbox-launcher eseguendo questo comando:
gcloud beta run jobs update JOB --no-sandbox-launcher
Sostituisci JOB con il nome del job.
YAML
Se stai creando un nuovo job, salta questo passaggio. Se stai aggiornando un job esistente, scarica la relativa configurazione YAML:
gcloud run jobs describe JOB --format export > job.yaml
Aggiorna il file YAML per rimuovere l'attributo
sandboxLauncherall'interno della configurazione del container:apiVersion: run.googleapis.com/v1 kind: Job metadata: name: JOB spec: template: spec: template: spec: containers: - name: CONTAINER image: IMAGE_URLSostituisci quanto segue:
- JOB: il nome del job Cloud Run.
- CONTAINER: il nome del container.
IMAGE_URL: un riferimento all'immagine container, ad esempious-docker.pkg.dev/cloudrun/container/job:latest
Crea o aggiorna il job utilizzando il seguente comando:
gcloud run jobs replace job.yaml
Per impostazione predefinita, il comando
gcloud run jobs replaceutilizza il filejob.yaml, se presente.
Visualizza le impostazioni della sandbox
Per visualizzare le impostazioni attuali della sandbox per il job Cloud Run:
Console
Nella console Google Cloud , vai alla pagina Job di Cloud Run:
Fai clic sul job per aprire la pagina Dettagli job.
Nella scheda Cronologia, fai clic sull'ID del job eseguito nell'elenco.
Nella scheda Container, individua l'impostazione Avvio sandbox per visualizzare se i container in modalità sandbox sono abilitati o disabilitati.
gcloud
Utilizza il seguente comando:
gcloud run jobs executions describe EXECUTION_NAME --format yaml
Sostituisci EXECUTION_NAME con il nome dell'esecuzione del job.
Per verificare che i container con sandbox siano abilitati, individua l'attributo
sandboxLauncher: truenella configurazione restituita.
Per eseguire codice non attendibile in una sandbox dal tuo job, consulta Esecuzione di codice in Cloud Run.
Configura i template sandbox
I template di sandbox consentono di definire immagini container per le sandbox. Anziché eseguire sessioni di sandbox all'interno del container dell'applicazione principale, i comandi sandbox do
--template e sandbox run --template avviano nuovi container utilizzando le immagini specificate, ad esempio Python, Node.js o un ambiente di esecuzione personalizzato.
Queste sandbox vengono eseguite nei propri container e condividono i limiti di CPU e memoria del container principale. Non puoi impostare limiti di CPU e memoria separati per un template. Cloud Run supporta fino a 10 template di sandbox.
I punti di montaggio del volume devono fare riferimento a un volume in memoria nella risorsa Cloud Run.
I template sandbox offrono le seguenti funzionalità:
Immagini container dedicate: dichiara immagini container distinte, come
python:3.12-slimobusybox:latest, come template di sandbox. Puoi anche utilizzare altri runtime e strumenti per le sandbox che non sono richiesti nel container principale. In questo modo, il container principale rimane leggero isolando gli strumenti e i runtime utilizzati solo per il sandboxing.Creazione di istanze on demand: l'interfaccia a riga di comando della sandbox (
/usr/local/gcp/bin/sandbox) genera nuovi container sandbox da un template senza eseguire il provisioning di nuove VM o addebitare costi per nuove istanze.Condivisione di file isolata per sandbox: condividi un volume in memoria tra il container principale e più sandbox, limitando al contempo ogni sandbox alla propria sottodirectory isolata per impedire alle sandbox di visualizzare o modificare altri file.
Puoi configurare i template di sandbox utilizzando una configurazione YAML o l'API Cloud Run Admin:
YAML
Se stai creando un nuovo job, salta questo passaggio. Se stai aggiornando un job esistente, scarica la relativa configurazione YAML:
gcloud run jobs describe JOB --format export > job.yaml
Aggiorna il file YAML del job in modo da includere la configurazione dei template
sandboxes:apiVersion: run.googleapis.com/v1 kind: Job metadata: name: JOB annotations: run.googleapis.com/launch-stage: BETA spec: template: spec: template: spec: containers: - image: IMAGE_URL sandboxLauncher: true volumeMounts: - name: VOLUME_NAME mountPath: CONTAINER_MOUNT_PATH volumes: - name: VOLUME_NAME emptyDir: medium: Memory sandboxes: templates: - name: TEMPLATE_NAME image: TEMPLATE_IMAGE_URL volumeMounts: - name: VOLUME_NAME mountPath: SANDBOX_MOUNT_PATH subPath: SUBPATHSostituisci quanto segue:
- JOB: il nome del job Cloud Run.
- IMAGE_URL: l'URL dell'immagine container da utilizzare per il container principale.
- TEMPLATE_NAME: il nome del template.
- TEMPLATE_IMAGE_URL: l'URL dell'immagine container da utilizzare per il template della sandbox.
- (Facoltativo) VOLUME_NAME: il nome del volume da montare.
- (Facoltativo) CONTAINER_MOUNT_PATH: il percorso in cui viene montato il volume all'interno del container principale.
- (Facoltativo) SANDBOX_MOUNT_PATH: il percorso in cui è montato il volume all'interno del container della sandbox.
- (Facoltativo) SUBPATH: un percorso di sottodirectory relativo all'interno del volume da montare nel container della sandbox, ad esempio
my-subdir. Per impostare una sottodirectory diversa per ogni sandbox in fase di runtime, utilizza un segnaposto$(VARIABLE_NAME), ad esempio$(SANDBOX_DIR):- VARIABLE_NAME può contenere solo lettere ASCII e trattini bassi; i numeri e i trattini non sono supportati.
- Per risolvere il segnaposto in fase di runtime, passa il flag
--template-var=VARIABLE_NAME=VALUEinsieme a--template. subPathnon crea automaticamente le directory. Crea la directory SUBPATH risolta nel volume dal container principale, ad esempio utilizzandomkdir -p, prima di eseguiresandbox doosandbox run.
Crea o aggiorna il job utilizzando il seguente comando:
gcloud run jobs replace job.yaml
Per impostazione predefinita, il comando
gcloud run jobs replaceutilizza il filejob.yaml, se presente.
API REST
Per configurare i template di sandbox, invia una richiesta PATCH all'API Cloud Run Admin:
curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -X PATCH \ "https://run.googleapis.com/v2/projects/PROJECT_ID/locations/REGION/jobs/JOB" \ -d '{ "launchStage": "BETA", "template": { "template": { "containers": [ { "image": "IMAGE_URL", "sandboxLauncher": true, "volumeMounts": [ { "name": "VOLUME_NAME", "mountPath": "CONTAINER_MOUNT_PATH" } ] } ], "sandboxes": { "templates": [ { "name": "TEMPLATE_NAME", "image": "TEMPLATE_IMAGE_URL", "volumeMounts": [ { "name": "VOLUME_NAME", "mountPath": "SANDBOX_MOUNT_PATH", "subPath": "SUBPATH" } ] } ] }, "volumes": [ { "name": "VOLUME_NAME", "emptyDir": { "medium": "MEMORY" } } ] } } }'
Sostituisci quanto segue:
- JOB: il nome del job Cloud Run.
- PROJECT_ID: il tuo ID progetto Google Cloud .
- REGION: la regione in cui è stato eseguito il deployment della risorsa Cloud Run.
- IMAGE_URL: l'URL dell'immagine container da utilizzare per il container principale.
- TEMPLATE_NAME: il nome del template.
- TEMPLATE_IMAGE_URL: l'URL dell'immagine container da utilizzare per il template della sandbox.
- (Facoltativo) VOLUME_NAME: il nome del volume da montare.
- (Facoltativo) CONTAINER_MOUNT_PATH: il percorso in cui viene montato il volume all'interno del container principale.
- (Facoltativo) SANDBOX_MOUNT_PATH: il percorso in cui è montato il volume all'interno del container della sandbox.
- (Facoltativo) SUBPATH: un percorso di sottodirectory relativo all'interno del volume da montare nel container della sandbox, ad esempio
my-subdir. Per impostare una sottodirectory diversa per ogni sandbox in fase di runtime, utilizza un segnaposto$(VARIABLE_NAME), ad esempio$(SANDBOX_DIR):- VARIABLE_NAME può contenere solo lettere ASCII e trattini bassi; i numeri e i trattini non sono supportati.
- Per risolvere il segnaposto in fase di runtime, passa il flag
--template-var=VARIABLE_NAME=VALUEinsieme a--template. subPathnon crea automaticamente le directory. Crea la directory SUBPATH risolta nel volume dal container principale, ad esempio utilizzandomkdir -p, prima di eseguiresandbox doosandbox run.
Per eseguire i template utilizzando l'interfaccia a riga di comando dall'interno del container del job, consulta Esegui i comandi utilizzando i template della sandbox.