Configurar sandboxes para serviços

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

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

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

  3. Instale e inicialize a CLI gcloud.
  4. 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:

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

  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 para remover o atributo sandboxLauncher dentro 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: 8080
    

    Substitua:

    • 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 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 ele estiver presente.

Ver configurações do sandbox

Para ver as configurações atuais do sandbox do serviço do Cloud Run:

Console

  1. No console do Google Cloud , acesse a página Serviços do Cloud Run:

    Acessar o Cloud Run

  2. Clique no serviço para abrir a página Detalhes do serviço.

  3. Clique na guia Histórico de revisões.

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

  1. Use o comando a seguir:

    gcloud beta run services describe SERVICE

    SERVICE pelo nome do serviço;

  2. Para verificar se os contêineres em sandbox estão ativados, localize o atributo sandboxLauncher: true na 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-slim ou busybox: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

  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 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: SUBPATH
    

    Substitua:

    • 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=VALUE com --template.
      • O subPath não cria diretórios automaticamente. Crie o diretório SUBPATH resolvido no volume do contêiner principal, por exemplo, usando mkdir -p, antes de executar sandbox do ou sandbox run.
  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 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=VALUE com --template.
    • O subPath não cria diretórios automaticamente. Crie o diretório SUBPATH resolvido no volume do contêiner principal, por exemplo, usando mkdir -p, antes de executar sandbox do ou sandbox run.

Para executar modelos usando a CLI no contêiner de serviço, consulte Executar comandos usando modelos de sandbox.