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

En este documento, se muestra cómo ejecutar código generado por IA en una zona de pruebas aislada en un clúster de Google Kubernetes Engine (GKE). Crea una plantilla de zona de pruebas y un grupo de zonas de pruebas listas en el clúster. Luego, ejecuta una secuencia de comandos de Python que solicita una zona de pruebas del grupo y ejecuta un comando en la zona de pruebas. La secuencia de comandos usa el cliente de Python de Agent Sandbox, una biblioteca para crear y administrar entornos de pruebas.

Ejecutar código no confiable en una zona de pruebas ayuda a proteger tu sistema de posibles vulnerabilidades en el código generado por IA, aumentar la velocidad de desarrollo y mejorar la seguridad de tus implementaciones. Para obtener una descripción general de cómo Agent Sandbox en GKE aísla el código no confiable generado por IA, consulta Acerca de Agent Sandbox en GKE.

Costos

Agent Sandbox en GKE es un software de código abierto que puedes usar sin cargo adicional. Los precios de GKE se aplican a los recursos que creas, incluidos los recursos de procesamiento que usa el controlador de Agent Sandbox.

Antes de comenzar

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

    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.
    • Crea 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 Cloud de Confiance .

  3. Habilita la API de Kubernetes Engine si aún no está habilitada.

    Roles necesarios para habilitar las APIs

    Para habilitar las 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 obtenerlo a través del rol de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin). Obtén más información para otorgar roles.

    Habilitar la API

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

    Activa Cloud Shell

  5. Verifica que tengas los permisos necesarios para completar este documento.
  6. Asegúrate de tener un clúster de GKE que tenga instalado el controlador de Agent Sandbox y el Sandbox Router implementado. De lo contrario, completa solo las siguientes secciones de Instala Agent Sandbox en GKE y, luego, regresa a este documento:
    1. Define las variables de entorno.
    2. Cree un clúster de GKE
    3. Instala Agent Sandbox
    4. Implementa el router de la zona de pruebas
    No es necesario que completes las otras secciones de ese documento, como Implementa un entorno de zona de pruebas. Más adelante en este documento, crearás tus propios recursos SandboxTemplate y SandboxWarmPool.

Roles obligatorios

Para obtener los permisos que necesitas para crear y administrar entornos de pruebas, pídele a tu administrador que te otorgue el rol de IAM de 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 CLUSTER_NAME="agent-sandbox-cluster"
export LOCATION="us-central1"

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

  • CLUSTER_NAME: Es el nombre de tu clúster de GKE, por ejemplo, agent-sandbox-cluster.
  • LOCATION: Es la región o zona de Cloud de Confiance by S3NS en la que se encuentra tu clúster de GKE. Si usas un clúster de Autopilot, configúralo en la región (por ejemplo, us-central1). Si usas un clúster de Standard, configúralo en la zona (por ejemplo, us-central1-a).

Implementa un entorno de zona de pruebas

En esta sección, se muestra cómo crear el plano de la zona de pruebas (un recurso SandboxTemplate), verificar el router de red y, también, 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 una zona de pruebas, desde la creación hasta la limpieza. Es una biblioteca de Python que puedes usar para crear, usar y borrar entornos de pruebas de manera programática.

El cliente usa un router 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 necesites 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 entornos de desarrollo.

Crea recursos SandboxTemplate y SandboxWarmPool

Ahora, define la configuración de tu zona de pruebas creando un recurso SandboxTemplate y un recurso SandboxWarmPool. El recurso 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 preparados siempre se ejecute y esté lista para reclamarse. Una zona de pruebas precalentada es un Pod en ejecución que ya se inicializó. Esta inicialización previa permite que se creen zonas de pruebas nuevas en menos de un segundo y evita la latencia de inicio que se produce cuando se inicia 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/v1beta1
    kind: SandboxTemplate
    metadata:
      name: python-sandbox-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/v1beta1
    kind: SandboxWarmPool
    metadata:
      name: python-sandbox-warmpool
      namespace: default
    spec:
      replicas: 2
      sandboxTemplateRef:
        name: python-sandbox-template
    
  2. Aplica el manifiesto SandboxTemplate y SandboxWarmPool:

    kubectl apply -f sandbox-template-and-pool.yaml
    
  3. Espera hasta que las zonas de pruebas del grupo de preparación estén listas:

    kubectl wait sandboxwarmpool python-sandbox-warmpool \
        --for=jsonpath='{.status.readyReplicas}'=2 \
        --timeout=600s
    

    Más adelante en este documento, el cliente de Python crea un recurso SandboxClaim. Si el cliente crea la reclamación antes de que las zonas de pruebas del grupo estén listas, el controlador podría crear una zona de pruebas nueva para la reclamación en lugar de asignar una del grupo. En un clúster de Autopilot, las zonas de pruebas pueden tardar varios minutos en estar listas, ya que es posible que GKE deba crear nodos para ellas.

