Vault アップグレード手順

本稿は、HA 構成の Vault を対象に、ダウンタイムを発生させないか、極小化するためのローリングアップグレード手順をまとめます。

特に Integrated Storage（Raft）と Consul ストレージの差分、ヘルスチェックとトラフィック制御、スナップショット取得、リーダーの扱いを重点的に扱います。

アップグレード戦略と互換性の原則

基本方針は、パッチバージョンはローリング可能、マイナーバージョンはリリースノートと互換性注意事項に従う、の二点です。複数マイナーをまたぐ一気のアップグレードは避け、段階的に進めます。HA クラスタではフォロワーから順に更新し、リーダーは最後に更新します。

ストレージ別では、Raft はクラスタ内の混在バージョンを短時間許容する前提で設計されていますが、許容範囲はリリースごとに明記されます。Consul ストレージの場合も Vault ノードのローリング更新が基本ですが、Consul 自体の互換性とヘルスにも留意します。プラグイン（Secrets/Auth/Database など）を使っている場合は、対象バージョンの互換性と署名/ABI を事前に確認してください。

• パッチはローリング可、マイナーはリリースノートに従う（スキップせず段階更新）
• フォロワーから更新、リーダーは最後。必要に応じて step-down を使用
• スナップショット（Raft または Consul）を必ず取得
• ロードバランサのヘルスチェックで更新中ノードを確実に除外
• プラグインとレプリケーション（DR/Performance）の互換性を事前確認

ローリングアップグレード（LB 配下、Raft 3ノード例）

Clients
   |
[ Load Balancer ]  (Health: /v1/sys/health)
   |        |        |
 [n1]----[n2]----[n3]
  |        |        |
 follower  follower  leader
   ^  Step1   ^ Step2   ^ Step3(last)

Step1: LB で n1 をドレイン → n1 を更新/再起動 → ヘルスOKで LB 戻し
Step2: 同様に n2 を更新
Step3: leader を step-down → n3 を更新（再選出後に最後更新）

前提チェック（互換性・ヘルス・ピア）

# バージョン確認
vault version

# クラスタ状態（リーダー/スタンバイ）
vault status

# ヘルスエンドポイント（LB のチェックに合わせる）
curl -s -o /dev/null -w "%{http_code}\n" http://vault.example.com:8200/v1/sys/health
# 代表的なコード: 200=active、429=standby、503=sealed/uninit

# Raft ピア確認（Integrated Storage の場合）
vault operator raft list-peers

事前チェックリストとバックアップ

アップグレードの安全性は事前準備で決まります。対象バージョンのリリースノート、ストレージの互換性、プラグイン署名/ABI、レプリケーション有無、ヘルスチェック挙動（戻り値/タイムアウト）を確認します。RBAC 変更や TLS 設定変更を伴う場合は必ず別環境で検証し、設定差分を明確化します。

バックアップは、Raft なら Vault のスナップショット、Consul なら Consul のスナップショットを取得します。復元手順（リストア）をドキュメント化し、ロールバック時の意思決定ポイント（どの時点で戻すか）を合意しておきます。

• 対象リリースの互換性注意を確認（特にストレージ、API 互換、プラグイン）
• メンテナンスウィンドウ・連絡体制・ロールバック条件の合意
• スナップショット取得と保管先の冗長化
• LB 健全性のしきい値とドレイン手順のリハーサル
• 監視/アラートを一時的にノイズ抑制（メンテナンスモード）

バックアップ取得例

# Raft（Integrated Storage）のスナップショット
env VAULT_TOKEN=... vault operator raft snapshot save /backups/vault-`date +%F-%H%M`.snap

# Consul（Vault が Consul をストレージに使用）
consul snapshot save /backups/consul-`date +%F-%H%M`.snap

# 復元（参考: 事前に単体検証必須）
# vault operator raft snapshot restore /backups/vault-xxxx.snap

トラフィック制御とヘルスチェック設計

最小ダウンタイムの鍵は、アップグレード対象ノードを確実にトラフィックから切り離し、復帰時も健全性が確認できるまで受け入れさせないことです。LB のドレインと Vault のヘルス API を組み合わせ、ローリングの各段階でクォーラムと応答性を確認します。

Vault の /v1/sys/health は、一般的に 200（アクティブ）、429（スタンバイ）、503（シールド/未初期化）を返します。LB は 200 のみを通すか、スタンバイを通してもよい設計かを事前に決め、ルールを固定します。

• LB でノードを手動/自動でドレイン（接続終了待ちを設定）
• ヘルス API のしきい値（200 のみ許容など）を明確化
• 更新時は対象ノードのヘルスが安定するまで LB 復帰させない
• 並列更新は避け、常にクォーラムとリーダー有無を確認

ヘルスチェック例と LB ドレイン（例示）

