Ejecución de código en Cloud Run

Cloud Run ya está en un entorno de pruebas y aislado, lo que lo hace ideal para alojar agentes de IA. Cuando habilitas las zonas de pruebas de Cloud Run, la herramienta de línea de comandos sandbox estará disponible en tu contenedor. Usa esta herramienta de línea de comandos para ejecutar código no confiable escrito en cualquier lenguaje, en un entorno de zona de pruebas altamente optimizado y aislado del resto de tu contenedor.

Los agentes de IA pueden aprovechar las zonas de pruebas para ejecutar de forma segura subagentes, realizar tareas computacionales o abrir navegadores en un entorno rápido y aislado sin poner en riesgo el sistema host.

Las zonas de pruebas de Cloud Run proporcionan las siguientes ventajas clave:

  • Creación rápida: Las zonas de pruebas son interactivas y están listas para ejecutar comandos casi de inmediato. Si creas zonas de pruebas dentro de un recurso de Cloud Run existente en el que se ejecuta tu agente, reduces los tiempos de creación en comparación con la creación de un recurso de Cloud Run nuevo para cada tarea. Esta eficiencia ayuda a garantizar que tu agente siga respondiendo.

  • Seguridad: Las zonas de pruebas aíslan la ejecución de procesos. De forma predeterminada, las zonas de pruebas no tienen acceso a la carga de trabajo principal, las variables de entorno, los secretos ni el servidor de metadatos Google Cloud . Todas las zonas de pruebas están completamente aisladas entre sí.

  • Control de acceso y entorno: Los procesos se ejecutan con privilegios de sudo como usuario no raíz, lo que te permite instalar herramientas con administradores de paquetes como apt, pip o npm durante la ejecución. Si bien el entorno de zona de pruebas es efímero y se borra cuando se completa, puedes usar directorios persistentes o instantáneas para guardar espacios de trabajo específicos o asignar datos a un bucket de Cloud Storage.

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 la CLI de gcloud
  7. Implementa un servicio de Cloud Run en el entorno de ejecución de segunda generación.

Habilita las zonas de pruebas

Cuando habilitas los entornos 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 o una configuración en YAML:

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 del 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 el archivo YAML de tu servicio 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: El nombre de tu contenedor
    • IMAGE_URL: Una referencia a la imagen del 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.

Las zonas de pruebas comparten la CPU y la memoria asignadas al contenedor host. Asegúrate de que los límites del contenedor principal para la CPU y la memoria sean suficientes para admitir tu aplicación y los sandbox activos que ejecutes al mismo tiempo.

Inhabilita 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 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 el archivo YAML de tu servicio 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: El nombre de tu contenedor
    • IMAGE_URL: Una referencia a la imagen del 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.

Cómo iniciar zonas de pruebas

Una vez que habilites las zonas de pruebas, podrás iniciarlas desde tu entorno de ejecución de contenedores. El objeto binario de zona de pruebas se encuentra en /usr/local/gcp/bin/sandbox.

Puedes ejecutar el archivo binario haciendo referencia a su ruta de acceso absoluta en el código fuente. Por ejemplo, para imprimir Hello dentro de tu zona de pruebas aislada, elige una de las siguientes opciones:

Node.js

Para ejecutar el comando de zona de pruebas desde una aplicación de Node.js, incluye el siguiente código:

exec(`/usr/local/gcp/bin/sandbox do -- /bin/echo "Hello"`, (e, stdout, stderr) => {
    res.send({ stdout, stderr });
});

Python

Para ejecutar el comando de zona de pruebas desde una aplicación de Python, incluye el siguiente código:

import subprocess
result = subprocess.run(
    ["/usr/local/gcp/bin/sandbox", "do", "--", "/bin/echo", "Hello"],
    capture_output=True,
    text=True,
)
return {"stdout": result.stdout, "stderr": result.stderr}

Go

Para ejecutar el comando de zona de pruebas desde una aplicación de Go, incluye el siguiente código:

cmd := exec.Command("/usr/local/gcp/bin/sandbox", "do", "--", "/bin/echo", "Hello")
out, err := cmd.CombinedOutput()

CLI de Sandbox

Para ejecutar el comando de zona de pruebas directamente desde la línea de comandos, ejecuta el siguiente comando:

