Vault トラブルシューティング：よくある障害と対処（Ops向け実務＋資格対策）

本稿は、Vault 運用（Ops）で実際によく遭遇する障害の切り分けと対処を、最短で原因に到達する型とともにまとめたものです。公式ドキュメントの基本動作に沿い、環境差やバージョン差でブレにくい概念とコマンド中心に解説します。

HashiCorp 認定（Security Automation / Vault 系）でも頻出のテーマであるヘルスチェックの戻りコード、HA 配下でのリダイレクト、トークン/リースの制約、Raft のクォーラムとスナップショットなどを、試験で問われやすい表現に合わせて押さえます。

まずは症状と層で切り分ける

Vault 障害は、クライアント層（CLI/SDK）、ネットワーク/TLS、Vault サーバ（初期化/Seal/状態）、ストレージ/HA（Raft/Consul）、認証/ポリシー/シークレットの5層に分けると速いです。まず「どの層で失敗しているか」を一発で仮置きしてから深掘りします。

最低限の現状把握として、サーバの状態（initialized/sealed/standby/active）と、API の疎通、LB のヘルス、ログの重大エラー（panic, permission denied, context deadline exceeded）を時系列で確認します。環境変数（VAULT_ADDR, VAULT_TOKEN, VAULT_CACERT など）の取り違えは頻出です。

• サーバ状態の確認：vault status と /v1/sys/health の両方を使う
• CLI 側の環境変数と証明書束の確認（VAULT_ADDR/VAULT_NAMESPACE/VAULT_CACERT）
• LB 経由とノード直打ちの比較（どちらで再現するか）
• サーバログ（systemd/journal）と監査ログ（audit）を分けて読む
• 時刻同期（NTP）とディスク空き容量の確認は最初に済ませる

最初の確認コマンド（疎通・状態・環境）

export VAULT_ADDR="https://vault.example.com:8200"
export VAULT_CACERT="/etc/ssl/certs/vault-ca.pem"

# サーバ状態（CLI）
vault status

# ヘルスエンドポイント（LB経由とノード直打ちを比較）
curl -sS --cacert "$VAULT_CACERT" "$VAULT_ADDR/v1/sys/health"

# 環境確認
env | grep -E "^VAULT_|^HTTPS?_" | sort

# サーバログ（systemd）
sudo journalctl -u vault -n 200 --no-pager

# ポート疎通（FW/LB確認）
nc -vz vault.example.com 8200 || true

起動・初期化・Unseal でつまずいたら

初期化済みか未初期化かを誤認すると遠回りになります。/v1/sys/init で initialized の真偽を確認し、初期化済みに再 init をかけないこと。Shamir の Unseal は同一クラスタの key shares を threshold 個集める必要があります。別クラスタのキー混入は定番事故です。

Auto-unseal（KMS 等）失敗は、KMS の権限不足、ネットワーク到達性、Vault 設定の seal ブロックのタイプ/パラメータ誤りが主要因です。監査ログやサーバログに KMS のエラーがそのまま出るので、まずそこを確認します。起動ループは、監査デバイスの出力先が書き込み不可でも発生します。

• 未初期化なら operator init、初期化済みなら絶対に再 init しない
• Shamir Unseal は正しいクラスタの key shares を threshold 集める
• Auto-unseal は seal { type = "awskms" | "gcpckms" | "azurekeyvault" | HSM } の設定・権限・疎通を確認
• 監査デバイス（file/socket）出力先の権限・容量不足で起動失敗する点に注意
• 開発用途以外で file ストレージは避け、運用は基本 Integrated Storage(Raft) か Consul

初期化状態・Unseal の確認と実施

# 初期化状態の確認（真に未初期化かを確認）
curl -sS --cacert "$VAULT_CACERT" "$VAULT_ADDR/v1/sys/init" | jq .

# 初期化（未初期化時のみ。shares/threshold は運用基準で設計）
# 出力される Unseal Keys と Initial Root Token は安全に分割保管
vault operator init \
  -key-shares=5 \
  -key-threshold=3 \
  -format=json > /secure/offline/vault-init.json

# Shamir での Unseal（threshold 回実行）
vault operator unseal

# Auto-unseal 利用時はログで KMS 側の失敗を確認（例）
sudo journalctl -u vault -n 200 --no-pager | grep -i -E "kms|seal|unseal|permission|denied"

ストレージ/HA/Integrated Storage（Raft）の典型障害

Raft は過半数のクォーラムが前提です。ノード故障やネットワーク分断でリーダー選出ができないと全体が停滞します。まず list-peers と autopilot を見て、投票権の有無、リーダー、ラグを把握します。

ディスク逼迫は最も多い障害です。スナップショットを計画的に取得・保管し、必要時にリストアできる運用を整えます。TLS/ホスト名不整合、api_addr/cluster_addr の誤設定も、転送失敗やリダイレクト失敗の大きな原因です。

