Configura le sandbox per i servizi

Anteprima — Sandbox 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.

Le sandbox di Cloud Run forniscono un ambiente rapido, sicuro e isolato per eseguire codice non attendibile o strumenti, come gli agenti di AI, all'interno del tuo servizio esistente nell'ambiente di seconda generazione. 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 la CLI, consulta Esecuzione del 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 dei carichi di lavoro.

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

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

Verify that billing is enabled for your Google Cloud project.

1. Installa e inizializza gcloud CLI.
2. Esegui il deployment di un servizio Cloud Run nell'ambiente di esecuzione di seconda generazione.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per configurare ed eseguire il deployment di servizi Cloud Run, chiedi all'amministratore di concederti i seguenti ruoli IAM:

• Cloud Run Developer (roles/run.developer) sul servizio Cloud Run
• Service Account User (roles/iam.serviceAccountUser) sull'identità di servizio

Se esegui il deployment di un servizio o di una funzione dal codice sorgente, devi disporre anche di ruoli aggiuntivi concessi al tuo progetto e al account di servizio Cloud Build.

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

Abilitare le sandbox

Qualsiasi modifica alla configurazione comporta la creazione di una nuova revisione. Anche le revisioni successive riceveranno automaticamente questa impostazione di configurazione, a meno che tu non apporti aggiornamenti espliciti per modificarla.

Quando abiliti le sandbox, il servizio Cloud Run viene sottoposto a deployment nell'ambiente di esecuzione di seconda generazione. Per attivare le sandbox nei servizi Cloud Run, utilizza Google Cloud CLI o una configurazione YAML:

gcloud

Per eseguire il deployment o l'aggiornamento del servizio, specifica il flag --sandbox-launcher:

• Per eseguire il deployment di un nuovo servizio, esegui questo comando:

  gcloud beta run deploy SERVICE --image IMAGE_URL --sandbox-launcher

  Sostituisci quanto segue:

  • SERVICE: il nome del tuo servizio Cloud Run.
  • IMAGE_URL: un riferimento all'immagine container, ad esempio us-docker.pkg.dev/cloudrun/container/hello:latest. Se utilizzi Artifact Registry, il repository REPO_NAME deve essere già stato creato. L'URL segue il formato LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG

• Per aggiornare un servizio esistente, esegui questo comando:

  gcloud beta run services update SERVICE --sandbox-launcher

YAML

1. Se stai creando un nuovo servizio, salta questo passaggio. Se stai aggiornando un servizio esistente, scarica la relativa configurazione YAML:

   gcloud run services describe SERVICE --format export > service.yaml

2. Aggiorna il file YAML del servizio in modo da includere l'attributo sandboxLauncher impostato su true all'interno della configurazione del container:

   apiVersion: serving.knative.dev/v1
   kind: Service
   metadata:
     name: SERVICE
     annotations:
       run.googleapis.com/launch-stage: BETA
   spec:
     template:
       spec:
         containers:
         - name: CONTAINER
           image: IMAGE_URL
           sandboxLauncher: true
           port: 8080
   

   Sostituisci quanto segue:

   • SERVICE: il nome del tuo servizio Cloud Run.
   • CONTAINER: il nome del contenitore.
   • IMAGE_URL: un riferimento all'immagine container, ad esempio us-docker.pkg.dev/cloudrun/container/hello:latest. Se utilizzi Artifact Registry, il repository REPO_NAME deve essere già stato creato. L'URL segue il formato LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG

3. Crea o aggiorna il servizio utilizzando il seguente comando:

   gcloud run services replace service.yaml

   Il comando gcloud run services replace utilizza per impostazione predefinita il file service.yaml, se presente.

I sandbox condividono la CPU e la memoria allocate al container host. Assicurati che i limiti principali del container per CPU e memoria siano sufficienti per ospitare sia l'applicazione sia le sandbox attive che esegui contemporaneamente.

Disattivare le sandbox

Per disattivare la possibilità di avviare una sandbox nel tuo servizio, utilizza Google Cloud CLI o una configurazione YAML:

gcloud

Aggiorna il servizio utilizzando il flag --no-sandbox-launcher eseguendo questo comando:

gcloud beta run services update SERVICE --no-sandbox-launcher

Sostituisci SERVICE con il nome del servizio.

YAML

1. Se stai creando un nuovo servizio, salta questo passaggio. Se stai aggiornando un servizio esistente, scarica la relativa configurazione YAML:

   gcloud run services describe SERVICE --format export > service.yaml

2. Aggiorna il file YAML del servizio per rimuovere l'attributo sandboxLauncher all'interno della configurazione del container:

   apiVersion: serving.knative.dev/v1
   kind: Service
   metadata:
     name: SERVICE
   spec:
     template:
       spec:
         containers:
         - name: CONTAINER
           image: IMAGE_URL
           port: 8080
   

   Sostituisci quanto segue:

   • SERVICE: il nome del tuo servizio Cloud Run.
   • CONTAINER: il nome del contenitore.
   • IMAGE_URL: un riferimento all'immagine container, ad esempio us-docker.pkg.dev/cloudrun/container/hello:latest. Se utilizzi Artifact Registry, il repository REPO_NAME deve essere già stato creato. L'URL segue il formato LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG

3. Crea o aggiorna il servizio utilizzando il seguente comando:

   gcloud run services replace service.yaml

   Il comando gcloud run services replace utilizza per impostazione predefinita il file service.yaml, se presente.

Avviare le sandbox

Dopo aver attivato le sandbox, puoi avviarle dall'ambiente di esecuzione del container. Il binario della sandbox si trova in /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(`/usr/local/gcp/bin/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(
    ["/usr/local/gcp/bin/sandbox", "do", "--", "/bin/echo", "Hello"],
    capture_output=True,
    text=True,
)
return {"stdout": result.stdout, "stderr": result.stderr}

Go

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

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

Interfaccia a riga di comando di Sandbox

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

/usr/local/gcp/bin/sandbox do -- /bin/echo "Hello"

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

Per visualizzare l'elenco completo dei comandi disponibili, esegui il comando /usr/local/gcp/bin/sandbox -h.

Per eseguire codice non attendibile in una sandbox dal tuo servizio, consulta Esecuzione del codice in Cloud Run.