本文是 HashiCorp Vault overview 的 implementation-layer deep article。Overview 已說明 Vault 在 secrets / credentials 治理譜系的定位（跟 cloud-native secrets manager / cert-manager 的取捨）、本文聚焦 dynamic credential engine 的實作層：怎麼配 database engine、application 怎麼 renew lease、production 踩過哪些坑、跟 cloud-native vault 跟 vault-agent injector 怎麼整合。

問題情境

Long-lived database credential 寫進 application config 是 production 環境最常見的 secret hygiene 失敗：credential 一旦外洩、輪替成本是 跨團隊協調 + 多服務同步重啟、實務上半年才換一次、credential 在 git history / log / dump file 留下軌跡。動態憑證（dynamic credential）的核心承諾是 credential 生命週期跟 application session 對齊、用完就 revoke、外洩窗口從幾個月縮到幾分鐘。

但 dynamic credential 不是「換個 SDK 就好」、它把 credential 治理 從 secret rotation 問題轉成 lease lifecycle 問題。lease TTL 設多久、renewal 怎麼跑、DB 端 user 創建會不會撞 max_connections、Vault sealed 時 application 怎麼降級 — 每個都是 production-grade 議題、無法靠 vendor doc 預設值直接上線。

核心概念：lease lifecycle 跟 secrets engine 模型

Vault dynamic credential 由三個元件協作：

跟 static secret（K/V store）對照、dynamic credential 的關鍵差異是 credential 在 read 時才產生、且 Vault 追蹤每個 outstanding lease；application 必須 主動 renew 或接受 credential 失效。

Lease 的兩個 TTL：

• default_ttl：credential 初始有效期、application 不 renew 就到期
• max_ttl：credential 最長有效期、不管 renew 幾次都不能超過

實務 default 配置：default_ttl: 1h + max_ttl: 24h、application 每 30-45 分鐘 renew 一次、credential 最多活 24 小時必換新的。

Step-by-step 配置

Vault server 啟用 database secrets engine

 1# 1. enable secrets engine
 2vault secrets enable -path=database database
 3
 4# 2. 配置 PostgreSQL connection
 5vault write database/config/myapp-prod \
 6  plugin_name=postgresql-database-plugin \
 7  allowed_roles="myapp-reader,myapp-writer" \
 8  connection_url="postgresql://{{username}}:{{password}}@db.internal:5432/myapp?sslmode=require" \
 9  username="vault_root" \
10  password="<vault_root_pw>"
11
12# 3. 創建 role
13vault write database/roles/myapp-reader \
14  db_name=myapp-prod \
15  creation_statements="CREATE ROLE \"{{name}}\" WITH LOGIN PASSWORD '{{password}}' VALID UNTIL '{{expiration}}'; \
16                       GRANT SELECT ON ALL TABLES IN SCHEMA public TO \"{{name}}\";" \
17  default_ttl="1h" \
18  max_ttl="24h"

關鍵：vault_root 是 Vault 用來創建其他 user 的 bootstrapping account、權限要含 CREATEROLE、但不需要 SUPERUSER；creation_statements 必須含 VALID UNTIL '{{expiration}}'、否則 DB 端 user 不會自動過期、Vault revoke 失敗時會留 zombie account。

Application 取得 credential

1# Read 動態 credential（每次 read 都產生新 user）
2vault read database/creds/myapp-reader
3# Key                Value
4# lease_id           database/creds/myapp-reader/abc123
5# lease_duration     1h
6# username           v-myapp-reader-x7y8z9-1747512345
7# password           A1b2C3d4E5f6...

Application 從 response 拿三個值：lease_id（用來 renew / revoke）、username + password（DB 連線）、lease_duration（決定何時 renew）。

Renew lease

1# 在 lease 到期前 renew（推薦在 50-70% TTL 跑）
2vault lease renew database/creds/myapp-reader/abc123
3# Key                Value
4# lease_id           database/creds/myapp-reader/abc123
5# lease_duration     1h    # renew 後重置回 default_ttl

lease_duration 在 renew 後 重置回 default_ttl、但 不會超過 max_ttl。例：default 1h / max 24h、application 連 renew 23 小時後、第 24 次 renew Vault 拒絕、application 必須拿新 credential。

