Instala Agent Substrate en GKE

Agent Substrate en GKE ejecuta cargas de trabajo de agentes de forma eficiente en clústeres de GKE: tu aplicación suspende los agentes inactivos y el sistema los restablece cuando necesitan volver a actuar. Agent Substrate en GKE es un software de código abierto que puedes instalar en un clúster de GKE Standard. Para comparar Agent Substrate en GKE con Agent Sandbox en GKE y elegir una arquitectura para tus cargas de trabajo de agentes de IA, consulta Planifica una arquitectura para cargas de trabajo de agentes de IA en GKE.

Este documento te ayuda a preparar tu proyecto de Google Cloud y el clúster de GKE para Agent Substrate en GKE, explica cómo ejecutar el instalador y describe los recursos que crea la instalación.

Precios

Agent Substrate en GKE se ofrece sin cargo adicional. Los precios de GKE se aplican a los recursos que creas.

Limitaciones

Agent Substrate en GKE tiene las siguientes limitaciones de instalación:

  • Cloud Shell: No puedes instalar Agent Substrate en GKE en Cloud Shell porque Cloud Shell proporciona 5 GB de almacenamiento en disco persistente, lo que no es suficiente para la instalación. Debes ejecutar el instalador en tu máquina local.
  • Modo del clúster: Puedes instalar Agent Substrate en GKE solo en clústeres de GKE Standard. Los clústeres de Autopilot no son compatibles.
  • Versión del clúster: Tanto el plano de control como los grupos de nodos de tu clúster deben ejecutar la versión 1.37 o posterior de GKE. No se admiten las versiones anteriores a la 1.37.
  • Canal de versiones: No puedes instalar Agent Substrate en GKE en clústeres que estén inscritos en el canal de versiones extendido. El instalador habilita las APIs beta de Kubernetes en tu clúster, y el canal extendido no admite APIs beta habilitadas de forma explícita.
  • Tipos de máquinas: No puedes usar series de máquinas que se ejecuten en arquitecturas de CPU mixtas (como los tipos de máquinas E2).

Antes de comenzar

Antes de comenzar, asegúrate de haber realizado las siguientes tareas:

  • Habilita la API de Google Kubernetes Engine.
  • Habilitar la API de Google Kubernetes Engine
  • Para usar Google Cloud CLI en esta tarea, instala y, luego, inicializa la gcloud CLI. Si ya instalaste gcloud CLI, ejecuta el comando gcloud components update para obtener la versión más reciente. Es posible que las versiones anteriores de gcloud CLI no admitan la ejecución de los comandos de este documento.
  • Instala los siguientes componentes en gcloud CLI:
    • kubectl
    • gke-gcloud-auth-plugin
  • Asegúrate de que las siguientes herramientas estén instaladas en tu máquina local:
    • Git para clonar el repositorio de Agent Substrate.
    • Go para ejecutar los programas del instalador, que se distribuyen como código fuente.
    • make para iniciar el instalador.
    • Docker y su complemento Buildx para compilar las imágenes de contenedor de Agent Substrate en GKE.
    • sha256sum, zstd, unzip y jq para configurar el entorno de ejecución de microVM, si planeas usarlo. El instalador no ofrece el entorno de ejecución de microVM si falta alguna de estas herramientas.
  • Para permitir que el instalador envíe las imágenes que compila, configura Docker para que se autentique en Artifact Registry en la región de tu clúster:

    gcloud auth configure-docker REGION-docker.pkg.dev
    

    Reemplaza REGION por la región de tu clúster, como us-west1. Para obtener más información, consulta Configura la autenticación en Artifact Registry para Docker.

  • Debido a que el instalador actúa en tu nombre para habilitar las APIs y aprovisionar recursos, configura las credenciales predeterminadas de la aplicación (ADC) ejecutando el siguiente comando:

    gcloud auth application-default login
    

    Para obtener más información sobre la autenticación con ADC, consulta Configura las credenciales predeterminadas de la aplicación.

Roles obligatorios

Para obtener los permisos que necesitas para instalar Agent Substrate en GKE, pídele a tu administrador que te otorgue los siguientes roles de IAM 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.

Requisitos del clúster

