Habilita Agent Sandbox en GKE

En este documento, se explica cómo habilitar la función Agent Sandbox en un clúster de Google Kubernetes Engine (GKE). También se explica cómo crear un entorno de zona de pruebas en el clúster para ejecutar de forma segura código que no es de confianza.

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.

Para evitar cargos innecesarios, asegúrate de inhabilitar GKE o borrar el proyecto después de completar este documento.

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

3. Habilita las APIs de Artifact Registry y Google Kubernetes Engine si aún no están habilitadas.

   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 Cloud de Confiance , activa Cloud Shell.

   Activa Cloud Shell

5. Asegúrate de que tu clúster ejecute la versión 1.36.3-gke.1767000 o posterior de GKE (admite la API de v1beta1).

Define las variables de entorno

Para simplificar los comandos que ejecutas en este documento, puedes establecer 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 CLUSTER_VERSION="1.36.3-gke.1767000"
export NODE_POOL_NAME="agent-sandbox-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 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 de tu clúster de GKE, por ejemplo, agent-sandbox-cluster.
• LOCATION: La Cloud de Confiance by S3NS región o zona en la que se creó tu clúster de GKE. Establece este parámetro en la región (por ejemplo, us-central1) si creas un clúster de Autopilot o en la zona (por ejemplo, us-central1-a) si creas un clúster estándar.
• CLUSTER_VERSION: Es la versión de GKE en la que se ejecutará tu clúster (1.36.3-gke.1767000 o posterior).
• NODE_POOL_NAME: Es el nombre del grupo de nodos que ejecutará cargas de trabajo en zona de pruebas, por ejemplo, agent-sandbox-pool. Esta variable solo es obligatoria si creas un clúster de GKE estándar.
• 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. Esta variable solo es obligatoria si creas un clúster de GKE estándar.

Habilita la zona de pruebas del agente

Puedes habilitar la función Agent Sandbox cuando creas un clúster nuevo o cuando actualizas uno existente.

Habilita Agent Sandbox cuando crees un clúster de GKE nuevo

Te recomendamos que uses un clúster de Autopilot para una experiencia de Kubernetes completamente administrada. Para elegir el modo de operación de GKE que se adapte mejor a tus cargas de trabajo, consulta Elige un modo de operación de GKE.

gcloud beta container clusters create-auto ${CLUSTER_NAME} \
    --location=${LOCATION} \
    --cluster-version=${CLUSTER_VERSION} \
    --enable-agent-sandbox

Habilita Agent Sandbox cuando actualices un clúster de GKE existente

Para habilitar Agent Sandbox en un clúster existente, el clúster debe ejecutar la versión 1.36.3-gke.1767000 o una posterior, que admite la API de v1beta1.

Asegúrate de que tu variable de entorno LOCATION esté configurada en la región o zona en la que se encuentra tu clúster existente.

1. Si usas un clúster de GKE Standard, Agent Sandbox depende de gVisor. Si tu clúster estándar no tiene un grupo de nodos habilitado para gVisor, primero debes crear uno:

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

2. Actualiza el clúster para habilitar la función de zona de pruebas del agente:

   gcloud beta container clusters update ${CLUSTER_NAME} \
       --location=${LOCATION} \
       --enable-agent-sandbox
   

Verifica la configuración

Para verificar si la función Agent Sandbox está habilitada, inspecciona la descripción del clúster.

gcloud beta container clusters describe ${CLUSTER_NAME} \
    --location=${LOCATION} \
    --format="value(addonsConfig.agentSandboxConfig.enabled)"

Si creaste un clúster de Autopilot, la ubicación es la región (por ejemplo, us-central1). Si creaste un clúster estándar, la ubicación es la zona (por ejemplo, us-central1-a).

Si la función se habilita correctamente, el comando devuelve True.

Requisitos de implementación de la zona de pruebas del agente

Para implementar correctamente una carga de trabajo, como Sandbox o SandboxTemplate, tu manifiesto YAML debe incluir parámetros de configuración y seguridad específicos. GKE aplica estos requisitos con una política de admisión de validación (VAP). Si no se cumplen estos requisitos, el controlador de admisión rechaza la implementación.

Configuración obligatoria

Tu manifiesto de implementación debe incluir los siguientes parámetros de configuración:

