Vault Integrated Storage: Raft Peers 管理（ノード追加と削除）実務

本稿は、Vault の Integrated Storage（Raft）を前提に、クラスタへのノード追加と削除に焦点を当てます。奇数台構成の維持、過半数の確保、TLS/アドレス設計、そして計画停止・障害時の除去パターンを実務寄りに解説します。

試験対策としては、コマンドの適用対象（リーダー／任意ノード）、過半数の計算、join/remove の要件、そして autopilot の役割を把握しておくと得点に直結します。公式ドキュメントの用語・動作に沿って説明します。

前提と推奨トポロジ：Raft クラスタ運用の土台

Vault の Integrated Storage は Raft でレプリケーションとリーダー選出を行います。投票権を持つノードの過半数が到達可能であることが可用性の鍵です。推奨は 3 台または 5 台の奇数構成で、メンバーの増減時も常に過半数を割らない計画が必要です。

各ノードはローカルディスク上の raft データディレクトリを持ち、TLS を前提とした API 用ポート(既定 8200)とクラスタ内部通信用ポート(既定 8201)を使います。api_addr と cluster_addr は正しい FQDN/SAN で設定し、相互に名前解決・疎通できることがノード追加の前提です。

• 基本コマンド: vault operator raft list-peers / join / remove-peer / autopilot state / step-down
• 奇数台を維持（3 または 5）。追加・削除は1台ずつ、毎回過半数を確認
• 追加前に新ノードの raft データディレクトリが空であること、TLS/SAN とポート(8200/8201)疎通を検証

最小限の Vault サーバ設定例（新規ノード用）

storage "raft" {
  path    = "/opt/vault/data"           # 空ディレクトリを指定
  node_id = "vault-3"                    # 各ノードで一意
}

cluster_name = "vault-prod"
api_addr     = "https://vault-3.example.com:8200"
cluster_addr = "https://vault-3.example.com:8201"

listener "tcp" {
  address        = "0.0.0.0:8200"
  tls_cert_file  = "/etc/vault.d/certs/vault.crt"
  tls_key_file   = "/etc/vault.d/certs/vault.key"
}

tls_disable = 0

ノード追加（オンラインでの拡張）

運用中クラスタへ新しいノードを追加する典型手順です。既存クラスタの可用性を維持したまま拡張できます。追加対象ノードは起動前に設定・証明書・ポート疎通を満たしている必要があります。

join は新ノード側から実行します。コマンドは自身が参照する VAULT_ADDR を新ノードの API に、引数には既存クラスタのリーダー（または到達可能なメンバー）の API アドレスを指定します。

• 新ノード準備: 設定ファイル、TLS 証明書（SAN に api_addr/cluster_addr のホスト名）、空の raft データディレクトリ
• 新ノードを起動し、必要に応じて unseal（自動アンシール推奨）
• 新ノードで vault operator raft join https://<leader>:8200 を実行
• 既存クラスタで vault operator raft list-peers を確認（Peer に追加されること）

ノード追加の流れ（イメージ）

Before (3 nodes):

  [vault-1] (Leader) ---- [vault-2] (Follower)
          \
           \---------------- [vault-3] (Follower)

Add vault-4:

  New Node: [vault-4]
    - start w/ empty raft dir
    - api_addr/cluster_addr set
    - join -> https://vault-1:8200

After (4 nodes,推奨は最終的に5台へ):

  [vault-1] (Leader) ---- [vault-2]
          \
           \---- [vault-3] ---- [vault-4]

ノード追加の実行コマンド例

# 新ノード側で（自身の Vault API に対して操作）
export VAULT_ADDR="https://vault-4.example.com:8200"
export VAULT_CACERT="/etc/vault.d/certs/ca.crt"

# 既存クラスタの API アドレスを指定して join
vault operator raft join https://vault-1.example.com:8200

# 既存クラスタの任意ノードからピア確認
export VAULT_ADDR="https://vault-1.example.com:8200"
vault operator raft list-peers

ノード削除（計画停止と故障時の除去）

削除は必ず過半数を維持できる構成で実施します。5 台構成で 1 台を外す場合は 4 台になり、過半数は 3 です。次の作業で 2 台を同時に停止しないように計画します。

計画停止（ノード健全）の場合は、対象がリーダーであれば step-down を先に実行し、その後 remove-peer でクラスタメンバーシップから外します。恒久故障などでノードが帰ってこない場合も、peer_id を指定して remove-peer します。

