Configurar sandboxes para jobs

Os sandboxes do Cloud Run oferecem um ambiente rápido, seguro e isolado para executar o código do agente, realizar transformações de dados e executar scripts com segurança no job atual. 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. 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.
  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. Crie um job do Cloud Run.

Funções exigidas

Para receber as permissões necessárias para configurar os jobs do Cloud Run, peça ao administrador para conceder a você os seguintes papéis do IAM:

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 job do Cloud Run interagir com APIs doGoogle Cloud , como 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

Para ativar sandboxes em jobs do Cloud Run, use a Google Cloud CLI, uma configuração YAML ou o Terraform:

gcloud

Para criar ou atualizar o job, especifique a flag --sandbox-launcher:

  • Para criar um job, execute o seguinte comando:

    gcloud beta run jobs create JOB --image IMAGE_URL --sandbox-launcher

    Substitua:

    • JOB: o nome do seu job do Cloud Run;
    • IMAGE_URL: uma referência à imagem do contêiner. Por exemplo, us-docker.pkg.dev/cloudrun/container/job:latest.
  • Para atualizar um job, execute o seguinte comando:

    gcloud beta run jobs update JOB --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 jobs describe JOB --format export > job.yaml
  2. Atualize o arquivo YAML para incluir o atributo sandboxLauncher definido como true na configuração do contêiner:

    apiVersion: run.googleapis.com/v1
    kind: Job
    metadata:
      name: JOB
      annotations:
        run.googleapis.com/launch-stage: BETA
    spec:
      template:
        spec:
          template:
            spec:
              containers:
              - name: CONTAINER
                image: IMAGE_URL
                sandboxLauncher: true
    

    Substitua:

    • JOB: o nome do seu job 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/job:latest.
  3. Crie ou atualize o serviço usando o seguinte comando:

    gcloud run jobs replace job.yaml

    O comando gcloud run jobs replace usa o arquivo job.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_job na configuração do Terraform:
resource "google_cloud_run_v2_job" "default" {
  name     = "JOB"
  location = "REGION"

  template {
    template {
      containers {
        image            = "IMAGE_URL"
        sandbox_launcher = true
      }
    }
  }
}

Substitua:

  • JOB: o nome do seu job 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/job:latest.

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 job, use a Google Cloud CLI ou uma configuração YAML:

gcloud

Atualize o job usando a flag --no-sandbox-launcher com o seguinte comando:

gcloud beta run jobs update JOB --no-sandbox-launcher

Substitua JOB pelo nome do seu nó.

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 jobs describe JOB --format export > job.yaml
  2. Atualize o arquivo YAML para remover o atributo sandboxLauncher dentro da configuração do contêiner:

    apiVersion: run.googleapis.com/v1
    kind: Job
    metadata:
      name: JOB
    spec:
      template:
        spec:
          template:
            spec:
              containers:
              - name: CONTAINER
                image: IMAGE_URL
    

    Substitua:

    • JOB: o nome do seu job 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/job:latest.
  3. Crie ou atualize o serviço usando o seguinte comando:

    gcloud run jobs replace job.yaml

    O comando gcloud run jobs replace usa o arquivo job.yaml por padrão, se ele estiver presente.

Ver configurações do sandbox

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

Console

  1. No console do Google Cloud , acesse a página Jobs do Cloud Run:

    Acessar jobs do Cloud Run

  2. Clique no job para abrir a página Detalhes do job.

  3. Na guia Histórico, clique no ID do job executado na lista.

  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 run jobs executions describe EXECUTION_NAME --format yaml

    Substitua EXECUTION_NAME pelo nome da execução do job.

  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 job, 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 jobs describe JOB --format export > job.yaml
  2. Atualize o arquivo YAML do job para incluir a configuração de modelos sandboxes:

    apiVersion: run.googleapis.com/v1
    kind: Job
    metadata:
      name: JOB
      annotations:
        run.googleapis.com/launch-stage: BETA
    spec:
      template:
        spec:
          template:
            spec:
              containers:
              - image: IMAGE_URL
                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:

    • JOB: o nome do seu job 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 jobs replace job.yaml

    O comando gcloud run jobs replace usa o arquivo job.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/jobs/JOB" \
-d '{
  "launchStage": "BETA",
  "template": {
    "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:

  • JOB: o nome do seu job 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 do job, consulte Executar comandos usando modelos de sandbox.