/usr/local/gcp/bin/sandbox do -- /bin/echo "Hello"

En los ejemplos de esta guía, se usa el comando sandbox en lugar de su ruta de acceso absoluta /usr/local/gcp/bin/sandbox.

Para ver la lista completa de comandos disponibles, ejecuta el comando /usr/local/gcp/bin/sandbox -h.

Usa las capacidades de la línea de comandos de la zona de pruebas

La herramienta de línea de comandos de sandbox contiene comandos para ejecutar, configurar y administrar zonas de pruebas.

Ejecuta un comando en tu zona de pruebas

Puedes ejecutar una instrucción en una zona de pruebas efímera nueva con el comando sandbox do. El comando sandbox do realiza las siguientes tareas:

  1. Inicia un entorno de zona de pruebas (sandbox run).
  2. Ejecuta el comando que especificas (sandbox exec).
  3. Borra el entorno de pruebas después de la ejecución correcta (sandbox delete).

Por ejemplo, para realizar un cálculo matemático dentro de la zona de pruebas, ejecuta los siguientes fragmentos de código para tu lenguaje preferido. Asegúrate de que cualquier comando o herramienta que ejecutes, como python3, esté instalado en la imagen de contenedor:

Node.js

Para ejecutar el comando de zona de pruebas desde una aplicación de Node.js, haz lo siguiente:

exec(`sandbox do -- /usr/bin/python3 -c "print(1+2)"`, (e, stdout, stderr) => {
    res.send({ stdout, stderr });
});

Python

Para ejecutar el comando de zona de pruebas desde una aplicación de Python, haz lo siguiente:

import subprocess
result = subprocess.run(
    ["sandbox", "do", "--", "/usr/bin/python3", "-c", "print(1+2)"],
    capture_output=True,
    text=True,
)
return {"stdout": result.stdout, "stderr": result.stderr}

Go

Para ejecutar el comando de zona de pruebas desde una aplicación de Go, haz lo siguiente:

cmd := exec.Command("sandbox", "do", "--", "/usr/bin/python3", "-c", "print(1+2)")
out, err := cmd.CombinedOutput()

CLI de Sandbox

Para ejecutar el comando de zona de pruebas directamente desde la línea de comandos, haz lo siguiente:

sandbox do -- /usr/bin/python3 -c "print(1+2)"

Si ejecutas un comando por nombre sin su ruta absoluta, como python3 en lugar de /usr/bin/python3, configura de forma explícita la variable de entorno PATH en el entorno de pruebas con la marca --env.

Cómo conservar datos en diferentes ejecuciones

Los entornos de pruebas son efímeros de forma predeterminada. Para conservar los datos en diferentes ejecuciones de la zona de pruebas dentro de la misma instancia de Cloud Run, puedes importar y exportar el estado del sistema de archivos del espacio de trabajo con archivos de archivo tar estándar. Como alternativa, puedes configurar activaciones de vinculación para compartir directorios directamente entre el contenedor host y los entornos de zona de pruebas.

Usa las siguientes marcas cuando ejecutes el comando sandbox do:

  • --export-tar: Captura los archivos de superposición modificados en un archivo de almacenamiento tar cuando se completa la operación.
  • --import-tar: Extrae archivos de un archivo tar en el sandbox antes de la ejecución.
  • --sync-tar: Realiza una sincronización bidireccional importando antes de la ejecución y exportando al finalizar.

Por ejemplo, para pasar datos entre dos llamadas de zona de pruebas con archivos, ejecuta los siguientes comandos:

  1. Escribe datos dentro de un entorno de pruebas y exporta el estado a un archivo:

    sandbox do --write --export-tar=/tmp/work.tar \
  -- /usr/bin/bash -c "mkdir -p /tmp/work && echo 'task-complete' > /tmp/work/status.txt"

  2. Importa el archivo de archivo en una llamada posterior para recuperar los datos:

    sandbox do --write --import-tar=/tmp/work.tar \
  -- /usr/bin/bash -c "cat /tmp/work/status.txt"

Como alternativa, para importar automáticamente el estado del archivo existente y exportar los cambios nuevos en un solo comando, usa --sync-tar=/tmp/work.tar. Cuando finaliza un proceso de zona de pruebas, Cloud Run borra de forma permanente los archivos de superposición efímeros que no se exportaron a un archivo.

