Execução de código no Cloud Run

Pré-lançamento — Sandboxes do Cloud Run

Este recurso está sujeito aos Termos das Soluções Pré-GA na seção Termos Gerais de Serviço dos Termos Específicos de Serviço. Os recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

Os sandboxes do Cloud Run permitem executar código não confiável em um ambiente isolado diretamente nas cargas de trabalho do contêiner. Esse recurso ajuda os agentes de IA a executar subagentes com segurança, realizar tarefas computacionais ou iniciar navegadores automatizados sem colocar o sistema host em risco.

Veja as principais vantagens

Os sandboxes do Cloud Run oferecem as seguintes vantagens principais:

• Criação rápida: os sandboxes são interativos e estão prontos para executar comandos quase instantaneamente. Ao criar sandboxes em um recurso atual do Cloud Run em que o agente é executado, você reduz os tempos de criação em comparação com a criação de um novo recurso do Cloud Run para cada tarefa. Essa eficiência ajuda a garantir que o agente continue responsivo.

• Segurança: os sandboxes isolam a execução do processo. Por padrão, os sandboxes não têm acesso à carga de trabalho mãe, às variáveis de ambiente, aos secrets ou ao servidor de metadados do Google Cloud . Todos os sandboxes são completamente isolados uns dos outros.

• Controle de acesso e ambiente: os processos são executados com privilégios sudo como um usuário raiz, permitindo que você instale ferramentas usando gerenciadores de pacotes como apt, pip ou npm durante a execução. Embora o ambiente de sandbox seja temporário e excluído após a conclusão, é possível usar diretórios persistentes ou snapshots para salvar espaços de trabalho específicos ou mapear dados para um bucket do Cloud Storage.

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 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. Instale e inicialize a CLI gcloud.
2. Implante um recurso do Cloud Run, como um serviço, job, pool de workers ou instância da segunda geração .

Ativar sandboxes

Para usar sandboxes, primeiro é necessário ativá-los no recurso do Cloud Run usando a flag --sandbox-launcher ou o atributo YAML sandboxLauncher. Para ver as etapas de configuração detalhadas, escolha um dos seguintes tipos de recurso:

• Serviços
• Jobs
• Pools de workers
• Instâncias (pré-lançamento)

Iniciar sandboxes

Depois de ativar os sandboxes, você pode iniciá-los no ambiente de execução do contêiner. O binário do sandbox está localizado em /usr/local/gcp/bin/sandbox.

Os exemplos neste guia usam o comando sandbox em vez do caminho absoluto /usr/local/gcp/bin/sandbox.

Para executar o binário, faça referência ao caminho absoluto dele no código-fonte. Por exemplo, para imprimir Hello dentro do sandbox isolado, escolha uma das seguintes opções:

Node.js

Para executar o comando de sandbox em um aplicativo Node.js, inclua o seguinte código:

exec(`sandbox do -- /bin/echo "Hello"`, (e, stdout, stderr) => {
    res.send({ stdout, stderr });
});

Python

Para executar o comando de sandbox em um aplicativo Python, inclua o seguinte código:

import subprocess
result = subprocess.run(
    ["sandbox", "do", "--", "/bin/echo", "Hello"],
    capture_output=True,
    text=True,
)
return {"stdout": result.stdout, "stderr": result.stderr}

Go

Para executar o comando de sandbox em um aplicativo Go, inclua o seguinte código:

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

CLI do Sandbox

Para executar o comando de sandbox diretamente na linha de comando, execute o seguinte comando:

sandbox do -- /bin/echo "Hello"

Para ver a lista completa de comandos disponíveis, execute o comando sandbox -h.

Usar os recursos de linha de comando do sandbox

A ferramenta de linha de comando sandbox contém comandos para executar, configurar e gerenciar sandboxes.

Executar um comando no sandbox

É possível executar uma instrução em um sandbox novo e temporário usando o comando sandbox do. O comando sandbox do executa as seguintes tarefas:

1. Ativa um ambiente de sandbox (sandbox run).
2. Executa o comando especificado (sandbox exec).
3. Exclui o sandbox após a execução (sandbox delete).