Revoke lease（application shutdown 時）

1# Graceful shutdown 時主動 revoke
2vault lease revoke database/creds/myapp-reader/abc123

Application 結束時 revoke 是 credential hygiene 的最後一道閘門 — 即使 lease 還有時間、主動 revoke 讓 DB 端 user 立刻消失、避免 credential 在 application crash dump / log 內被翻出時還能用。

故障演練 / 邊界 case

Case 1：Lease renewal race，credential 中途失效

徵兆：application log 突然出現 FATAL: role "v-myapp-reader-x7y8z9-..." does not exist、且時間點接近某個整點 / 半點。

根因：application 用 lease_duration 推算 renew 時機、但用了 系統時間 而非 lease 簽發時間；application 啟動晚於 lease 簽發 30 秒、renew 跑在 lease 過期後 5 秒、Vault 已 revoke credential、DB 端 user 已刪除。

修法：用 server 回傳的 lease_duration 反推 renew 時機、留 20-30% buffer。例：lease_duration 3600 秒、application 在 2400-2520 秒（66-70%）開始 renew、不要拖到 3500 秒。Vault SDK 多數有 LifetimeWatcher（Go SDK）或 Renewer（Python hvac）這類 helper、優先用 SDK 不要自管 ticker。

Case 2：DB max_connections 撞牆

徵兆：application 在流量高峰開始大量 FATAL: too many connections for role、Vault audit log 顯示新 credential 還在發、PostgreSQL pg_stat_activity 看到上百個 v-myapp-... user 同時連著。

根因：每個 application instance / pod 在啟動時 read 一次 credential、credential lease 1h、但 application 跑 30 分鐘就重啟（K8s rolling update / OOM）；舊 user 還在 PostgreSQL 端連著（connection pool 沒釋放）、新 user 又被創建、累積到 max_connections。

修法：兩層

1. Application graceful shutdown 時 vault lease revoke + connection pool drain
2. PostgreSQL connection pool 加 pool_lifetime_max 跟 application instance lifetime 對齊、避免 connection leak 到 lease 失效後仍 holding

Case 3：Vault sealed 中、existing lease 仍可用但新 lease 拿不到

徵兆：deploy 新 version 時、新 pod 起不來、vault read database/creds/... 卡住或回 Vault is sealed；但 舊 pod 持續運作正常（因為已持有 lease）。

根因：Vault sealed（master key 被 wrap、需要 unseal key 解封）時、existing lease 因為 credential 已在 DB 端創建、application 連線不需要 Vault 介入；但 新 lease 創建需要 Vault / renew 也需要 Vault。Sealed 期間 application 還能用、但無法擴容、無法 renew。

修法：

1. Vault HA cluster + auto-unseal（KMS / HSM auto-unseal）避免人工 unseal 鏈
2. Application 加 retry-with-backoff、Vault 短暫 unavailable 時不要立刻 crash
3. Lease 設長一點（default 4h、max 48h）給 unseal 流程留時間

Case 4：Application Vault token expire、lease orphan

徵兆：application 在連續跑 1-2 週後突然開始 Permission denied on vault lease renew、credential 在 max_ttl 後失效但 application 不知道。

根因：application 的 Vault token（不是 DB credential 的 lease）也有 TTL；token 過期後 application 無法 renew lease、但 application 可能還沒到 自己拿新 token 的循環。Lease 變 orphan（沒人能 renew）、TTL 到就被 revoke。

修法：

1. Application 用 vault-agent injector / sidecar pattern、由 sidecar 維護 token + lease；application 只讀 file
2. 不用 sidecar 時、application token 用 renewable token + 跟 lease 同 lifecycle 管
3. AppRole auth method 的 secret_id 跟 token TTL 都要納入 application reload 流程

Case 5：CircleCI 2023 incident 對照 — secret_id scope 過寬

徵兆：CircleCI 2023 1 月事件、攻擊者拿到開發者 endpoint session token、進而拿到 Vault AppRole 的 secret_id；secret_id 對應的 policy 含 跨環境跨資料庫 read、攻擊者用 secret_id 拿到大量動態 credential。

