Segredos com Vault · Agent-Lab

Como o Agent-Lab utiliza o Vault

O Agent-Lab utiliza o HashiCorp Vault para a gestão segura de segredos: chaves de API, credenciais de bases de dados e outros valores sensíveis residem no Vault, e não na base de dados nem em ficheiros de ambiente. Durante o arranque da aplicação, a ConfigSource ativa liga-se ao Vault e carrega o payload de configuração; as Integrações guardam referências na base de dados, enquanto os valores sensíveis são obtidos do Vault a pedido.

Configurar 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 início de sessão dev-only-token). Consulte Executar a aplicação.

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

Aprovisionar o payload de segredos

A VaultConfigSource lê um único segredo KV-v2 — mount secret, caminho app_secrets — e mapeia-o para as chaves de configuração da aplicação. As chaves do payload estão listadas na Referência de configuração; escreva-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) utilizar um VAULT_TOKEN estático, a fonte predefinida passa automaticamente para KubernetesVaultConfigSource quando VAULT_K8S_ROLE está definido — autentica-se com o token projetado da ServiceAccount do pod, pelo que não é necessário aprovisionar nem rodar nenhum token estático.

Produção

Seguindo os nossos princípios cloud-native, recomendamos a configuração de HA do Vault em Kubernetes. O módulo Terraform 15_agent-lab-dependencies/ liga as credenciais de runtime; a aplicação obtém tudo no arranque através do contrato de configuração.