• vault operator raft list-peers でリーダーと投票権を確認
• autopilot の状態と修復提案を確認し、ラグ大のノードを外す判断も検討
• snapshot save/restore の手順を事前検証。保管先の整備と復旧RTOを把握
• NTP による時刻同期、ディスク空き、inode 空きの監視を有効化
• api_addr はクライアントから到達可能、cluster_addr はノード間通信用に正しく設定

Raft 周りの調査とスナップショット運用

# ピア状況とオートパイロット
vault operator raft list-peers -format=json | jq .
vault operator raft autopilot get -format=json | jq .

# スナップショットの取得（定期バックアップに組み込む）
vault operator raft snapshot save /backup/vault-$(date +%F).snap

# リストア（検証環境で手順を必ず確認）
# vault operator raft snapshot restore /backup/vault-YYYY-MM-DD.snap

# ディスク確認
df -h /var/lib/vault
inode=$(df -i /var/lib/vault | awk 'NR==2{print $4}') && echo "free inodes: $inode"

リクエスト経路とヘルスチェックの要点（LB 配下運用）

HA クラスタで LB を前段に置く場合は、api_addr がクライアントから解決・到達でき、スタンバイがアクティブへ適切にフォワード/リダイレクトできることが重要です。cluster_addr はノード間通信に使用されます。

ヘルスエンドポイントは状態により戻りコードが変わります。デフォルトでは、アクティブは 200、スタンバイは 429、シールドは 503、未初期化は 501。LB のヘルスチェックでスタンバイも通したい場合は、standbyok=true を使い、必要に応じてパラメータで戻りコードを調整します。

• LB のヘルスは /v1/sys/health?standbyok=true などを利用
• api_addr は各ノード固有で外部到達可能なアドレスを設定（LB からの 3xx/フォワード先が到達可能に）
• 証明書の SAN に LB 名・ノード名・IP など必要な識別子を含める
• perf standby を使う場合は perfstandbyok=true も検討

Vault リクエスト経路（HA + LB）

ヘルスエンドポイントの実用例

# アクティブ/スタンバイをともに正常とみなす（LB 側で 200 を期待）
curl -sS --cacert "$VAULT_CACERT" \
  "$VAULT_ADDR/v1/sys/health?standbyok=true&perfstandbyok=true" | jq .

# 状態別コードを明示指定（必要に応じて）
# 例: アクティブ200、スタンバイ200、シールド503、未初期化501
curl -sS --cacert "$VAULT_CACERT" \
  "$VAULT_ADDR/v1/sys/health?standbyok=true&activecode=200&standbycode=200&sealedcode=503&uninitcode=501" -o /dev/null -w "%{http_code}\n"

認証・トークン・リース更新の失敗を最短で直す

トークンの TTL は、発行時 TTL がマウントの max_ttl を超えない、かつトークン自体が renewable である必要があります。periodic トークンは max_ttl の制約を受けず、明示的に renew が必要です。更新が失敗する場合、対象のリース/トークンが renew 不可か、上限 TTL を越えようとしている可能性が高いです。

OIDC/JWT 認証の失敗は、audience、iss、bound_claims の不一致や時刻ずれが定番です。ポリシー不足による permission denied は、token capabilities で対象パスの権限を見るのが最短です。ダイナミックシークレット（DB など）のリース更新/破棄は、ネットワークやバックエンド権限で失敗しやすいので、エンジン側ログとの突合を行います。

• vault token lookup と token capabilities で事実確認
• renew できない時は max_ttl/explicit_max_ttl と renewable フラグを確認
• OIDC/JWT では時計合わせ（NTP）とクレーム一致をまず検証
• ダイナミックシークレットは役割ロールの ttl/max_ttl と DB 権限を両面確認

トークン/リース調査の実例

# トークンの属性確認
vault token lookup $VAULT_TOKEN

# 対象パスの実効権限を確認（permission denied の切り分け）
vault token capabilities $VAULT_TOKEN secret/data/app/config

# リースの一覧と更新（更新不可ならエラーに）
vault list sys/leases/lookup/database/creds/app-role || true
vault lease renew <lease_id>

# マウントやロールの TTL 設定確認
vault read sys/mounts | jq '.data'
# 例: KV の場合はバージョンとパスに注意（kv-v2 は data/ パス）

よくあるエラーメッセージ早見表（原因と即応）

現場で頻出するログ/メッセージを、原因と確認ポイント、即使えるコマンドに紐付けました。まずは再現環境を固定し、LB 経由/直打ち、TLS 有無を比べるのが鉄則です。

• ログは時系列で束ね、クライアント側・サーバ側・監査を突き合わせる
• 証明書の SAN と api_addr/cluster_addr の不一致は高頻度

ログから特徴語を拾う（例）

sudo journalctl -u vault -S "-5min" | grep -i -E \
  "sealed|unseal|forward|leader|raft|denied|deadline|certificate|x509" -n

問題で確認

よくある質問