• runtimeClassName: gvisor: Garantiza que el Pod se ejecute en una zona de pruebas de gVisor.
• automountServiceAccountToken: false: Evita que el Pod active automáticamente el token de la cuenta de servicio predeterminada.
• securityContext.runAsNonRoot: true: Garantiza que el contenedor no se ejecute como usuario raíz.
• securityContext.capabilities.drop: ["ALL"]: Descarta todas las capacidades de Linux del contenedor.
• resources.limits: Debes especificar límites de CPU y memoria para evitar posibles situaciones de denegación de servicio (DoS).
• nodeSelector: Debe segmentarse para sandbox.gke.io/runtime: gvisor.
• tolerations: Debe incluir una tolerancia para el taint sandbox.gke.io/runtime=gvisor:NoSchedule.

Configuración prohibida

Tu manifiesto de implementación no debe incluir ninguno de los siguientes elementos:

• hostNetwork: true, hostPID: true o hostIPC: true
• privileged: true en contextos de seguridad de contenedores.
• HostPath volúmenes
• Se agregaron capacidades (capabilities.add).
• Configuración de hostPort.
• Sysctls personalizados
• Son los volúmenes proyectados para los tokens o certificados de cuentas de servicio.

Implementa un entorno de zona de pruebas

Recomendamos implementar un entorno de zona de pruebas definiendo un SandboxTemplate y manteniendo listas las instancias precalentadas con un SandboxWarmPool. Luego, puedes solicitar una instancia de este grupo de nodos preparado con un SandboxClaim. Como alternativa, puedes crear un entorno de pruebas directamente, pero este enfoque no admite grupos de instancias cálidos.

SandboxTemplate, SandboxWarmPool, SandboxClaim y Sandbox son recursos personalizados de Kubernetes.

Recomendación: Crea un SandboxTemplate y un SandboxWarmPool

SandboxTemplate actúa como un esquema reutilizable. SandboxWarmPool ayuda a garantizar que una cantidad especificada de Pods preparados previamente siempre estén en ejecución y listos para ser reclamados. El uso de este recurso personalizado minimiza la latencia de inicio.

Para implementar un entorno de zona de pruebas creando SandboxTemplate y SandboxWarmPool, completa los siguientes pasos:

1. En Cloud Shell, crea un archivo llamado sandbox-template.yaml con el siguiente contenido:

   apiVersion: extensions.agents.x-k8s.io/v1beta1
   kind: SandboxTemplate
   metadata:
     name: python-runtime-template
     namespace: default
   spec:
     podTemplate:
       metadata:
         labels:
           sandbox-type: python-runtime
       spec:
         runtimeClassName: gvisor # Required
         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: runtime
           image: registry.k8s.io/agent-sandbox/python-runtime-sandbox:v0.1.0
           ports:
           - containerPort: 8888
           resources:
             requests:
               cpu: "250m"
               memory: "512Mi"
             limits:
               cpu: "500m"
               memory: "1Gi" # Required
           securityContext:
             capabilities:
               drop: ["ALL"] # Required
         restartPolicy: OnFailure
   

2. Aplica el manifiesto SandboxTemplate:

   kubectl apply -f sandbox-template.yaml
   

3. Crea un archivo llamado sandbox-warmpool.yaml con el siguiente contenido:

   apiVersion: extensions.agents.x-k8s.io/v1beta1
   kind: SandboxWarmPool
   metadata:
     name: python-runtime-warmpool
     namespace: default
     labels:
       app: python-runtime-warmpool
   spec:
     replicas: 2
     sandboxTemplateRef:
       # This must match the name of the SandboxTemplate.
       name: python-runtime-template
   

4. Aplica el manifiesto SandboxWarmPool:

   kubectl apply -f sandbox-warmpool.yaml
   

Crea un SandboxClaim

SandboxClaim solicita una zona de pruebas del grupo preparado. Como creaste un grupo de nodos cálido, el Sandbox creado adopta un Pod en ejecución del grupo en lugar de iniciar un Pod nuevo.

Para solicitar un entorno de pruebas de la reserva activa creando un SandboxClaim, completa los siguientes pasos:

1. Crea un archivo llamado sandbox-claim.yaml con el siguiente contenido:

   apiVersion: extensions.agents.x-k8s.io/v1beta1
   kind: SandboxClaim
   metadata:
     name: sandbox-claim
     namespace: default
   spec:
     warmPoolRef:
       # This must match the name of the SandboxWarmPool.
       name: python-runtime-warmpool
   

2. Aplica el manifiesto SandboxClaim:

   kubectl apply -f sandbox-claim.yaml
   

3. Verifica que el entorno de pruebas, el reclamo y el grupo de instancias en espera estén listos:

   kubectl get sandboxwarmpool,sandboxclaim,sandbox,pod
   

Alternativa: Crea una zona de pruebas directamente

