Configura zonas de pruebas para trabajos

Las zonas de pruebas de Cloud Run proporcionan un entorno rápido, seguro y aislado para ejecutar código de agentes, realizar transformaciones de datos y ejecutar secuencias de comandos de forma segura dentro de tu trabajo existente. Las zonas de pruebas están muy optimizadas para la latencia y se ejecutan dentro de la misma instancia que tu contenedor, por lo que comparten la CPU y la memoria asignadas.

En esta página, se describe cómo configurar zonas de pruebas en tu contenedor. Para obtener detalles sobre cómo escribir código para interactuar con la zona de pruebas con la CLI, consulta Ejecución de código en Cloud Run.

Antes de comenzar

  1. Accede a tu cuenta de Google Cloud . Si eres nuevo en Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.
  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. Instala e inicializa gcloud CLI.
  7. Crea un trabajo de Cloud Run.

Roles obligatorios

Para obtener los permisos que necesitas para configurar los trabajos de Cloud Run, pídele a tu administrador que te otorgue los siguientes roles de IAM:

Para obtener una lista de los roles y los permisos de IAM asociados con Cloud Run, consulta los roles de IAM de Cloud Run y los permisos de IAM de Cloud Run. Si tu trabajo de Cloud Run interactúa con las APIs deGoogle Cloud , como las bibliotecas cliente de Cloud, consulta la guía de configuración de identidades del servicio. Para obtener más información sobre cómo otorgar roles, consulta los permisos de implementación y cómo administrar el acceso.

Habilita las zonas de pruebas

Para habilitar las zonas de pruebas en los trabajos de Cloud Run, usa Google Cloud CLI, una configuración de YAML o Terraform:

gcloud

Para crear o actualizar el trabajo, especifica la marca --sandbox-launcher:

  • Para crear un trabajo, ejecuta el siguiente comando:

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

    Reemplaza lo siguiente:

    • JOB por el nombre del trabajo de Cloud Run.
    • IMAGE_URL: Es una referencia a la imagen de contenedor, por ejemplo, us-docker.pkg.dev/cloudrun/container/job:latest.
  • Para actualizar un trabajo existente, ejecuta el siguiente comando:

    gcloud beta run jobs update JOB --sandbox-launcher

YAML

  1. Si creas un trabajo nuevo, omite este paso. Si actualizas un trabajo existente, descarga su configuración de YAML:

    gcloud run jobs describe JOB --format export > job.yaml
  2. Actualiza tu archivo YAML para incluir el atributo sandboxLauncher establecido en true dentro de la configuración del contenedor:

    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
    

    Reemplaza lo siguiente:

    • JOB por el nombre del trabajo de Cloud Run.
    • CONTAINER: Es el nombre de tu contenedor.
    • IMAGE_URL: Es una referencia a la imagen de contenedor, por ejemplo, us-docker.pkg.dev/cloudrun/container/job:latest.
  3. Crea o actualiza el servicio con el siguiente comando:

    gcloud run jobs replace job.yaml

    El comando gcloud run jobs replace usa de forma predeterminada el archivo job.yaml si está presente.

Terraform

Si deseas obtener más información para aplicar o quitar una configuración de Terraform, consulta los comandos básicos de Terraform.

