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

Puedes implementar un entorno de desarrollador 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 mediante el aislamiento de código no confiable dentro de un entorno de Python en 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

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 Cloud de Confiance consola de, en la página del selector de proyectos, selecciona o crea un Cloud de Confiance proyecto de.

    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 resourcemanager.projects.create permiso. Obtén más información para otorgar roles.

    Ir al selector de proyectos

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

  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 Cloud de Confiance consola de, 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

Si quieres obtener los permisos que necesitas para crear y administrar zonas de pruebas, pídele a tu administrador que te otorgue el rol de IAM de administrador de Kubernetes Engine (roles/container.admin) en el 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 mediante 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 el significado de estas variables de entorno:

  • PROJECT_ID: Es el ID del proyecto actual. Cloud de Confiance by S3NS 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 del clúster de GKE, por ejemplo, agent-sandbox-cluster.
  • LOCATION: Es la Cloud de Confiance by S3NS 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á las cargas de trabajo en zona de pruebas, por ejemplo, agent-sandbox-node-pool.
  • MACHINE_TYPE: Es el tipo de máquina de los nodos de tu grupo de nodos, por ejemplo, e2-standard-2. Para obtener detalles sobre las diferentes series de máquinas y elegir entre diferentes opciones, consulta la guía de comparación y recursos de familias de máquinas.

Implementa un entorno en zona de pruebas

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

La forma recomendada de crear y, luego, interactuar con tu zona de pruebas 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 zonas de pruebas de forma 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 el uso de 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 mediante la creación de un SandboxTemplate y un recurso SandboxWarmPool. El SandboxTemplate actúa como un plano reutilizable que usa el controlador de Agent Sandbox 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. Una zona de pruebas precalentada es un pod en ejecución que ya se inicializó. Esta inicialización previa permite que se creen nuevas zonas de pruebas 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 en zona de pruebas y, luego, interactuar con ellos usa un componente llamado router de zona de pruebas para comunicarse con las zonas de pruebas.

Para 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 router de zona de pruebas 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.

Sigue estos pasos para implementar el router 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 router 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 router de zona de pruebas, 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. 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 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 mediante 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 tu 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 se genera desde la zona de pruebas.

¡Felicitaciones! Ejecutaste correctamente un comando de shell dentro de una zona de pruebas segura. 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 la zona de pruebas, espera a que esté lista y, luego, usa el método sandbox.run() para ejecutar comandos de shell de bash dentro del contenedor seguro. Luego, el cliente captura e imprime el stdout de ese comando. La zona 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 nodos precalentados al objeto Sandbox y la reclamación se marca como lista. Luego, SandboxWarmPool se reabastece automáticamente para mantener la cantidad configurada de réplicas.

Para verificar si se reclamó o está disponible una zona de pruebas específica, consulta ownerReferences en los metadatos del pod de la zona 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 espera a ser reclamado.

Ejecuta zonas de pruebas en producción

En este documento, interactúas 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 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 de controlador, como se indica a continuación:

  • Enrutamiento: Las solicitudes del cliente de Python en tu aplicación de controlador deben llegar al router de 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 de 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 router de zona de pruebas.
    • Si la aplicación de 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 de la zona de pruebas a los Cloud de Confiance recursos: Si el código de la zona de pruebas necesita enviar solicitudes a las Cloud de Confiance APIs, como Cloud Storage, usa una política de IAM con la federación de identidades para cargas de trabajo para 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 Cloud de Confiance by S3NS servidor de metadatos (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 estricta Secure-by-Default (networkPolicyManagement: Managed). Se aplican las siguientes restricciones en esta postura:

    • Se bloquea la entrada de todas las fuentes, excepto el router de zona de pruebas designado.
    • Se permite la salida a la Internet pública, pero se bloquea de forma explícita la salida a los rangos de LAN privada (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 la federación de identidades para cargas de trabajo para GKE o acceder a otros recursos privados, debes definir políticas de red personalizadas en SandboxTemplate. Para obtener detalles de configuración detallados y plantillas personalizables (como zonas de pruebas aisladas o integración de la federación de identidades para cargas de trabajo para GKE), consulta Administración de políticas de red de Agent Sandbox.

Políticas de seguridad de la zona de pruebas

Para garantizar un entorno Secure-by-Default, el complemento GKE Agent Sandbox usa políticas de admisión de validación (VAPs) de Kubernetes para aplicar restricciones de seguridad en los recursos Sandbox y SandboxTemplate. Estas políticas se aplican de forma automática.

El complemento divide la aplicación de seguridad en un modelo de políticas de dos niveles para una mayor flexibilidad. 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, como inhabilitar hostNetwork, y aislamiento del sistema de archivos, como bloquear hostPath. Debido a 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 seguridad de endurecimiento (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, evitar la adición de capacidades nuevas y requerir que los contenedores se ejecuten como no raíz con límites de recursos. GKE implementa esta política en el 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.

Modifica o quita las restricciones de endurecimiento

Debido a que la política de endurecimiento se implementa en el modo EnsureExists, GKE crea la política si falta, pero no anula 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 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 la política de endurecimiento por completo 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 un sidecar de malla de servicios (por ejemplo, Envoy o Istio), la política de seguridad de endurecimiento podría bloquear 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 servicios suelen usar un contenedor de inicialización, como istio-init o proxy-init. Estos contenedores de inicialización requieren capacidades como NET_ADMIN o NET_RAW para configurar iptables reglas para el enrutamiento de salida transparente. De forma predeterminada, la 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 la ValidatingAdmissionPolicy para permitir que contenedores de inicialización confiables específicos soliciten capacidades NET_ADMIN y NET_RAW. Para obtener instrucciones sobre cómo modificar o quitar estas restricciones de endurecimiento, consulta Modifica o quita las restricciones de endurecimiento. Por ejemplo, puedes actualizar las expresiones o variables de validación de la política para eximir los nombres de contenedores confiables de la regla de capacidades.

Latencia o tiempo de espera de salida cuando se conectan a 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 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 habilitado IPv6 de pila doble, la resolución de DNS para las APIs de Google muestra direcciones IPv4 (A) e IPv6 (AAAA) direcciones. Algunos algoritmos en motores de tiempo 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 IPv6 válida, como una puerta de enlace de Cloud NAT o de Internet para IPv6, la conexión TCP deja 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 recurre a IPv4.

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

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

    • Prefiere IPv4 en la carga de trabajo: 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 la 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 Cloud de Confiance by S3NS cuenta, debes borrar el clúster de GKE que creaste:

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

¿Qué sigue?