Por exemplo, para realizar um cálculo matemático dentro do sandbox, execute os seguintes snippets de código para o idioma de sua preferência. Verifique se todos os comandos ou ferramentas executados, como python3, estão instalados na imagem do contêiner:

Node.js

Para executar o comando de sandbox em um aplicativo Node.js:

exec(`sandbox do -- /usr/bin/python3 -c "print(1+2)"`, (e, stdout, stderr) => {
    res.send({ stdout, stderr });
});

Python

Para executar o comando de sandbox em um aplicativo Python:

import subprocess
result = subprocess.run(
    ["sandbox", "do", "--", "/usr/bin/python3", "-c", "print(1+2)"],
    capture_output=True,
    text=True,
)
return {"stdout": result.stdout, "stderr": result.stderr}

Go

Para executar o comando de sandbox em um aplicativo Go:

cmd := exec.Command("sandbox", "do", "--", "/usr/bin/python3", "-c", "print(1+2)")
out, err := cmd.CombinedOutput()

CLI do Sandbox

Para executar o comando de sandbox diretamente na linha de comando:

sandbox do -- /usr/bin/python3 -c "print(1+2)"

Se você executar um comando pelo nome sem o caminho absoluto, como python3 em vez de /usr/bin/python3, configure explicitamente a variável de ambiente PATH no sandbox usando a flag --env.

Manter dados em diferentes execuções

Os sandboxes são temporários por padrão. Para persistir dados em diferentes execuções de sandbox na mesma instância do Cloud Run, é possível importar e exportar o estado do sistema de arquivos do espaço de trabalho usando arquivos de arquivo tar padrão. Como alternativa, é possível configurar montagens de vinculação para compartilhar diretórios diretamente entre o contêiner do host e os ambientes de sandbox.

Use as seguintes flags ao executar o comando sandbox do:

• --export-tar: captura arquivos de sobreposição modificados em um arquivo tar após a conclusão.
• --import-tar: extrai arquivos de um arquivo tar para o sandbox antes da execução.
• --sync-tar: realiza uma sincronização bidirecional importando antes da execução e exportando após a conclusão.

O diretório /tmp dentro do sandbox não faz parte da sobreposição do sistema de arquivos raiz. Portanto, os arquivos de arquivamento não incluem arquivos gravados em /tmp. Para persistir dados, grave-os em um diretório diferente, como /workspace.

Por exemplo, para transmitir dados entre duas chamadas de sandbox usando arquivos de arquivo, execute os seguintes comandos:

1. Grave dados em um sandbox e exporte o estado para um arquivo:

   sandbox do --write --export-tar=/tmp/work.tar \
     -- /usr/bin/bash -c "mkdir -p /workspace && echo 'task-complete' > /workspace/status.txt"
   

2. Importe o arquivo em uma chamada subsequente para recuperar os dados:

   sandbox do --write --import-tar=/tmp/work.tar \
     -- /usr/bin/bash -c "cat /workspace/status.txt"
   

Como alternativa, para importar automaticamente o estado do arquivo atual e exportar novas mudanças em um único comando, use --sync-tar=/tmp/work.tar. Quando um processo de sandbox é encerrado, o Cloud Run exclui permanentemente os arquivos de sobreposição temporários que não foram exportados para um arquivo de arquivamento.

Executar um comando em segundo plano

Para executar processos de longa duração, navegadores headless ou servidores em segundo plano, como um loop de agente em segundo plano que detecta continuamente as solicitações recebidas, use a flag --detach.

Por exemplo, execute o seguinte comando para iniciar um sandbox separado com um programa inativo ou em segundo plano:

sandbox run my-web-server --detach -- /usr/bin/long_running_or_idle_program

Use a flag detach para reutilizar o mesmo sandbox em vários testes. Para interagir ou executar outros comandos em um sandbox separado em execução, use o comando sandbox exec e segmente o sandbox pelo nome.

Por exemplo, para executar um comando de teste no sandbox em segundo plano my-web-server, execute o seguinte comando:

sandbox exec my-web-server -- /usr/bin/python3 -c "print('test-complete')"

Configure as variáveis de ambiente

Configure variáveis de ambiente em sandboxes como faria com qualquer outro contêiner. Os sandboxes não herdam variáveis de ambiente do contêiner host. É preciso fornecê-los explicitamente usando a flag --env ao executar o comando sandbox.

Por exemplo, para transmitir uma variável de configuração para um sandbox, execute o seguinte comando:

sandbox do --env AGENT_MODE="test" -- /usr/bin/bash -c "echo \$AGENT_MODE"

Evite transmitir secrets usando a flag env, porque eles podem ficar visíveis para os processos do sandbox.

Criar snapshots do sistema de arquivos

Implante um sandbox nomeado em segundo plano para lidar com tarefas contínuas, como servidores da Web ou Agentic Workflows de longa duração, execute comandos no sandbox de forma dinâmica e capture o estado do sistema de arquivos modificado em um arquivo tar.

Dica : se você executar muitos comandos repetidamente em um único sandbox, considere iniciar um sandbox uma vez, com um ponto de entrada inativo, como sleep 12m, e, em seguida, executar o comando sandbox exec que segmenta esse sandbox para uma execução de comando muito rápida.

Por exemplo, para implantar um sandbox em segundo plano, gravar um arquivo na sobreposição dele e criar um snapshot do estado para verificar se os dados foram capturados, execute os seguintes comandos:

1. Implante um sandbox nomeado em segundo plano com o acesso de gravação ativado, criando um arquivo no espaço de trabalho dele. Grave o arquivo em um caminho fora de /tmp, porque os arquivos gravados em /tmp dentro do sandbox não são capturados em snapshots:

   sandbox run --write my-sandbox --detach -- /usr/bin/bash -c "echo 'hi' > /workspace/hello.txt && sleep 1h"
   

2. Crie um snapshot do sistema de arquivos modificado do sandbox em execução usando o comando sandbox tar:

   sandbox tar my-sandbox --file=/tmp/foo.tar
   

3. Extraia e verifique se o arquivo de snapshot contém os dados gravados no sandbox:

   tar -xvf /tmp/foo.tar
   

   Você deve ver os seguintes resultados:

   ./
   ./workspace/
   ./workspace/hello.txt
   

Configurar rede

Por padrão, todo o tráfego de saída do sandbox é bloqueado. Para permitir o acesso à rede de saída, use a flag --allow-egress:

Por exemplo, para buscar dados de um endpoint externo, execute o seguinte comando:

sandbox do --allow-egress -- /usr/bin/python3 -c 'import urllib.request; print(urllib.request.urlopen("https://google.com").getcode())'

Esse comando retorna o código de status HTTP padrão 200, indicando uma conexão bem-sucedida.

Acessar o sistema de arquivos

Por padrão, os processos executados dentro do sandbox têm acesso somente leitura ao sistema de arquivos raiz do contêiner do host. Use a flag --write para ativar a gravação em uma sobreposição de sistema de arquivos temporário (tmpfs). No entanto, as gravações serão perdidas quando o sandbox for excluído. Para ativar a gravação persistente no contêiner do host, configure montagens de vinculação.

O diretório /tmp dentro do sandbox é sempre gravável, mesmo sem a flag --write. O diretório /tmp é excluído quando o sandbox é excluído e não é incluído em snapshots ou arquivos de arquivo.

Acesso padrão somente leitura

Dentro do sandbox, os processos podem ler arquivos do contêiner do host, mas não podem gravar no sistema de arquivos raiz fora de /tmp.

Os exemplos a seguir pressupõem que você está executando comandos no diretório raiz (/) do contêiner do host.

Para verificar o acesso padrão somente leitura, execute os seguintes comandos:

1. Crie um script Python no contêiner do host:

   mkdir -p /tmp/my-scripts
   echo "print('hi')" > /tmp/my-scripts/task.py
   

2. Verifique se o arquivo existe localmente:

   cat /tmp/my-scripts/task.py
   

