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 código no confiable de forma segura.

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.

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 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.
    • 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 Google Cloud .

  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 Google Cloud , 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 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 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 de Google Cloud actual. 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: Es la región o zona de Google Cloud en la que se crea 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 que 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 necesaria si creas un clúster de GKE Standard.
  • MACHINE_TYPE: el tipo de máquina de los nodos del 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 Agent Sandbox

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.

Autopilot

Para crear un clúster de GKE Autopilot nuevo con Agent Sandbox habilitado, incluye la marca --enable-agent-sandbox:

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

En el caso de un clúster de Autopilot, asegúrate de que la variable de entorno LOCATION esté configurada en una región (por ejemplo, us-central1).

Estándar

Para crear un clúster de GKE Standard nuevo con Agent Sandbox habilitado, debes crear el clúster, agregar un grupo de nodos con gVisor habilitado y, luego, habilitar la función de Agent Sandbox. Para ahorrar costos, te recomendamos que crees un clúster zonal con un solo nodo por grupo:

  1. Crea el clúster:

    gcloud beta container clusters create ${CLUSTER_NAME} \
    --location=${LOCATION} \
    --num-nodes=1 \
    --cluster-version=${CLUSTER_VERSION}

    Para este clúster de Standard, asegúrate de que la variable de entorno LOCATION esté configurada en una zona (por ejemplo, us-central1-a).

  2. Crea un grupo de nodos independiente con gVisor habilitado:

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

    El valor de LOCATION debe ser la misma zona que usaste cuando creaste el clúster.

  3. Actualiza el clúster para habilitar la función de Agent Sandbox:

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

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

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

Asegúrate de que la variable de entorno LOCATION esté configurada en la región o zona donde 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 Agent Sandbox:

    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 de Standard, 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 los límites de CPU y memoria para evitar posibles situaciones de denegación del 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 de volúmenes.
  • Se agregaron capacidades (capabilities.add).
  • Configuración de hostPort.
  • Sysctls personalizados
  • Volúmenes proyectados para 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 una zona de pruebas directamente, pero este enfoque no admite grupos de preparación.

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

SandboxTemplate actúa como un esquema reutilizable. SandboxWarmPool ayuda a garantizar que una cantidad especificada de Pods preparados previamente siempre se ejecute y esté lista para reclamarse. 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 de preparación. Como creaste un grupo de nodos en espera, 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 entorno de pruebas 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

Concepto Comportamiento de v1alpha1 Comportamiento de v1beta1 Impacto de la migración
Destinos de SandboxClaim Se permite la referencia directa a SandboxTemplate sin un grupo de instancias en espera (inicio en frío). Requiere una referencia a un SandboxWarmPool (spec.warmPoolRef.name). Los reclamos de inicio en frío se deben asignar a un grupo preparado secundario (replicas: 0).
Modo de operación de la zona de pruebas Se infiere a partir de los campos de réplicas o de estado. Valor explícito para el campo spec.operatingMode (como Running o Suspended) El webhook de conversión asigna y establece automáticamente este campo.
Versión de almacenamiento de CustomResourceDefinition v1alpha1 almacenado en etcd (storage: true). v1beta1 almacenado en etcd (storage: true). El webhook se convierte de forma dinámica; el paso posterior a la actualización vuelve a conservar los objetos de etcd.
Webhook de conversión Ninguno Activo en /convert (puerto 9447) Es una conversión bidireccional entre v1alpha1 y v1beta1.

Migra con la herramienta de migración

Para crear automáticamente grupos de preparación de sombra y volver a conservar el almacenamiento persistente, 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 los 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 sombra 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 servidores de respaldo 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 se reinician ni tienen 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 tareas de verificación posterior a la migración

Marcar elemento Comando Resultado esperado
Versiones de almacenamiento de CustomResourceDefinition kubectl get crd sandboxes.agents.x-k8s.io sandboxclaims.extensions.agents.x-k8s.io sandboxtemplates.extensions.agents.x-k8s.io sandboxwarmpools.extensions.agents.x-k8s.io -o jsonpath='{range .items[*]}{.metadata.name}{": storedVersions="}{.status.storedVersions}{"\n"}{end}' Se muestran los 4 CustomResourceDefinitions:
storedVersions=["v1beta1"]
Continuidad del grupo de anuncios kubectl get pods -n default -o wide Status: 1/1 Running
Restarts: 0
(se aplica a los clústeres con zonas de pruebas en ejecución activas)
Vinculación de reclamos kubectl get sandboxclaims -n default -o yaml spec.warmPoolRef.name: shadow-pool-...
status.conditions: Ready=True (requiere que la plantilla cumpla con los requisitos de admisión)
Compatibilidad con v1alpha1 kubectl get sandboxes.v1alpha1.agents.x-k8s.io Muestra una advertencia de baja y devuelve el recurso
CRUD nativo de v1beta1 kubectl apply -f sandbox-claim.yaml Se aplica con 0 advertencias

Si un CustomResourceDefinition sigue mostrando ["v1alpha1", "v1beta1"] en .status.storedVersions después de que se complete la fase de migración, se trata del 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 de almacenamiento, resuélvelos en lugar de intentar cambiar a una versión anterior del plano de control:

  • El reclamo está 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 una reclamación nombró un grupo de preparación específico que ya no existe, crea el recurso SandboxWarmPool faltante con ese nombre o actualiza spec.warmPoolRef.name en la reclamación para hacer referencia a un grupo de preparación 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 la zona de pruebas del agente y vuelve a aplicar la plantilla si es necesario.

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

Inhabilitar la zona de pruebas del agente

Para inhabilitar la función de zona de pruebas del agente, 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 Google Cloud , 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?