Instala Agent Substrate en GKE

Estándar

Nota: Agent Substrate está disponible para todos los clientes de Google Cloud para su evaluación y uso no productivo. La asistencia para producción se ofrece en función de una lista de entidades permitidas en el marco de un programa de DG privada. Para solicitar asistencia de producción para tus cargas de trabajo, envía el formulario de registro para la asistencia de producción de Agent Substrate. Nuestro equipo se comunicará contigo en un plazo de 48 horas.

Agent Substrate ejecuta de manera eficiente cargas de trabajo basadas en agentes en clústeres de GKE, ya que suspende los agentes inactivos y los restablece cuando deben volver a actuar. Agent Substrate es un software de código abierto que puedes instalar en un clúster de GKE Standard.

En este documento, se explica cómo preparar tu proyecto Google Cloud y tu clúster de GKE para Agent Substrate, cómo ejecutar el instalador y los recursos que crea la instalación.

Precios

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

Limitaciones

Agent Substrate tiene las siguientes limitaciones de instalación:

• Cloud Shell: No puedes instalar Agent Substrate en Cloud Shell porque este proporciona 5 GB de almacenamiento de disco persistente, lo que es insuficiente para la instalación. Debes ejecutar el instalador en tu máquina local.
• Modo del clúster: Solo puedes instalar Agent Substrate en clústeres de GKE Standard. Los clústeres de Autopilot no son compatibles.
• Clústeres existentes y APIs beta: Si habilitas las APIs beta requeridas (podcertificaterequests y clustertrustbundles) en un clúster existente que ejecuta la versión 1.36, debes reemplazar los nodos existentes antes de instalar Agent Substrate. Los nodos creados antes de la actualización no tienen habilitada la proyección de certificados de Pod (MountVolume.SetUp failed: unimplemented). En los clústeres que ejecutan la versión 1.37 o posterior, no es necesario reemplazar los nodos existentes.
• 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
• Si deseas usar Google Cloud CLI para esta tarea, instala y, luego, inicializa gcloud CLI. Si ya instalaste la 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 que se indican en este documento.
  Nota: Para las instalaciones de gcloud CLI existentes, asegúrate de configurar la propiedad compute/region. Si usas principalmente clústeres zonales, configura compute/zone en su lugar. Cuando configuras una ubicación predeterminada, puedes evitar errores en gcloud CLI como el siguiente: One of [--zone, --region] must be supplied: Please specify location. Es posible que debas especificar la ubicación en ciertos comandos si la ubicación de tu clúster difiere de la predeterminada que estableciste.

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

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

  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, pídele a tu administrador que te otorgue los siguientes roles de IAM en tu proyecto:

• Administrador de Service Usage ()roles/serviceusage.serviceUsageAdmin
• Administrador de Kubernetes Engine (roles/container.admin)
• Administrador de almacenamiento (roles/storage.admin)
• Administrador de IAM de proyecto (roles/resourcemanager.projectIamAdmin)
• Editor de Monitoring (roles/monitoring.editor)

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 permites 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.

Si, en cambio, decides instalar Agent Substrate en un clúster existente, este debe cumplir con los siguientes requisitos:

• Se ejecuta en GKE Standard (Agent Substrate solo es compatible con clústeres Standard).
• Ejecuta la versión 1.36 de GKE (con las marcas beta habilitadas) o la versión 1.37 o posterior.
• Usa tipos de máquinas c3-standard-4 o más grandes para los nodos.

• Tiene habilitadas las APIs de Kubernetes PodCertificateRequest y ClusterTrustBundle (certificates.k8s.io/v1beta1/podcertificaterequests y certificates.k8s.io/v1beta1/clustertrustbundles). Para habilitar estas APIs en un clúster existente, ejecuta el siguiente comando:

  gcloud container clusters update CLUSTER_NAME \
      --location=CONTROL_PLANE_LOCATION \
      --enable-kubernetes-unstable-apis=certificates.k8s.io/v1beta1/podcertificaterequests,certificates.k8s.io/v1beta1/clustertrustbundles
  

  • Versión 1.36: Después de habilitar las APIs, debes reemplazar los nodos existentes, por ejemplo, actualizando el grupo de nodos o volviendo a crear sus nodos. La proyección de certificados de Pod no está habilitada en los nodos que existían antes de la actualización (MountVolume.SetUp failed: unimplemented).
  • Versión 1.37 o posterior: La proyección de certificados de Pod ya está habilitada en los nodos existentes, por lo que no es necesario reemplazar los nodos después de habilitar las APIs.

