Deployment

Dois modelos de deployment

Local: Docker Compose

O repositório da framework inclui duas stacks completas — aplicação, PostgreSQL (com pgvector), Redis, Vault e uma stack de observabilidade:

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

Os projetos gerados a partir do scaffold têm o seu próprio compose.yml (app + postgres + redis + vault) — consulte O seu primeiro agente.

Produção: Kubernetes com Terraform

O Agent-Lab disponibiliza scripts Terraform que fazem o deployment da aplicação e das respetivas dependências em Kubernetes. Este guia utiliza um cluster Minikube para efeitos de referência — utilize um cluster preparado para produção em deployments reais.

Pré-requisitos

• Terraform
• kubectl
• jq

Configurar um cluster Kubernetes

Minikube (Linux) — atribua recursos suficientes (a stack de referência é pesada):

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

Obtenha o IP do cluster e associe-lhe os domínios dos serviços:

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) — ative o Kubernetes incluído:

Com o Docker Desktop, os domínios são resolvidos atravé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 as dependências

Todos os módulos abaixo encontram-se em terraform/ — aplique-os com terraform init && terraform apply em cada diretório, por esta ordem:

Instância do Keycloak (09_keycloak-instance/); em seguida, obtenha a palavra-passe de administrador:

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

Configure a ligação OIDC conforme Autenticação com Keycloak, ou deixe que o módulo 12_agent-lab-auth-realm/ o faça (ver abaixo).

Inicialização do Vault (com 08_vault-instance/ aplicado) — inicialize e faça o 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

Observabilidade (opcional, mas recomendada) — as plataformas de observabilidade de LLM utilizadas pela suite de simulação e pelos backends de tracing:

Obtenha as credenciais do 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/) — o endpoint OTLP para o qual a aplicação exporta (Observabilidade).

Gateway LiteLLM (17_litellm-instance/) — um gateway de LLM auto-alojado e compatível com OpenAI, com chaves virtuais, controlo de gastos e uma UI de administração (/ui):

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

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

Fazer o deployment do Agent-Lab

Três módulos ligam tudo:

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 segredos: o deployment lê a sua configuração do Vault no arranque (secret/app_secrets) — as chaves do payload estão listadas na Referência de configuração.

Helm chart

O repositório inclui também um Helm chart, charts/agent-lab, que empacota o deployment da aplicação com os seus sidecars: Chrome headless (CDP) para agentes web, um HPA, ingress, configuração e conta de serviço. Utilize-o quando já operar as suas próprias dependências e pretender apenas instalar a aplicação.

Lista de verificação

Antes de dar o trabalho por concluído, verifique:

• GET /status/liveness e GET /status/readiness devolvem 200
• GET /docs é apresentado e GET /agents/list responde (com um token quando a autenticação está ativada)
• Os traces chegam ao seu endpoint OTLP (consulte Observabilidade)
• O Vault contém secret/app_secrets com todas as chaves do payload
• O realm do Keycloak tem um cliente e uma conta de serviço