Vault によるシークレット管理

Agent-Lab における Vault の使い方

Agent-Lab は、安全なシークレット管理のために HashiCorp Vault を使用します。API キー、データベースの認証情報、その他の機密性の高い値は、データベースや環境ファイルではなく Vault に保存されます。アプリケーションの起動時には、有効な ConfigSource が Vault に接続して設定ペイロードを読み込みます。Integrations はデータベースに参照のみを保存し、機密性の高い値は必要に応じて Vault から取得されます。

Vault のセットアップ

ローカル開発では、Compose スタックに開発用設定の Vault サーバーが同梱されています（UI は http://localhost:8200、ログイントークンは dev-only-token）。アプリケーションの実行を参照してください。

本番環境では、デプロイガイドの Terraform モジュール terraform/08_vault-instance/ でインスタンスをプロビジョニングします。 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

シークレットペイロードのプロビジョニング

VaultConfigSource は単一の KV-v2 シークレット（マウント secret、パス app_secrets）を読み込み、アプリケーションの設定キーにマッピングします。ペイロードのキーは設定リファレンスに一覧があります。 Vault CLI で一度書き込んでおきます。

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"

アプリが静的な VAULT_TOKEN を使用できない（または使用すべきでない）場合は、 VAULT_K8S_ROLE を設定すると、デフォルトのソースが自動的に KubernetesVaultConfigSource に切り替わります。これは Pod に投影された ServiceAccount トークンで認証するため、静的トークンのプロビジョニングやローテーションは不要です。

本番環境

クラウドネイティブの原則に従い、 Vault Kubernetes HA 構成を推奨します。 Terraform モジュール 15_agent-lab-dependencies/ がランタイムの認証情報を設定し、アプリは起動時に設定コントラクトを通じてすべてを読み込みます。