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

En este documento se proporcionan instrucciones para instalar y ejecutar el controlador AgentSandbox en un clúster de Google Kubernetes Engine (GKE). También se explica cómo desplegar un entorno aislado en el clúster en el que puedes probar comandos de shell que no son de confianza.

El controlador del entorno aislado de agentes proporciona un marco para crear y gestionar entornos de ejecución efímeros. Este enfoque te permite definir una plantilla para el entorno de tu aplicación y, a continuación, crear instancias de ella bajo demanda.

Entorno aislado de agentes proporciona un entorno seguro y aislado para ejecutar código no fiable, como el código generado por modelos de lenguaje extensos (LLMs). Ejecutar este tipo de código directamente en un clúster supone riesgos de seguridad, ya que el código no fiable podría acceder a otras aplicaciones o al nodo del clúster subyacente, o interferir con ellos.

Agent Sandbox mitiga estos riesgos proporcionando un aislamiento sólido de los procesos, el almacenamiento y la red para el código que ejecuta. Este aislamiento se consigue mediante gVisor, una tecnología que crea una barrera segura entre la aplicación y el sistema operativo del nodo del clúster. Se pueden usar otras tecnologías de aislamiento, como contenedores Kata. Sin embargo, en el ejemplo de este documento solo se usa gVisor.

En este documento se proporcionan instrucciones para ejecutar Agent Sandbox en un clúster de Autopilot o Estándar de GKE.

Agent Sandbox es un proyecto de código abierto. Para obtener más información sobre cómo contribuir al proyecto o encontrar detalles técnicos más detallados, consulta el proyecto de software libre Agent Sandbox.

Costes

Si sigues los pasos que se indican en este documento, se te cobrará en tu cuenta de Google Cloud. Los costes empiezan cuando creas un clúster de GKE. Estos costes incluyen los cargos por clúster de GKE, tal como se indica en la página de precios, y los cargos por ejecutar máquinas virtuales de Compute Engine.

Para evitar cargos innecesarios, inhabilita GKE o elimina el proyecto después de completar este documento.

Antes de empezar

  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. Enable the Artifact Registry, Google Kubernetes Engine APIs.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the APIs

  4. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    Definir variables de entorno

    Para simplificar los comandos que ejecutas en este documento, puedes definir variables de entorno en Cloud Shell. En Cloud Shell, define las siguientes variables de entorno útiles ejecutando los comandos que se indican a continuación:

    export PROJECT_ID=$(gcloud config get project)