Ejecuta un comando en segundo plano

Para ejecutar procesos de larga duración, navegadores sin interfaz gráfica o servidores en segundo plano, como un bucle de agente en segundo plano que escucha continuamente las solicitudes entrantes, usa la marca --detach.

Por ejemplo, ejecuta el siguiente comando para iniciar una zona de pruebas separada con un programa inactivo o en segundo plano:

sandbox run my-web-server --detach -- /usr/bin/long_running_or_idle_program

Puedes usar la marca detach para volver a usar el mismo entorno de pruebas para varias pruebas. Para interactuar con una zona de pruebas separada en ejecución o ejecutar comandos adicionales dentro de ella, usa el comando sandbox exec y apunta a tu zona de pruebas por su nombre.

Por ejemplo, para ejecutar un comando de prueba dentro de tu zona de pruebas en segundo plano my-web-server existente, ejecuta el siguiente comando:

sandbox exec my-web-server -- /usr/bin/python3 -c "print('test-complete')"

Configure las variables de entorno

Configura variables de entorno en los entornos de pruebas como lo harías con cualquier otro contenedor. Los entornos de pruebas no heredan variables de entorno del contenedor host. Debes proporcionarlos de forma explícita con la marca --env cuando ejecutes el comando sandbox.

Por ejemplo, para pasar una variable de configuración a un entorno de pruebas, ejecuta el siguiente comando:

sandbox do --env AGENT_MODE="test" -- /usr/bin/bash -c "echo \$AGENT_MODE"

Evita pasar secretos con la marca env, ya que los procesos de la zona de pruebas podrían verlos.

Crea instantáneas del sistema de archivos

Implementa una zona de pruebas con nombre en segundo plano para controlar tareas continuas, como servidores web o flujos de trabajo de agentes de larga duración, ejecuta comandos en la zona de pruebas de forma dinámica y captura el estado modificado del sistema de archivos en un archivo de tar.

Por ejemplo, para implementar un sandbox en segundo plano, escribir un archivo en su superposición y tomar una instantánea de su estado para verificar que se capturaron los datos, ejecuta los siguientes comandos:

  1. Implementa una zona de pruebas con nombre en segundo plano con acceso de escritura habilitado y crea un archivo dentro de su espacio de trabajo:

    sandbox run --write my-sandbox --detach -- /usr/bin/bash -c "echo 'hi' > /tmp/hello.txt && sleep 1h"

  2. Crea una instantánea del sistema de archivos modificado del espacio aislado en ejecución con el comando sandbox tar:

    sandbox tar my-sandbox --file=/tmp/foo.tar

  3. Extrae y verifica que el archivo de instantánea contenga los datos escritos dentro del sandbox:

    tar -xvf /tmp/foo.tar

    Debería ver los siguientes resultados:

    ./
./tmp/
./tmp/hello.txt

Configura las redes

De forma predeterminada, se bloquea todo el tráfico saliente del entorno de pruebas. Para permitir el acceso a la red saliente, usa la marca --allow-egress:

Por ejemplo, para recuperar datos de un extremo externo, ejecuta el siguiente comando:

sandbox do --allow-egress -- /usr/bin/python3 -c 'import urllib.request; print(urllib.request.urlopen("https://google.com").getcode())'

Este comando devuelve el código de estado HTTP estándar 200, que indica que la conexión se realizó correctamente.

Acceder al sistema de archivos

De forma predeterminada, los procesos que ejecutas dentro de la zona de pruebas tienen acceso de solo lectura al sistema de archivos raíz del contenedor host. Puedes usar la marca --write para habilitar la escritura en una superposición del sistema de archivos temporal (tmpfs). Sin embargo, las escrituras se perderán cuando se borre el sandbox. Para habilitar la escritura persistente en el contenedor host, puedes configurar vinculaciones de montaje.

Acceso predeterminado de solo lectura

Dentro de la zona de pruebas, los procesos pueden leer archivos del contenedor host, pero no pueden escribir en el sistema de archivos raíz.

En los siguientes ejemplos, se supone que ejecutas comandos desde el directorio raíz (/) de tu contenedor host.

