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
-
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 permisoresourcemanager.projects.create. Obtén más información para otorgar roles.
-
Verifica que la facturación esté habilitada para tu proyecto de Cloud de Confiance .
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.-
En la consola de Cloud de Confiance , activa Cloud Shell.
- Verifica que tengas los permisos necesarios para completar este documento.
- 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:
- Define las variables de entorno.
- Cree un clúster de GKE
- Instala Agent Sandbox
- Implementa el router de la zona de pruebas
SandboxTemplateySandboxWarmPool.
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:
En Cloud Shell, crea un archivo llamado
sandbox-template-and-pool.yamlcon 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-templateAplica el manifiesto
SandboxTemplateySandboxWarmPool:kubectl apply -f sandbox-template-and-pool.yamlEspera 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=600sMá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:
Crea y activa un entorno virtual de Python:
python3 -m venv .venv source .venv/bin/activateInstala 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.
Crea una secuencia de comandos de Python llamada
test_sandbox.pycon 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}")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
SandboxDirectConnectionConfigpara 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
SandboxGatewayConnectionConfigpara 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.
- Si la aplicación del controlador se ejecuta en el mismo clúster, usa la
función
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-routeren el espacio de nombresagent-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.- La entrada se bloquea desde todas las fuentes, excepto el router de la zona de pruebas
designado (Pods que tienen la etiqueta
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-initoproxy-init. Estos contenedores de inicialización requieren capacidades comoNET_ADMINoNET_RAWpara configurar reglas deiptablespara el enrutamiento de salida transparente. La ValidatingAdmissionPolicysecure-sandbox-policybloquea 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
ValidatingAdmissionPolicypara permitir que contenedores de inicialización de confianza específicos soliciten las capacidadesNET_ADMINyNET_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?
- Obtén información para guardar y restablecer Agent Sandbox en entornos de GKE con instantáneas de Pods.
- Obtén más información sobre el proyecto de código abierto de Agent Sandbox en GitHub.
- Obtén información para usar Kata Containers de código abierto con Agent Sandbox en GKE. Kata Containers no es un producto de Cloud de Confiance . Si instalas y usas este software, eres responsable de la administración y la solución de problemas. La asistencia y los ANS de Google no se aplican a Kata Containers.
- Para comprender la tecnología subyacente que proporciona aislamiento de seguridad para 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 la descripción general de la seguridad de GKE.