Vault KV v1: シンプルなキーバリューで始める静的シークレット管理

KV v1は、バージョニングやメタデータを持たないシンプルなキーバリュー型のシークレットエンジンです。読み書きと削除に特化しており、初期ブートストラップや小規模な設定値の保管に向きます。

現在のVaultではkv v2が既定で使われることが多いため、v1を使いたい場合は有効化時に-version=1を明示します。試験ではこの差異とパスの違いが頻出です。

KV v1の概要と設計原則

KV v1は、指定したマウント配下にキーと値をそのまま保存する静的シークレットストアです。バージョニングや削除の履歴は保持せず、操作は基本的にPUT/GET/LIST/DELETEのみ。動的クレデンシャルのようなリースや自動失効は関与しません。

シンプルさが最大の利点で、アプリの初期化用APIキー、Webhookトークン、少量の設定値などに適します。既定でkv v2が選ばれがちな昨今でも、バージョン管理が不要/不要不急な場合はv1のほうが運用が軽く、ポリシーやパス設計も簡潔です。

• 静的シークレット向け。リース/自動ローテーションなし
• バージョニングなし。削除は即時・不可逆
• パスは <mount>/<path>（例: secret/app）
• LISTには明示的にlist権限が必要
• Wrapはプロトコル機能として利用可能（エンジン非依存）

KV v1の論理フロー（認可→保管）

有効化と基本操作（CLIとHTTP）

kv v1を使うには、マウント時に-version=1を指定します。以降は mount/path へそのままPUT/GET/LIST/DELETEを行います。値は単純なキー=値のマップで、CLIは複数のk=vを一度に扱えます。

LISTには専用のHTTPメソッド（LIST）とポリシーcapability=listが必要です。削除は即時で、v2のような論理削除・復元・破壊削除はありません。

• 有効化: vault secrets enable -version=1 kv
• 書き込み: vault kv put <mount>/<path> k=v ...
• 読み取り: vault kv get <mount>/<path>
• 一覧: vault kv list <mount>/<prefix>
• 削除: vault kv delete <mount>/<path>（不可逆）

CLIとHTTP APIの最小手順

# kv v1 を secret/ にマウント
vault secrets enable -path=secret -version=1 kv

# 書き込み（複数キー）
vault kv put secret/app api_key=s3cr3t env=prod

# 読み取り
vault kv get secret/app

# 一覧（末尾スラッシュに注意）
vault kv list secret/

# 削除（即時・不可逆）
vault kv delete secret/app

# HTTP API（書き込み）
curl \
  -H "X-Vault-Token: $VAULT_TOKEN" \
  -X PUT \
  -d '{"api_key":"s3cr3t","env":"prod"}' \
  "$VAULT_ADDR/v1/secret/app"

# HTTP API（読み取り）
curl -H "X-Vault-Token: $VAULT_TOKEN" "$VAULT_ADDR/v1/secret/app"

KV v1とv2の違い（試験対策の比較表）

Associateでは、v1とv2の相違がよく問われます。特にパスの違い（v1は<mount>/<path>、v2はdata/とmetadata/）と、削除・復元・CASの有無を確実に押さえてください。

CLIは多くの状況でマウントのバージョンを自動検出しますが、ポリシーのパス指定やHTTP APIのエンドポイントは明確に異なります。

• v1はシンプル、バージョニングなし、即時削除
• v2はバージョニング、CAS、論理削除/復元に対応
• ポリシーのパス指定が最大の落とし穴

ポリシー設計と最小権限（LISTを忘れない）

Vaultはデフォルト拒否です。KV v1では、読み取り（read）、書き込み（create/update）、削除（delete）、一覧（list）を必要最小限で付与します。特にLISTは明示しない限りvault kv listが失敗します。

パスはv1なら<mount>/*（例: secret/*）。v2のdata/metadataパス指定と混同しないこと。チームやアプリ単位でprefixを切ると、将来のスケールにも対応しやすくなります。

• デフォルト拒否 → 必要最小限のcapabilitiesを明示
• LISTは専用capability。readとは別物
• パスの粒度はアプリ/環境単位で分割（例: secret/prod/appA/*）
• 書き込み専用トークンと読み取り専用トークンを分離

KV v1向けサンプルACLポリシー（HCL）

path "secret/appA/*" {
  capabilities = ["create", "read", "update", "delete", "list"]
}

# 読み取り専用の例
path "secret/appA/*" {
  capabilities = ["read", "list"]
}

# ルート一覧のみ（インベントリ用途）
path "secret/" {
  capabilities = ["list"]
}

運用のベストプラクティスと落とし穴

バージョニングが無いKV v1では、誤削除・上書きの影響が直撃します。変更フローを明確化し、レビューやバックアップ（例: 定期的にexportして暗号化保管）を用意すると安全です。

キーの命名はprefixで整理し、環境/アプリ/用途で階層化します。大きなバイナリや頻繁な更新が必要なデータは不向きで、外部のストアやv2の採用を検討します。監査ログ（audit device）は必ず有効化し、誰がどのパスを読んだか記録を残しましょう。

• 削除は不可逆 → 事前レビューとエクスポートの仕組み
• 環境・アプリでパスを分離（prod/stg/devなど）
• 大容量データは避け、値は必要最小限に
• Wrapや短命トークンで取り回し時の露出を最小化
• v2が必要な要件（履歴/復元/CAS）が無いか再確認

Associate試験対策チェックリスト

コマンドやパスの差異、ポリシーcapabilitiesの使い分けが頻出です。特にv1とv2のパス、LISTの有無、削除の挙動は取りこぼしやすいポイントです。

• 有効化: vault secrets enable -version=1 kv（-pathで任意マウント）
• v1のAPI: /v1/<mount>/<path>、LISTは/prefixに対して
• v1にバージョニング/CAS/論理削除はない
• v1のポリシーパス例: path "secret/*"
• LIST権限が無いとkv listは失敗する
• 削除は即時・復元不可 → 試験の引っかけに注意

問題で確認

よくある質問