Si dejas que el instalador cree un clúster por ti, este configurará automáticamente un clúster que cumpla con todos los requisitos de Agent Substrate en GKE.

Si, en cambio, eliges instalar Agent Substrate en GKE en un clúster existente, ese clúster debe cumplir con los siguientes requisitos:

  • Se ejecuta en GKE Standard (Agent Substrate en GKE solo es compatible con clústeres de Standard).
  • Ejecuta la versión 1.37 o posterior de GKE tanto en el plano de control como en los grupos de nodos. Si el plano de control ejecuta una versión anterior, primero actualiza el plano de control. Luego, actualiza los grupos de nodos que ejecutan una versión anterior para que los nodos puedan activar los certificados de Pod en los Pods.
  • No está inscrito en el canal de versiones extendido. Para obtener más información, consulta Limitaciones.
  • Usa GKE Dataplane V2.
  • Usa tipos de máquinas c3-standard-4 o más grandes para los nodos.
  • Si planeas ejecutar más de 800 zonas de pruebas simultáneas por nodo, el clúster usa nodos que tienen límites más altos en el kernel de Linux para la supervisión del sistema de archivos (inotify) y para la tabla de vecinos del protocolo de resolución de direcciones (ARP). Sin estos límites más altos, es posible que las zonas de pruebas no se inicien y que las redes se detengan. Los nodos necesitan la siguiente configuración de kernel:

    • net.ipv4.neigh.default.gc_thresh1: 4096
    • net.ipv4.neigh.default.gc_thresh2: 16384
    • net.ipv4.neigh.default.gc_thresh3: 32768
    • fs.inotify.max_user_instances: 65536
    • fs.inotify.max_user_watches: 1048576

    El instalador aplica estos parámetros de configuración de forma automática solo a los clústeres que crea. Para aplicar estos parámetros de configuración a los grupos de nodos de un clúster existente, usa una configuración del sistema de nodos. Para obtener más información, consulta las opciones de configuración de sysctl.

Instala Agent Substrate en GKE

Para instalar Agent Substrate en GKE, ejecuta uno de los siguientes comandos en tu terminal local:

  • Para instalarlo en tus propias cargas de trabajo, ejecuta el siguiente comando:

    curl -sSL https://raw.githubusercontent.com/ai-on-gke/substrate-gke/main/install.sh | bash
    
  • Para instalar y, luego, probar la demostración de Counter, ejecuta el siguiente comando:

    curl -sSL https://raw.githubusercontent.com/ai-on-gke/substrate-gke/main/install.sh | bash -s -- --demo
    

