Vault Request Forwarding 実装ノート: クラスタ内ルーティングを正しく設計・運用する

Vault の HA クラスタでは、スタンバイノードがクライアントからのリクエストをアクティブノードへ内部転送する Request Forwarding が既定で機能します。これにより、クライアントやロードバランサがリーダーを意識せずに運用できます。

本稿では、安定機能と公式ドキュメントに基づく実装要点を、試験対策（Ops）に通用する観点でまとめます。バージョン依存の挙動は避け、HA 前提の基本を押さえます。

Request Forwarding の基本と前提条件

Request Forwarding は、スタンバイノードが受けた API リクエストをクラスタ内のアクティブノードへ内部転送する仕組みです。従来の 307 リダイレクトと異なり、クライアントはリーダーの場所を意識せず、任意ノードに送るだけで処理されます。

前提はシンプルです。HA 対応ストレージ（Raft 統合ストレージまたは Consul）を使用し、各ノードで api_addr と cluster_addr を正しく設定し、TLS を有効にします。これらが満たされると、スタンバイは自動的に転送を行います。

• HA ストレージが必須（Raft または Consul）
• api_addr はクライアント向け、cluster_addr はノード間通信用
• TLS を有効化し、証明書 SAN に api_addr と cluster_addr のホスト名/IP を含める
• リーダー不在時は転送できないため、LB のヘルスチェックでスタンバイ許可を使い分ける

最小構成例（server.hcl 抜粋: Raft+TLS）

listener "tcp" {
  address       = "0.0.0.0:8200"
  tls_cert_file = "/opt/vault/tls/server.crt"
  tls_key_file  = "/opt/vault/tls/server.key"
}

# クライアントが到達する FQDN/ポート
api_addr    = "https://vault-1.example.com:8200"
# ノード間通信用アドレス（通常 8201）
cluster_addr = "https://vault-1.example.com:8201"

storage "raft" {
  path = "/opt/vault/data"
  retry_join {
    leader_api_addr = "https://vault-1.example.com:8200"
  }
}

tls_disable = 0

通信フローを理解する（クラスタ内ルーティング）

クライアントは LB または直接任意のノードに接続します。スタンバイが受けたリクエストは cluster_addr を用いたノード間 TLS でアクティブに転送され、レスポンスはスタンバイ経由でクライアントへ返ります。追加ホップは生じますが、クライアント実装は単純化されます。

フォワーディングは API の種類を意識せず動作します（書き込み系も転送対象）。ただし、アクティブ不在やノード間通信断では転送失敗となるため、健全性監視とネットワーク疎通の確保が重要です。

• クライアントは任意ノードへ送信可。スタンバイは受信→アクティブに転送→応答を返却
• ノード間は cluster_addr で到達性・TLS が必須
• フォワーディング不可時はエラー（LB の再試行/複数ノード振り分けで軽減）

Request Forwarding の全体フロー

フロー確認（どのノードに当たってもリーダーが応答）

# 任意ノード経由でリーダー情報を取得
$ curl -sS https://vault.any.example.com:8200/v1/sys/leader -k
{"ha_enabled":true,"is_self":false,"leader_address":"https://vault-1.example.com:8200"}

# スタンバイに当たっても転送され、アクティブが処理する

ロードバランサ設計（L4 推奨、ヘルスチェック、タイムアウト）

実務では L4（TCP）LB を推奨します。HTTP レイヤでの書き換えやヘッダ付与は避け、長時間のリクエスト（ワッチ系）に備えてアイドルタイムアウトを十分に確保します。スティッキーは不要です。

ヘルスチェックは /v1/sys/health を使用します。待機系も可とするかは運用方針次第ですが、Request Forwarding を活かすなら standbyok=true を使い、全ノードを配下に入れる設計が扱いやすくなります。

• LB は L4/TCP 型、TLS は基本的にノード終端（終端する場合は再暗号化）
• スティッキー/セッション保持は不要（リーダー固定は不要）
• ヘルスチェック例: /v1/sys/health?standbyok=true
• アイドル/バックエンドのタイムアウトはやや長めに（例: ≥ 65s）

