Aísla la ejecución de código de IA con Agent Sandbox

En este documento, se proporcionan instrucciones para implementar un entorno de desarrollo y usar el cliente de Python de Agent Sandbox en un clúster de Google Kubernetes Engine (GKE).

Para obtener una descripción general de cómo la función Agent Sandbox aísla el código no confiable generado por IA, consulta Acerca de GKE Agent Sandbox.

Costos

Agent Sandbox se ofrece sin cargo adicional en GKE. Los precios de GKE se aplican a los recursos que creas.

Antes de comenzar

  1. En la consola de Google Cloud , en la página del selector de proyectos, selecciona o crea un proyecto de Google Cloud .

    Roles necesarios para seleccionar o crear un proyecto

    • Selecciona un proyecto: Para seleccionar un proyecto, no se requiere un rol de IAM específico. Puedes seleccionar cualquier proyecto en el que se te haya otorgado un rol.
    • Crear un proyecto: Para crear un proyecto, necesitas el rol de Creador de proyectos (roles/resourcemanager.projectCreator), que contiene el permiso resourcemanager.projects.create. Obtén más información para otorgar roles.

    Ir al selector de proyectos

  2. Verifica que la facturación esté habilitada para tu proyecto de Google Cloud .

  3. Habilita las APIs de Artifact Registry y Kubernetes Engine.

    Roles necesarios para habilitar las APIs

    Para habilitar las APIs, necesitas el rol de IAM de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin), que contiene el permiso serviceusage.services.enable. Obtén más información para otorgar roles.

    Habilitar las API

  4. En la consola de Google Cloud , activa Cloud Shell.

    Activa Cloud Shell

  5. Verifica que tengas los permisos necesarios para completar esta guía.
  6. Debes tener un clúster de GKE con la función Agent Sandbox habilitada. Si no tienes uno, sigue las instrucciones en Habilita Agent Sandbox en GKE para crear un clúster nuevo o actualizar uno existente.

Roles obligatorios

Para obtener los permisos que necesitas para crear y administrar zonas de pruebas, pídele a tu administrador que te otorgue el rol de IAM Administrador de Kubernetes Engine (roles/container.admin) en tu proyecto. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Define las variables de entorno

Para simplificar los comandos que ejecutas en este documento, puedes configurar variables de entorno en Cloud Shell. En Cloud Shell, define las siguientes variables de entorno útiles ejecutando los siguientes comandos:

export PROJECT_ID=$(gcloud config get project)
export CLUSTER_NAME="agent-sandbox-cluster"
export LOCATION="us-central1"
export NODE_POOL_NAME="agent-sandbox-node-pool"
export MACHINE_TYPE="e2-standard-2"

A continuación, se explica cada una de estas variables de entorno:

  • PROJECT_ID: Es el ID de tu proyecto actual de Google Cloud . Definir esta variable ayuda a garantizar que todos los recursos, como tu clúster de GKE, se creen en el proyecto correcto.
  • CLUSTER_NAME: Es el nombre de tu clúster de GKE, por ejemplo, agent-sandbox-cluster.
  • LOCATION: La Google Cloud región o zona en la que se encuentra tu clúster de GKE. Establece este parámetro en la región (por ejemplo, us-central1) si usas un clúster de Autopilot o en la zona (por ejemplo, us-central1-a) si usas un clúster de Standard.
  • NODE_POOL_NAME: Es el nombre del grupo de nodos que ejecutará cargas de trabajo en zona de pruebas, por ejemplo, agent-sandbox-node-pool.
  • MACHINE_TYPE: Es el tipo de máquina de los nodos en tu grupo de nodos, por ejemplo, e2-standard-2. Para obtener detalles sobre las diferentes series de máquinas y elegir entre las distintas opciones, consulta la guía de comparación y recursos de familias de máquinas.

Implementa un entorno de zona de pruebas

En esta sección, se muestra cómo crear el blueprint de zona de pruebas (SandboxTemplate), implementar el router de redes necesario y, luego, instalar el cliente de Python que usarás para interactuar con la zona de pruebas.