Si no necesitas los tiempos de inicio rápidos que proporcionan los grupos de instancias activas, puedes implementar una zona de pruebas directamente sin usar plantillas.

Para implementar un entorno de zona de pruebas creando una zona de pruebas directamente, completa los siguientes pasos:

1. Crea un archivo llamado sandbox.yaml con el siguiente contenido:

   apiVersion: agents.x-k8s.io/v1beta1
   kind: Sandbox
   metadata:
     name: sandbox-example-2
   spec:
     replicas: 1
     podTemplate:
       metadata:
         labels:
           sandbox: sandbox-example
       spec:
         runtimeClassName: gvisor
         restartPolicy: OnFailure
         automountServiceAccountToken: false # Required
         securityContext:
           runAsNonRoot: true # Required
           runAsUser: 1000 # Required if image defaults to root (e.g. busybox)
         nodeSelector:
           sandbox.gke.io/runtime: gvisor
         tolerations:
         - key: "sandbox.gke.io/runtime"
           value: "gvisor"
           effect: "NoSchedule" # Required
         containers:
         - name: my-container
           image: busybox
           command: ["/bin/sh", "-c"]
           args: ["sleep 3600000; echo 'Container finished successfully'; exit 0"]
           securityContext:
             capabilities:
               drop: ["ALL"] # Required
             allowPrivilegeEscalation: false
           resources:
             limits:
               cpu: "100m"
               memory: "128Mi" # Required
   

2. Aplica el manifiesto Sandbox:

   kubectl apply -f sandbox.yaml
   

3. Verifica que el sandbox se esté ejecutando:

   kubectl get sandbox
   

Migra la zona de pruebas del agente de v1alpha1 a v1beta1

Si tu clúster se implementó con una versión anterior de Agent Sandbox usando recursos personalizados de v1alpha1, puedes actualizar a la versión 1.36.3-gke.1767000 de GKE o una posterior con un tiempo de inactividad de la carga de trabajo casi nulo.

Nota: Este procedimiento de migración se aplica a los clústeres que usan la función administrada de GKE Agent Sandbox (--enable-agent-sandbox). Si implementaste Agent Sandbox con manifiestos de código abierto, consulta la guía de migración upstream.

Principales diferencias entre las APIs de v1alpha1 y v1beta1

Migra con la herramienta de migración

Para crear automáticamente grupos de nodos cálidos secundarios y volver a conservar el almacenamiento, usa la secuencia de comandos de migración canónica del repositorio de Agent Sandbox.

Descarga y prepara la secuencia de comandos:

curl -LO https://raw.githubusercontent.com/kubernetes-sigs/agent-sandbox/v0.5.6/helm/files/migrate.sh
chmod +x migrate.sh

Manual de ejecución de la migración paso a paso

Para migrar un clúster existente con un tiempo de inactividad de la carga de trabajo casi nulo, completa las siguientes tres fases en orden:

Fase 1: Fase de arranque previa a la actualización

1. Crea una copia de seguridad de los recursos existentes: Guarda una copia de seguridad en formato YAML de tus recursos declarativos de Agent Sandbox (sandboxtemplates, sandboxwarmpools y sandboxclaims):

   kubectl get sandboxtemplates,sandboxwarmpools,sandboxclaims \
       --all-namespaces -o yaml > agent-sandbox-v1alpha1-backup.yaml
   

2. Verifica el cumplimiento de la seguridad de la plantilla: Asegúrate de que los recursos SandboxTemplate existentes cumplan con los requisitos de implementación de Agent Sandbox. Durante la migración del almacenamiento en la fase 3, el controlador de admisión rechaza las actualizaciones de las plantillas que no cumplen con estas políticas de seguridad.

3. Obtén una vista previa de los grupos de nodos secundarios que se crearán:

   ./migrate.sh --phase=bootstrap --dry-run
   

4. Ejecuta la fase de arranque:

   ./migrate.sh --phase=bootstrap
   

5. Verifica los grupos de instancias virtuales creados:

   kubectl get sandboxwarmpools --all-namespaces \
       -o custom-columns="NAMESPACE:.metadata.namespace,NAME:.metadata.name,REPLICAS:.spec.replicas,SHADOW:.metadata.annotations.agents\.x-k8s\.io/migration-shadow"
   

Fase 2: Actualiza el plano de control de GKE

Actualiza el plano de control de GKE a la versión 1.36.3-gke.1767000 o posterior:

gcloud container clusters upgrade ${CLUSTER_NAME} \
    --location=${LOCATION} \
    --master \
    --cluster-version=1.36.3-gke.1767000

