Os sandboxes do Cloud Run oferecem um ambiente rápido, seguro e isolado para executar o código do agente, realizar transformações de dados e executar scripts com segurança no job atual. Os sandboxes são altamente otimizados para latência e são executados na mesma instância que o contêiner, compartilhando a CPU e a memória alocadas.
Nesta página, descrevemos como configurar sandboxes no seu contêiner. Para saber como escrever código para interagir com o sandbox usando a CLI, consulte Execução de código no Cloud Run.
Antes de começar
- Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloudagora, crie uma conta para avaliar o desempenho dos nossos produtos em situações reais. Clientes novos também recebem US $300 em créditos para executar, testar e implantar cargas de trabalho sem custos financeiros.
-
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.
- Instale e inicialize a CLI gcloud.
- Crie um job do Cloud Run.
Funções exigidas
Para receber as permissões necessárias para configurar os jobs do Cloud Run, peça ao administrador para conceder a você os seguintes papéis do IAM:
- Desenvolvedor do Cloud Run (
roles/run.developer) no job do Cloud Run - Usuário da conta de serviço (
roles/iam.serviceAccountUser) na conta de serviço
Para uma lista de papéis e permissões do IAM associados ao Cloud Run, consulte Papéis do IAM do Cloud Run e Permissões do IAM do Cloud Run. Se o job do Cloud Run interagir com APIs doGoogle Cloud , como bibliotecas de cliente do Cloud, consulte o guia de configuração de identidade de serviço. Para mais informações sobre como conceder papéis, consulte permissões de implantação e gerenciar acesso.
Ativar sandboxes
Para ativar sandboxes em jobs do Cloud Run, use a Google Cloud CLI, uma configuração YAML ou o Terraform:
gcloud
Para criar ou atualizar o job, especifique a flag --sandbox-launcher:
Para criar um job, execute o seguinte comando:
gcloud beta run jobs create JOB --image IMAGE_URL --sandbox-launcher
Substitua:
- JOB: o nome do seu job do Cloud Run;
IMAGE_URL: uma referência à imagem do contêiner. Por exemplo,us-docker.pkg.dev/cloudrun/container/job:latest.
Para atualizar um job, execute o seguinte comando:
gcloud beta run jobs update JOB --sandbox-launcher
YAML
Se você estiver criando um novo serviço, pule esta etapa. Se você estiver atualizando um serviço existente, faça o download da configuração YAML correspondente:
gcloud run jobs describe JOB --format export > job.yaml
Atualize o arquivo YAML para incluir o atributo
sandboxLauncherdefinido comotruena configuração do contêiner: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: trueSubstitua:
- JOB: o nome do seu job do Cloud Run;
- CONTAINER: o nome do contêiner.
IMAGE_URL: uma referência à imagem do contêiner. Por exemplo,us-docker.pkg.dev/cloudrun/container/job:latest.
Crie ou atualize o serviço usando o seguinte comando:
gcloud run jobs replace job.yaml
O comando
gcloud run jobs replaceusa o arquivojob.yamlpor padrão, se ele estiver presente.
Terraform
Para saber como aplicar ou remover uma configuração do Terraform, consulte Comandos básicos do Terraform.
Adicione o seguinte a um recursogoogle_cloud_run_v2_job
na configuração do Terraform:resource "google_cloud_run_v2_job" "default" {
name = "JOB"
location = "REGION"
template {
template {
containers {
image = "IMAGE_URL"
sandbox_launcher = true
}
}
}
}
Substitua:
- JOB: o nome do seu job do Cloud Run;
- REGION: a região do Google Cloud . Por exemplo,
europe-west1. IMAGE_URL: uma referência à imagem do contêiner. Por exemplo,us-docker.pkg.dev/cloudrun/container/job:latest.
Os sandboxes compartilham a CPU e a alocação de memória alocadas para o contêiner do host. Verifique se os limites de CPU e memória do contêiner principal podem acomodar o aplicativo e os sandboxes ativos que você executa ao mesmo tempo.
Desativar sandboxes
Para desativar a capacidade de iniciar um sandbox no job, use a Google Cloud CLI ou uma configuração YAML:
gcloud
Atualize o job usando a flag --no-sandbox-launcher com o seguinte comando:
gcloud beta run jobs update JOB --no-sandbox-launcher
Substitua JOB pelo nome do seu nó.
YAML
Se você estiver criando um novo serviço, pule esta etapa. Se você estiver atualizando um serviço existente, faça o download da configuração YAML correspondente:
gcloud run jobs describe JOB --format export > job.yaml
Atualize o arquivo YAML para remover o atributo
sandboxLauncherdentro da configuração do contêiner:apiVersion: run.googleapis.com/v1 kind: Job metadata: name: JOB spec: template: spec: template: spec: containers: - name: CONTAINER image: IMAGE_URLSubstitua:
- JOB: o nome do seu job do Cloud Run;
- CONTAINER: o nome do contêiner.
IMAGE_URL: uma referência à imagem do contêiner. Por exemplo,us-docker.pkg.dev/cloudrun/container/job:latest.
Crie ou atualize o serviço usando o seguinte comando:
gcloud run jobs replace job.yaml
O comando
gcloud run jobs replaceusa o arquivojob.yamlpor padrão, se ele estiver presente.
Ver configurações do sandbox
Para ver as configurações atuais do sandbox do job do Cloud Run:
Console
No console do Google Cloud , acesse a página Jobs do Cloud Run:
Clique no job para abrir a página Detalhes do job.
Na guia Histórico, clique no ID do job executado na lista.
Na guia Contêineres, localize a configuração Iniciador de sandbox para conferir se os contêineres em sandbox estão ativados ou desativados.
gcloud
Use o comando a seguir:
gcloud run jobs executions describe EXECUTION_NAME --format yaml
Substitua EXECUTION_NAME pelo nome da execução do job.
Para verificar se os contêineres em sandbox estão ativados, localize o atributo
sandboxLauncher: truena configuração retornada.
Para executar código não confiável em um sandbox do seu job, consulte Execução de código no Cloud Run.
Configurar modelos de sandbox
Com os modelos de sandbox, é possível definir imagens de contêiner para sandboxes. Em vez de
executar sessões de sandbox no contêiner principal do aplicativo, os comandos sandbox do
--template e sandbox run --template iniciam novos contêineres usando
as imagens especificadas, como Python, Node.js ou um ambiente de execução personalizado.
Esses sandboxes são executados nos próprios contêineres e compartilham os limites de CPU e
memória do contêiner principal. Não é possível definir limites separados de CPU e memória
para um modelo. O Cloud Run aceita até 10 modelos de sandbox.
As montagens de volume precisam referenciar um volume na memória no recurso do Cloud Run.
Os modelos de sandbox oferecem os seguintes recursos:
Imagens de contêiner dedicadas: declare imagens de contêiner distintas, como
python:3.12-slimoubusybox:latest, como modelos de sandbox. Também é possível usar outros ambientes de execução e ferramentas para sandboxes que não são necessários no contêiner principal. Isso mantém o contêiner principal leve, isolando ferramentas e ambientes de execução usados apenas para sandbox.Instanciação sob demanda: a CLI do sandbox (
/usr/local/gcp/bin/sandbox) gera novos contêineres de sandbox com base em um modelo sem provisionar novas VMs ou faturar novas instâncias.Compartilhamento de arquivos isolado por sandbox: compartilhe um volume na memória entre o contêiner principal e vários sandboxes, restringindo cada sandbox ao próprio subdiretório isolado para impedir que os sandboxes visualizem ou modifiquem outros arquivos.
É possível configurar modelos de sandbox usando uma configuração YAML ou a API Cloud Run Admin:
YAML
Se você estiver criando um novo serviço, pule esta etapa. Se você estiver atualizando um serviço existente, faça o download da configuração YAML correspondente:
gcloud run jobs describe JOB --format export > job.yaml
Atualize o arquivo YAML do job para incluir a configuração de modelos
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: SUBPATHSubstitua:
- JOB: o nome do seu job do Cloud Run;
- IMAGE_URL: o URL da imagem do contêiner a ser usado para o contêiner principal.
- TEMPLATE_NAME: o nome do modelo.
- TEMPLATE_IMAGE_URL: o URL da imagem de contêiner a ser usado para o modelo de sandbox.
- Opcional: VOLUME_NAME: o nome do volume a ser montado.
- Opcional: CONTAINER_MOUNT_PATH: o caminho em que o volume é montado dentro do contêiner principal.
- Opcional: SANDBOX_MOUNT_PATH: o caminho em que o volume é montado dentro do contêiner de sandbox.
- Opcional: SUBPATH: um caminho de subdiretório relativo no volume a ser montado no contêiner de sandbox, como
my-subdir. Para definir um subdiretório diferente para cada sandbox no ambiente de execução, use um marcador de posição$(VARIABLE_NAME), como$(SANDBOX_DIR):- VARIABLE_NAME pode conter apenas letras ASCII e sublinhados. Dígitos e hifens não são aceitos.
- Para resolver o marcador de posição no ambiente de execução, transmita a flag
--template-var=VARIABLE_NAME=VALUEcom--template. - O
subPathnão cria diretórios automaticamente. Crie o diretório SUBPATH resolvido no volume do contêiner principal, por exemplo, usandomkdir -p, antes de executarsandbox doousandbox run.
Crie ou atualize o serviço usando o seguinte comando:
gcloud run jobs replace job.yaml
O comando
gcloud run jobs replaceusa o arquivojob.yamlpor padrão, se ele estiver presente.
API REST
Para configurar modelos de sandbox, envie uma solicitação PATCH à 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" } } ] } } }'
Substitua:
- JOB: o nome do seu job do Cloud Run;
- PROJECT_ID: o ID do projeto Google Cloud .
- REGION: a região em que o recurso do Cloud Run está implantado.
- IMAGE_URL: o URL da imagem do contêiner a ser usado para o contêiner principal.
- TEMPLATE_NAME: o nome do modelo.
- TEMPLATE_IMAGE_URL: o URL da imagem de contêiner a ser usado para o modelo de sandbox.
- Opcional: VOLUME_NAME: o nome do volume a ser montado.
- Opcional: CONTAINER_MOUNT_PATH: o caminho em que o volume é montado dentro do contêiner principal.
- Opcional: SANDBOX_MOUNT_PATH: o caminho em que o volume é montado dentro do contêiner de sandbox.
- Opcional: SUBPATH: um caminho de subdiretório relativo no volume a ser montado no contêiner de sandbox, como
my-subdir. Para definir um subdiretório diferente para cada sandbox no ambiente de execução, use um marcador de posição$(VARIABLE_NAME), como$(SANDBOX_DIR):- VARIABLE_NAME pode conter apenas letras ASCII e sublinhados. Dígitos e hifens não são aceitos.
- Para resolver o marcador de posição no ambiente de execução, transmita a flag
--template-var=VARIABLE_NAME=VALUEcom--template. - O
subPathnão cria diretórios automaticamente. Crie o diretório SUBPATH resolvido no volume do contêiner principal, por exemplo, usandomkdir -p, antes de executarsandbox doousandbox run.
Para executar modelos usando a CLI no contêiner do job, consulte Executar comandos usando modelos de sandbox.