# ヘルスチェック（LB から）
curl -s -o /dev/null -w "%{http_code}\n" http://n1:8200/v1/sys/health

# 例: HA アクティブのみ通す Nginx 的判定（擬似。実装は環境に合わせる）
# if (status == 200) upstream enable; else disable;

# ドレイン（擬似コマンド。実際は LB ベンダ固有のAPI/CLIを使用）
# lbcli target detach --pool vault --node n1 --drain --timeout 120

Raft（Integrated Storage）のローリング手順

3台以上（奇数台）でクォーラムを維持しながら、フォロワーから順に更新します。最後にリーダーを step-down して更新し、再選出後の安定性を確認します。Auto Unseal を使用していない場合、再起動後の unseal キー投入手順を事前に準備してください。

バイナリ更新は各ノードで停止→置換→起動の順です。サービス管理は systemd 相当を前提にしていますが、実運用の起動管理に合わせて読み替えてください。

• 対象ノードを LB からドレイン
• vault status と raft list-peers でクラスタ健全性を確認
• フォロワーから停止→バイナリ置換→起動→ヘルス安定→LB 復帰
• 最後にリーダー: step-down → 更新 → 安定確認
• 更新ごとにスナップショットが最新であることを再確認

Raft ノードの更新コマンド例（Linux/systemd）

# 1) 対象ノードの切り離し（LB 側）
# lbcli target detach --pool vault --node <node> --drain

# 2) クラスタ状態確認
vault status
vault operator raft list-peers

# 3) サービス停止
sudo systemctl stop vault

# 4) バイナリ置換（検証済みバージョンを配置）
sudo install -m 0755 /tmp/vault-new /usr/local/bin/vault
vault version

# 5) 起動・ヘルス確認
sudo systemctl start vault
sleep 3
vault status
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8200/v1/sys/health

# 6) LB 復帰
# lbcli target attach --pool vault --node <node>

# （リーダー更新時）
# リーダーを明示的に降格してから更新
vault operator step-down
# リーダー再選出後に同様の停止→置換→起動を実施

Consul ストレージ利用時のローリング手順

Vault は Consul をストレージとして利用している場合、Vault ノード自体はステートレスに近く、ローリング更新が容易です。ただし Consul の健全性、スナップショット、ネットワーク/TLS 設定には留意します。まず Consul のスナップショット取得とクラスタ状態確認を行い、Vault ノードをフォロワーから順に更新します。

リーダーの扱いは Raft と同様に、最後に更新します。LB ドレインとヘルスチェックでトラフィック影響を抑え、各ノードごとに起動後の到達性とトークン操作を確認します。

• Consul: consul snapshot save で事前バックアップ
• Vault: フォロワーからローリング、最後にリーダー（必要に応じて step-down）
• LB ドレインとヘルス API による受け入れ制御
• Consul 側のヘルス/リーダー選出も監視

Consul ストレージ時の更新例

# 事前に Consul のバックアップ
consul snapshot save /backups/consul-`date +%F-%H%M`.snap

# Vault ノードのローリング（フォロワーから）
# LB ドレイン → 停止 → 置換 → 起動 → ヘルスOK → LB 復帰
sudo systemctl stop vault
sudo install -m 0755 /tmp/vault-new /usr/local/bin/vault
sudo systemctl start vault
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8200/v1/sys/health

# リーダーは最後に
vault operator step-down

検証・ロールバック・試験対策の要点

各ノード更新後に機能検証を行い、最後にクラスター全体のテストを実施します。代表的には、認証（例: approle/login）、シークレット読み書き（KV v2 で put/get）、重要な Transit 暗号化/復号、レプリケーション状態、監査ログ出力の確認です。主要コンシューマのアプリからも 5xx の増加がないかを確認します。

ロールバックは、直前に取得したスナップショットの存在と、旧バイナリの保全を前提に、問題の出たノードを切り離して旧バイナリに戻します。ストレージ破壊的変更がなければ、バイナリ差し戻しのみで復旧できるケースが多いですが、リリースノートでストレージスキーマ変更の有無は必ず確認してください。

• 検証: auth/secret/API/監査ログ/レプリケーションをカバー
• メトリクス: 5xx/レイテンシ/リーダー再選出回数を監視
• ロールバック: LB 切り離し→旧バイナリへ戻す→必要時スナップショットから復元
• 試験対策: フォロワー先行、リーダー最後、ヘルス 200/429/503、スナップショット取得、LB ドレインがキーワード

代表的な検証コマンド

# レプリケーション状態
vault read -format=json sys/replication/status | jq .

# KV v2 動作確認
env VAULT_TOKEN=... vault kv put secret/app/foo bar=baz
env VAULT_TOKEN=... vault kv get secret/app/foo

# 監査ログの直近イベント確認（出力先に応じて）
sudo tail -n 100 /var/log/vault/audit.log

問題で確認

よくある質問