La forma recomendada de crear tu zona de pruebas y de interactuar con ella es usar el cliente de Python de Agentic Sandbox. Este cliente proporciona una interfaz que simplifica todo el ciclo de vida de un entorno de pruebas, desde la creación hasta la limpieza. Es una biblioteca de Python que puedes usar para crear, usar y borrar zonas de pruebas de forma programática.

El cliente usa un enrutador de zona de pruebas como punto de entrada central para todo el tráfico. En el ejemplo que se describe en este documento, el cliente crea un túnel a este router con el comando kubectl port-forward, de modo que no es necesario exponer ninguna dirección IP pública. Ten en cuenta que usar kubectl port-forward no es una solución segura y su uso debe limitarse a los entornos de desarrollo.

Crea un SandboxTemplate y un SandboxWarmPool

Ahora definirás la configuración de tu zona de pruebas creando un recurso SandboxTemplate y un recurso SandboxWarmPool. El SandboxTemplate actúa como un plano reutilizable que el controlador de Agent Sandbox usa para crear entornos de zona de pruebas coherentes y preconfigurados. El recurso SandboxWarmPool ayuda a garantizar que una cantidad especificada de Pods precalentados siempre estén en ejecución y listos para ser reclamados. Un sandbox precalentado es un Pod en ejecución que ya se inicializó. Esta preinicialización permite crear zonas de pruebas nuevas en menos de un segundo y evita la latencia de inicio de una zona de pruebas normal:

  1. En Cloud Shell, crea un archivo llamado sandbox-template-and-pool.yaml con el siguiente contenido:

    apiVersion: extensions.agents.x-k8s.io/v1alpha1
kind: SandboxTemplate
metadata:
  name: python-runtime-template
  namespace: default
spec:
  podTemplate:
    metadata:
      labels:
        sandbox: python-sandbox-example
    spec:
      runtimeClassName: gvisor
      automountServiceAccountToken: false # Required
      securityContext:
        runAsNonRoot: true # Required
      nodeSelector:
        sandbox.gke.io/runtime: gvisor # Required
      tolerations:
      - key: "sandbox.gke.io/runtime"
        value: "gvisor"
        effect: "NoSchedule" # Required
      containers:
      - name: python-runtime
        image: registry.k8s.io/agent-sandbox/python-runtime-sandbox:v0.1.0
        ports:
        - containerPort: 8888
        readinessProbe:
          httpGet:
            path: "/"
            port: 8888
          initialDelaySeconds: 0
          periodSeconds: 1
        resources:
          requests:
            cpu: "250m"
            memory: "512Mi"
          limits:
            cpu: "500m"
            memory: "1Gi" # Required
        securityContext:
          capabilities:
            drop: ["ALL"] # Required
      restartPolicy: "OnFailure"
---
apiVersion: extensions.agents.x-k8s.io/v1alpha1
kind: SandboxWarmPool
metadata:
  name: python-sandbox-warmpool
  namespace: default
spec:
  replicas: 2
  sandboxTemplateRef:
    name: python-runtime-template

  2. Aplica el manifiesto SandboxTemplate y SandboxWarmPool:

    kubectl apply -f sandbox-template-and-pool.yaml

Implementa el router de zona de pruebas

El cliente de Python que usarás para crear entornos de zona de pruebas y para interactuar con ellos usa un componente llamado Sandbox Router para comunicarse con las zonas de pruebas.

En este ejemplo, usarás el modo de desarrollador del cliente para realizar pruebas. Este modo está diseñado para el desarrollo local y usa el comando kubectl port-forward para establecer un túnel directo desde tu máquina local al servicio de Sandbox Router que se ejecuta en el clúster. Este enfoque de tunelización evita la necesidad de una dirección IP pública o una configuración de entrada compleja, y simplifica la interacción con los entornos de pruebas desde tu entorno local.

Sigue estos pasos para implementar el enrutador de zona de pruebas:

  1. En Cloud Shell, crea un archivo llamado sandbox-router.yaml con el siguiente contenido:

    # A ClusterIP Service to provide a stable endpoint for the router pods.
