Despliegue

Dos modelos de despliegue

Local: Docker Compose

El repositorio del framework incluye dos stacks completos: aplicación, PostgreSQL (con pgvector), Redis, Vault y un stack de observabilidad:

docker compose -f compose-grafana.yml up --build      # Grafana stack
docker compose -f compose-opensearch.yml up --build   # OpenSearch Dashboards stack

Los proyectos generados con el scaffold tienen su propio compose.yml (app + postgres + redis + vault); consulta Tu primer agente.

Producción: Kubernetes con Terraform

Agent-Lab proporciona scripts de Terraform que despliegan la aplicación y sus dependencias en Kubernetes. Este recorrido utiliza un clúster de Minikube con fines de referencia; usa un clúster preparado para producción en despliegues reales.

Requisitos previos

• Terraform
• kubectl
• jq

Configurar un clúster de Kubernetes

Minikube (Linux): asigna suficientes recursos (el stack de referencia es pesado):

minikube start --memory=20g --cpus=4

Obtén la IP del clúster y asígnale los dominios de los servicios:

minikube ip
# 192.168.49.2

192.168.49.2 vault.my-domain.com kibana.my-domain.com elasticsearch.my-domain.com agent-lab.my-domain.com litellm.my-domain.com

Docker Desktop (Mac / Windows): habilita el Kubernetes integrado:

Con Docker Desktop, los dominios se resuelven a través de localhost:

127.0.0.1 vault.my-domain.com kibana.my-domain.com elasticsearch.my-domain.com agent-lab.my-domain.com litellm.my-domain.com

Aprovisionar las dependencias

Todos los módulos siguientes se encuentran en terraform/; aplícalos con terraform init && terraform apply en cada directorio, en este orden:

Instancia de Keycloak (09_keycloak-instance/); después, obtén la contraseña de administrador:

echo "$(kubectl --namespace keycloak get secret/keycloak-initial-admin -o go-template='{{index .data "password" | base64decode}}')"

Configura la conexión OIDC según Autenticación con Keycloak, o deja que lo haga el módulo 12_agent-lab-auth-realm/ (más abajo).

Inicialización de Vault (con 08_vault-instance/ aplicado): inicializa y desprecinta (unseal):

kubectl --namespace vault exec vault-0 -- vault operator init \
    -key-shares=1 \
    -key-threshold=1 \
    -format=json > cluster-keys.json

export VAULT_UNSEAL_KEY=$(jq -r ".unseal_keys_b64[]" cluster-keys.json)
kubectl --namespace vault exec vault-0 -- vault operator unseal $VAULT_UNSEAL_KEY

Observabilidad (opcional, pero recomendada): las plataformas de observabilidad de LLM que utilizan la batería de simulaciones y los backends de trazas:

Obtén las credenciales de Elastic:

echo "$(kubectl --namespace elastic get secret elasticsearch-es-elastic-user -o=jsonpath='{.data.elastic}' | base64 --decode)"

echo "$(kubectl --namespace elastic get secret/elastic-eck-apm-server-apm-token \
    -o go-template='{{index .data "secret-token" | base64decode}}')"

OpenTelemetry Collector (11_otel-instance/): el endpoint OTLP al que exporta la aplicación (Observabilidad).

Gateway LiteLLM (17_litellm-instance/): un gateway de LLM autoalojado y compatible con OpenAI, con claves virtuales, seguimiento del gasto y una interfaz de administración (/ui):

echo "$(kubectl --namespace litellm get secret/litellm-masterkey -o go-template='{{index .data "masterkey" | base64decode}}')"

curl -s https://<litellm_fqdn>/health/readiness

Desplegar Agent-Lab

Tres módulos lo conectan todo:

cd terraform/12_agent-lab-auth-realm/ && terraform init && terraform apply
cd terraform/15_agent-lab-dependencies/ && terraform init && terraform apply
cd terraform/16_agent-lab-instance/ && terraform init && terraform apply

Nota sobre los secretos: el despliegue lee su configuración de Vault al arrancar (secret/app_secrets); las claves de la carga se enumeran en la Referencia de configuración.

Chart de Helm

El repositorio también incluye un chart de Helm, charts/agent-lab, que empaqueta el despliegue de la aplicación con sus sidecars: Chrome headless (CDP) para agentes web, un HPA, ingress, configuración y cuenta de servicio. Úsalo cuando ya gestiones tus propias dependencias y solo quieras instalar la aplicación.

Lista de comprobación

Antes de darlo por terminado, verifica que:

• GET /status/liveness y GET /status/readiness devuelven 200
• GET /docs se muestra y GET /agents/list responde (con un token cuando la autenticación está activada)
• Las trazas llegan a tu endpoint OTLP (consulta Observabilidad)
• Vault contiene secret/app_secrets con todas las claves de la carga
• El realm de Keycloak tiene un cliente y una cuenta de servicio