El instalador interactivo te solicita las imágenes de contenedor y la configuración del proyecto, el clúster, el almacenamiento y la entrada. El instalador sugiere valores predeterminados recomendados siempre que sea posible, que puedes aceptar o personalizar:

  • Imágenes de contenedor (obligatorio): Cuando el instalador te pida que elijas tus imágenes, selecciona Compilar desde la fuente. El instalador compila las imágenes desde el repositorio de Agent Substrate ascendente y las envía a un repositorio de Artifact Registry en tu proyecto. De forma predeterminada, el instalador compila la versión más reciente de Agent Substrate. Para compilar una versión diferente, ingresa una rama, una etiqueta o un SHA de confirmación completo desde el repositorio upstream.
  • ID del proyecto (obligatorio): Especifica el proyecto de Google Cloud en el que se aprovisionarán los recursos. Si configuraste un proyecto predeterminado para la gcloud CLI, el instalador usará ese ID del proyecto.
  • Clúster (obligatorio): Elige si quieres que el instalador cree un nuevo clúster de GKE con la configuración predeterminada recomendada o si quieres instalar Agent Substrate en GKE en un clúster existente. Si decides instalarlo en un clúster existente, verifica que cumpla con los requisitos de la sección Requisitos del clúster.
  • Snapshot bucket (opcional): Especifica un nombre de bucket de Cloud Storage personalizado o déjalo en blanco para que el instalador cree un bucket predeterminado llamado ate-snapshots-<project>-<cluster>-<zone>. Debido a que el nombre predeterminado incluye el nombre del clúster, los clústeres del mismo proyecto y de la misma zona no comparten un bucket. Un nombre personalizado puede tener hasta 56 caracteres, ya que el instalador también crea un bucket de recursos agregando el sufijo -assets al nombre, y los nombres de los buckets pueden tener hasta 63 caracteres. Si el nombre predeterminado tiene más de 56 caracteres, el instalador lo acorta y agrega un hash.
  • Clientes de Ingress (obligatorio): Ingresa los IDs de SPIFFE de las cargas de trabajo que envían solicitudes a tus Actors, como el servicio de frontend o el servicio de backend de tu aplicación. Un ID de SPIFFE identifica una carga de trabajo por el espacio de nombres y la cuenta de servicio de Kubernetes como la que se ejecutan sus Pods. Por ejemplo, los Pods que se ejecutan en el espacio de nombres shop como la cuenta de servicio frontend tienen el ID de SPIFFE spiffe://cluster.local/ns/shop/sa/frontend. Debido a que el ID solo depende del espacio de nombres y de la cuenta de servicio, puedes ingresar IDs para los clientes que aún no implementaste. Si ingresas varios IDs, sepáralos con comas. Las solicitudes llegan a tus Actores a través de un router de entrada, que solo admite clientes que presentan un certificado de Pod cuyo ID de SPIFFE está en esta lista. Cualquier cliente de la lista puede comunicarse con cualquier actor. Si incluyes la marca --demo, el instalador solo permitirá los Pods de la demostración de Counter en lugar de solicitar IDs. Para agregar clientes después de la instalación, consulta Cómo llegar a los actores a través del router de entrada en el archivo README de substrate-gke.

Qué hace el instalador

El instalador ejecuta los siguientes programas en tu nombre:

  • setup-gcp: Crea o verifica los recursos de Google Cloud necesarios, habilita las APIs, crea el clúster de GKE (si elegiste no usar un clúster existente) y el bucket de Cloud Storage, y configura las políticas de IAM.
  • ate-setup: Implementa las imágenes de contenedor y los controladores de Agent Substrate en GKE en tu clúster de GKE.

Primero, el instalador realiza los siguientes cambios en tu proyecto de Google Cloud :

  1. Habilita las APIs de Google Cloud que Agent Substrate necesita en GKE.
  2. Crea un clúster de GKE Standard (si no usas un clúster existente) que ejecute la versión 1.37 o posterior y tenga los siguientes parámetros de configuración:
    • Workload Identity Federation for GKE: Permite que Agent Substrate en GKE acceda a Cloud Storage sin almacenar claves en los nodos.
    • GKE Dataplane V2: Controla las herramientas de redes necesarias para enrutar las solicitudes entrantes a tus agentes.
    • OpenTelemetry administrado: Recopila métricas y seguimientos de tu clúster.
  3. Crea los buckets de Cloud Storage que usa Agent Substrate en GKE: uno para tus instantáneas y otro para los archivos que necesita el entorno de ejecución de microVM. El nombre del segundo bucket es el nombre del bucket de instantáneas seguido del sufijo -assets.
  4. Crea un repositorio de Artifact Registry llamado ate-images para las imágenes de contenedor que compila el instalador.
  5. Crea una cuenta de servicio llamada ate-snapshot-transfer que Agent Substrate en GKE usa para transferir instantáneas.
  6. Otorga a los nodos de GKE, a los componentes de Agent Substrate en GKE y a la cuenta de servicio de ate-snapshot-transfer los permisos de IAM que necesitan para acceder a los buckets y a las imágenes de contenedor.
  7. Crea paneles de Cloud Monitoring que grafican la latencia de enrutamiento, el tamaño de las instantáneas y el tráfico de gRPC de Agent Substrate en GKE.

