Implementación

Dos modelos de implementación

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 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 implementan la aplicación y sus dependencias en Kubernetes. Este recorrido usa un clúster de Minikube como referencia; usa un clúster listo para producción en implementaciones reales.

Requisitos previos

• Terraform
• kubectl
• jq

Configura 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 incluido:

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

Aprovisiona las dependencias

Cada uno de los módulos siguientes está en terraform/; aplícalos con terraform init && terraform apply en cada directorio, en este orden:

Instancia de Keycloak (09_keycloak-instance/); luego 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 el módulo 12_agent-lab-auth-realm/ lo haga (más abajo).

Inicialización de Vault (con 08_vault-instance/ aplicado): inicializa y quita el sellado (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 usan la suite de simulación y los backends de rastreo:

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 de LiteLLM (17_litellm-instance/): un gateway de LLM autoalojado y compatible con OpenAI, con claves virtuales, seguimiento de gastos 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

Implementa Agent-Lab

Tres módulos 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: la implementación lee su configuración desde Vault al iniciar (secret/app_secrets); las claves del contenido 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 la implementación de la aplicación con sus sidecars: Chrome headless (CDP) para los agentes web, un HPA, ingress, configuración y cuenta de servicio. Úsalo cuando ya operes tus propias dependencias y solo quieras instalar la aplicación.

Lista de verificación

Antes de darlo por terminado, verifica que:

• GET /status/liveness y GET /status/readiness devuelvan 200
• GET /docs se muestre y GET /agents/list responda (con un token cuando la autenticación esté activada)
• Las trazas lleguen a tu endpoint OTLP (consulta Observabilidad)
• Vault contenga secret/app_secrets con todas las claves del contenido
• El realm de Keycloak tenga un cliente y una cuenta de servicio