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

Puedes implementar un entorno de desarrollo para usar el cliente de Python de Agent Sandbox en un clúster de Google Kubernetes Engine (GKE). Esta configuración te ayuda a ejecutar y probar de forma segura el código generado por IA, ya que aísla el código no confiable en un entorno de Python de zona de pruebas. Este aislamiento es fundamental para proteger tu sistema de posibles vulnerabilidades en el código generado por IA, aumentar la velocidad de desarrollo y garantizar implementaciones seguras. 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

La zona de pruebas del agente 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 APIs, necesitas el permiso serviceusage.services.enable. Si creaste el proyecto, es probable que ya tengas este permiso a través del rol de propietario (roles/owner). De lo contrario, puedes obtener este permiso a través del rol de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin). 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. Configura 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 reclamarse. 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 se encarga de 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 activo 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:

  • 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 Google Cloud recursos de zona de pruebas: 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. Debido a que la política de red predeterminada bloquea el acceso al servidor de metadatos Google Cloud (169.254.169.254), debes personalizar la política de red para permitir este tráfico.

  • Restricciones de la política de red: De forma predeterminada, Agent Sandbox aplica una postura de red segura de forma predeterminada estricta (networkPolicyManagement: Managed). Se aplican las siguientes restricciones en virtud de esta postura:

    • El Ingress está bloqueado desde todas las fuentes, excepto el enrutador de zona de pruebas designado.
    • El tráfico de salida se permite a Internet pública, pero el tráfico de salida a rangos de LAN privados (RFC 1918), el DNS interno del clúster (CoreDNS) y el servidor de metadatos del proveedor de Cloud (169.254.0.0/16) se bloquean de forma explícita.

    Para usar Workload Identity Federation for GKE o acceder a otros recursos privados, debes definir políticas de red personalizadas en SandboxTemplate. Para obtener detalles de configuración y plantillas personalizables (como sandboxes aislados o integración de Workload Identity Federation for GKE), consulta Administración de políticas de red de Agent Sandbox.

Políticas de seguridad de la zona de pruebas

Para ayudar a garantizar un entorno seguro de forma predeterminada, el complemento de zona de pruebas del agente de GKE usa políticas de admisión de validación (VAP) de Kubernetes para aplicar restricciones de seguridad en los recursos Sandbox y SandboxTemplate. Estas políticas se aplican automáticamente.

Para una mayor flexibilidad, el complemento divide la aplicación de la seguridad en un modelo de políticas de dos niveles. En las siguientes secciones, se describen estas políticas: la política principal estrictamente administrada y la política de endurecimiento personalizable.

Política de seguridad principal (sandbox-core-policy)

La política de seguridad principal aplica requisitos de aislamiento que ayudan a proteger la integridad de la zona de pruebas. Esta política incluye reglas que requieren el uso de gVisor, aislamiento de red (por ejemplo, inhabilitar hostNetwork) y aislamiento del sistema de archivos (por ejemplo, bloquear hostPath). Dado que GKE administra esta política a través del parámetro de configuración addonmanager.kubernetes.io/mode: Reconcile, no puedes modificar ni anular estas reglas principales.

Política de endurecimiento de la seguridad (sandbox-hardening-policy)

La política de seguridad de endurecimiento proporciona prácticas recomendadas de seguridad y opciones de administración adicionales. Aplica restricciones, como descartar todas las capacidades, impedir la adición de capacidades nuevas y exigir que los contenedores se ejecuten como no raíz con límites de recursos. GKE implementa esta política en modo EnsureExists a través del parámetro de configuración addonmanager.kubernetes.io/mode: EnsureExists. Este parámetro de configuración significa que GKE crea la política si falta, pero puedes modificar o borrar la política o su vinculación si es necesario.

Cómo modificar o quitar restricciones de refuerzo

Dado que la política de endurecimiento se implementa en el modo EnsureExists, GKE crea la política si falta, pero no reemplaza tus modificaciones. Si tus cargas de trabajo requieren exenciones de estas reglas de endurecimiento, puedes modificar la política para quitar restricciones específicas o borrar la vinculación de la política por completo.