根因：AppRole secret_id 的 policy scope 設成 single AppRole 服務所有環境、而不是 per-environment AppRole；secret_id 外洩等於拿到全公司 dynamic credential 發放權。

修法：

1. Per-environment AppRole：dev / staging / prod 各有獨立 AppRole + secret_id、policy 只允許該環境的 database engine path
2. Secret_id TTL 短化（< 24h）、用 response wrapping 傳遞、拿到後立刻 unwrap、減少 secret_id 在 build pipeline log 留軌跡
3. Vault audit log 接 SIEM、approle/login 異常 location / IP 即刻 alert

容量規劃

Dynamic credential 的容量設計圍繞 lease churn rate — 每秒多少新 lease 創建、多少 renew、多少 revoke。

實務 sizing 範例：100 個 application pod、lease_duration 1h、renew at 50% TTL：

• 新 lease：100 / 3600 ≈ 0.03/s（pod 重啟才有）
• Renew：100 / 1800 ≈ 0.06/s
• Outstanding lease：~100 個（每 pod 一個）
• DB user 數：~100 個（peak ~150 含 grace period）
• DB connection：100 × 5（pool size）= 500、需要 PostgreSQL max_connections >= 600

超出單 Vault node 容量（~50 ops/s）時、走 Vault HA cluster + auto-unseal、或拆 namespace。

整合 / 下一步

vault-agent injector（K8s 環境推薦）

 1# pod annotation
 2metadata:
 3  annotations:
 4    vault.hashicorp.com/agent-inject: "true"
 5    vault.hashicorp.com/role: "myapp-reader"
 6    vault.hashicorp.com/agent-inject-secret-db-creds: "database/creds/myapp-reader"
 7    vault.hashicorp.com/agent-inject-template-db-creds: |
 8      {{- with secret "database/creds/myapp-reader" -}}
 9      DB_USER={{ .Data.username }}
10      DB_PASSWORD={{ .Data.password }}
11      {{- end }}

Sidecar 自動 renew lease、credential 寫進 pod shared volume、application 讀 file。Application code 不需要 Vault SDK、降低 dependency。

SDK pattern（非 K8s 環境）

Go：hashicorp/vault/api + LifetimeWatcher、Java：spring-cloud-vault、Python：hvac + Renewer。SDK 已處理 renew timing / retry / token rotation、不要自寫 ticker。

跟 cloud-native secret manager 的混搭

AWS Secrets Manager / Google Secret Manager 也有 dynamic credential rotation（每 30 天輪替）、但 cadence 是按時間、不是 按 application session。混搭 pattern：

• Cloud-native：infrastructure-level credential（RDS master / k8s service account）、long TTL（30-90 天）
• Vault dynamic：application-level credential、short TTL（1-24 小時）
• Vault root credential 存 cloud-native secret manager、Vault auto-unseal 也用 cloud KMS

下一步議題

• Database snapshot 跟 dynamic credential 衝突：PostgreSQL pg_dump 用 long-lived credential、不適用 dynamic；snapshot user 用 static + scoped policy、跟 application user 分離
• Connection pool 端的 dynamic credential 支援：PgBouncer 不支援 per-connection credential rotation、需要 connection 整個 lifecycle 跟 lease 對齊
• 多 region Vault replication：performance replication 跟 disaster recovery replication 對 lease 的處理不同、跨 region application 要 sticky 同一 region 的 Vault primary

相關連結

• 上游 vendor 頁：HashiCorp Vault
• 對照案例：Failure: Credential Rotation Without Scope
• 對照案例：CircleCI 2023 AppRole 事件 — Cross-vendor mapping
• 上游 chapter：7.6 秘密管理與機器憑證治理
• 平行 deep article：pgBouncer 配置
• Methodology：Vendor 深度技術文章的寫作方法論

本文是跨 vendor migration playbook、cross-link HashiCorp Vault 跟 AWS Secrets Manager。本文同時是 #128 self-aware limitation 第 1 點「6 維仍可能漏類（identity / consistency / residency 三軸候選）」的 identity 軸驗證。

「secret」不是「secret」：兩家對「secret」的定義不同

把 Vault → AWS Secrets Manager 當成「secret store 替換」是最常見的誤判 — 兩家的「secret」概念跨完全不同的 identity model：

