Segreti con Vault · Agent-Lab

Come Agent-Lab usa Vault

Agent-Lab utilizza HashiCorp Vault per gestire i segreti in modo sicuro: API key, credenziali del database e altri valori sensibili risiedono in Vault, non nel database né nei file di ambiente. Durante l'avvio dell'applicazione, la ConfigSource attiva si connette a Vault e carica il payload di configurazione; le Integrazioni archiviano riferimenti nel database, mentre i valori sensibili vengono recuperati da Vault su richiesta.

Configurare Vault

Per lo sviluppo locale, gli stack Compose includono un server Vault con una configurazione di sviluppo (UI su http://localhost:8200, token di login dev-only-token). Vedi Eseguire l'applicazione.

In produzione, effettua il provisioning dell'istanza con il modulo Terraform terraform/08_vault-instance/ descritto nella guida al deployment, inclusa la sequenza 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

Provisioning del payload del segreto

VaultConfigSource legge un singolo segreto KV-v2 (mount secret, path app_secrets) e lo mappa sulle chiavi di configurazione dell'applicazione. Le chiavi del payload sono elencate nel Riferimento della configurazione; scrivilo una sola volta con la CLI di 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 l'app non può (o non deve) usare un VAULT_TOKEN statico, la sorgente predefinita passa automaticamente a KubernetesVaultConfigSource se VAULT_K8S_ROLE è impostata: si autentica con il token ServiceAccount proiettato del pod, quindi non è necessario effettuare il provisioning né la rotazione di alcun token statico.

Produzione

In linea con i nostri principi cloud-native, consigliamo la configurazione HA di Vault su Kubernetes. Il modulo Terraform 15_agent-lab-dependencies/ collega le credenziali di runtime; l'app recupera tutto all'avvio tramite il contratto di configurazione.