Instala Agent Substrate

Para instalar Agent Substrate, ejecuta el siguiente comando en tu terminal local:

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

El instalador interactivo te solicita la configuración de tu proyecto, clúster y almacenamiento. Te sugiere valores predeterminados recomendados cuando es posible, que puedes aceptar o personalizar:

• ID del proyecto (obligatorio): Especifica el proyecto Google Cloud en el que se aprovisionarán los recursos. Si configuraste un proyecto predeterminado para gcloud CLI, el instalador usará ese ID del proyecto.
• Clúster (obligatorio): Elige si deseas permitir que el instalador cree un clúster de GKE nuevo con la configuración predeterminada recomendada o si deseas instalar Agent Substrate en un clúster existente. Si decides instalar en un clúster existente, verifica que cumpla con los requisitos que se indican en la sección Requisitos del clúster.
• Bucket de instantáneas (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>-<zone>.

Cuando se te solicite que selecciones una fuente de imagen de contenedor, puedes elegir entre las siguientes opciones:

• Imágenes compiladas previamente: Extrae imágenes publicadas desde un registro de contenedores. Como no se compila ni se envía nada, tu proyecto Google Cloud no necesita su propio registro de contenedores.
• Build from source: Compila las imágenes desde el repositorio de Agent Substrate upstream (o una rama personalizada) y las envía al registro de Artifact Registry de tu proyecto.

Qué hace el instalador

El instalador ejecuta los siguientes programas en tu nombre:

• setup-gcp: Crea o verifica los recursos Google Cloud necesarios, habilita las APIs, crea el clúster de GKE (si decidiste 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 y los controladores de contenedores de Agent Substrate prediseñados 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 necesita Agent Substrate.
2. Crea un clúster de GKE Standard (si no usas un clúster existente) con la siguiente configuración:
   • Workload Identity Federation for GKE: Permite que Agent Substrate acceda a Cloud Storage sin almacenar claves en los nodos.
   • GKE Dataplane V2: Controla las redes necesarias para enrutar las solicitudes entrantes a tus agentes.
   • APIs de certificados (PodCertificateRequest y ClusterTrustBundle): Habilita estas APIs beta de Kubernetes para emitir certificados para la comunicación TLS entre los componentes de Agent Substrate.
   • OpenTelemetry administrado: Recopila métricas y registros de tu clúster.
3. Crea el bucket de Cloud Storage en el que Agent Substrate escribe tus instantáneas.
4. Otorga acceso al sustrato del agente a Cloud Storage para almacenar instantáneas. Si eliges compilar desde la fuente, también se otorga acceso a Artifact Registry para las imágenes de contenedor.
5. Crea paneles de Cloud Monitoring que registran la latencia de enrutamiento, el tamaño de la instantánea y el tráfico de gRPC de Agent Substrate.

A continuación, el instalador realiza los siguientes cambios en tu clúster:

1. Agrega el grupo y los recursos de la API de Agent Substrate a tu clúster. Estos son recursos personalizados de Kubernetes, como ActorTemplate (que define las imágenes de contenedor y los recursos que usan tus agentes) y WorkerPool (que define cuántos entornos de pruebas inactivos se mantienen listos).
2. Configura las autoridades certificadoras que emiten los certificados que identifican los componentes de Agent Substrate y tus actores. Los componentes presentan estos certificados para autenticarse entre sí con mTLS.
3. Implementa los componentes de Agent Substrate en tu clúster, junto con una base de datos de PostgreSQL que hace un seguimiento del estado de tus actores y trabajadores. El instalador espera a que la base de datos y todos los Pods del plano de control estén listos.

Agent Substrate implementa sus componentes como cargas de trabajo comunes en los espacios de nombres ate-system y podcertificate-controller-system. La instalación no modifica el plano de control de GKE.

Entre los componentes que se implementan, se incluye el entorno de ejecución basado en gVisor que Agent Substrate usa de forma predeterminada para aislar cada uno de tus agentes del nodo en el que se ejecuta. El instalador no configura los tiempos de ejecución de microVM. Para usar los tiempos de ejecución de microVM, debes implementarlos manualmente en un grupo de nodos que tenga habilitada la virtualización anidada. Para obtener más detalles, consulta las instrucciones de tiempo de ejecución de microVM en el repositorio upstream de Agent Substrate.

Si la instalación falla en algún momento (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 quedó.

Para actualizar Agent Substrate en un clúster existente, ejecuta el instalador y selecciona Upgrade an installed cluster. Para obtener más detalles, consulta Cómo actualizar un clúster instalado en el 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. Elige esta opción si tus agentes necesitan almacenamiento de archivos compartido en todos los Pods, como espacios de trabajo o repositorios compartidos. Si tu clúster tiene habilitado el complemento de Filestore administrado de GKE, el instalador lo inhabilita antes de implementar el controlador.
• Ajuste de escala automático de grupos de nodos: Habilita el ajuste de escala automático de clústeres de GKE en tu grupo de nodos. Especificas la cantidad mínima y máxima de nodos para el grupo. Elige esta opción si quieres que GKE agregue nodos automáticamente durante los aumentos repentinos de la demanda y quite nodos cuando se suspendan los agentes. Omite esta opción si prefieres una cantidad fija de nodos con costos de procesamiento predecibles.
• Demostración del contador: Implementa una carga de trabajo de ejemplo que demuestra la suspensión y el restablecimiento del agente. Elige esta opción si deseas probar el clúster después de la instalación. Para obtener más información, consulta Prueba la demostración del contador.

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

Etiquetado y versiones de nodos

El instalador aplica la etiqueta ate.dev/substrate-version a cada nodo de tu clúster. Esta etiqueta especifica qué versión de Agent Substrate está instalada en tu clúster, y Agent Substrate ejecuta Workers solo en los nodos que tienen esta etiqueta de versión.

Para verificar qué versión de Agent Substrate está instalada en tu clúster, ejecuta el siguiente comando:

kubectl get ds -n ate-system -l app=atelet -L ate.dev/substrate-version

Ten en cuenta los siguientes detalles sobre el etiquetado de nodos:

• Grupos de trabajadores: Cuando crees un WorkerPool, configúralo para que se oriente a esta etiqueta de versión. Para ver ejemplos, consulta Cómo fijar grupos de fijaciones a la versión de sustrato instalada en la guía de la API de Substrate.
• Nodos nuevos: El instalador etiqueta nodos individuales en lugar del grupo de nodos. Por este motivo, los nodos nuevos que se agreguen después de la instalación, incluso en un grupo de nodos creado por el instalador, se inician sin la etiqueta de versión. Debes etiquetar tu grupo de nodos de GKE para que los nodos nuevos reciban automáticamente la etiqueta.

Prueba la demostración de Counter

Si elegiste implementar la demostración de Counter cuando te lo solicitó el instalador, puedes observar las capacidades de suspensión y restablecimiento de Agent Substrate. La demostración ejecuta un pequeño servidor web que mantiene un recuento en la memoria.

Después de implementar los objetos WorkerPool y ActorTemplate de la demostración, el instalador imprime los comandos que necesitas para crear un objeto Actor a partir del objeto ActorTemplate y para enviar una solicitud a ese objeto Actor. El README de la demostración del contador en el repositorio upstream de Agent Substrate explica los próximos pasos que debes seguir.

Cómo desinstalar Agent Substrate

Cuando finaliza la instalación 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 de un clúster existente: Si realizaste la instalación en un clúster existente y deseas conservar el clúster y sus otras cargas de trabajo, borra solo los componentes de Agent Substrate ejecutando el comando ate-setup delete ate-system que imprime el instalador. El instalador completa previamente 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, el bucket de instantáneas, las vinculaciones de IAM y los paneles, ejecuta el comando cleanup-gcp que imprime el instalador. El instalador completa previamente este comando con los valores del proyecto, el clúster, la ubicación y el bucket que se configuraron durante la instalación. Para obtener más detalles, consulta la sección "Desmantelamiento" del archivo README de substrate-gke.

¿Qué sigue?

• Para obtener más información sobre Agent Substrate, consulta Acerca de Agent Substrate.