Execução de código no Cloud Run

Visualização prévia : 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.

O Cloud Run já está em sandbox e isolado, o que o torna ideal para hospedar agentes de IA. Ao ativar as sandboxes do Cloud Run, a ferramenta de linha de comando sandbox fica disponível no contêiner. Use esta ferramenta de linha de comando para executar código não confiável escrito em qualquer linguagem, em um ambiente de sandbox altamente otimizado e isolado do restante do contêiner.

Os agentes de IA podem aproveitar as sandboxes para executar subagentes com segurança, realizar tarefas computacionais ou abrir navegadores em um ambiente rápido e isolado sem arriscar o sistema host.

As sandboxes do Cloud Run oferecem as seguintes vantagens principais:

• Criação rápida: as sandboxes são interativas e estão prontas para executar comandos quase instantaneamente. Ao criar sandboxes em um recurso 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 permaneça responsivo.

• Segurança: as sandboxes isolam a execução do processo. Por padrão, as sandboxes não têm acesso à carga de trabalho mãe, variáveis de ambiente, secrets ou ao Google Cloud servidor de metadados. Todas as sandboxes são completamente isoladas umas das outras.

• Controle de acesso e ambiente: os processos são executados com privilégios sudo como um usuário não 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 efêmero e excluído após a conclusão, você pode usar diretórios permanentes 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 Google Cloud conta do. 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.

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 de segunda geração , job, pool de workers ou instância.

Ativar sandboxes

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

• Serviços
• Jobs
• Pools de workers
• Instâncias (visualização prévia)

Iniciar sandboxes

Depois de ativar as sandboxes, você pode iniciá-las no ambiente de execução do contêiner. O binário da 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.

Você pode executar o binário referenciando o caminho absoluto no código-fonte. Por exemplo, para imprimir Hello na sandbox isolada, escolha uma das seguintes opções:

Node.js

Para executar o comando da 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 da 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}

Ir

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

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

CLI da sandbox

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

sandbox do -- /bin/echo "Hello"

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

Usar os recursos de linha de comando da sandbox

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

Executar um comando na sandbox

É possível executar uma instrução em uma sandbox nova e efêmera usando o comando sandbox do. O comando sandbox do realiza as seguintes tarefas:

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

Por exemplo, para realizar um cálculo matemático dentro da sandbox, execute os seguintes snippets de código para a linguagem 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 da 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 da 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}

Ir

Para executar o comando da sandbox em um aplicativo Go:

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

CLI da sandbox

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

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

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

Persistir dados em diferentes execuções

As sandboxes são efêmeras por padrão. Para persistir dados em diferentes execuções de sandbox na mesma instância do Cloud Run, importe e exporte o estado do sistema de arquivos do espaço de trabalho usando arquivos de arquivo tar padrão. Como alternativa, você pode configurar montagens de vinculação para compartilhar diretórios diretamente entre o contêiner 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 de arquivo tar após a conclusão.
• --import-tar: extrai arquivos de um arquivo de arquivo tar para a sandbox antes da execução.
• --sync-tar: realiza uma sincronização bidirecional importando antes da execução e exportando após a conclusão.

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

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

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

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

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

Como alternativa, para importar automaticamente o estado do arquivo 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 efêmeros que não foram exportados para um arquivo de arquivo.

Executar um comando em segundo plano

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

Por exemplo, execute o comando a seguir para iniciar uma sandbox desanexada com um programa inativo ou em segundo plano:

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

Você pode usar a flag detach para reutilizar a mesma sandbox para vários testes. Para interagir ou executar outros comandos em uma sandbox desanexada em execução, use o comando sandbox exec e direcione a sandbox pelo nome.

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

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

Configurar as variáveis de ambiente

Configure variáveis de ambiente nas sandboxes da mesma forma que faria com qualquer outro contêiner. As sandboxes não herdam variáveis de ambiente do contêiner host. É necessário fornecê-las explicitamente usando a flag --env ao executar o comando sandbox.

Por exemplo, para transmitir uma variável de configuração para uma 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 de sandbox.

Criar snapshots do sistema de arquivos

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

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

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

1. Implante uma sandbox nomeada em segundo plano com acesso de gravação ativado, criando um arquivo no espaço de trabalho:

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

2. Crie um snapshot do sistema de arquivos modificado da 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 arquivo de snapshot contém os dados gravados na sandbox:

   tar -xvf /tmp/foo.tar
   

   Você deve ver os seguintes resultados:

   ./
   ./tmp/
   ./tmp/hello.txt
   

Configurar rede

Por padrão, todo o tráfego de saída da 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 na sandbox têm acesso somente leitura ao sistema de arquivos raiz do contêiner host. Você pode usar a flag --write para ativar a gravação em uma sobreposição temporária do sistema de arquivos (tmpfs). No entanto, as gravações serão perdidas quando a sandbox for excluída. Para ativar a gravação persistente no contêiner host, configure montagens de vinculação.

Acesso somente leitura padrão

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

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

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

1. Crie um script Python no contêiner 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 na sandbox:

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

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

   Se você tentar gravar dados diretamente no sistema de arquivos raiz da sandbox sem configuração adicional, a execução falhará. Por exemplo, tentar gravar em /tmp na 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' > /tmp/testfile.txt"
   

   O comando falha com o seguinte erro:

   /usr/bin/bash: line 1: /tmp/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 da sandbox gravem dados persistentes, anexe um volume compartilhado usando a flag --mount:

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

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

2. Execute a 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 a sandbox para gravar novos dados de volta 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 host se a sandbox modificou o arquivo:

   cat /tmp/my-volume/readwrite.txt
   

   Esse comando retorna write.

Configurar montagens somente leitura

Para conceder à sandbox acesso a um diretório host, impedindo explicitamente que ela modifique arquivos, anexe o atributo readonly à especificação de montagem.

Por exemplo, execute o seguinte comando para testar 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

Ver registros

O Cloud Run captura automaticamente eventos do ciclo de vida da sandbox, como inicializações e saídas de execução, 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 visualizar esses registros no Cloud Logging, encaminhe os streams para a saída 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.
• Confira a automação de navegador e SO no Cloud Run.
• Analise o contrato de ambiente de execução do contêiner.