HashiCorp Vault Mount Tuning 実践ガイド: TTLと可視性の正しい設計

Vaultでは、シークレットエンジンや認証方式ごと（マウント単位）にTTLと可視性を微調整できます。これが適切に設計されていると、短寿命の動的シークレットを安全に回しつつ、不要な露出を避けられます。

本稿は公式ドキュメントの安定仕様に基づき、運用で迷いがちなdefault_lease_ttl・max_lease_ttlの優先関係、listing_visibilityの振る舞いを具体例とともに解説します。バージョンにより微細な差異がある項目は注意書きを付し、試験で問われやすい要点も整理します。

Mount Tuningの基本: どこをどう変えるか

Vaultはシークレットエンジンと認証方式を“マウント”として有効化します。Mount Tuningは、そのマウント単位でTTL（default_lease_ttl, max_lease_ttl）や可視性（listing_visibility）などの振る舞いを上書きする仕組みです。

ポイントは、サーバ全体のデフォルトTTL/最大TTLをベースにしつつ、マウント固有の要件（例: 動的DB資格情報は短TTL、汎用KVは長め）に合わせて微調整すること。tuneの変更は新規に発行されるリース・トークンから適用され、既存のものには遡及しません。

• 対象: シークレットエンジン（例: kv/, database/）、認証方式（例: kubernetes/, oidc/）
• 反映: 新規発行・以後の更新に適用。既存リース/トークンには遡及しない
• 上限: マウントのmax_lease_ttlはサーバ全体のmax_lease_ttlを超えられない

MountごとのTTLと可視性のイメージ

TTLの仕組みと優先順位

default_lease_ttlは、そのマウントから新規に発行されるリースの標準寿命。max_lease_ttlは上限で、更新や発行時のTTLはこの値を超えられません。サーバ全体のmax_lease_ttl（vault serverの設定）も最終上限として働き、マウント側でこれを上回る指定はできません。

更新時の挙動は要注意です。クライアントが長いTTLを要求しても、マウントのmax_lease_ttl（およびサーバ全体の上限）を超える延長は拒否または上限に切り詰められます。エンジンやAPIによってはエラーになる場合と上限に丸められる場合があり得るため、実運用では想定どおりに丸められるかを事前に検証してください。

ロールやエンジン固有のTTL（例: DatabaseエンジンのRoleに設定したTTL）がある場合、しばしばそれがdefault_lease_ttlより優先されますが、いずれもmax_lease_ttlとサーバ上限には拘束されます。

• 新規発行: default_lease_ttlが初期TTL、ただしロール/エンジン固有TTLがあればそれが優先されることがある
• 更新時: 要求TTLはmax_lease_ttl（およびサーバ上限）を超過できない
• 既存リース: tune変更の影響は受けない（更新時の扱いのみ影響）

実践: CLIとAPIでのtune手順

運用で使うのはvault secrets tune（シークレットエンジン）とvault auth tune（認証方式）。単位は1hや30m、3600sのようにわかりやすく指定できます。変更後は-detailedフラグで反映を必ず確認します。

APIで自動化したい場合は、/sys/mounts/<path>/tune（シークレットエンジン）や/sys/auth/<path>/tune（認証方式）に対する読み書きを使います。CI/CDからの変更は、変更前後の値を取得してドリフト検知できるようにしておくと安全です。

• 前提権限: sys/mounts/* または sys/auth/* のtuneに対するupdate/read
• 単位: 30m, 1h, 24h などの期間表記。整数秒も可
• 検証: vault secrets list -detailed、vault auth list -detailed、および /sys/*/tune 読み取り

CLIとAPIの具体例

# シークレットエンジン(database/)のTTLを調整
vault secrets tune -default-lease-ttl=1h -max-lease-ttl=24h database/

# 認証方式(kubernetes/)のTTLを調整
vault auth tune -default-lease-ttl=20m -max-lease-ttl=4h kubernetes/

# KVを一覧から隠す
vault secrets tune -listing-visibility=hidden kv/

# 反映確認（詳細表示）
vault secrets list -detailed
vault auth list -detailed

# APIでtune値を取得（例: database/）
# VAULT_ADDRとVAULT_TOKENを環境変数で指定している前提
curl -sH "X-Vault-Token: $VAULT_TOKEN" "$VAULT_ADDR/v1/sys/mounts/database/tune" | jq .

listing_visibilityでの可視性制御

listing_visibilityは、マウントを一覧にどの程度見せるかを制御します。運用では、存在自体を隠したいパス（例: 管理用KV）にhiddenを使う一方、一般利用のエンジンはdefaultにしておくのが無難です。

値のバリエーションや細かい挙動はVaultのバージョンやUI/ポリシーとの関係に影響されます。特にunauth系の可視化は、未認証状態での列挙挙動に関係するため、利用前に公式ドキュメントと環境での検証を行ってください。

• hiddenは“存在を一覧に出さない”だけで、直アクセスは可能（ポリシーで拒否すべき）
• 可視性設定は誤解されやすいので、一覧に出ない=安全という誤認を避ける
• CI/CDや運用Runbookに、可視性の意図と検証手順を明記

運用パターン: TTL設計と更新戦略

動的シークレットは“短TTL・自動更新”が基本です。例として、database/の資格情報は15〜60分程度、クラウド一時クレデンシャルも同等かやや短めを目安にし、アプリ側は期限前に更新できるよう設計します。更新の上限はマウントのmax_lease_ttlとサーバ上限で縛られるため、更新間隔と上限の差分（バッファ）を十分に確保してください。

KVのような静的データはTTLが直接は関係しませんが、マウントの可視性をhiddenにして運用系パスを目立たせないなどの工夫が有効です。重要なのは、可視性よりも最終的にはポリシーでアクセスを制限することです。

• 短TTLの原則: 失効しても再取得できる設計に
• 更新の健全性: 監視でlease_renew_errorや期限切れを検知
• 上限の管理: max_lease_ttlとサーバ上限の差分を把握
• Runbook: 期待TTL、更新間隔、失効時の復旧手順を明文化

トラブルシュートと試験対策の要点

よくある落とし穴は、tune後に既存リースのTTLが変わらないこと、更新要求がmax_lease_ttlにより想定より短くなる（または拒否される）こと、hiddenにした結果“一覧に見えない=アクセス不可”と誤解することです。いずれも仕様通りの挙動です。

試験対策としては、サーバ上限→マウントmax→マウントdefault/ロール固有TTLの流れ、vault secrets tuneとvault auth tuneの使い分け、listing_visibility=hiddenの意味（非表示だが存在はする）を確実に押さえてください。

• 確認コマンド: vault secrets list -detailed、vault auth list -detailed
• API確認: /sys/mounts/<path>/tune、/sys/auth/<path>/tune
• 変更は新規発行から有効。既存は更新時のみ影響

問題で確認

よくある質問