Configura zonas de pruebas para los servicios

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

  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. Instala e inicializa gcloud CLI.
  4. 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:

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

  1. 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
  2. Actualiza tu archivo YAML para incluir el atributo sandboxLauncher establecido en true dentro 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: 8080
    

    Reemplaza 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 de LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
  3. Crea o actualiza el servicio con el siguiente comando:

    gcloud run services replace service.yaml

    El comando gcloud run services replace usa de forma predeterminada el archivo service.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_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 de LOCATION-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

  1. 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
  2. Actualiza tu archivo YAML para quitar el atributo sandboxLauncher dentro 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: 8080
    

    Reemplaza 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 de LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
  3. Crea o actualiza el servicio con el siguiente comando:

    gcloud run services replace service.yaml

    El comando gcloud run services replace usa de forma predeterminada el archivo service.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 servicio de Cloud Run, sigue estos pasos:

Console

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

    Ir a Cloud Run

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

  3. Haz clic en la pestaña Historial de revisión.

  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 beta run services describe SERVICE

    SERVICE por el nombre del servicio

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

    Reemplaza 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=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 services replace service.yaml

    El comando gcloud run services replace usa de forma predeterminada el archivo service.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/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=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 servicios, consulta Ejecuta comandos con plantillas de zona de pruebas.