Para modificar la política de endurecimiento y quitar una restricción específica (por ejemplo, para permitir que los contenedores se ejecuten como raíz o para omitir los límites de recursos), edita el recurso ValidatingAdmissionPolicy:

kubectl edit validatingadmissionpolicy sandbox-hardening-policy

En el editor de texto que se abre, busca la sección validations y quita o modifica la expresión de restricción que bloquea tu carga de trabajo.

Como alternativa, si deseas inhabilitar por completo la política de endurecimiento para tu clúster, borra la vinculación de la política:

kubectl delete validatingadmissionpolicybinding sandbox-hardening-binding

Problemas conocidos

En esta sección, se describen los problemas conocidos cuando se usa Agent Sandbox en GKE y cómo resolverlos o evitarlos.

La política de seguridad bloquea las capacidades cuando se usa una malla de servicios

Si intentas implementar una zona de pruebas que se integra con una malla de servicios sidecar (por ejemplo, Envoy o Istio), es posible que la política de seguridad de endurecimiento bloquee la creación de la zona de pruebas con un error como el siguiente:

sandbox create error: sandboxes.agents.x-k8s.io "claude-cli-claim-managed" is forbidden:
ValidatingAdmissionPolicy 'sandbox-hardening-policy' with binding 'sandbox-hardening-binding'
denied request: Security Violation: Capabilities.add must be empty. You cannot add capabilities.
  • Causa: Los sidecars de malla de servicio suelen usar un contenedor de inicialización, como istio-init o proxy-init. Estos contenedores init requieren capacidades como NET_ADMIN o NET_RAW para configurar reglas de iptables para el enrutamiento de salida transparente. De forma predeterminada, sandbox-hardening-policy de GKE bloquea todas las adiciones de capacidades en todos los tipos de contenedores.
  • Solución alternativa: Debido a que la política de endurecimiento de GKE se implementa en el modo EnsureExists, puedes modificar ValidatingAdmissionPolicy para permitir que contenedores init específicos y de confianza soliciten capacidades de NET_ADMIN y NET_RAW. Para obtener instrucciones sobre cómo modificar o quitar estas restricciones de endurecimiento, consulta Cómo modificar o quitar restricciones de endurecimiento. Por ejemplo, puedes actualizar las expresiones de validación o las variables de la política para eximir los nombres de contenedores de confianza de la regla de capacidades.

Latencia de salida o tiempo de espera cuando se conectan a las APIs de Google a través de IPv6

Es posible que las cargas de trabajo dentro del sandbox experimenten tiempos de espera de conexión o latencia alta, de hasta dos minutos, cuando intenten conectarse a recursos externos o a las APIs de Google (como Vertex AI o Cloud Storage).

  • Causa: Si tu clúster de GKE tiene habilitado IPv6 de pila doble, la resolución de DNS para las APIs de Google devuelve direcciones IPv4 (A) y IPv6 (AAAA). Algunos algoritmos en los motores de ejecución, como Node.js, intentan conectarse a través de IPv6 primero. Si tu VPC de GKE no tiene una ruta de salida de IPv6 válida, como una puerta de enlace de Cloud NAT o de Internet para IPv6, la conexión TCP dejará de responder (para obtener más información, consulta https://developers.google.com/style/word-list#hang) hasta que venza el tiempo de espera de TCP SYN. Luego, la conexión TCP vuelve a IPv4.

  • Resolución: Para resolver este problema, realiza una de las siguientes acciones:

    • Configura la salida de IPv6: Para permitir que el tráfico IPv6 saliente regrese al clúster, configura una puerta de enlace de Internet o Cloud NAT de IPv6 válida en tu red de VPC.

    • Prefer IPv4 in the workload: Para preferir la resolución de DNS IPv4, configura el tiempo de ejecución de tu carga de trabajo. Por ejemplo, en una aplicación de Node.js, puedes establecer las siguientes variables de entorno en tu definición de SandboxTemplate:

      env:
- name: NODE_OPTIONS
  value: "--dns-result-order=ipv4first --no-network-family-autoselection"

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?