HAProxy の最小例（L4/TCP、ヘルスチェック付き）

frontend vault_in
  bind *:8200
  default_backend vault_nodes

backend vault_nodes
  option tcp-check
  # 健全性: スタンバイも可（要件に応じて変更）
  tcp-check connect
  tcp-check send GET\ /v1/sys/health?standbyok=true\ HTTP/1.1\r\nHost:\ vault\r\n\r\n
  tcp-check expect rstring "(200|429)"
  server vault1 10.0.0.11:8200 check
  server vault2 10.0.0.12:8200 check
  server vault3 10.0.0.13:8200 check

設定検証とトラブルシューティング手順

まずはノード間疎通（cluster_addr）とリーダー選出を確認します。次に任意ノード経由でシークレット読み書きが成功するかを確認し、ログに転送エラーが出ていないか点検します。

失敗しやすいのは証明書 SAN 不備、cluster_addr の名前解決不一致、LB のアイドルタイムアウト過小、ノード間 TCP ブロック（セキュリティグループやファイアウォール）です。

• cluster_addr の解決・TLS ハンドシェイクをまず確認
• sys/leader と sys/health を使って状態取得
• ログに転送失敗（forwarding, cluster）関連の行がないか確認

よく使う確認コマンド

# リーダー確認（任意ノードで可）
$ curl -sS https://vault-2.example.com:8200/v1/sys/leader -k | jq .

# スタンバイ許容の健全性（LB 用）
$ curl -sS "https://vault-2.example.com:8200/v1/sys/health?standbyok=true" -k

# Raft ピア確認（統合ストレージ時）
$ vault operator raft list-peers

# ノード間ポート疎通（cluster_addr 側）
$ nc -vz vault-1.example.com 8201

可用性と障害時の挙動（フェイルオーバと分断）

アクティブがダウンすると、ストレージのリーダー選出により新しいアクティブが昇格します。Request Forwarding は新アクティブに追随します。昇格完了前は転送できないため、クライアントは再試行戦略を持たせるのが安全です。

ネットワーク分断では、スタンバイ→アクティブのノード間 TLS が成立しない側では転送エラーになります。LB を複数 AZ/ゾーンで構成し、任意ノードへの接続と再試行で影響を抑えます。

• フェイルオーバ中は一時的な 5xx/接続失敗があり得るためクライアントでリトライ
• LB の接続先に複数ノードを登録し、短い接続失敗時のバックオフを設定
• 証明書 SAN と DNS がゾーン間で一貫していることを確認

障害シナリオの簡易検証

# 例: 旧アクティブを停止して挙動を見る（検証環境でのみ）
# active ノード
$ sudo systemctl stop vault

# 別ノードから連続でヘルスチェック
$ watch -n 1 'curl -sS https://vault.any.example.com:8200/v1/sys/health -k | jq .'
# 数秒〜十数秒で新アクティブが反映され、転送が再開することを確認

セキュリティと監査の観点

Request Forwarding では、スタンバイからアクティブへの転送経路も TLS で保護されます。ノード間通信用の証明書は api_addr/cluster_addr 双方の SAN を満たすように管理し、証明書更新時は順次ローリングで入れ替えます。

監査ログは最終的にリクエストを処理したノードで確実に記録されます。よって、アクティブ側での監査デバイス設定が中核です。スタンバイ側での監査は転送メタ情報に留まる場合があるため、監査要件はアクティブ側で満たす設計が安全です。

• ノード間 TLS を必須化（tls_disable=0）
• ファイアウォールで 8200/TCP（API）と 8201/TCP（cluster_addr）を許可
• 監査はアクティブ側で必ず有効化し、ローテーション・保全を徹底

最低限の監査・通信制御例

# 監査デバイスの有効化（アクティブで実施、永続化先は運用方針に合わせる）
$ vault audit enable file file_path=/var/log/vault_audit.log

# 例: セキュリティグループ/ファイアウォールの許可（概念）
# API:    8200/TCP クライアント -> すべての Vault ノード
# Cluster:8201/TCP 各 Vault ノード間（双方向）

問題で確認

よくある質問