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
- 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.
-
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 theresourcemanager.projects.createpermission. Learn how to grant roles.
-
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 theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
- Instala e inicializa gcloud CLI.
- 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:
- Desarrollador de Cloud Run (
roles/run.developer) en el trabajo de Cloud Run - Usuario de la cuenta de servicio (
roles/iam.serviceAccountUser) en la identidad del servicio
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
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
Actualiza tu archivo YAML para incluir el atributo
sandboxLauncherestablecido entruedentro 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: trueReemplaza 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.
Crea o actualiza el servicio con el siguiente comando:
gcloud run jobs replace job.yaml
El comando
gcloud run jobs replaceusa de forma predeterminada el archivojob.yamlsi 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 recursogoogle_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
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
Actualiza tu archivo YAML para quitar el atributo
sandboxLauncherdentro 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_URLReemplaza 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.
Crea o actualiza el servicio con el siguiente comando:
gcloud run jobs replace job.yaml
El comando
gcloud run jobs replaceusa de forma predeterminada el archivojob.yamlsi 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
En la consola de Google Cloud , ve a la página Trabajos de Cloud Run:
Haz clic en el trabajo para abrir la página Detalles del trabajo.
En la pestaña Historial, haz clic en el ID del trabajo ejecutado de la lista.
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
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.
Para verificar que los contenedores de zona de pruebas estén habilitados, busca el atributo
sandboxLauncher: trueen 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-slimobusybox: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
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
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: SUBPATHReemplaza 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=VALUEjunto con--template. subPathno crea directorios automáticamente. Crea el directorio SUBPATH resuelto en el volumen desde el contenedor principal, por ejemplo, conmkdir -p, antes de ejecutarsandbox doosandbox run.
Crea o actualiza el servicio con el siguiente comando:
gcloud run jobs replace job.yaml
El comando
gcloud run jobs replaceusa de forma predeterminada el archivojob.yamlsi 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=VALUEjunto con--template. subPathno crea directorios automáticamente. Crea el directorio SUBPATH resuelto en el volumen desde el contenedor principal, por ejemplo, conmkdir -p, antes de ejecutarsandbox doosandbox run.
Para ejecutar plantillas con la CLI desde el contenedor de trabajos, consulta Ejecuta comandos con plantillas de zona de pruebas.