Configurare le sandbox per i job

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

  1. 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.
  2. 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

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

  4. 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

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

  6. Installa e inizializza gcloud CLI.
  7. 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:

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 esempio us-docker.pkg.dev/cloudrun/container/job:latest
  • Per aggiornare un job esistente, esegui questo comando:

    gcloud beta run jobs update JOB --sandbox-launcher

YAML

  1. 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
  2. Aggiorna il file YAML in modo da includere l'attributo sandboxLauncher impostato su true all'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: true
    

    Sostituisci quanto segue:

    • JOB: il nome del job Cloud Run.
    • CONTAINER: il nome del container.
    • IMAGE_URL: un riferimento all'immagine container, ad esempio us-docker.pkg.dev/cloudrun/container/job:latest
  3. Crea o aggiorna il job utilizzando il seguente comando:

    gcloud run jobs replace job.yaml

    Per impostazione predefinita, il comando gcloud run jobs replace utilizza il file job.yaml, se presente.

Terraform

Per scoprire come applicare o rimuovere una configurazione Terraform, consulta Comandi Terraform di base.

Aggiungi quanto segue a una risorsa google_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 esempio us-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

  1. 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
  2. Aggiorna il file YAML per rimuovere l'attributo sandboxLauncher all'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_URL
    

    Sostituisci quanto segue:

    • JOB: il nome del job Cloud Run.
    • CONTAINER: il nome del container.
    • IMAGE_URL: un riferimento all'immagine container, ad esempio us-docker.pkg.dev/cloudrun/container/job:latest
  3. Crea o aggiorna il job utilizzando il seguente comando:

    gcloud run jobs replace job.yaml

    Per impostazione predefinita, il comando gcloud run jobs replace utilizza il file job.yaml, se presente.

Visualizza le impostazioni della sandbox

Per visualizzare le impostazioni attuali della sandbox per il job Cloud Run:

Console

  1. Nella console Google Cloud , vai alla pagina Job di Cloud Run:

    Vai ai job Cloud Run

  2. Fai clic sul job per aprire la pagina Dettagli job.

  3. Nella scheda Cronologia, fai clic sull'ID del job eseguito nell'elenco.

  4. Nella scheda Container, individua l'impostazione Avvio sandbox per visualizzare se i container in modalità sandbox sono abilitati o disabilitati.

gcloud

  1. Utilizza il seguente comando:

    gcloud run jobs executions describe EXECUTION_NAME --format yaml

    Sostituisci EXECUTION_NAME con il nome dell'esecuzione del job.

  2. Per verificare che i container con sandbox siano abilitati, individua l'attributo sandboxLauncher: true nella 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-slim o busybox: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

  1. 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
  2. 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: SUBPATH
    

    Sostituisci 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=VALUE insieme a --template.
      • subPath non crea automaticamente le directory. Crea la directory SUBPATH risolta nel volume dal container principale, ad esempio utilizzando mkdir -p, prima di eseguire sandbox do o sandbox run.
  3. Crea o aggiorna il job utilizzando il seguente comando:

    gcloud run jobs replace job.yaml

    Per impostazione predefinita, il comando gcloud run jobs replace utilizza il file job.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=VALUE insieme a --template.
    • subPath non crea automaticamente le directory. Crea la directory SUBPATH risolta nel volume dal container principale, ad esempio utilizzando mkdir -p, prima di eseguire sandbox do o sandbox 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.