Durante el lanzamiento del plano de control, ten en cuenta lo siguiente:

• Los Pods no experimentan reinicios ni tiempo de inactividad.
• El nuevo controlador y el extremo del webhook /convert se implementan en el plano de control.

Fase 3: Migración del almacenamiento posterior a la actualización

Una vez que se complete la actualización del plano de control, actualiza tus credenciales y vuelve a escribir los objetos etcd almacenados ejecutando la fase de migración del almacenamiento:

./migrate.sh --phase=migrate

Lista de verificación posterior a la migración

Si un CustomResourceDefinition sigue mostrando ["v1alpha1", "v1beta1"] en .status.storedVersions después de que se complete la fase de migración, este es el comportamiento esperado de Kubernetes. La secuencia de comandos de migración reescribe todos los registros existentes en v1beta1 en etcd, pero Kubernetes no quita automáticamente las versiones obsoletas de la lista status.storedVersions.

Después de confirmar que se migraron todos los recursos, puedes, de manera opcional, quitar v1alpha1 de las versiones almacenadas:

for crd in \
    sandboxes.agents.x-k8s.io \
    sandboxclaims.extensions.agents.x-k8s.io \
    sandboxtemplates.extensions.agents.x-k8s.io \
    sandboxwarmpools.extensions.agents.x-k8s.io; do
  kubectl patch crd "${crd}" --subresource=status --type=merge \
    -p '{"status":{"storedVersions":["v1beta1"]}}'
done

Soluciona problemas de migración

Si tienes problemas después de actualizar el plano de control o ejecutar la migración del almacenamiento, resuélvelos en lugar de intentar cambiar a una versión inferior del plano de control:

• El reclamo se quedó atascado en WarmPoolNotFound:

  • Si se actualizó un reclamo de v1alpha1 inicio en frío sin ejecutar ./migrate.sh --phase=bootstrap, crea manualmente el grupo semicaliente de sombra faltante:

    apiVersion: extensions.agents.x-k8s.io/v1beta1
    kind: SandboxWarmPool
    metadata:
      name: shadow-pool-TEMPLATE_NAME
      namespace: NAMESPACE
      annotations:
        agents.x-k8s.io/migration-shadow: "true"
    spec:
      replicas: 0
      sandboxTemplateRef:
        name: TEMPLATE_NAME
    

  • Si un reclamo menciona un grupo de instancias en espera específico que ya no existe, crea el recurso SandboxWarmPool faltante con ese nombre o actualiza spec.warmPoolRef.name en el reclamo para hacer referencia a un grupo de instancias en espera existente.

• Condición del reclamo Ready=False: Ejecuta kubectl describe sandboxclaim para inspeccionar los eventos del reclamo. Asegúrate de que el SandboxTemplate al que se hace referencia cumpla con todos los requisitos de implementación de Agent Sandbox y vuelve a aplicar la plantilla si es necesario.

• Errores de conversión o de controlador: Para verificar que el arrendamiento de elección del líder del plano de control esté activo, ejecuta kubectl get leases -n gke-managed-agentsandbox. Si los problemas persisten, comunícate con Atención al cliente de Cloud.

Inhabilita la zona de pruebas del agente

Para inhabilitar la función de Agent Sandbox, usa el comando gcloud beta container clusters update con la marca --no-enable-agent-sandbox.

gcloud beta container clusters update ${CLUSTER_NAME} \
    --location=${LOCATION} \
    --no-enable-agent-sandbox

Si creaste un clúster de Autopilot, la ubicación es la región (por ejemplo, us-central1). Si creaste un clúster estándar, la ubicación es la zona (por ejemplo, us-central1-a).

Limpia los recursos

Para evitar que se apliquen cargos a tu cuenta de Cloud de Confiance by S3NS , borra el clúster de GKE que creaste.

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

Si creaste un clúster de Autopilot, la ubicación es la región (por ejemplo, us-central1). Si creaste un clúster estándar, la ubicación es la zona (por ejemplo, us-central1-a).

¿Qué sigue?

• Obtén más información para guardar y restablecer entornos de la zona de pruebas del agente con instantáneas de Pods.
• Obtén información sobre la tecnología subyacente que usa Agent Sandbox.
• Obtén más información sobre la seguridad de GKE.
• Explora el proyecto de código abierto de Agent Sandbox en GitHub.
• Obtén más información para usar Kata Containers de código abierto con Agent Sandbox. Kata Containers no es un Cloud de Confiance producto. 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 los Kata Containers.