export CLUSTER_NAME="agent-sandbox-cluster"
export GKE_LOCATION="us-central1"
export AGENT_SANDBOX_VERSION="v0.1.0"
export NODE_POOL_NAME="agent-sandbox-node-pool"
export MACHINE_TYPE="e2-standard-2"
export PYTHON_CLIENT_VERSION="main"

    A continuación, se explica qué son estas variables de entorno:

    • PROJECT_ID: el ID de tu proyecto de Google Cloud actual. Definir esta variable ayuda a asegurarse de que todos los recursos, como el clúster de GKE, se creen en el proyecto correcto.
    • CLUSTER_NAME: el nombre de tu clúster de GKE. Por ejemplo, agent-sandbox-cluster.
    • GKE_LOCATION: la región Google Cloud en la que se crearán tu clúster de GKE y tu repositorio de Artifact Registry. Por ejemplo, us-central1. Te recomendamos que los coloques en el mismo lugar, ya que así se reduce la latencia de extracción de imágenes.
    • AGENT_SANDBOX_VERSION: la versión del controlador de Agent Sandbox que se va a implementar en tu clúster.
    • NODE_POOL_NAME: el nombre del grupo de nodos que ejecutará cargas de trabajo en un espacio aislado. Por ejemplo, agent-sandbox-node-pool.
    • MACHINE_TYPE: el tipo de máquina de los nodos de tu grupo de nodos. Por ejemplo, e2-standard-2. Para obtener información sobre las diferentes series de máquinas y elegir entre las distintas opciones, consulta la guía de comparación y recursos de las familias de máquinas.
    • PYTHON_CLIENT_VERSION: la versión del cliente de Python del entorno de pruebas con agentes que se va a instalar.

    Desplegar el entorno aislado del agente

    Ahora que ya has configurado tu Google Cloud proyecto y el entorno de Cloud Shell, puedes aprovisionar la infraestructura necesaria y desplegar Agent Sandbox.

    Crear un clúster de GKE

    A continuación, crea un clúster de GKE con gVisor habilitado. Este clúster proporciona el entorno de Kubernetes en el que desplegarás y ejecutarás el controlador de entorno aislado del agente y la aplicación de ejemplo en entorno aislado. gVisor proporciona la tecnología de entorno aislado para ejecutar de forma segura código que no es de confianza.

    Puedes crear un clúster de Autopilot o un clúster estándar. Autopilot habilita gVisor automáticamente, mientras que los clústeres Standard requieren que crees un grupo de nodos con gVisor habilitado manualmente:

    Autopilot

    Para crear un clúster de Autopilot con gcloud CLI, ejecuta el siguiente comando:

    gcloud container clusters create-auto ${CLUSTER_NAME} \
    --location=${GKE_LOCATION} \
    --project=${PROJECT_ID}

    Estándar

    Para crear un clúster estándar con gcloud CLI, sigue estos pasos:

    1. Crea el clúster:

      gcloud container clusters create ${CLUSTER_NAME} \
    --location=${GKE_LOCATION}

    2. Crea un grupo de nodos independiente con gVisor habilitado:

      gcloud container node-pools create ${NODE_POOL_NAME} \
  --cluster=${CLUSTER_NAME} \
  --location=${GKE_LOCATION} \
  --machine-type=${MACHINE_TYPE} \
  --image-type=cos_containerd \
  --sandbox type=gvisor

    Obtén las credenciales del clúster para que la CLI de kubectl pueda conectarse al clúster. Este comando actualiza el archivo de configuración de Kubernetes, que se almacena de forma predeterminada en el directorio ~/.kube/config. Este archivo de configuración contiene las credenciales que kubectl necesita para interactuar con tu clúster de GKE:

    gcloud container clusters get-credentials ${CLUSTER_NAME} \
    --location=${GKE_LOCATION}

    Desplegar el controlador de Agent Sandbox en el clúster

    Puedes implementar el controlador de Agent Sandbox y sus componentes necesarios aplicando los manifiestos de la versión oficial a tu clúster. Estos manifiestos son archivos de configuración que indican a Kubernetes que descargue todos los componentes necesarios para desplegar y ejecutar el controlador de Agent Sandbox en tu clúster.

    Ejecuta los siguientes comandos para implementar el controlador de Agent Sandbox en tu clúster de GKE:

    kubectl apply \
-f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/${AGENT_SANDBOX_VERSION}/manifest.yaml \
-f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/${AGENT_SANDBOX_VERSION}/extensions.yaml

    Verificar el controlador del entorno aislado de pruebas del agente

    Después de aplicar los manifiestos, comprueba que el pod del controlador del sandbox del agente se esté ejecutando correctamente en el espacio de nombres agent-sandbox-system:

    kubectl get pods -n agent-sandbox-system

    Espera a que el pod muestre el estado "Running" en la columna STATUS y "1/1" en la columna READY. Si el pod funciona correctamente, la salida tendrá un aspecto similar a este:

    NAME                         READY   STATUS    RESTARTS   AGE
