Las zonas de pruebas de Cloud Run proporcionan un entorno rápido, seguro y aislado para ejecutar código no confiable o herramientas, como agentes de IA, dentro de tu servicio existente en el entorno de segunda generación. Las zonas de pruebas están muy optimizadas para la latencia y se ejecutan dentro de la misma instancia que tu contenedor, compartiendo 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
-
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.
- Implementa un servicio de Cloud Run en el entorno de ejecución de segunda generación.
Roles obligatorios
Para obtener los permisos que necesitas para configurar y, luego, implementar los servicios 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 servicio de Cloud Run - Usuario de la cuenta de servicio (
roles/iam.serviceAccountUser) en la identidad del servicio
Si implementas un servicio o una función desde el código fuente, también debes tener roles adicionales otorgados en tu proyecto y en la cuenta de servicio de Cloud Build.
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 servicio 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
Cualquier cambio en la configuración conlleva la creación de una revisión nueva. Las revisiones posteriores también adoptarán esta configuración de manera automática, a menos que realices actualizaciones explícitas para cambiarla.
Cuando habilitas las zonas de pruebas, tu servicio de Cloud Run se implementa en el entorno de ejecución de segunda generación. Para habilitar las zonas de pruebas en los servicios de Cloud Run, usa Google Cloud CLI, una configuración de YAML o Terraform:
gcloud
Para implementar o actualizar el servicio, especifica la marca --sandbox-launcher:
Para implementar un servicio nuevo, ejecuta el siguiente comando:
gcloud beta run deploy SERVICE --image IMAGE_URL --sandbox-launcher
Reemplaza lo siguiente:
- SERVICE: el nombre de tu servicio de Cloud Run.
IMAGE_URL: una referencia a la imagen de contenedor, por ejemplo,us-docker.pkg.dev/cloudrun/container/hello:latest. Si usas Artifact Registry, el repositorio REPO_NAME debe estar creado. La URL sigue el formato deLOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
Para actualizar un servicio existente, ejecuta el siguiente comando:
gcloud beta run services update SERVICE --sandbox-launcher
YAML
Si creas un servicio nuevo, omite este paso. Si actualizas un servicio existente, descarga su configuración de YAML:
gcloud run services describe SERVICE --format export > service.yaml
Actualiza tu archivo YAML para incluir el atributo
sandboxLauncherestablecido entruedentro de la configuración del contenedor: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: 8080Reemplaza lo siguiente:
- SERVICE: el nombre de tu servicio de Cloud Run.
- CONTAINER: Es el nombre de tu contenedor.
IMAGE_URL: una referencia a la imagen de contenedor, por ejemplo,us-docker.pkg.dev/cloudrun/container/hello:latest. Si usas Artifact Registry, el repositorio REPO_NAME debe estar creado. La URL sigue el formato deLOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
Crea o actualiza el servicio con el siguiente comando:
gcloud run services replace service.yaml
El comando
gcloud run services replaceusa de forma predeterminada el archivoservice.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_service
en tu configuración de Terraform:resource "google_cloud_run_v2_service" "default" {
name = "SERVICE"
location = "REGION"
template {
containers {
image = "IMAGE_URL"
sandbox_launcher = true
ports {
container_port = 8080
}
}
}
}
Reemplaza lo siguiente:
- SERVICE: el nombre de tu servicio de Cloud Run.
- REGION: La Google Cloud región Por ejemplo,
europe-west1. IMAGE_URL: una referencia a la imagen de contenedor, por ejemplo,us-docker.pkg.dev/cloudrun/container/hello:latest. Si usas Artifact Registry, el repositorio REPO_NAME debe estar creado. La URL sigue el formato deLOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
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 servicio, usa Google Cloud CLI o una configuración de YAML:
gcloud
Actualiza el servicio con la marca --no-sandbox-launcher ejecutando el siguiente comando:
gcloud beta run services update SERVICE --no-sandbox-launcher
SERVICE por el nombre del servicio
YAML
Si creas un servicio nuevo, omite este paso. Si actualizas un servicio existente, descarga su configuración de YAML:
gcloud run services describe SERVICE --format export > service.yaml
Actualiza tu archivo YAML para quitar el atributo
sandboxLauncherdentro de la configuración del contenedor:apiVersion: serving.knative.dev/v1 kind: Service metadata: name: SERVICE spec: template: spec: containers: - name: CONTAINER image: IMAGE_URL port: 8080Reemplaza lo siguiente:
- SERVICE: el nombre de tu servicio de Cloud Run.
- CONTAINER: Es el nombre de tu contenedor.
IMAGE_URL: una referencia a la imagen de contenedor, por ejemplo,us-docker.pkg.dev/cloudrun/container/hello:latest. Si usas Artifact Registry, el repositorio REPO_NAME debe estar creado. La URL sigue el formato deLOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
Crea o actualiza el servicio con el siguiente comando:
gcloud run services replace service.yaml
El comando
gcloud run services replaceusa de forma predeterminada el archivoservice.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 servicio de Cloud Run, sigue estos pasos:
Console
En la consola de Google Cloud , ve a la página Servicios de Cloud Run:
Haz clic en el servicio para abrir la página Detalles del servicio.
Haz clic en la pestaña Historial de revisión.
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 beta run services describe SERVICE
SERVICE por el nombre del servicio
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 servicio, 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 servicio nuevo, omite este paso. Si actualizas un servicio existente, descarga su configuración de YAML:
gcloud run services describe SERVICE --format export > service.yaml
Actualiza el archivo YAML de tu servicio para incluir la configuración de plantillas de
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: SUBPATHReemplaza lo siguiente:
- SERVICE: el nombre de tu servicio 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 services replace service.yaml
El comando
gcloud run services replaceusa de forma predeterminada el archivoservice.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/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" } } ] } }'
Reemplaza lo siguiente:
- SERVICE: el nombre de tu servicio 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 servicios, consulta Ejecuta comandos con plantillas de zona de pruebas.