Luego, el instalador realiza los siguientes cambios en tu clúster:

  1. Agrega los recursos personalizados de Kubernetes de Agent Substrate en GKE a tu clúster, como WorkerPool (que define cuántas zonas de pruebas inactivas permanecen listas) y SandboxConfig (que define un entorno de ejecución de zona de pruebas). Otros recursos de Agent Substrate en GKE, como ActorTemplate (que define las imágenes de contenedor y los recursos que usan tus agentes) y los actores, no son recursos de Kubernetes. Los administras a través de la API de Agent Substrate en GKE con el complemento kubectl ate, un complemento de kubectl para administrar Actors y Workers. Para instalar el complemento, consulta Instala el complemento de kubectl ate.
  2. Configura las autoridades certificadoras que emiten los certificados que identifican Agent Substrate en los componentes de GKE y tus actores. Los componentes presentan estos certificados para autenticarse entre sí con mTLS.
  3. Implementa Agent Substrate en los componentes de GKE en tu clúster, junto con una base de datos de PostgreSQL que hace un seguimiento del estado de tus actores y trabajadores. La base de datos almacena sus datos en un disco persistente de 500 GiB. El instalador espera a que la base de datos y todos los Pods del plano de control estén listos. En el caso de los clústeres de producción, puedes aislar la base de datos de PostgreSQL y los componentes de la infraestructura del sistema en grupos de nodos dedicados antes de ejecutar el instalador. Para obtener instrucciones, consulta Aísla la infraestructura del sistema y los nodo trabajador trabajadores.

Agent Substrate en GKE implementa sus componentes como cargas de trabajo comunes dentro de los espacios de nombres ate-system y podcertificate-controller-system. Si realizas la instalación en un clúster existente, el instalador también actualiza el clúster para activar las siguientes funciones si están desactivadas: Workload Identity Federation for GKE, OpenTelemetry administrado y las versiones beta de las APIs de Kubernetes podcertificaterequests y clustertrustbundles. Activar las APIs de versión beta actualiza el plano de control de GKE, lo que tarda alrededor de 10 minutos.

Los componentes que se implementan incluyen el entorno de ejecución basado en gVisor que Agent Substrate en GKE usa de forma predeterminada para aislar cada uno de tus agentes del nodo en el que se ejecuta. Si eliges el entorno de ejecución de microVM durante los pasos opcionales, el instalador también sube los archivos que necesita el entorno de ejecución de microVM a Cloud Storage y aplica un recurso SandboxConfig para todo el clúster llamado microvm que apunta a esos archivos.

Los trabajadores que usan el entorno de ejecución de microVM necesitan nodos que puedan ejecutar máquinas virtuales. Cuando el instalador crea un clúster, el grupo de nodos que crea tiene habilitada la virtualización anidada. Si eliges la configuración Avanzada y cambias el tipo de máquina, elige una serie de máquinas que admita la virtualización anidada, como C3, C4, N2 o N4.

Si instalas Agent Substrate en GKE en un clúster existente, el instalador no agrega grupos de nodos al clúster. Para usar el entorno de ejecución de microVM, el clúster necesita un grupo de nodos que tenga habilitada la virtualización anidada o que use un tipo de máquina de equipos físicos x86. Solo puedes habilitar la virtualización anidada cuando creas un grupo de nodos. Si el clúster no tiene ese grupo de nodos, el instalador te advertirá cuando elijas el entorno de ejecución de microVM. Si continúas, los trabajadores de microVM permanecerán en el estado Pending. Para obtener más información sobre cómo configurar estos grupos de nodos, incluidos los taints, consulta Entornos de ejecución de zona de pruebas en el archivo README de substrate-gke.

Si la instalación falla en algún punto (por ejemplo, debido a un error de red transitorio o al vencimiento del token), vuelve a ejecutar el comando. El instalador conserva los recursos existentes y se reanuda desde donde se detuvo.

Para actualizar una instalación existente de Agent Substrate en GKE, ejecuta el instalador y selecciona Actualizar un clúster instalado. Esta opción no cambia tu clúster. En cambio, el instalador descarga el código fuente de la versión instalada y de la versión a la que actualizas, y prepara el directorio ~/ate-upgrade que usa la guía de actualización. Para realizar la actualización, ejecuta el comando que imprime el instalador y, luego, sigue el runbook de actualización en el repositorio upstream de Agent Substrate del primer paso. La guía de runbook admite actualizaciones a una versión de parche posterior de la misma versión secundaria y, para la versión 1.0 y posteriores, a la siguiente versión secundaria. Para las versiones anteriores a la 1.0, pasar a una versión secundaria posterior requiere una reinstalación. Para obtener más información, consulta Actualiza un clúster instalado en el archivo README de substrate-gke.

