Ejecución de código en Cloud Run

Vista previa : Zonas 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.

Cloud Run ya está en zona 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, 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 al instante. 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 nuevo recurso de Cloud Run 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 Google Cloud servidor de metadatos. Todas las zonas de pruebas están completamente aisladas entre sí.

• Control de acceso y entorno: Los procesos se ejecutan con sudo privilegios como un 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 o instantáneas persistentes para guardar espacios de trabajo específicos o asignar datos a un bucket de Cloud Storage.

Antes de comenzar

Accede a tu Google Cloud cuenta de. 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 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

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

Verify that billing is enabled for your Google Cloud project.

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

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 sandboxLauncher de YAML. Para obtener pasos de configuración detallados, elige entre los siguientes tipos de recursos:

• Servicios
• Trabajos
• Grupos de trabajadores
• Instancias (vista previa)

Inicia 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 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 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(`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(
    ["sandbox", "do", "--", "/bin/echo", "Hello"],
    capture_output=True,
    text=True,
)
return {"stdout": result.stdout, "stderr": result.stderr}

Ir

Para ejecutar el comando de 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 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 sandbox -h comando.

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

La herramienta de línea de comandos 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. Activa un entorno de zona de pruebas (sandbox run).
2. Ejecuta el comando que especificas (sandbox exec).
3. Borra la zona 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 tu contenedor:

Node.js

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

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:

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}

Ir

Para ejecutar el comando de zona de pruebas desde una aplicación de Go:

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 zona de pruebas directamente desde la línea de comandos:

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 explícitamente la variable de entorno PATH en la zona de pruebas con la marca --env.

Conserva datos en diferentes ejecuciones

Las zonas de pruebas son efímeras de forma predeterminada. Para conservar 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 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 tar cuando se completa.
• --import-tar: Extrae archivos de un archivo tar a la zona de pruebas antes de la ejecución.
• --sync-tar: Realiza una sincronización bidireccional importando antes de la ejecución y exportando cuando se completa.

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 /tmp/work && echo 'task-complete' > /tmp/work/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 /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 encabezado 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 la misma zona 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 orienta 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 las variables de entorno en las zonas de pruebas como lo harías con cualquier otro contenedor. Las zonas de pruebas no heredan variables de entorno del contenedor host. Debes proporcionarlas 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 ejecució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 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 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:

   ./
   ./tmp/
   ./tmp/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 muestra el código de estado HTTP estándar 200, lo 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 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 la zona de pruebas. Para habilitar la escritura persistente en el contenedor host, puedes configurar activaciones de vinculación.

Acceso de solo lectura predeterminado

Dentro de la zona de pruebas, los procesos pueden leer archivos del contenedor host y 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 de solo lectura predeterminado, 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 muestra 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 falla. Por ejemplo, si intentas escribir en /tmp dentro de la zona de pruebas predeterminada, se muestra un error del 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
   

Comparte datos con activaciones de vinculación

Para permitir que los procesos dentro de la zona de pruebas escriban datos persistentes, conecta 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 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 muestra 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 host que la zona de pruebas haya modificado el archivo correctamente:

   cat /tmp/my-volume/readwrite.txt
   

   Este comando muestra write.

Configura activaciones de solo lectura

Para otorgar acceso a la zona de pruebas a un directorio host y, al mismo tiempo, evitar explícitamente 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 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 zona de pruebas directamente en las transmisiones estándar del proceso de invocación. Para ver estos registros en Cloud Logging, enruta las transmisiones 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 del navegador y del SO en Cloud Run.
• Revisa el contrato de entorno de ejecución de contenedores.