Agrega lo siguiente a un recurso google_cloud_run_v2_job en tu configuración de Terraform:
resource "google_cloud_run_v2_job" "default" {
  name     = "JOB"
  location = "REGION"

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

Reemplaza lo siguiente:

  • JOB por el nombre del trabajo de Cloud Run.
  • REGION: La Google Cloud región Por ejemplo, europe-west1.
  • IMAGE_URL: Es una referencia a la imagen de contenedor, por ejemplo, us-docker.pkg.dev/cloudrun/container/job:latest.

Las zonas de pruebas comparten la CPU y la memoria asignadas al contenedor del host. Asegúrate de que los límites de CPU y memoria del contenedor principal puedan alojar tanto tu aplicación como las zonas de pruebas activas que ejecutes al mismo tiempo.

Inhabilitar las zonas de pruebas

Para inhabilitar la capacidad de iniciar una zona de pruebas en tu trabajo, usa Google Cloud CLI o una configuración de YAML:

gcloud

Actualiza el trabajo con la marca --no-sandbox-launcher ejecutando el siguiente comando:

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

Reemplaza JOB por el nombre de tu trabajo.

YAML

  1. Si creas un trabajo nuevo, omite este paso. Si actualizas un trabajo existente, descarga su configuración de YAML:

    gcloud run jobs describe JOB --format export > job.yaml
  2. Actualiza tu archivo YAML para quitar el atributo sandboxLauncher dentro de la configuración del contenedor:

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

    Reemplaza lo siguiente:

    • JOB por el nombre del trabajo de Cloud Run.
    • CONTAINER: Es el nombre de tu contenedor.
    • IMAGE_URL: Es una referencia a la imagen de contenedor, por ejemplo, us-docker.pkg.dev/cloudrun/container/job:latest.
  3. Crea o actualiza el servicio con el siguiente comando:

    gcloud run jobs replace job.yaml

    El comando gcloud run jobs replace usa de forma predeterminada el archivo job.yaml si está presente.

Ver la configuración de la zona de pruebas

Para ver la configuración actual de la zona de pruebas de tu trabajo de Cloud Run, sigue estos pasos:

Console

  1. En la consola de Google Cloud , ve a la página Trabajos de Cloud Run:

    Ir a Trabajos de Cloud Run

  2. Haz clic en el trabajo para abrir la página Detalles del trabajo.

  3. En la pestaña Historial, haz clic en el ID del trabajo ejecutado de la lista.

  4. En la pestaña Contenedores, busca el parámetro de configuración Selector de zona de pruebas para ver si los contenedores de zona de pruebas están habilitados o inhabilitados.

gcloud

  1. Usa el siguiente comando:

    gcloud run jobs executions describe EXECUTION_NAME --format yaml

    Reemplaza EXECUTION_NAME por el nombre de la ejecución del trabajo.

  2. Para verificar que los contenedores de zona de pruebas estén habilitados, busca el atributo sandboxLauncher: true en la configuración que se muestra.

Para ejecutar código no confiable en una zona de pruebas desde tu trabajo, consulta Ejecución de código en Cloud Run.

Configura plantillas de zona de pruebas

Las plantillas de zona de pruebas te permiten definir imágenes de contenedor para las zonas de pruebas. En lugar de ejecutar sesiones de zona de pruebas dentro del contenedor de la aplicación principal, los comandos sandbox do --template y sandbox run --template inician contenedores nuevos con las imágenes especificadas, como Python, Node.js o un entorno de ejecución personalizado. Estas zonas de pruebas se ejecutan en sus propios contenedores y comparten los límites de CPU y memoria del contenedor principal. No puedes establecer límites de CPU y memoria independientes para una plantilla. Cloud Run admite hasta 10 plantillas de zona de pruebas. Las activaciones de volumen deben hacer referencia a un volumen en memoria en tu recurso de Cloud Run. Las plantillas de zona de pruebas proporcionan las siguientes funciones:

  • Imágenes de contenedor dedicadas: Declara imágenes de contenedor distintas, como python:3.12-slim o busybox:latest, como plantillas de zona de pruebas. También puedes usar otros entornos de ejecución y herramientas para las zonas de pruebas que no se requieren en tu contenedor principal. Esto mantiene tu contenedor principal liviano, ya que aísla las herramientas y los entornos de ejecución que solo se usan para la zona de pruebas.

  • Creación de instancias on demand: La CLI de la zona de pruebas (/usr/local/gcp/bin/sandbox) genera contenedores de zona de pruebas nuevos a partir de una plantilla sin aprovisionar VMs nuevas ni facturar por instancias nuevas.

  • Uso compartido de archivos aislado por zona de pruebas: Comparte un volumen en la memoria entre tu contenedor principal y varias zonas de pruebas, y restringe cada zona de pruebas a su propio subdirectorio aislado para evitar que las zonas de pruebas vean o modifiquen otros archivos.

Puedes configurar plantillas de zona de pruebas con una configuración de YAML o la API de Cloud Run Admin:

YAML

  1. Si creas un trabajo nuevo, omite este paso. Si actualizas un trabajo existente, descarga su configuración de YAML:

    gcloud run jobs describe JOB --format export > job.yaml
  2. Actualiza el archivo YAML de tu trabajo para incluir la configuración de plantillas de 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
    

    Reemplaza lo siguiente:

    • JOB por el nombre del trabajo de Cloud Run.

    • IMAGE_URL: Es la URL de la imagen de contenedor que se usará para el contenedor principal.
    • TEMPLATE_NAME: el nombre de la plantilla.
    • TEMPLATE_IMAGE_URL: Es la URL de la imagen de contenedor que se usará para la plantilla de la zona de pruebas.
    • Opcional: VOLUME_NAME: Es el nombre del volumen que se activará.
    • Opcional: CONTAINER_MOUNT_PATH: Es la ruta de acceso en la que se activa el volumen dentro del contenedor principal.
    • Opcional: SANDBOX_MOUNT_PATH: Es la ruta de acceso en la que se activa el volumen dentro del contenedor de la zona de pruebas.
    • Opcional: SUBPATH: Es una ruta de acceso de subdirectorio relativa dentro del volumen que se activará en el contenedor de la zona de pruebas, como my-subdir. Para establecer un subdirectorio diferente para cada zona de pruebas en el entorno de ejecución, usa un marcador de posición $(VARIABLE_NAME), como $(SANDBOX_DIR):
      • VARIABLE_NAME solo puede contener letras ASCII y guiones bajos; no se admiten dígitos ni guiones.
      • Para resolver el marcador de posición en el entorno de ejecución, pasa la marca --template-var=VARIABLE_NAME=VALUE junto con --template.
      • subPath no crea directorios automáticamente. Crea el directorio SUBPATH resuelto en el volumen desde el contenedor principal, por ejemplo, con mkdir -p, antes de ejecutar sandbox do o sandbox run.
  3. Crea o actualiza el servicio con el siguiente comando:

    gcloud run jobs replace job.yaml

    El comando gcloud run jobs replace usa de forma predeterminada el archivo job.yaml si está presente.

API de REST

Para configurar plantillas de zona de pruebas, envía una solicitud PATCH a la API de 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"
          }
        }
      ]
    }
  }
}'