核心差異不在「存 secret 的地方」、在「身份從哪來、怎麼 enforce、怎麼 audit」。 Migration 的真實工作量在 identity model 重設計、不是 secret 搬遷。

跑 6 維 diff dimension audit：

6 維 audit 抓不到「Identity model = High」這軸 — 用既有 6 維歸類、會走 Type C operational redesign + Application change 高維獨立段；但實際工作量分佈：

• Operational redesign（vault cluster 拆 / Lambda 配 / 監控換）：~25%
• Application change（SDK / retry / token 換 IAM credential）：~30%
• Identity model 重設計（每個 secret 對應的 principal / policy / 跨 service auth chain）：~45%

最大工作量塊在 identity model 重設計、不在既有 6 維任一個。Identity 是 候選的第 7 維。

Identity axis 是否獨立：4 個論據

Yes、identity 是獨立軸：

1. Identity 不變 → operational 仍可變：Vault on-prem → Vault on-EKS、operational 變 high 但 identity model 不變（仍 Vault token）；可分開 audit
2. Operational 不變 → identity 仍可變：Vault namespace 重組（管理 50 個 namespace → 5 個 namespace + namespace-level policy）、operational 不變但 identity boundary 重劃；可分開 audit
3. Application change 不變 → identity 仍可變：純 infrastructure-level rotation（手動 → 自動）、application code 不變但 identity issuance flow 變；可分開 audit
4. Paradigm 不變 → identity 仍可變：同樣是 secret store paradigm、Vault token vs IAM principal 是 identity model 差、不是 paradigm 差

No、identity 可塞 application change：

• 反論：application code 改 SDK + IAM signer 都算 application change
• 拒絕：application change 是 consequence、不是 root cause；identity model 變動才是驅動 application change 的原因

實證上、本文 migration 工作量 45% 在 identity 對位、確認 identity 是 獨立的工作量主軸、不該被壓進 application change 軸。

結構：Type C + identity model 對位獨立段

跟既有 Type C PostgreSQL → Aurora 對照、本文多出 identity model 對位 獨立段：

11. 「secret」不是「secret」（identity axis paradox 開頭）
22. Identity axis 是否獨立的論據
33. 結構 differentiator（Type C + identity 獨立段）
44. Identity model 對位（Vault → AWS principal mapping）
55. Operational migration（4 phase）
66. Application change（SDK + retry pattern）
77. Production 故障演練
88. Capacity / cost
99. 整合 / 下一步

9 章節、260-280 行。比標準 Type C 多 1 段（identity model 對位）+ 1 段（axis 獨立論據）。

