Ejecución de código en Cloud Run

Versión preliminar : Entornos de pruebas de Cloud Run

Esta función está sujeta a las "Condiciones de la oferta previa a la DG" en la sección Condiciones Generales del Servicio de las Condiciones Específicas del Servicio. Las funciones de la fase previa a la DG están disponibles “sin modificaciones” y pueden tener asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

Las zonas de pruebas de Cloud Run te permiten ejecutar código que no es de confianza en un entorno aislado directamente dentro de las cargas de trabajo de contenedores. Esta capacidad ayuda a los agentes de IA a ejecutar de forma segura subagentes, realizar tareas de procesamiento o iniciar navegadores automatizados sin poner en riesgo el sistema host.

Ventajas principales

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 entornos 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 superior, las variables de entorno, los secretos ni el servidor de metadatos de Google Cloud . Todas las zonas de pruebas están completamente aisladas unas de otras.

• Control de acceso y entorno: Los procesos se ejecutan con sudo privilegios como un usuario que no es usuario 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. 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.
   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

2. Verify that billing is enabled for your Google Cloud project.

3. Instala e inicializa gcloud CLI.
4. Implementa un recurso de Cloud Run, como un servicio, un trabajo, un grupo de trabajadores o una instancia de segunda generación .

Habilita las zonas de pruebas

Para usar las zonas de pruebas, primero debes habilitarlas en tu recurso de Cloud Run con la marca --sandbox-launcher o el atributo YAML sandboxLauncher. Para conocer los pasos de configuración detallados, elige uno de los siguientes tipos de recursos:

• Servicios
• Trabajos
• Grupos de trabajadores
• Instancias (versión preliminar)

Iniciar zonas de pruebas

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

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.

Puedes ejecutar el objeto binario haciendo referencia a su ruta de acceso absoluta en tu 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 la zona de pruebas desde una aplicación de Node.js, incluye el siguiente código:

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

Python

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

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

Go

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

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

CLI de la zona de pruebas

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

sandbox do -- /bin/echo "Hello"

Para ver la lista completa de comandos disponibles, ejecuta el comando sandbox -h.

Usa las funciones 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 sandboxes.

Ejecuta un comando en tu zona de pruebas

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

1. Activa un entorno de zona de pruebas (sandbox run).
2. Ejecuta el comando que especifiques (sandbox exec).
3. Borra la zona de pruebas después de que se ejecuta correctamente (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 el lenguaje que prefieras. Asegúrate de que cualquier comando o herramienta que ejecutes, como python3, esté instalado en tu imagen de contenedor:

Node.js

Para ejecutar el comando de la 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 la 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 la zona de pruebas

Para ejecutar el comando de la 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 de acceso absoluta, como python3 en lugar de /usr/bin/python3, configura de forma explícita la variable de entorno PATH en la zona de pruebas con la marca --env.

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 almacenamiento tar estándar. Como alternativa, puedes configurar activaciones de vinculación para compartir directorios directamente entre el contenedor del 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 tar cuando se completa.
• --import-tar: Extrae archivos de un archivo tar en la zona de pruebas antes de la ejecución.
• --sync-tar: Realiza una sincronización bidireccional importando antes de la ejecución y exportando después de que se complete.

El directorio /tmp dentro de la zona de pruebas no forma parte de la superposición del sistema de archivos raíz, por lo que los archivos de almacenamiento no incluyen los archivos escritos en /tmp. Para conservar los datos, escríbelos en un directorio diferente, como /workspace.

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

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

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

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

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

Como alternativa, para importar automáticamente el estado de 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 de forma continua las solicitudes entrantes, usa la marca --detach.

Por ejemplo, ejecuta el siguiente comando para iniciar una zona de pruebas desconectada 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 la misma zona de pruebas en varias pruebas. Para interactuar con una zona de pruebas desconectada en ejecución o ejecutar comandos adicionales dentro de ella, usa el comando sandbox exec y orienta tu zona de pruebas por su nombre.

Por ejemplo, para ejecutar un comando de prueba dentro de la zona de pruebas en segundo plano de 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 las zonas de pruebas como lo harías con cualquier otro contenedor. Las zonas de pruebas no heredan las 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 una zona 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 podrían ser visibles para los procesos de la zona de pruebas.

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, ejecutar comandos en la zona de pruebas de forma dinámica y capturar su estado de sistema de archivos modificado en un archivo tar.

Sugerencia: Si ejecutas muchos comandos de forma repetida en una sola zona de pruebas, considera iniciar una zona de pruebas una vez, con un punto de entrada inactivo, como sleep 12m, y, luego, ejecutar el comando sandbox exec que se orienta a esta zona de pruebas para una ejecución de comandos muy rápida.

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

1. Implementa una zona de pruebas con nombre en segundo plano con el acceso de escritura habilitado, lo que crea un archivo dentro de su espacio de trabajo. Escribe el archivo en una ruta de acceso fuera de /tmp, ya que los archivos escritos en /tmp dentro de la zona de pruebas no se capturan en las instantáneas:

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

2. Crea una instantánea del sistema de archivos modificado de la zona de pruebas 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 de la zona de pruebas:

   tar -xvf /tmp/foo.tar
   

   Debería ver los siguientes resultados:

   ./
   ./workspace/
   ./workspace/hello.txt
   

Configura las redes

De forma predeterminada, se bloquea todo el tráfico saliente de la zona 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.

Accede 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 del host. Puedes usar la marca --write para habilitar la escritura en una superposición de sistema de archivos temporal (tmpfs). Sin embargo, las escrituras se perderán cuando se borre la zona de pruebas. Para habilitar la escritura persistente en el contenedor del host, puedes configurar activaciones de vinculación.

Siempre se puede escribir en el directorio /tmp dentro de la zona de pruebas, incluso sin la marca --write. El directorio /tmp se borra cuando se borra la zona de pruebas y no se incluye en las instantáneas ni en los archivos de almacenamiento.

Acceso de solo lectura predeterminado

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

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

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

1. Crea una secuencia de comandos de Python en el contenedor de 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 la 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 una configuración adicional, la ejecución fallará. Por ejemplo, si intentas escribir en el directorio raíz (/) dentro de la zona de pruebas predeterminada, se muestra 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' > /testfile.txt"
   

   El comando falla con el siguiente error:

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

Cómo compartir datos con activaciones de vinculación

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 activación de vinculació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 la zona de pruebas para volver a escribir datos nuevos en el host desde la activación:

   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 del host que la zona de pruebas haya modificado correctamente el archivo:

   cat /tmp/my-volume/readwrite.txt
   

   Este comando devuelve write.

Configura activaciones de solo lectura

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

Por ejemplo, ejecuta el siguiente comando para probar las restricciones de escritura en una activación de 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 de la 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?

• Obtén más información para alojar agentes de IA en Cloud Run.
• Explora la automatización de navegadores y SO en Cloud Run.
• Revisa el contrato del entorno de ejecución de contenedores.