agent-sandbox-controller-0   1/1     Running   0          44d

    Ahora que el controlador de Agent Sandbox está en funcionamiento, puede crear y gestionar automáticamente entornos aislados para cualquier recurso de Sandbox que crees en tu clúster.

    Desplegar un entorno aislado

    Ahora que tienes el controlador de Agent Sandbox en tu clúster de GKE, debes desplegar los componentes del entorno de pruebas de ejemplo. En esta sección se explica cómo crear el blueprint de la sandbox (SandboxTemplate), desplegar el router de red necesario e instalar el cliente de Python que usarás para interactuar con la sandbox.

    La forma recomendada de crear tu entorno aislado e interactuar con él es usar el cliente de Python de Agentic Sandbox. Este cliente proporciona una interfaz que simplifica todo el ciclo de vida de un sandbox, desde la creación hasta la limpieza. Es una biblioteca de Python que puedes usar para crear, usar y eliminar sandboxes de forma programática.

    El cliente usa un router de pruebas como punto de entrada central para todo el tráfico. En el ejemplo descrito en este documento, el cliente crea un túnel a este router mediante el comando kubectl port-forward, por lo 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 que su uso debe limitarse a entornos de desarrollo.

    Crear un SandboxTemplate y un SandboxWarmPool

    Ahora, define la configuración de tu sandbox creando un recurso SandboxTemplate y un recurso SandboxWarmPool. El SandboxTemplate actúa como un plano reutilizable que el controlador del entorno aislado del agente usa para crear entornos aislados coherentes y preconfigurados. El recurso SandboxWarmPool se asegura de que siempre haya en ejecución y listos para reclamarse un número específico de pods precalentados. Un sandbox precalentado es un pod en ejecución que ya se ha inicializado. Esta preinicialización permite crear nuevos entornos aislados en menos de un segundo y evita la latencia de inicio de un entorno aislado 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
      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"
            ephemeral-storage: "512Mi"
      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

    Desplegar el router de entorno aislado

    El cliente de Python que usarás para crear entornos aislados y comunicarte con ellos usa un componente llamado Sandbox Router para comunicarse con los entornos aislados.

    En este ejemplo, se usa el modo para desarrolladores del cliente para hacer pruebas. Este modo está pensado para el desarrollo local y usa el comando kubectl port-forward para establecer un túnel directo desde tu máquina local al servicio Sandbox Router que se ejecuta en el clúster. Este enfoque de túnel 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 router de entorno aislado:

    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: 2 # Run at least two replicas for high availability
  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:v20251124-v0.1.0-10-ge26ddb2
        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: "250m"
            memory: "512Mi"
          limits:
            cpu: "1000m"
            memory: "1Gi"
      securityContext:
        runAsUser: 1000
        runAsGroup: 1000

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

      kubectl apply -f sandbox-router.yaml

    Instalar el cliente de Python

    Ahora que se han desplegado los componentes del clúster, como el enrutador de Sandbox, el último paso preparatorio 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 eliminar sandboxes mediante programación. Lo 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 de cliente desde el repositorio agent-sandbox:

      pip install "git+https://github.com/kubernetes-sigs/agent-sandbox.git@${PYTHON_CLIENT_VERSION}#subdirectory=clients/python/agentic-sandbox-client"

    Probar el entorno aislado

    Una vez que hayas configurado todos los componentes, podrás crear una zona de pruebas e interactuar con ella mediante el cliente de Python de Agentic Sandbox.

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

      from agentic_sandbox import SandboxClient

# Automatically tunnels to svc/sandbox-router-svc
with SandboxClient(
    template_name="python-runtime-template",
    namespace="default"
) as sandbox:
    print(sandbox.run("echo 'Hello from the sandboxed environment!'").stdout
)

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

      python3 test_sandbox.py

    Debería aparecer el mensaje "Hello from the sandboxed environment!" (Hola desde el entorno aislado), que es el resultado de la sandbox.

    ¡Enhorabuena! Has ejecutado correctamente un comando de shell en un sandbox seguro. Con el método sandbox.run(), puedes ejecutar cualquier comando de shell. El entorno aislado del agente ejecuta el comando dentro de una barrera segura que protege los nodos de tu clúster y otras cargas de trabajo de código no fiable. De esta forma, un agente de IA o cualquier flujo de trabajo automatizado puede ejecutar tareas de forma segura y fiable.

    Cuando ejecutas la secuencia de comandos, SandboxClient se encarga de todos los pasos. Crea el recurso SandboxClaim para iniciar el entorno aislado, espera a que esté listo y, a continuación, usa el método sandbox.run() para ejecutar comandos de shell bash en el contenedor seguro. A continuación, el cliente captura e imprime el stdout de ese comando. El espacio aislado se elimina automáticamente después de ejecutar el programa.

    Eliminar los recursos

    Para evitar que se apliquen cargos en tu Google Cloud cuenta, debes eliminar el clúster de GKE que has creado:

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

    Siguientes pasos

    • Consulta más información sobre el proyecto de código abierto Agent Sandbox en GitHub.
    • Para conocer la tecnología subyacente que proporciona aislamiento de seguridad a tus cargas de trabajo, consulta GKE Sandbox.
    • Para obtener más información sobre cómo mejorar la seguridad de tus clústeres y cargas de trabajo, consulta el artículo Información general sobre la seguridad de GKE.