Para verificar el acceso predeterminado de solo lectura, ejecuta los siguientes comandos:

  1. Crea una secuencia de comandos de Python en el contenedor host:

    mkdir -p /tmp/my-scripts
echo "print('hi')" > /tmp/my-scripts/task.py

  2. Verifica que el archivo exista de forma local:

    cat /tmp/my-scripts/task.py

  3. Ejecuta el archivo dentro de tu zona de pruebas:

    sandbox do -- /usr/bin/python3 /tmp/my-scripts/task.py

    Este comando devuelve hi, lo que confirma que la zona de pruebas tiene acceso de lectura.

    Si intentas escribir datos directamente en el sistema de archivos raíz de la zona de pruebas sin configuración adicional, la ejecución fallará. Por ejemplo, si intentas escribir en /tmp dentro de la zona de pruebas predeterminada, se mostrará un error de sistema de archivos de solo lectura:

    Ejecuta el siguiente comando para escribir en el sistema de archivos raíz:

    sandbox do -- /usr/bin/bash -c "echo 'hi' > /tmp/testfile.txt"

    El comando falla con el siguiente error:

    /usr/bin/bash: line 1: /tmp/testfile.txt: Read-only file system
Error: failed to exec in container: cmd.Wait(exec) failed: exit status 1

Cómo compartir datos con vinculaciones de montaje

Para permitir que los procesos dentro de la zona de pruebas escriban datos persistentes, adjunta un volumen compartido con la marca --mount:

  1. Crea un directorio de volumen compartido en el contenedor host y propágalo con un archivo inicial:

    mkdir -p /tmp/my-volume
echo 'read' > /tmp/my-volume/readwrite.txt

  2. Ejecuta la zona de pruebas para leer el archivo desde la ruta de acceso de la vinculación de la unión:

    sandbox do --mount type=bind,source=/tmp/my-volume,destination=/mnt/my-mount -- /usr/bin/bash -c "cat /mnt/my-mount/readwrite.txt"

    Este comando devuelve read.

  3. Ejecuta el entorno de pruebas para escribir datos nuevos en el host desde el interior del punto de montaje:

    sandbox do --mount type=bind,source=/tmp/my-volume,destination=/mnt/my-mount -- /usr/bin/bash -c "echo 'write' > /mnt/my-mount/readwrite.txt"

  4. Verifica en el contenedor host que el sandbox haya modificado correctamente el archivo:

    cat /tmp/my-volume/readwrite.txt

    Este comando devuelve write.

Configura activaciones de solo lectura

Para otorgar acceso a la zona de pruebas a un directorio del host y, al mismo tiempo, evitar explícitamente que modifique archivos, agrega el atributo readonly a la especificación de la unión.

Por ejemplo, ejecuta el siguiente comando para probar las restricciones de escritura en una vinculación de solo lectura:

sandbox do --mount type=bind,source=/tmp/my-volume,destination=/mnt/my-mount,readonly -- /usr/bin/bash -c "echo 'fails' > /mnt/my-mount/hello.txt"

El intento de escritura falla con el siguiente error:

/usr/bin/bash: line 1: /mnt/my-mount/hello.txt: Read-only file system
Error: failed to exec in container: cmd.Wait(exec) failed: exit status 1

Ver registros

Cloud Run captura automáticamente los eventos del ciclo de vida de la zona de pruebas, como los inicios y las salidas de la ejecución, en Cloud Logging.

La CLI de sandbox escribe la salida estándar (stdout) y el error estándar (stderr) de los comandos en zona de pruebas directamente en los flujos estándar del proceso de invocación. Para ver estos registros en Cloud Logging, enruta los flujos a la salida estándar y al error estándar de tu contenedor:

Node.js 

const { exec } = require('child_process');
const child = exec('sandbox do -- /usr/bin/python3 -c "print(1+2)"');
child.stdout.pipe(process.stdout);
child.stderr.pipe(process.stderr);

Python 

subprocess.run(
    ["sandbox", "do", "--", "/usr/bin/python3", "-c", "print(1+2)"],
    stdout=sys.stdout,
    stderr=sys.stderr,
)

Go 

cmd := exec.Command("sandbox", "do", "--", "/usr/bin/python3", "-c", "print(1+2)")
cmd.Stdout = os.Stdout
cmd.Stderr = os.Stderr
cmd.Run()

¿Qué sigue?