Pasos opcionales

Después de implementar los componentes principales, el instalador ofrece los siguientes pasos opcionales:

  • Controlador de CSI de Filestore: Instala el controlador de CSI de Filestore configurado para Agent Substrate en GKE. Elige esta opción si tus agentes necesitan almacenamiento persistente que permanezca disponible cuando un agente se reanude en un nodo diferente. Cada agente obtiene su propio almacenamiento, que no se comparte con otros agentes. La compatibilidad de producción para los volúmenes de agentes de Filestore tiene una DG limitada, por lo que debes solicitar acceso. Para obtener más detalles, consulta Usa volúmenes de agentes de Filestore con Agent Substrate en GKE. Si tu clúster tiene habilitado el complemento de Filestore de GKE administrado, el instalador lo inhabilita antes de implementar el controlador. El instalador implementa el controlador en el espacio de nombres gcp-filestore-csi-driver y crea una cuenta de servicio llamada substrate-filestore-csi, que tiene los permisos de IAM que necesita el controlador.
  • Ajuste de escala automático del grupo de nodos: habilita el ajuste de escala automático del clúster de GKE en tu grupo de nodos. Debes especificar la cantidad mínima y máxima de nodos para el grupo. Elige esta opción si quieres que GKE agregue nodos de forma automática durante los aumentos de demanda y quite nodos cuando se suspendan los agentes. Omite esta opción si prefieres un recuento de nodos fijo con costos de procesamiento predecibles. Para configurar el resguardo de hardware automatizado con ComputeClasses personalizadas, búferes de capacidad en espera y protecciones de reducción de escala vertical para los actores activos, consulta Diseña tu infraestructura para Agent Substrate en GKE.
  • Entorno de ejecución de la zona de pruebas: Te permite elegir el entorno de ejecución que aísla a tus agentes. El instalador instala el entorno de ejecución de gVisor como parte de los componentes principales, por lo que el entorno de ejecución de gVisor no necesita configuración adicional. Si deseas un aislamiento que use la virtualización de hardware, elige el entorno de ejecución de microVM. Antes de elegir esta opción para un clúster existente, asegúrate de que el clúster tenga un grupo de nodos que tenga habilitada la virtualización anidada o que use un tipo de máquina bare metal x86. Para obtener más información, consulta Qué hace el instalador.
  • Demostración de contador: Implementa una carga de trabajo de ejemplo que muestra la suspensión y el restablecimiento del agente. Este paso solo aparece si incluyes la marca --demo cuando inicias el instalador. Elige esta opción si deseas probar el clúster después de la instalación. Para obtener más detalles, consulta Prueba la demostración de Counter.

Verifique la instalación

Para verificar que la instalación se haya realizado correctamente y que los componentes principales se estén ejecutando, ejecuta los siguientes comandos y asegúrate de que todos los Pods tengan el estado Running:

kubectl get pods -n ate-system
kubectl get pods -n podcertificate-controller-system

Instala el complemento de kubectl ate

Para administrar los actores y los recursos de ActorTemplate, instala el complemento de kubectl ate desde el código fuente de la versión de Agent Substrate que instalaste:

git clone --depth 1 --branch VERSION https://github.com/agent-substrate/substrate.git
cd substrate
go install ./cmd/kubectl-ate

Reemplaza VERSION por la versión de Agent Substrate que instalaste, como v1.0.0, la versión predeterminada del instalador.

El comando go install coloca el complemento en el directorio bin de tu espacio de trabajo de Go. La herramienta kubectl encuentra el complemento solo si ese directorio está en tu variable de entorno PATH. Si tu variable de entorno PATH no incluye ese directorio, agrégalo antes de ejecutar cualquier comando de kubectl ate:

export PATH="$PATH:$(go env GOPATH)/bin"

Prueba la demostración de Counter

Si incluiste la marca --demo cuando ejecutaste el instalador y elegiste implementar la demostración de Counter, el instalador implementa un WorkerPool y un ActorTemplate para un servidor web que cuenta las solicitudes en la memoria y en un archivo. Agent Substrate en GKE conserva ambos recuentos cuando suspendes y restableces el Actor que ejecuta el servidor.