• peer_id の取得: vault operator raft list-peers（Node ID を控える）
• 対象がリーダーなら: vault operator step-down（新しいリーダー選出を先行）
• 除去: vault operator raft remove-peer -peer-id=<PEER_ID>
• OS サービス停止とデータディレクトリの扱い: 再利用しないなら安全に破棄（別クラスタに混入させない）

安全な削除手順（計画停止/故障時）

# 1) ピア確認（任意ノードで）
export VAULT_ADDR="https://vault-1.example.com:8200"
vault operator raft list-peers
# 出力の Node ID から対象の PEER_ID を特定

# 2) 対象がリーダーなら一旦降格
vault operator step-down

# 3) メンバーシップから除去
vault operator raft remove-peer -peer-id=<PEER_ID>

# 4) 対象ノード側のサービス停止とデータ処理
# systemctl stop vault
# rm -rf /opt/vault/data  # 再利用しない場合のみ（慎重に）

過半数と可用性の計算：同時作業を避ける指針

Raft は投票権ノードの過半数が生存していなければ書き込み不可になります。追加や削除、ローリングアップグレードでは、常に『次の瞬間に残る台数』で過半数が成り立つかを確認してください。

同時に 2 台以上を止めない、障害発生時は計画作業を凍結し、まずはクラスタの安定化を優先する、といった基本原則を運用 Runbook に明文化しておくと事故を防げます。

• 3 台構成: 1 台までダウン可（2/3 が過半数）
• 5 台構成: 2 台までダウン可（3/5 が過半数）だが、計画停止は常に 1 台ずつ
• 削除前に list-peers と autopilot state を確認して健全性を把握

健全性のクイックチェック

export VAULT_ADDR="https://vault-1.example.com:8200"
# ピア情報
vault operator raft list-peers
# Autopilot の健全性（ラグや候補性）
vault operator raft autopilot state

TLS とアドレス設計：join 失敗の典型原因と対処

join 失敗の多くは TLS/SAN とアドレス設定の不整合です。api_addr はクライアント/CLI が到達する URL、cluster_addr はノード間レプリケーション（ポート 8201）で使われる URL です。証明書の SAN に両者のホスト名（もしくはワイルドカード/SubjectAltName）が含まれているか確認してください。

もう一つの典型は、既にデータが入った raft ディレクトリで join しようとして失敗するケースです。新規参加ノードの raft データディレクトリは空である必要があります。

• ファイアウォール/NACL: 8200（API）と 8201（cluster）双方向を許可
• cluster_name の不一致はメンバーシップに混乱を生むため統一
• node_id の重複は不可。一意な ID を設定
• CA 証明書の配布と VAULT_CACERT/VAULT_CAPATH の設定を徹底

TLS/SAN と疎通の事前チェック例

# SAN の確認（証明書の拡張に api_addr/cluster_addr のホストが含まれるか）
openssl x509 -in /etc/vault.d/certs/vault.crt -noout -text | grep -A1 "Subject Alternative Name"

# API/クラスタ疎通
curl --cacert /etc/vault.d/certs/ca.crt https://vault-1.example.com:8200/v1/sys/health
curl --cacert /etc/vault.d/certs/ca.crt https://vault-1.example.com:8201/raft/configuration || true  # 8201 は証明に失敗しても到達性を把握

自動化とローリングメンテ：踏む手順を固定化する

ローリングアップグレードや OS パッチ適用時は、対象がリーダーであれば step-down → 停止 → 起動 → 健全性確認、を 1 台ずつ進めます。毎回 list-peers/autopilot state を取り、過半数を割らない計画を守ります。

Autopilot はクラスタの健全性監視や不要サーバのクリーンアップに役立ちます。運用では『状態の可視化（state）』をまず活用し、必要に応じて設定変更（set-config）は段階的に検証してから本番に適用しましょう。

• step-down は安全なリーダー交代の基本動作
• 各作業前後に list-peers と autopilot state で差分確認
• 自動化（IaC/スクリプト）でも 1 台単位・待機条件を厳格に

ローリング作業の定型シェル（抜粋）

# 対象ホストがリーダーなら降格
vault operator step-down || true
# 健全性確認
vault operator raft list-peers
vault operator raft autopilot state
# ここで OS/バイナリ更新 → 再起動
# 再度健全性確認して次のノードへ

問題で確認

よくある質問