Verifica el router de la zona de pruebas

El cliente de Python que usarás para crear entornos de zona de pruebas y, también, interactuar con ellos usa un componente llamado router de zona de pruebas 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 hasta el 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 las zonas de pruebas desde tu entorno local.

Verifica que el Sandbox Router se esté ejecutando en el espacio de nombres agent-sandbox-system:

kubectl get deployment sandbox-router --namespace=agent-sandbox-system

Cuando el router se está ejecutando, la columna READY muestra que todas las réplicas están listas, por ejemplo, 2/2. Si el comando devuelve un error NotFound, implementa el router siguiendo los pasos que se indican en Implementa el router de la zona de pruebas.

Instala el cliente de Python

Ahora que se implementaron los componentes en el clúster, como el Sandbox Router, 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 borrar entornos de pruebas de manera 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 de cliente. Usa la misma versión que el controlador de Agent Sandbox:

    pip install k8s-agent-sandbox==1.0.6
    

Prueba la zona de pruebas

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

  1. 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
    
    # Tunnels to svc/sandbox-router-svc in the agent-sandbox-system namespace.
    # cleanup=True deletes the sandbox when the script exits.
    client = SandboxClient(
        connection_config=SandboxLocalTunnelConnectionConfig(),
        cleanup=True,
    )
    
    sandbox = client.create_sandbox(warmpool="python-sandbox-warmpool", 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 una zona de pruebas segura. Con el método sandbox.commands.run(), puedes ejecutar cualquier comando de shell, y Agent Sandbox en GKE 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 la zona de pruebas, espera a que esté lista y, luego, usa el método sandbox.commands.run() para ejecutar comandos de shell de bash dentro del contenedor seguro. Luego, el cliente captura y muestra el stdout de ese comando. Debido a que la secuencia de comandos establece el parámetro cleanup en True, el cliente borra la zona de pruebas cuando se cierra el programa.

Cuando se crea un recurso SandboxClaim, se asigna una zona de pruebas disponible del grupo activo a la reclamación y esta se marca como lista. Luego, el recurso SandboxWarmPool se reabastece automáticamente para mantener la cantidad configurada de réplicas.

Para verificar si una zona de pruebas específica está reclamada o disponible, consulta el ownerReferences en los metadatos del recurso Sandbox. Si el valor del campo kind es SandboxClaim, la zona de pruebas está en uso. Si el valor del campo kind es SandboxWarmPool, la zona de pruebas está inactiva y esperando que se reclame.

Ejecuta 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 la 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 organizador de IA) es responsable de crear y administrar recursos de la zona de pruebas. Para usar Agent Sandbox en GKE 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 entornos de pruebas. La forma en que configuras la autenticación depende de dónde se ejecute la aplicación del controlador, como se indica a continuación:

    • Si la aplicación del controlador se ejecuta como un Pod en el mismo clúster, usa RBAC de Kubernetes o Workload Identity Federation para 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 una identidad a la aplicación a la que puedas hacer referencia en las políticas de permisos.
  • Enrutamiento: Las solicitudes del cliente de Python en tu aplicación de controlador deben llegar al router de la zona de pruebas 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 orientar 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 de cliente, usa la función SandboxGatewayConnectionConfig para hacer referencia a la 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 de la zona de pruebas a los recursos de Cloud de Confiance : si el código de la zona de pruebas necesita enviar solicitudes a las APIs de Cloud de Confiance , 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 la 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 de Cloud de Confiance by S3NS (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 en GKE aplica una postura de red estricta de seguridad predeterminada (networkPolicyManagement: Managed). Se aplican las siguientes restricciones en esta postura:

    • La entrada se bloquea desde todas las fuentes, excepto el router de la zona de pruebas designado (Pods que tienen la etiqueta app: sandbox-router en el espacio de nombres agent-sandbox-system).
    • Se permite la salida a la Internet pública, pero se bloquea de forma explícita la salida a los rangos de LAN privados (RFC 1918), el DNS interno del clúster (CoreDNS) y el servidor de metadatos del proveedor de servicios en la nube (169.254.0.0/16).

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

Políticas de seguridad de la zona de pruebas

De forma predeterminada, Agent Sandbox en GKE no aplica políticas de seguridad a las zonas de pruebas. Para ayudar a aplicar la configuración de aislamiento de tus entornos de pruebas, aplica la secure-sandbox-policy política de admisión de validación (VAP) de Kubernetes recomendada desde el repositorio de GitHub de Agent Sandbox. Para obtener instrucciones, consulta Aplica la política de seguridad recomendada.

La política aplica requisitos de aislamiento, como requerir gVisor, inhabilitar hostNetwork y bloquear volúmenes hostPath. La política también aplica requisitos de endurecimiento, como descartar todas las capacidades, evitar que se agreguen capacidades nuevas y exigir que los contenedores se ejecuten como no raíz y que establezcan límites de recursos. Para obtener la lista completa de requisitos, consulta Requisitos de implementación de Agent Sandbox en GKE.

Modifica o quita las restricciones de la política

Como tú aplicas la política, puedes cambiarla para que se adapte a tus cargas de trabajo. Si tus cargas de trabajo requieren exenciones de algunas de las reglas, puedes modificar la política para quitar restricciones específicas o borrar la vinculación de la política por completo. Quitar una restricción reduce el aislamiento que proporciona la política, por lo que debes quitar solo las restricciones que requieren tus cargas de trabajo.

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

kubectl edit validatingadmissionpolicy secure-sandbox-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 quieres dejar de aplicar la política en tu clúster, borra la vinculación de la política:

kubectl delete validatingadmissionpolicybinding secure-sandbox-binding

Problemas conocidos

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

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

Si aplicaste la política de seguridad recomendada y tratas de implementar una zona de pruebas que se integra en un archivo adicional de malla de servicios (por ejemplo, Envoy o Istio), es posible que la política 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 'secure-sandbox-policy' with binding 'secure-sandbox-binding'
denied request: Security Violation: Capabilities.add must be empty. You cannot add capabilities.
  • Causa: Los sidecars de malla de servicios suelen usar un contenedor de inicio, como istio-init o proxy-init. Estos contenedores de inicialización requieren capacidades como NET_ADMIN o NET_RAW para configurar reglas de iptables para el enrutamiento de salida transparente. La ValidatingAdmissionPolicy secure-sandbox-policy bloquea todas las adiciones de capacidades en todos los tipos de contenedores.
  • Solución alternativa: Como administras esta política en tu clúster, puedes modificar el ValidatingAdmissionPolicy para permitir que contenedores de inicialización de confianza específicos soliciten las capacidades NET_ADMIN y NET_RAW. Para obtener instrucciones sobre cómo modificar o quitar restricciones de políticas, consulta Modifica o quita restricciones de políticas. Por ejemplo, puedes actualizar las expresiones o variables de validación de la política para eximir los nombres de contenedores de confianza de la regla de capacidades.

Latencia de salida o tiempo de espera agotado cuando se establece conexión con las APIs de Google a través de IPv6

Las cargas de trabajo dentro de la zona de pruebas pueden experimentar tiempos de espera de conexión o una latencia alta, de hasta dos minutos, cuando intentan conectarse a recursos externos o APIs de Google (como Vertex AI o Cloud Storage).

  • Causa: Si tu clúster de GKE tiene habilitada la pila doble de IPv6, la resolución de DNS para las APIs de Google devuelve direcciones IPv4 (A) e IPv6 (AAAA). Algunos algoritmos en los motores de entorno de ejecución, como Node.js, intentan conectarse primero a través de IPv6. Si tu VPC de GKE no tiene una ruta de salida IPv6 válida, como una puerta de enlace de Internet o de Cloud NAT para IPv6, la conexión TCP deja de responder hasta que venza el tiempo de espera de TCP SYN. Luego, la conexión TCP recurre 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 de Cloud NAT de IPv6 válida en tu red de VPC.
    • Preferir IPv4 en la carga de trabajo: Para preferir la resolución de DNS de IPv4, configura el entorno 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 Cloud de Confiance by S3NS , debes borrar el clúster de GKE que creaste:

gcloud container clusters delete ${CLUSTER_NAME} \
    --location=${LOCATION} \
    --quiet

¿Qué sigue?