Después de la instalación, el instalador imprime los siguientes pasos de la demostración: un comando que instala el complemento kubectl ate y un comando que crea un Actor a partir de ActorTemplate. Antes de ejecutar los comandos de kubectl ate, asegúrate de que el complemento esté en tu variable de entorno PATH, como se describe en Instala el complemento de kubectl ate.

El instalador no imprime un comando que envíe solicitudes al Actor. El router de entrada solo admite clientes que presenten un certificado de Pod cuyo ID de SPIFFE esté en su lista de entidades permitidas, por lo que rechaza las solicitudes que envías directamente desde tu máquina local. Para obtener más información sobre la demostración, consulta el archivo README de la demostración de Counter para la versión 1.0.0 de Agent Substrate, que el instalador implementa de forma predeterminada. En un clúster que configuró el instalador, los pasos del archivo README que envían solicitudes a través de una redirección de puertos no funcionan por el mismo motivo.

Desinstala Agent Substrate en GKE

Cuando la instalación se completa y se cierra, el instalador imprime comandos de limpieza personalizados para tu entorno.

Para quitar los recursos creados durante la instalación, elige una de las siguientes opciones:

  • Quita Agent Substrate en GKE de un clúster existente: Si instalaste el agente en un clúster existente y quieres conservar el clúster y sus otras cargas de trabajo, borra solo los componentes de Agent Substrate en GKE ejecutando el comando ate-setup delete ate-system que imprime el instalador. El instalador prepropaga este comando con los valores del proyecto, el clúster y la ubicación configurados durante la instalación.

  • Borra todos los recursos (incluido el clúster): Para borrar el clúster de GKE, los buckets de instantáneas y recursos, la cuenta de servicio ate-snapshot-transfer, las vinculaciones de IAM, los paneles y el repositorio de Artifact Registry ate-images, ejecuta el comando cleanup-gcp que imprime el instalador. El instalador completa previamente este comando con los valores de proyecto, clúster, ubicación y bucket configurados durante la instalación. Debido a que el comando ejecuta la secuencia de comandos tools/cleanup-gcp con una ruta de acceso relativa, ejecuta el comando desde el directorio en el que el instalador clonó el repositorio substrate-gke. De forma predeterminada, el instalador clona el repositorio en el directorio ~/.substrate-gke.

    Si otros clústeres del proyecto ejecutan Agent Substrate en GKE, agrega la marca --cluster-scoped al comando. Esta marca conserva los paneles, la cuenta de servicio de ate-snapshot-transfer y las vinculaciones de IAM a nivel de proyecto, que comparten esos clústeres. La marca --cluster-scoped no conserva el repositorio ate-images. Si otros clústeres de la misma región usan el repositorio ate-images, agrega también la marca --keep-repository al final del comando. Para obtener más detalles, consulta la sección "Tearing down" del README de substrate-gke.

El comando cleanup-gcp no borra los siguientes recursos:

  • El disco persistente de la base de datos de PostgreSQL: GKE conserva los discos persistentes cuando borra un clúster, por lo que sigues pagando por el disco de 500 GiB. Para borrar el disco, ejecuta el comando ate-setup delete ate-system que imprime el instalador. Luego, espera hasta que el comando kubectl get pv ya no muestre un volumen para la reclamación ate-system/data-postgres-0 antes de ejecutar cleanup-gcp. Si ya borraste el clúster, busca el disco con el siguiente comando y, luego, bórralo con el comando gcloud compute disks delete:

    gcloud compute disks list --filter="description~data-postgres-0"
    
  • La cuenta de servicio substrate-filestore-csi: Todos los clústeres del proyecto que ejecutan el controlador de CSI de Filestore comparten esta cuenta de servicio. Si instalaste el controlador y ningún otro clúster del proyecto lo ejecuta, borra la cuenta de servicio con el siguiente comando:

    gcloud iam service-accounts delete substrate-filestore-csi@PROJECT_ID.iam.gserviceaccount.com
    

    Reemplaza PROJECT_ID con el ID del proyecto.

¿Qué sigue?