Vault Token Renewal: TTLとMax TTLを正しく理解して更新運用を固める

Vaultのトークンや動的シークレットはTTLで失効し、更新時はMax TTLやPeriodなど複数の上限に縛られます。資格試験でも“どこで何が上限になるか”が頻出です。

この記事では、公式ドキュメントに沿った安定仕様に限定し、TTL/Max TTL/Periodの違い、更新の制約、チューニングの優先順位、運用時の落とし穴をまとめます。

TTLとMax TTLの基本：定義と捉え方

TTLは発行時からの残存有効期間、Max TTLは更新を含む通算の最長寿命（非Periodicの場合）です。更新要求はサーバ側で上限に丸め込まれるため、指定した-increment通りに延びるとは限りません。

PeriodicトークンはPeriodを必ず継続更新する前提で、理論上の最大寿命に上限がありません。一方、Batchトークンは軽量だが更新不可です。動的シークレットの“リースTTL”はトークンのTTLとは別物で、各シークレットエンジン/ロールの設定とマウントの上限に従います。

• 非Periodicトークン: TTLは更新で延長可能。ただし通算寿命はMax TTLまで。
• Periodicトークン: Periodごとに更新必須。Max TTLの概念は適用外（理論上無期限）。
• Batchトークン: 更新不可。短寿命のアクセストークン用途。
• 動的シークレット: リースのTTL/Max TTLはシークレットエンジンやロール設定に依存。

非Periodicトークンの寿命イメージ（TTLとMax TTL）

T0                   T1             T2                T_max
|---------------------|--------------|------------------|
発行                  更新1          更新2               Max TTL到達

残TTL:  ^^^^^^^^^^^^^
更新は可能だが、T_max（発行時刻+token_max_ttl）を越えては延長されない

更新可否とトークン種別：Service / Periodic / Batch

更新可能かどうかは、トークンの種類と作成時属性で決まります。serviceトークンはrenewable=trueであれば更新可能、periodicはPeriod前提で更新必須、batchは更新不可です。lookupでrenewableやperiodの有無を確認できます。

CLIでの作成例を示します。periodicトークンの発行は、認可されたルート/管理権限またはperiodを定義する認証メソッド/ロール経由で行います。

• vault token lookupでrenewable, ttl, policies, periodを確認
• batchは軽量だが、更新・子トークン発行・cubbyholeが不可
• periodicはMax TTLの上限なく継続運用が可能だが、更新漏れ即失効

トークンの作成と更新の基本

# サービストークン（非Periodic、更新可）
$ vault token create -ttl=20m
Key                  Value
---                  -----
token                s.XYZ...

# 更新（サーバ側で上限に丸められる）
$ vault token renew -increment=30m s.XYZ...

# バッチトークン（更新不可）
$ vault token create -type=batch -ttl=30m
$ vault token renew s.BATCH...
Error: token is not renewable

# Periodicトークン（権限がある場合の例。認証メソッド/ロールでperiodを設定するのが実務的）
$ vault token create -period=1h
$ vault token lookup s.PERIODIC...
period          1h
renewable       true

上限の決まり方：ロール/認証メソッド/システムの優先順位

トークンの初期TTLと更新上限は“要求値”が最上位に見えても、実際はロール、認証メソッド、システム設定で順に制約されます。試験ではどの層がどの値を支配するかを問われます。

代表的な順序は以下です。periodが設定されると、そのトークンはPeriodicになり、Max TTLは無視されます。

• 発行要求のTTL/Period（CLIオプションやAPIのリクエスト）
• ロールの設定（例: token_ttl, token_max_ttl, token_period）
• 認証メソッドのチューニング（token_ttl, token_max_ttl, token_period）
• マウント/システムのdefault_lease_ttl, max_lease_ttl（最終上限）
• Periodicが有効な場合、Max TTLは適用外（Period内更新が必須）

認証メソッドのチューニング例（userpass）

# 認証メソッドを有効化
$ vault auth enable userpass

# 初期TTLとMax TTLをチューニング（非Periodic）
$ vault auth tune -token-ttl=30m -token-max-ttl=4h userpass/

# Periodicにしたい場合（Max TTLではなくPeriodが効く）
$ vault auth tune -token-period=1h userpass/

# ユーザー作成とログイン（例）
$ vault write auth/userpass/users/alice password='s3cr3t' policies=default
$ vault login -method=userpass username=alice password='s3cr3t'

# 付与されたトークンの属性を確認
$ vault token lookup

更新の実務：-incrementの意味と丸め込み、観測の仕方

renewの-incrementは“希望値”です。サーバはMax TTLやPeriod、ポリシー上限で結果TTLを丸めます。丸め込みは正常動作であり、エラーではありません。

更新前後のTTLはlookupで都度確認します。スケジューラでPeriodicの更新タイミング（例: Periodの60–80%時点）を切ると安定します。

• 丸め込み例: 現在TTL 8分、Max TTLまで残り10分のトークンに-increment=30m → 実際のTTLは最大で10分にしか延びない
• PeriodicはPeriodを越える延長は不可。更新をサボると即時失効
• Batchはrenew対象外。エラーを監視で握りつぶさない

renewと観測の最小セット

# 現在のTTL/属性を確認
$ vault token lookup s.XYZ...

# 希望増分を指定して更新（結果はサーバで丸め）
$ vault token renew -increment=45m s.XYZ...

# 再度確認
$ vault token lookup s.XYZ...

動的シークレットのリースとトークンTTLの関係

動的シークレットのリースTTLはトークンのTTLとは独立設定ですが、親トークンが失効/取り消しされると、そのトークンから派生したリースは原則として取り消されます。実務では“トークンTTL ≥ 利用中シークレットのTTL”か、確実なトークン更新ジョブを用意します。

リース更新はトークン更新とは別APIです。混同しないように運用パイプラインを分け、失効時の再発行と権限最小化を設計しましょう。

• リースの更新: sys/leases/renew（vault lease renew）
• トークンの更新: sys/auth/token/renew-self相当（vault token renew）
• 親トークン失効は子リース/子トークンの取り消しを引き起こす

リースとトークンの更新を分けて扱う

# 例: 動的シークレットのリースIDを更新
$ vault lease renew database/creds/readonly/AbCdEfGh

# 例: アクティブなトークンを延長
$ vault token renew -increment=30m

# 注意: トークンをrevokeすると、当該トークンで発行したリースは取り消される
$ vault token revoke s.XYZ...

試験対策チェックリストと落とし穴

Associate対策では、“どの設定がどの上限に影響するか”と“PeriodicはMax TTLに縛られない”の2点を確実に押さえます。実務では更新スケジュールと監視をセットで設計することが重要です。

• PeriodicとMax TTLは同時適用されない（Periodic優先）
• Batchは更新不可。renewable=falseのトークンはrenew不可
• 更新-incrementは希望値。結果はサーバが丸める
• ロール > 認証メソッド > システムの順で上限が絞られる（より厳しい側が勝つ）
• 親トークン失効は子リース/子トークンの取り消しを誘発
• lookupでrenewable/ttl/periodを常に観測し、警報はTTL閾値で発火

問題で確認

よくある質問