Implantação

Dois modelos de implantação

Local: Docker Compose

O repositório do 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 pelo scaffold recebem seu próprio compose.yml (app + postgres + redis + vault) — consulte Seu primeiro agente.

Produção: Kubernetes com Terraform

O Agent-Lab fornece scripts Terraform que implantam a aplicação e suas dependências no Kubernetes. Este passo a passo usa um cluster Minikube apenas como referência — use um cluster pronto para produção em implantações reais.

Pré-requisitos

• Terraform
• kubectl
• jq

Configure um cluster Kubernetes

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

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

Descubra o IP do cluster e mapeie os domínios dos serviços para ele:

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 via 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

Provisione as dependências

Todos os módulos abaixo ficam em terraform/ — aplique-os com terraform init && terraform apply em cada diretório, nesta ordem:

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

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

Configure a conexão OIDC conforme Autenticação com Keycloak, ou deixe o módulo 12_agent-lab-auth-realm/ fazer isso (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 usadas pela suíte de simulação e pelos backends de tracing:

Recupere 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 self-hosted compatível com a OpenAI, com chaves virtuais, controle 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

Implante o Agent-Lab

Três módulos conectam 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

Observação sobre segredos: a implantação lê sua configuração do Vault na inicialização (secret/app_secrets) — as chaves do payload estão listadas na Referência de configuração.

Helm chart

O repositório também inclui um Helm chart, charts/agent-lab, que empacota o deploy da aplicação com seus sidecars: Chrome headless (CDP) para agentes web, um HPA, ingress, configuração e service account. Use-o quando você já opera suas próprias dependências e quer apenas instalar a aplicação.

Checklist

Antes de dar por concluído, verifique:

• GET /status/liveness e GET /status/readiness retornam 200
• GET /docs é renderizado 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 client e uma service account