llm-wiki/raw/official-docs/secrets-vault-dynamic-secrets-hashicorp.md

---
title: HashiCorp Vault — Dynamic Secrets (DB credentials)
source_type: official-doc
url: https://developer.hashicorp.com/vault/docs/secrets/databases
archive_url:
status: raw
confidence: high
tags: [ca-secrets, vault, dynamic-secrets, lease, db-credentials, rotation]
related_projects: [ca-skeleton-operational-contract]
related_branches: [feature-secrets-config-source-contract]
created: 2026-05-22
last_reviewed: 2026-05-27
---

# HashiCorp Vault — Dynamic Secrets

> Layer: `raw/official-docs/` — HashiCorp Vault Database secrets engine 공식 문서 원문 발췌.
> ca-tmpl `feature-secrets-config-source-contract` 가 채택한 static + restart-only 모델의 **대안 2 (dynamic short-lived credential)** 비교 자료.

## Parent / 활용 branch (필수)

| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| [[raw/branch-notes/feature-secrets-config-source-contract]] | `prod = secret manager OR mounted env` + `rotation = restart-only` (static 모델) 결정의 **대안 2** — dynamic short-lived credential 모델이 ca-tmpl 에 부적합한 이유 |
| [[raw/project-notes/ca-skeleton-operational-contract]] | Secrets Config Source Contract 의 dynamic vs static 비교 baseline |

## 컨텍스트 / 왜 저장했는지

`feature-secrets-config-source-contract` ca-tmpl이 결정한 `prod = secret manager OR mounted env` + `rotation = restart-only`은 **static secret** 모델. Vault dynamic secret은 application restart 없이 short-lived credential을 매번 발급하는 대안 모델. baseline이 dynamic을 택하지 않은 이유를 명확히 하기 위함.

## 출처 / Source

- 원본 URL: https://developer.hashicorp.com/vault/docs/secrets/databases
- 아카이브 URL: (미확보)
- 저자 / 조직: HashiCorp — Vault Documentation
- 발행 상태: rolling docs (페이지 자체에 명시 없음)
- 관련: Vault Agent (sidecar), Vault K8s injector, `lease` API, `auto-renew`
- 마지막 확인일: 2026-05-27

## 핵심 인용 / Key quotes (verbatim)

> [§Database Secrets Engine — Overview, 2026-05-27 verified] "The database secrets engine generates database credentials dynamically based on configured roles."

> [§Database Secrets Engine — Overview, 2026-05-27 verified] "Services that need to access a database no longer need to hardcode credentials: they can request them from Vault, and use Vault's leasing mechanism to more easily roll keys."

> [§Database Secrets Engine — Overview, 2026-05-27 verified] "Since every service is accessing the database with unique credentials, it makes auditing much easier when questionable data access is discovered."

> [§Database Secrets Engine — Static Roles, 2026-05-27 verified] "Vault also supports static roles for all database secrets engines. Static roles are a 1-to-1 mapping of Vault roles to usernames in a database."

> **재검증 완료 (2026-05-27)**: WebFetch 권한 복구 후 https://developer.hashicorp.com/vault/docs/secrets/databases 원본에서 위 4개 인용 모두 verbatim 일치 확인. Strength `needs-confirmation` → `official-vendor-doc` 로 격상 (HashiCorp 공식 Vault 문서).

## Claims Extracted / 추출된 주장

| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| VAULT-DYN-C1 | Database secrets engine 은 configured roles 기반으로 **DB credential 을 동적으로 생성** | [§Overview] "The database secrets engine generates database credentials dynamically based on configured roles." | `official-vendor-doc` | Vault Database secrets engine 활성화 환경 | 모든 DB 엔진 (MySQL/PostgreSQL/Oracle/SQL Server 등) 에서 동일하게 동작한다는 뜻은 아님 — 엔진별 plugin 차이 있음 |
| VAULT-DYN-C2 | service 는 credential 을 hardcode 할 필요 없이 Vault 에 요청하고 **leasing mechanism** 으로 key rotation 을 처리 | [§Overview] "Services that need to access a database no longer need to hardcode credentials: they can request them from Vault, and use Vault's leasing mechanism to more easily roll keys." | `official-vendor-doc` | Vault 와 통합된 service | lease 만료 시 application 의 connection pool refresh 동작이 자동이라는 뜻은 아님 — application 측 로직 필요 |
| VAULT-DYN-C3 | 모든 service 가 unique credential 로 DB 에 접근하므로 **audit trail** 이 명확해진다 (의심 접근 추적 용이) | [§Overview] "Since every service is accessing the database with unique credentials, it makes auditing much easier when questionable data access is discovered." | `official-vendor-doc` | per-service unique credential 정책을 사용하는 환경 | DB 측 audit log 가 자동 활성화된다는 뜻은 아님 — DB 자체 audit 설정 별도 필요 |
| VAULT-DYN-C4 | Vault 는 모든 DB secrets engine 에 대해 **static role** 도 지원 (Vault role 과 DB username 의 1:1 매핑) | [§Static Roles] "Vault also supports static roles for all database secrets engines. Static roles are a 1-to-1 mapping of Vault roles to usernames in a database." | `official-vendor-doc` | Vault 의 static role 사용 시 | static role 이 dynamic role 보다 권장된다는 뜻은 아님 — 둘 다 첫 시민으로 지원, 선택은 운영 결정 |