Identity model 對位

 1Vault concept                    →  AWS Secrets Manager 對應
 2─────────────────────────────────   ────────────────────────────
 3Vault token (auth 結果)           →  AWS STS temporary credential
 4AppRole (auth method)             →  IAM role + AssumeRoleWithWebIdentity
 5Kubernetes auth method            →  IAM Role for Service Account (IRSA)
 6LDAP auth method                  →  IAM Identity Center (formerly SSO)
 7Vault policy (capabilities)       →  IAM policy + Resource policy
 8Path-level ACL (secret/db/*)      →  Resource ARN pattern (arn:aws:secretsmanager:...:secret:db/*)
 9Namespace                         →  AWS account + resource-based isolation
10Audit device                      →  CloudTrail event
11Database secrets engine           →  Lambda rotation function

每行對位都有 語意差、不是 1:1 mapping：

• Vault token TTL vs AWS STS credential expiration：Vault token TTL 可由 application 主動 renew；STS credential 不能 renew、必須 re-assume
• Vault policy capabilities vs IAM action：Vault read capability 對應 AWS secretsmanager:GetSecretValue、但 AWS 還要 resource policy 允許；雙層授權
• Vault Kubernetes auth vs IRSA：兩者都是 K8s service account → secret access、但 IRSA 需要 EKS + OIDC provider 設置、Vault K8s auth 不需要

Migration scope 包含每行對位的 application-level 適配、不是 secret 搬。

Operational migration (4 phase)

Phase 0：Audit + design

• 列所有 Vault secret + path + 使用 application
• 每個 secret 對應 AWS principal（IAM role / IRSA / federation）
• 設計 ARN 命名規則（按 namespace / application / environment）
• 規劃 AWS account boundary（dev / staging / prod 分 account）

Phase 1：AWS Secrets Manager + IAM 設置

• Terraform / CloudFormation 建 secret + IAM role + resource policy
• 設 IRSA / WebIdentity provider
• 預先建 staging secret、跑 application test

Phase 2：Application dual-read

1# Application 同時讀 Vault + AWS Secrets Manager
2def get_db_password():
3    aws_value = boto3.client('secretsmanager').get_secret_value(SecretId='myapp/db')['SecretString']
4    vault_value = vault_client.read('secret/data/myapp/db')['data']['data']['password']
5
6    if aws_value != vault_value:
7        logger.warning(f"Secret diff between Vault and AWS!")
8
9    return aws_value  # Use AWS as source of truth

跑 1-2 週、確認兩端一致 + AWS API latency / error rate 接受。

Phase 3：Cutover + cleanup

• Application 端切到 AWS Secrets Manager only
• Vault read-only 1-2 週 standby
• 之後 decommission Vault cluster

Application change

Application 端必改的 4 個 pattern：

1# Before: Vault SDK
2import hvac
3vault_client = hvac.Client(url='https://vault.internal', token=vault_token)
4secret = vault_client.read('secret/data/myapp/db')['data']['data']['password']
5
6# After: AWS SDK + IAM
7import boto3
8sm = boto3.client('secretsmanager')
9secret = sm.get_secret_value(SecretId='myapp/db')['SecretString']

關鍵差異點：

• Authentication：Vault token 由 application 自管 / refresh；AWS SDK 自動處理 STS credential（透過 IAM role / instance profile / IRSA）
• Caching：Vault secret read 通常 cache 5-15 分鐘；AWS Secrets Manager 有 cache library（aws-secretsmanager-caching-python）需顯式啟用
• Retry pattern：Vault 用 exponential backoff；AWS SDK 自帶 retry but boto3 default 跟 application requirement 不一定 match
• Rotation hook：Vault 用 SDK 端 lease renewal；AWS 用 Lambda rotation function、application 端只需要 re-read

Production 故障演練

Case 1：IAM principal 對位錯、production application 拿不到 secret

徵兆：cutover 後 application 啟動失敗、log 顯示 AccessDeniedException: User: arn:aws:sts::...:assumed-role/EKS-NodeRole/i-xxx is not authorized to perform: secretsmanager:GetSecretValue。

根因：EKS pod 用 node role 而非 pod IRSA role；Phase 0 audit 沒設 service account 對應的 OIDC trust。

修法：

1. 預先設 IRSA：建 IAM OIDC provider for EKS、設 service account annotation
2. 驗證 principal：aws sts get-caller-identity 從 pod 內跑、確認 returned role 是預期的
3. Resource policy + IAM policy 雙層：確認 secret 的 resource policy allow 該 role、IAM policy 也 allow

Case 2：Dynamic credential 對等失敗、application 連 DB 失敗

徵兆：Vault 端用 database secrets engine 自動 rotate DB password、application 透過 Vault SDK 拿 lease；切到 AWS Secrets Manager + Lambda rotation 後、Lambda rotation 完成、但 application 端仍用 cached old password、連 DB 拒絕。

根因：Vault SDK 自帶 lease renewal logic、application 知道 password 即將過期會主動 re-read；AWS SDK 沒 lease 概念、application 自己決定多久 re-read 一次。

修法：

1. 設 cache TTL 短於 rotation interval：rotation 24 小時、cache TTL 1 小時、最壞情況 1 小時 stale
2. 顯式 cache invalidation：rotation Lambda 跑完發 SNS、application subscribe 主動 refresh
3. Connection-level retry：DB connection 認證失敗時 application 重 fetch secret 跟重連
4. 重新評估 rotation cadence：AWS Lambda rotation 不是 Vault dynamic、是 scheduled rotation；不能假設兩者同 semantic

Case 3：Audit log 結構差、SOC dashboard 失效

徵兆：cutover 後 SOC 端 dashboard 顯示 secret access metric 全 0；舊 Vault audit log 結構在 Splunk 端 parse 過、AWS CloudTrail 結構完全不同、search query 全失效。

根因：Vault audit log 是 Vault-specific JSON 結構（含 lease_id / policy / token）；CloudTrail event 是 AWS-specific（含 eventName / requestParameters / userIdentity）；SOC parse rule 不能搬。

修法：

1. Pre-cutover 重寫 SOC rule：CloudTrail event 對應 Vault audit log 的 detection coverage 必須 1:1 mapping
2. GuardDuty integration：AWS GuardDuty 自動 surface secret access anomaly、降低自寫 rule 工作量
3. CloudTrail → S3 → Athena：long-term audit query 走 Athena、tooling 跟 Vault 完全不同、SOC re-training

Case 4：Calling cost 反轉、AWS 比 Vault 自管貴

徵兆：Vault on-prem 跑了 $200 / month（EC2 + ops），切到 AWS Secrets Manager 後 $1500 / month；帳單拆解後 GetSecretValue API call 是大頭。

根因：AWS Secrets Manager $0.05 per 10K API call — application 高頻 read（每 request 都讀 secret + 沒 cache）會爆 cost；Vault 端 application 自管 cache + token TTL 內無 API call。

修法：

1. 強制 application-side cache：用 aws-secretsmanager-caching library、cache TTL 5-15 分鐘、API call 從 100M/month 降到 10K/month
2. Re-architect application：把 high-frequency secret read 改 connection-level（建 DB connection 時讀一次、connection lifecycle 內復用）
3. Cost monitoring：對 secret access 設 CloudWatch alarm、過 threshold 立即 alert

Case 5：跨 region replication 對位失敗、DR 演練失效

徵兆：DR drill 切 region 後、application 連不到 secret；發現 us-west-2 的 Secrets Manager 沒有 us-east-1 的 secret。

根因：AWS Secrets Manager 不是 global resource、是 region-scoped；Vault 自管 multi-DC replication；cutover 漏設 cross-region replication。

修法：

1. 設 secret replication：AWS Secrets Manager 內建 replication 到其他 region（ReplicaRegions）
2. DR drill 必跑：cutover 前 + cutover 後各 drill 一次、驗證 region failover 順
3. 架構：考慮用 AWS Backup 對 Secrets Manager 做 cross-region backup 補強

Capacity / cost

判讀：少 secret + 中頻 read 走 AWS Secrets Manager；高頻 read + multi-cloud / on-prem 約束走 Vault。

整合 / 下一步

跟 Vault Dynamic Credential 對比

Vault dynamic credential 是 Vault 特有 feature、AWS Secrets Manager 用 Lambda rotation 對應、但 semantic 不同：

• Vault: per-application lease、application-aware lifecycle
• AWS: scheduled rotation、application 不知道何時被 rotate

Migration scope 應該 降級 dynamic credential 場景、用 Lambda rotation 替代、application logic 改 cache + retry pattern。

跟 IAM Identity Center 整合

人類存取 secret（emergency break-glass）走 IAM Identity Center + temporary role assumption；不要直接給 user IAM key。

下一步議題

• Reverse migration（AWS → Vault）：通常是 multi-cloud / on-prem 約束驅動、cost 在大 scale 反轉
• Hybrid pattern：cloud-native secret 走 AWS、cross-cloud / on-prem secret 走 Vault；應用程式根據 secret 來源 routing
• identity axis 驗證：本文認為 identity 是獨立軸、未來累積 LDAP → OIDC / 自管 RBAC → IAM 等 migration 驗證

相關連結

• Source vendor：HashiCorp Vault
• Target vendor：AWS Secrets Manager
• 平行 deep article：Vault Dynamic Credential
• 平行 migration playbook (Type C)：PostgreSQL → Aurora（標準 Type C） / MongoDB → Atlas
• 平行 axis 候選驗證 (sibling)：DynamoDB Consistency Model（consistency 候選） / PostgreSQL Multi-Region GDPR Rollout（residency 候選）
• Methodology：Migration playbook methodology / #128 self-aware limitation 第 1 點（identity axis 候選驗證、本文是該驗證的 dogfood）