Vault KV v2: バージョニングとメタデータ徹底整理

KV v2は、同じシークレットの複数バージョンを安全に保持できるのが最大の特徴です。現場ではロールバック、監査、変更衝突の抑止(CAS)に直結します。

この記事では、v1との違い、削除/破壊/復活の挙動、メタデータ項目、APIパスの落とし穴までを、試験で問われやすい観点で整理します。

全体像とKV v1との違い

KV v2は、値そのものと独立にメタデータを管理し、書き込み毎にバージョン番号を自動採番します。最新を書き換えても過去版は保持され、復元や比較が可能です。

APIパスはv1と互換ではありません。CLIは抽象化しますが、ポリシーや直叩きのAPIでは data/ と metadata/ の使い分けが必要です。

• 書き込みは常に新規バージョンを生成。過去版は参照可能
• メタデータは created_time, deletion_time, destroyed, version を含む
• APIエンドポイントは /v1/<mount>/data/<path>（値/バージョン）と /v1/<mount>/metadata/<path>（属性/上限/削除状態）
• CAS(check-and-set)により同時更新競合を検出
• delete は復活可能、destroy は復活不可

KV v2のリクエスト経路とバージョン保持

Client
  |  vault kv put/get/delete
  v
[Mount: secret (kv-v2)]
  |-- /v1/secret/data/<path>       # 値とバージョン操作
  |-- /v1/secret/metadata/<path>   # 属性・上限・削除状態
  '-- backend storage (raft/consul)

Versions: 1 -> 2 -> 3 (最新)
 delete: tombstone (復活可)
 destroy: purge (復活不可)

有効化と基本確認

vault secrets enable -path=secret kv-v2
vault kv put secret/app api_key=AAA env=prod   # v1 作成
vault kv put secret/app api_key=BBB            # v2 作成
vault kv get secret/app                        # デフォルトは最新(v2)
vault kv get -version=1 secret/app             # 過去版を参照

基本操作: put/get/list とバージョン指定

CLIでは -version フラグで任意の過去版を参照できます。書き込みは常に新規バージョンを生成し、既存バージョンを上書きはしません。

list は階層のキー一覧を返します（v2でも CLI の list は有効）。API直叩きでは metadata/ パス側での一覧が基本です。

• 最新以外の参照: vault kv get -version=N <mount>/<path>
• 一覧: vault kv list <mount>/<prefix>
• JSONでメタデータ取得: vault kv get -format=json で .data.metadata.version などを参照

バージョン参照と一覧

# 最新と特定版の取得
vault kv get secret/app
vault kv get -version=1 secret/app

# JSONでバージョン番号だけ取得
vault kv get -format=json secret/app | jq -r '.data.metadata.version'

# 一覧
vault kv list secret/

メタデータ深掘り: フィールドと設定

各バージョンのメタデータには created_time, deletion_time, destroyed, version が含まれます。これにより復元可否や生成時刻をプログラムから判定できます。

メタデータ設定では max_versions（保持上限）、cas_required（CAS必須化）、delete_version_after（論理削除の自動遅延削除タイマー）などを制御できます。未設定時はマウントの既定値に従います。

• max_versions: 上限を超える新規書き込み時、最古の版が自動的に整理対象になる
• cas_required: 更新時に -cas 指定が必須（APIでは options.cas）
• delete_version_after: tombstone後の自動クリーンアップまでの期間（例: 168h）

メタデータ取得/設定（CLIとAPI）

# 単一キーのメタデータ取得
vault kv metadata get secret/app

# メタデータ設定（上限/CAS/遅延削除）
vault kv metadata put -max-versions=20 -cas-required=true -delete-version-after=168h secret/app

# APIでのメタデータ取得と設定
curl -s \
  -H "X-Vault-Token: $VAULT_TOKEN" \
  $VAULT_ADDR/v1/secret/metadata/app | jq

curl -s -X POST \
  -H "X-Vault-Token: $VAULT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"max_versions":20, "cas_required":true, "delete_version_after":"168h"}' \
  $VAULT_ADDR/v1/secret/metadata/app

削除・破壊・復活(undelete)の挙動

KV v2の delete は指定バージョンを論理削除（墓標化）します。undelete で復活できます。destroy は指定バージョンのデータを完全に破壊し、復活できません。

キー全体のメタデータ削除（metadata delete）は、すべてのバージョンとメタデータを一括で破壊します。事故時の影響が大きいため権限設計に注意します。

• 論理削除: vault kv delete -versions=N <mount>/<path>
• 復活: vault kv undelete -versions=N <mount>/<path>
• 完全破壊: vault kv destroy -versions=N <mount>/<path>
• キーごと完全削除: vault kv metadata delete <mount>/<path>

削除と復活のシーケンス

# v2（最新）を確認
vault kv get secret/app

# v1を論理削除（復活可能）
vault kv delete -versions=1 secret/app
vault kv get -version=1 secret/app        # 取得不可（tombstone）
vault kv undelete -versions=1 secret/app  # 復活
vault kv get -version=1 secret/app        # 取得可

# v1を完全破壊（復活不可）
vault kv destroy -versions=1 secret/app

# キー全体を完全削除（全バージョンとメタデータ）
vault kv metadata delete secret/app

CASでの同時更新制御と安全なロールバック

CASは、更新時にクライアントが想定する現在バージョンを提示し、一致した場合のみ書き込みを許可する仕組みです。これにより並行更新の取り違えを防げます。

ロールバックは、過去版を読み出し、その内容を新規として再書き込みして新しいバージョンを作るのが基本です（過去版に“戻す”のではなく、“戻した内容で新規版を作る”）。

• 想定バージョンを確認: jqで .data.metadata.version を取得
• -cas=N を付けて put。ズレていればエラー
• cas_required を有効にすると、CASなし更新を拒否

CAS更新とロールバック例

# 現在バージョンを確認
CURR=$(vault kv get -format=json secret/app | jq -r '.data.metadata.version')

# CASで安全に更新（想定がズレていれば失敗）
vault kv put -cas="$CURR" secret/app api_key=CCC

# v1の内容でロールバック（v3として作成）
OLD=$(vault kv get -format=json -version=1 secret/app | jq -r '.data.data | to_entries | map(\"\(.key)=\(.value)\") | join(" ")')
eval vault kv put secret/app $OLD

ポリシーと運用の要点（Associate向け）

v2では data/ と metadata/ の両方に対して適切な権限を付ける必要があります。readとlist、deleteとdestroy/metadata deleteの違いを区別してください。

ストレージ抑制の観点では、max_versions と delete_version_after の併用が有効です。上限超過時の古い版整理により、不要な保持を防げます。

• 読み取り権限は data/、一覧・メタ操作は metadata/ に付与
• destroy/metadata delete は限定的ロールにのみ付与
• 上限と自動クリーンアップを併用して肥大化を回避

v2を考慮した最小権限ポリシー例

path "secret/data/app" {
  capabilities = ["create", "update", "read"]
}
path "secret/metadata/app" {
  capabilities = ["read", "list", "update"]
}
# 破壊系は分離ロールで
path "secret/destroy/app" {
  capabilities = ["update"]
}
path "secret/metadata/app" {
  capabilities = ["delete"]  # metadata delete 用（慎重に）
}

問題で確認

よくある質問