Execução de código no Cloud Run

O Cloud Run já é isolado e em sandbox, o que o torna ideal para hospedar agentes de IA. Quando você ativa os sandboxes do Cloud Run, a ferramenta de linha de comando sandbox fica disponível no contêiner. Use essa 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 usar 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.

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 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: as sandboxes isolam a execução de processos. Por padrão, os sandboxes não têm acesso à carga de trabalho principal, às variáveis de ambiente, aos secrets ou ao servidor de metadados Google Cloud . Todas as caixas de areia 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 temporário e excluído após a conclusão, é possível 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

  1. Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloud, crie uma conta para avaliar o desempenho de nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.

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

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

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

    Go to project selector

  5. Verify that billing is enabled for your Google Cloud project.

  6. Instale e inicialize a CLI gcloud.
  7. Implante um serviço do Cloud Run no ambiente de execução de segunda geração.

Ativar sandboxes

Quando você ativa os sandboxes, o serviço do Cloud Run é implantado no ambiente de execução de segunda geração. Para ativar sandboxes em serviços do Cloud Run, use a Google Cloud CLI ou uma configuração YAML:

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

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

  2. Atualize o arquivo YAML do serviço para incluir o atributo sandboxLauncher definido como true na 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: 8080

    Substitua:

    • SERVICE: o nome do seu serviço do Cloud Run.
    • CONTAINER: o nome do contêiner.
    • IMAGE_URL: uma referência à imagem de 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 LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG

  3. Crie ou atualize o serviço usando o seguinte comando:

    gcloud run services replace service.yaml

    Por padrão, o comando gcloud run services replace usa o arquivo service.yaml, se ele estiver presente.

Os sandboxes compartilham a CPU e a memória alocadas para o contêiner host. Verifique se os limites do contêiner principal para CPU e memória são suficientes para acomodar o aplicativo e as sandbox ativas que você executa ao mesmo tempo.

Desativar sandboxes

Para desativar a capacidade de iniciar uma 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 executando o seguinte comando:

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

SERVICE pelo nome do serviço;

YAML

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

  2. Atualize o arquivo YAML do serviço para remover o atributo sandboxLauncher na 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: 8080

    Substitua:

    • SERVICE: o nome do seu serviço do Cloud Run.
    • CONTAINER: o nome do contêiner.
    • IMAGE_URL: uma referência à imagem de 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 LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG

  3. Crie ou atualize o serviço usando o seguinte comando:

    gcloud run services replace service.yaml

    Por padrão, o comando gcloud run services replace usa o arquivo service.yaml, se ele estiver presente.

Iniciar sandboxes

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

Você pode executar o binário referenciando o caminho absoluto dele no código-fonte. Por exemplo, para imprimir Hello na sua 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(`/usr/local/gcp/bin/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(
    ["/usr/local/gcp/bin/sandbox", "do", "--", "/bin/echo", "Hello"],
    capture_output=True,
    text=True,
)
return {"stdout": result.stdout, "stderr": result.stderr}

Go

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

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

CLI do sandbox

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

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

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

Para ver a lista completa de comandos disponíveis, execute o comando /usr/local/gcp/bin/sandbox -h.

Usar os recursos da 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 novo sandbox efêmero usando o comando sandbox do. O comando sandbox do executa as seguintes tarefas:

  1. Cria 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 fazer um cálculo matemático dentro do sandbox, execute os snippets de código a seguir na linguagem de sua preferência. Verifique se todos os comandos ou ferramentas que você executa, 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}

Go

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

Os sandboxes são efêmeros por padrão. Para manter os 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 tar após a conclusão.
  • --import-tar: extrai arquivos de um 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 compactados, execute os seguintes comandos:

  1. Gravar dados em uma sandbox e exportar o estado para um arquivo de arquivamento:

    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 arquivamento 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 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 arquivos de sobreposição efêmeros que não foram exportados para um arquivo de arquivamento.

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 seguinte comando para iniciar uma sandbox independente com um programa ocioso 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 o mesmo sandbox em vários testes. Para interagir ou executar outros comandos em um sandbox independente em execução, use o comando sandbox exec e direcione o sandbox pelo nome.

Por exemplo, para executar um comando de teste na sua sandbox em segundo plano my-web-server atual, 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 da mesma forma que faria com qualquer outro contêiner. Os sandboxes não herdam variáveis de ambiente do contêiner host. É necessário fornecê-los 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 da 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 fluxos de trabalho de agentes de longa duração, execute comandos no sandbox de forma dinâmica e capture o estado modificado do sistema de arquivos em um arquivo de arquivo tar.

Por exemplo, para implantar uma sandbox em segundo plano, gravar um arquivo na sobreposição dela 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 acesso de gravação ativado, criando um arquivo no espaço de trabalho dele:

    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 resumo contém os dados gravados no 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 dentro da sandbox têm acesso somente leitura ao sistema de arquivos raiz do contêiner 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 a sandbox for excluída. Para ativar a gravação permanente no contêiner host, configure montagens de vinculação.

Acesso padrão somente leitura

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 padrão somente leitura, 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 no 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 vai falhar. Por exemplo, tentar gravar em /tmp dentro do sandbox padrão retorna um erro de sistema de arquivos somente leitura:

    Execute o comando a seguir 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 vinculações de montagem

Para permitir que 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 host e adicione um arquivo inicial a ele:

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

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

    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 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 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 host e impedir explicitamente que ele modifique arquivos, adicione o atributo readonly à especificação de montagem.

Por exemplo, execute o comando a seguir 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

Como visualizar registros

O Cloud Run captura automaticamente eventos do ciclo de vida da sandbox, como início e saída da 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 fluxos padrão do processo de invocação. Para ver esses registros no Cloud Logging, direcione os fluxos 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