Configurar sandboxes para serviços

Visualização — 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.

As 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. As sandboxes são altamente otimizadas para latência e são executadas na mesma instância do contêiner, compartilhando a CPU e a memória alocadas.

Esta página descreve como configurar sandboxes no contêiner. Para detalhes sobre como escrever código para interagir com a sandbox usando a CLI, consulte Execução de código no Cloud Run.

Antes de começar

Faça login na sua Google Cloud conta do. Se você não conhece o Google Cloud, crie uma conta para avaliar a performance dos nossos produtos em cenários 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 serviço do Cloud Run service 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 identidade do serviço

Se você estiver implantando um serviço ou função do código-fonte, você 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 Google Cloud APIs, 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 as sandboxes, o serviço do Cloud Run é implantado no ambiente de execução de segunda geração. Para ativar as sandboxes nos 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 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 de LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG

• Para atualizar um serviço atual, 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 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 de 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

   O comando gcloud run services replace usa o arquivo service.yaml por padrão, se presente.

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

Desativar sandboxes

Para desativar a capacidade de iniciar uma sandbox no 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

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

   O comando gcloud run services replace usa o arquivo service.yaml por padrão, se presente.

Iniciar sandboxes

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

É possível executar o binário referenciando o caminho absoluto dele 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(`/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}

Ir

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 da 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 conferir a lista completa de comandos disponíveis, execute o /usr/local/gcp/bin/sandbox -h comando.

Para executar códigos não confiáveis em uma sandbox do serviço, consulte Execução de código no Cloud Run.