3. Execute o arquivo dentro do sandbox:

   sandbox do -- /usr/bin/python3 /tmp/my-scripts/task.py
   

   Esse comando retorna hi, confirmando que o sandbox tem acesso de leitura.

   Se você tentar gravar dados diretamente no sistema de arquivos raiz do sandbox sem configuração adicional, a execução vai falhar. Por exemplo, tentar gravar no diretório raiz (/) dentro do sandbox padrão retorna um erro de sistema de arquivos somente leitura:

   Execute o seguinte comando para gravar no sistema de arquivos raiz:

   sandbox do -- /usr/bin/bash -c "echo 'hi' > /testfile.txt"
   

   O comando falha com o seguinte erro:

   /usr/bin/bash: line 1: /testfile.txt: Read-only file system
   Error: failed to exec in container: cmd.Wait(exec) failed: exit status 1
   

Compartilhar dados usando montagens de vinculação

Para permitir que os processos dentro do sandbox gravem dados persistentes, anexe um volume compartilhado usando a flag --mount:

1. Crie um diretório de volume compartilhado no contêiner do host e preencha-o com um arquivo inicial:

   mkdir -p /tmp/my-volume
   echo 'read' > /tmp/my-volume/readwrite.txt
   

2. Execute o sandbox para ler o arquivo do caminho de montagem de vinculação:

   sandbox do --mount type=bind,source=/tmp/my-volume,destination=/mnt/my-mount -- /usr/bin/bash -c "cat /mnt/my-mount/readwrite.txt"
   

   Esse comando retorna read.

3. Execute o sandbox para gravar novos dados no host de dentro da montagem:

   sandbox do --mount type=bind,source=/tmp/my-volume,destination=/mnt/my-mount -- /usr/bin/bash -c "echo 'write' > /mnt/my-mount/readwrite.txt"
   

4. Verifique no contêiner do host se o sandbox modificou o arquivo:

   cat /tmp/my-volume/readwrite.txt
   

   Esse comando retorna write.

Configurar montagens somente leitura

Para conceder ao sandbox acesso a um diretório de host e, ao mesmo tempo, impedir explicitamente que ele modifique arquivos, anexe o atributo readonly à especificação de montagem.

Por exemplo, execute o seguinte comando para testar as restrições de gravação em uma montagem de vinculação somente leitura:

sandbox do --mount type=bind,source=/tmp/my-volume,destination=/mnt/my-mount,readonly -- /usr/bin/bash -c "echo 'fails' > /mnt/my-mount/hello.txt"

A tentativa de gravação falha com o seguinte erro:

/usr/bin/bash: line 1: /mnt/my-mount/hello.txt: Read-only file system
Error: failed to exec in container: cmd.Wait(exec) failed: exit status 1

Como visualizar registros

O Cloud Run captura automaticamente eventos de ciclo de vida do sandbox, como início e término de execuções, no Cloud Logging.

A CLI sandbox grava a saída padrão (stdout) e o erro padrão (stderr) de comandos em sandbox diretamente nos streams padrão do processo de invocação. Para ver esses registros no Cloud Logging, encaminhe os streams para a saída padrão e o erro padrão do contêiner:

Node.js

const { exec } = require('child_process');
const child = exec('sandbox do -- /usr/bin/python3 -c "print(1+2)"');
child.stdout.pipe(process.stdout);
child.stderr.pipe(process.stderr);

Python

subprocess.run(
    ["sandbox", "do", "--", "/usr/bin/python3", "-c", "print(1+2)"],
    stdout=sys.stdout,
    stderr=sys.stderr,
)

Go

cmd := exec.Command("sandbox", "do", "--", "/usr/bin/python3", "-c", "print(1+2)")
cmd.Stdout = os.Stdout
cmd.Stderr = os.Stderr
cmd.Run()

A seguir

• Saiba mais sobre como hospedar agentes de IA no Cloud Run.
• Conheça a automação de navegador e SO no Cloud Run.
• Leia o contrato do ambiente de execução do contêiner.