apiVersion: v1
kind: Service
metadata:
  name: sandbox-router-svc
  namespace: default
spec:
  type: ClusterIP
  selector:
    app: sandbox-router
  ports:
  - name: http
    protocol: TCP
    port: 8080 # The port the service will listen on
    targetPort: 8080 # The port the router container listens on (from the sandbox_router/Dockerfile)
---
# The Deployment to manage and run the router pods.
apiVersion: apps/v1
kind: Deployment
metadata:
  name: sandbox-router-deployment
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: sandbox-router
  template:
    metadata:
      labels:
        app: sandbox-router
    spec:
      # Ensure pods are spread across different zones for HA
      topologySpreadConstraints:
        - maxSkew: 1
          topologyKey: topology.kubernetes.io/zone
          whenUnsatisfiable: ScheduleAnyway
          labelSelector:
            matchLabels:
              app: sandbox-router
      containers:
      - name: router
        image: us-central1-docker.pkg.dev/k8s-staging-images/agent-sandbox/sandbox-router:latest-main
        ports:
        - containerPort: 8080
        readinessProbe:
          httpGet:
            path: /healthz
            port: 8080
          initialDelaySeconds: 5
          periodSeconds: 5
        livenessProbe:
          httpGet:
            path: /healthz
            port: 8080
          initialDelaySeconds: 10
          periodSeconds: 10
        resources:
          requests:
            cpu: "100m"
            memory: "512Mi"
          limits:
            cpu: "1000m"
            memory: "1Gi"
      securityContext:
        runAsUser: 1000
        runAsGroup: 1000

  2. Aplica el manifiesto para implementar el router en tu clúster:

    kubectl apply -f sandbox-router.yaml

  3. Verifica que la implementación del enrutador de zona de pruebas se ejecute correctamente:

    kubectl get deployment sandbox-router-deployment

    Espera a que la implementación muestre 2/2 o 1/1 en la columna READY.

Instala el cliente de Python

Ahora que se implementaron los componentes del clúster, como el enrutador de Sandbox, el paso preparatorio final es instalar el cliente de Python de Agentic Sandbox en tu máquina local. Recuerda que este cliente es una biblioteca de Python que te permite crear, usar y borrar zonas de pruebas de forma programática. La usarás en la siguiente sección para probar el entorno:

  1. Crea y activa un entorno virtual de Python:

    python3 -m venv .venv
source .venv/bin/activate

  2. Instala el paquete del cliente:

    pip install k8s-agent-sandbox

Prueba la zona de pruebas

Con todos los componentes de configuración en su lugar, ahora puedes crear una zona de pruebas y, luego, interactuar con ella usando el cliente de Python de Agentic Sandbox.

  1. En tu directorio agent-sandbox, crea una secuencia de comandos de Python llamada test_sandbox.py con el siguiente contenido:

    from k8s_agent_sandbox import SandboxClient
from k8s_agent_sandbox.models import SandboxLocalTunnelConnectionConfig

# Automatically tunnels to svc/sandbox-router-svc
client = SandboxClient(
    connection_config=SandboxLocalTunnelConnectionConfig()
)

sandbox = client.create_sandbox(template="python-runtime-template", namespace="default")
try:
    print(sandbox.commands.run("echo 'Hello from the sandboxed environment!'").stdout)
except Exception as e:
    print(f"An error occurred: {e}")

  2. Desde la terminal (con el entorno virtual aún activo), ejecuta la secuencia de comandos de prueba:

    python3 test_sandbox.py

Deberías ver el mensaje "Hello from the sandboxed environment!", que es el resultado de la zona de pruebas.

¡Felicitaciones! Ejecutaste correctamente un comando de shell dentro de un entorno de pruebas seguro. Con el método sandbox.run(), puedes ejecutar cualquier comando de shell, y Agent Sandbox ejecuta el comando dentro de una barrera segura que protege los nodos de tu clúster y otras cargas de trabajo del código no confiable. Esto proporciona una forma segura y confiable para que un agente de IA o cualquier flujo de trabajo automatizado ejecute tareas.

