Os sandboxes do Cloud Run oferecem um ambiente rápido, seguro e isolado para executar códigos não confiáveis ou ferramentas, como agentes de IA, no serviço atual no ambiente de segunda geração. 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
-
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.
- Implante um serviço do Cloud Run no ambiente de execução de segunda geração.
Funções exigidas
Para receber as permissões necessárias para configurar e implantar os serviços 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 serviço Cloud Run - Usuário da conta de serviço (
roles/iam.serviceAccountUser) na conta de serviço
Se você estiver implantando um serviço ou uma função do código-fonte, também precisará ter outros papéis concedidos no projeto e na conta de serviço do Cloud Build.
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 serviço do Cloud Run interage com as APIs doGoogle Cloud , como as 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
Qualquer mudança na configuração leva à criação de uma nova revisão. As próximas revisões também recebem automaticamente essa configuração, a menos que você faça atualizações explícitas para alterá-la.
Quando você ativa os sandboxes, o serviço do Cloud Run é implantado no ambiente de execução de segunda geração. Para ativar sandboxes nos serviços do Cloud Run, use a Google Cloud CLI, uma configuração YAML ou o Terraform:
gcloud
Para implantar ou atualizar o serviço, especifique a flag --sandbox-launcher:
Para implantar um novo serviço, execute o seguinte comando:
gcloud beta run deploy SERVICE --image IMAGE_URL --sandbox-launcher
Substitua:
- SERVICE: o nome do seu serviço do Cloud Run.
IMAGE_URL: uma referência à imagem do contêiner, por exemplo,us-docker.pkg.dev/cloudrun/container/hello:latest. Se você usa o Artifact Registry, o repositório REPO_NAME já precisará ter sido criado. O URL segue o formato deLOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
Para atualizar um serviço, execute o seguinte comando:
gcloud beta run services update SERVICE --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 services describe SERVICE --format export > service.yaml
Atualize o arquivo YAML para incluir o atributo
sandboxLauncherdefinido comotruena configuração do contêiner: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: 8080Substitua:
- SERVICE: o nome do seu serviço 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/hello:latest. Se você usa o Artifact Registry, o repositório REPO_NAME já precisará ter sido criado. O URL segue o formato deLOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
Crie ou atualize o serviço usando o seguinte comando:
gcloud run services replace service.yaml
O comando
gcloud run services replaceusa o arquivoservice.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_service
na configuração do Terraform:resource "google_cloud_run_v2_service" "default" {
name = "SERVICE"
location = "REGION"
template {
containers {
image = "IMAGE_URL"
sandbox_launcher = true
ports {
container_port = 8080
}
}
}
}
Substitua:
- SERVICE: o nome do seu serviço 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/hello:latest. Se você usa o Artifact Registry, o repositório REPO_NAME já precisará ter sido criado. O URL segue o formato deLOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
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 seu serviço, use a Google Cloud CLI ou uma configuração YAML:
gcloud
Atualize o serviço usando a flag --no-sandbox-launcher com o seguinte comando:
gcloud beta run services update SERVICE --no-sandbox-launcher
SERVICE pelo nome do serviço;
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 services describe SERVICE --format export > service.yaml
Atualize o arquivo YAML para remover o atributo
sandboxLauncherdentro da configuração do contêiner:apiVersion: serving.knative.dev/v1 kind: Service metadata: name: SERVICE spec: template: spec: containers: - name: CONTAINER image: IMAGE_URL port: 8080Substitua:
- SERVICE: o nome do seu serviço 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/hello:latest. Se você usa o Artifact Registry, o repositório REPO_NAME já precisará ter sido criado. O URL segue o formato deLOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
Crie ou atualize o serviço usando o seguinte comando:
gcloud run services replace service.yaml
O comando
gcloud run services replaceusa o arquivoservice.yamlpor padrão, se ele estiver presente.
Ver configurações do sandbox
Para ver as configurações atuais do sandbox do serviço do Cloud Run:
Console
No console do Google Cloud , acesse a página Serviços do Cloud Run:
Clique no serviço para abrir a página Detalhes do serviço.
Clique na guia Histórico de revisões.
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 beta run services describe SERVICE
SERVICE pelo nome do serviço;
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 serviço, 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 services describe SERVICE --format export > service.yaml
Atualize o arquivo YAML do serviço para incluir a configuração de modelos
sandboxes:apiVersion: serving.knative.dev/v1 kind: Service metadata: name: SERVICE annotations: run.googleapis.com/launch-stage: BETA spec: template: spec: containers: - image: IMAGE_URL ports: - containerPort: 8080 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:
- SERVICE: o nome do seu serviço 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 services replace service.yaml
O comando
gcloud run services replaceusa o arquivoservice.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/services/SERVICE?updateMask=launchStage,template.containers,template.sandboxes,template.volumes" \ -d '{ "launchStage": "BETA", "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:
- SERVICE: o nome do seu serviço 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 de serviço, consulte Executar comandos usando modelos de sandbox.