Deployment

Due modelli di deployment

In locale: Docker Compose

Il repository del framework include due stack completi: applicazione, PostgreSQL (con pgvector), Redis, Vault e uno stack di osservabilità:

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

I progetti generati dallo scaffold hanno un proprio compose.yml (app + postgres + redis + vault): vedi Il tuo primo agente.

In produzione: Kubernetes con Terraform

Agent-Lab fornisce script Terraform che eseguono il deployment dell'applicazione e delle sue dipendenze su Kubernetes. Questa procedura usa un cluster Minikube a scopo di riferimento: per i deployment reali usa un cluster pronto per la produzione.

Prerequisiti

• Terraform
• kubectl
• jq

Configurare un cluster Kubernetes

Minikube (Linux): assegna risorse sufficienti (lo stack di riferimento è pesante):

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

Ricava l'IP del cluster e associa a esso i domini dei servizi:

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): abilita il Kubernetes integrato:

Con Docker Desktop, i domini vengono risolti tramite 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

Effettuare il provisioning delle dipendenze

Ogni modulo seguente si trova in terraform/: applicalo con terraform init && terraform apply in ciascuna directory, in questo ordine:

Istanza Keycloak (09_keycloak-instance/), poi recupera la password di amministratore:

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

Configura la connessione OIDC come descritto in Autenticazione con Keycloak, oppure lascia che se ne occupi il modulo 12_agent-lab-auth-realm/ (vedi sotto).

Inizializzazione di Vault (dopo aver applicato 08_vault-instance/): inizializza ed esegui l'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

Osservabilità (facoltativa ma consigliata): le piattaforme di osservabilità per LLM usate dalla suite di simulazione e i backend di tracing:

Recupera le credenziali di 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/): l'endpoint OTLP verso cui l'app esporta i dati (Osservabilità).

Gateway LiteLLM (17_litellm-instance/): un gateway LLM self-hosted compatibile con OpenAI, con chiavi virtuali, monitoraggio della spesa e un'interfaccia di amministrazione (/ui):

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

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

Eseguire il deployment di Agent-Lab

Tre moduli collegano tutti i componenti:

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 sui segreti: il deployment legge la propria configurazione da Vault all'avvio (secret/app_secrets); le chiavi del payload sono elencate nel Riferimento della configurazione.

Chart Helm

Il repository include anche un chart Helm, charts/agent-lab, che pacchettizza il deployment dell'applicazione con i suoi sidecar: Chrome headless (CDP) per gli agenti web, un HPA, ingress, configurazione e service account. Usalo quando gestisci già le tue dipendenze e vuoi installare solo l'app.

Checklist

Prima di considerare il lavoro concluso, verifica che:

• GET /status/liveness e GET /status/readiness restituiscano 200
• GET /docs venga visualizzata e GET /agents/list risponda (con un token quando l'autenticazione è attiva)
• Le trace arrivino al tuo endpoint OTLP (vedi Osservabilità)
• Vault contenga secret/app_secrets con tutte le chiavi del payload
• Il realm di Keycloak abbia un client e un service account