Cuando ejecutas la secuencia de comandos, SandboxClient controla todos los pasos por ti. Crea el recurso SandboxClaim para iniciar el entorno de pruebas, espera a que esté listo y, luego, usa el método sandbox.run() para ejecutar comandos de shell bash dentro del contenedor seguro. Luego, el cliente captura e imprime el stdout de ese comando. El entorno de pruebas se borra automáticamente después de que se ejecuta el programa.

Cuando se crea un recurso SandboxClaim, se asigna un Pod disponible del grupo de Pods activos al objeto Sandbox y se marca el reclamo como listo. Luego, el SandboxWarmPool se reabastece automáticamente para mantener la cantidad configurada de réplicas.

Para verificar si un entorno de pruebas específico está reclamado o disponible, consulta ownerReferences en los metadatos del pod del entorno de pruebas. Si el valor del campo kind es Sandbox, el pod está en uso. Si el valor del campo kind es SandboxWarmPool, el Pod está inactivo y a la espera de que se reclame.

Ejecutar zonas de pruebas en producción

En este documento, interactuarás con las zonas de pruebas desde fuera del clúster con Cloud Shell. El cliente de Python usa tus credenciales de usuario para autenticarse en el clúster y administrar los recursos de zona de pruebas, y usa el comando kubectl port-forward para establecer una conexión con las zonas de pruebas. Estos pasos funcionan bien para situaciones de desarrollo.

En una situación de producción, una aplicación de controlador (como un orquestador de IA) es responsable de crear y administrar recursos de zona de pruebas. Para usar Agent Sandbox en producción, ten en cuenta lo siguiente:

  • Autenticación: Tu aplicación de controlador debe autenticarse en el servidor de la API del clúster para ejecutar zonas de pruebas. La forma en que configures la autenticación dependerá de dónde se ejecute la aplicación del controlador, de la siguiente manera:

    • Si la aplicación del controlador se ejecuta como un Pod en el mismo clúster, usa el RBAC de Kubernetes o Workload Identity Federation for GKE con políticas de IAM para otorgar a la ServiceAccount de Kubernetes del Pod los permisos necesarios para supervisar las zonas de pruebas o descubrir los extremos de red.
    • Si la aplicación del controlador se ejecuta fuera del clúster, usa la federación de identidades para cargas de trabajo o las cuentas de servicio de IAM para otorgarle a la aplicación una identidad a la que puedas hacer referencia en las políticas de permiso.

  • Enrutamiento: Las solicitudes del cliente de Python en tu aplicación de controlador deben llegar al enrutador de Sandbox en tu clúster. En producción, usa uno de los siguientes métodos para establecer una conexión de red:

    • Si la aplicación del controlador se ejecuta en el mismo clúster, usa la función SandboxDirectConnectionConfig para segmentar la URL y el puerto que usa el servicio de Sandbox Router.
    • Si la aplicación del controlador se ejecuta fuera del clúster, usa la API de GKE Gateway para crear un balanceador de cargas interno o externo. En el código del cliente, usa la función SandboxGatewayConnectionConfig para hacer referencia a tu puerta de enlace.

    Para obtener más información sobre estos métodos de enrutamiento, consulta los ejemplos de uso en GitHub y los pasos de implementación de la puerta de enlace para el router.

  • Acceso a la zona de pruebas a los recursos de Google Cloud : Si el código de tu zona de pruebas necesita enviar solicitudes a las APIs de Google Cloud , como Cloud Storage, usa una política de IAM con Workload Identity Federation for GKE para otorgar a la ServiceAccount de Kubernetes que usa el Pod de zona de pruebas los permisos necesarios para ese acceso.

Limpia los recursos

Para evitar que se apliquen cargos a tu cuenta de Google Cloud , debes borrar el clúster de GKE que creaste:

gcloud container clusters delete $CLUSTER_NAME --location=$LOCATION --quiet

¿Qué sigue?