Reemplaza lo siguiente:

  • JOB por el nombre del trabajo de Cloud Run.

  • PROJECT_ID: Es el ID del proyecto de Google Cloud .
  • REGION: Es la región en la que se implementa tu recurso de Cloud Run.
  • IMAGE_URL: Es la URL de la imagen de contenedor que se usará para el contenedor principal.
  • TEMPLATE_NAME: el nombre de la plantilla.
  • TEMPLATE_IMAGE_URL: Es la URL de la imagen de contenedor que se usará para la plantilla de la zona de pruebas.
  • Opcional: VOLUME_NAME: Es el nombre del volumen que se activará.
  • Opcional: CONTAINER_MOUNT_PATH: Es la ruta de acceso en la que se activa el volumen dentro del contenedor principal.
  • Opcional: SANDBOX_MOUNT_PATH: Es la ruta de acceso en la que se activa el volumen dentro del contenedor de la zona de pruebas.
  • Opcional: SUBPATH: Es una ruta de acceso de subdirectorio relativa dentro del volumen que se activará en el contenedor de la zona de pruebas, como my-subdir. Para establecer un subdirectorio diferente para cada zona de pruebas en el entorno de ejecución, usa un marcador de posición $(VARIABLE_NAME), como $(SANDBOX_DIR):
    • VARIABLE_NAME solo puede contener letras ASCII y guiones bajos; no se admiten dígitos ni guiones.
    • Para resolver el marcador de posición en el entorno de ejecución, pasa la marca --template-var=VARIABLE_NAME=VALUE junto con --template.
    • subPath no crea directorios automáticamente. Crea el directorio SUBPATH resuelto en el volumen desde el contenedor principal, por ejemplo, con mkdir -p, antes de ejecutar sandbox do o sandbox run.

Para ejecutar plantillas con la CLI desde el contenedor de trabajos, consulta Ejecuta comandos con plantillas de zona de pruebas.