Segredos com Vault · Agent-Lab

Como o Agent-Lab usa o Vault

O Agent-Lab usa o HashiCorp Vault para o gerenciamento seguro de segredos: chaves de API, credenciais de banco de dados e outros valores sensíveis ficam no Vault, e não no banco de dados nem em arquivos de ambiente. Durante a inicialização da aplicação, o ConfigSource ativo se conecta ao Vault e carrega o payload de configuração; as Integrações armazenam referências no banco de dados, enquanto os valores sensíveis são buscados no Vault sob demanda.

Configurando o Vault

Para desenvolvimento local, as stacks do Compose incluem um servidor Vault com uma configuração de desenvolvimento (UI em http://localhost:8200, token de login dev-only-token). Consulte Executando a aplicação.

Para produção, provisione a instância com o módulo Terraform terraform/08_vault-instance/ do guia de implantação — incluindo a sequência de init + 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

Provisionando o payload de segredos

O VaultConfigSource lê um único segredo KV-v2 — mount secret, caminho app_secrets — e o mapeia para as chaves de configuração da aplicação. As chaves do payload estão listadas na Referência de configuração; grave-o uma única vez com a CLI do Vault:

vault kv put secret/app_secrets \
  api_base_url="https://<agent_lab_fqdn>" \
  cdp_url="http://<cdp_host>:9222" \
  auth_enabled="true" \
  auth_url="https://<auth_fqdn>" \
  auth_realm="<realm_name>" \
  auth_client_id="<client_name>" \
  auth_client_secret="<client_secret>" \
  broker_url="redis://:<password>@<redis_host>:6379/0" \
  db_url="postgresql://<user>:<pass>@<db_host>:5432/agent_lab" \
  db_vectors="postgresql://<user>:<pass>@<db_host>:5432/agent_lab_vectors" \
  db_checkpoints="postgresql://<user>:<pass>@<db_host>:5432/agent_lab_checkpoints"

Quando a aplicação não pode (ou não deve) usar um VAULT_TOKEN estático, a fonte padrão passa automaticamente para o KubernetesVaultConfigSource quando VAULT_K8S_ROLE está definida — ela se autentica com o token projetado da ServiceAccount do pod, de modo que nenhum token estático precisa ser provisionado ou rotacionado.

Produção

Seguindo nossos princípios cloud-native, recomendamos a configuração de HA do Vault no Kubernetes. O módulo Terraform 15_agent-lab-dependencies/ conecta as credenciais de runtime; a aplicação carrega tudo na inicialização por meio do contrato de configuração.