## Usage Boundaries / 적용 경계

- **이 자료가 직접 증명하는 것**:
  - `VAULT-DYN-C1`~`C4`: Vault Database secrets engine 의 4가지 공식 진술 — dynamic 생성 / lease rotation / unique credential audit / static role 지원
- **이 자료가 증명하지 않는 것**:
  - lease 만료 시 application 의 retry / pool refresh 동작이 자동이라는 보장
  - Vault outage 시 lease 갱신 실패의 fallback (SPoF 위험은 별도 운영 결정)
  - DB superuser 권한 필요성의 정확한 범위 (CREATE USER + GRANT 권한이 모든 DB 에서 동일하지 않음)
  - dynamic vs static 의 운영 비용 비교 (cluster, unseal, auth method, audit 부담)
  - ca-tmpl 의 dual-bind 60s rotation window 가 dynamic 모델에서 어떻게 다르게 동작하는지
- **내 프로젝트에 적용하려면 추가 확인이 필요한 것**:
  - HikariCP / Tomcat JDBC pool 이 lease 만료를 어떻게 감지하고 refresh 하는지 (별도 Vault Agent or sidecar 패턴)
  - ca-tmpl 의 `@RefreshScope bean 금지` 정책과 dynamic credential 의 호환성 (dynamic 은 bean refresh 패턴 거의 필수)
  - Vault 운영 (unseal, audit, auth method) 의 학습 비용 vs Secrets Manager rotation 의 cloud lock-in 비교

## 메모 / Notes (내 프로젝트 해석)

> 본 섹션은 자료 직접 인용 아님. ca-tmpl 적용 컨텍스트 해석.

- **dynamic vs static (ca-tmpl baseline 위치):**
  - dynamic = Vault가 매 요청마다 임시 DB user 생성 → lease 만료 시 자동 삭제.
  - static role = 기존 DB user를 Vault가 password rotation만.
  - ca-tmpl `restart-only` reload 정책 = static + 외부 secret manager 모델과 호환. dynamic은 ca-tmpl이 명시적으로 제외 (`@RefreshScope` bean 금지).
- **ca-tmpl이 dynamic을 채택하지 않은 이유 (추정):**
  - dynamic credential은 connection pool과 lifecycle 충돌 (lease 만료 시 pool refresh 필요).
  - dual-bind 60s 결정 (DB credential rotation 책임)이 이미 static rotation 가정.
  - Vault 운영 (cluster, unseal, auth method, audit) 부담을 skeleton에 두지 않음.
- **장점 (dynamic):**
  - secret in storage time이 짧음 (lease 단위, 예: 1h).
  - 사고 시 lease revocation으로 즉시 회수.
  - per-service credential로 audit trail 명확.
- **단점:**
  - DB user 생성/삭제 부담 (DB superuser 권한 필요).
  - application 재시도 / pool refresh logic 필요.
  - Vault outage가 SPoF가 됨 (lease 갱신 실패).
- **vs AWS Secrets Manager rotation (다른 raw 참조):**
  - Secrets Manager rotation = static + scheduled Lambda. Vault dynamic = on-demand lease. ca-tmpl baseline은 전자에 더 가까움.

## Related / 관련

- 같은 주제 다른 raw:
  - [[raw/official-docs/secrets-aws-secrets-manager-rotation]]
  - [[raw/official-docs/config-12-factor-app-config]]
- 인용하는 branch:
  - [[raw/branch-notes/feature-secrets-config-source-contract]]
- 인용하는 project:
  - [[raw/project-notes/ca-skeleton-operational-contract]]
- 대안 그룹: **Group G-B — Secrets sub-topic**
- 본 source의 위치: **대안 2 — HashiCorp Vault + dynamic secrets**
- 인용한 wiki 요약: (미작성)