Vault로 시크릿 관리

Agent-Lab이 Vault를 사용하는 방식

Agent-Lab은 안전한 시크릿 관리를 위해 HashiCorp Vault를 사용합니다. API 키, 데이터베이스 자격 증명 및 기타 민감한 값은 데이터베이스나 환경 파일이 아닌 Vault에 보관됩니다. 애플리케이션 시작 시 활성 ConfigSource가 Vault에 연결해 구성 페이로드를 로드합니다. 통합은 데이터베이스에 참조만 저장하며, 민감한 값은 필요할 때 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로 전환됩니다. 이 소스는 파드의 프로젝션된 ServiceAccount 토큰으로 인증하므로, 정적 토큰을 프로비저닝하거나 교체할 필요가 없습니다.

프로덕션

클라우드 네이티브 원칙에 따라 Vault Kubernetes HA 구성을 권장합니다. 15_agent-lab-dependencies/ Terraform 모듈이 런타임 자격 증명을 연결하며, 앱은 구성 계약에 따라 시작 시점에 모든 값을 가져옵니다.