Redis / Valkey の日常運用と障害シナリオ (Cluster と Sentinel)

構築ガイドではありません: 構築済みの Redis Cluster または Sentinel 管理の master/replica 構成を日常的に運用し、障害時に復旧するためのシナリオ別 runbook です (Redis 7.2、Redis 8、Valkey)。Cluster: ヘルスチェック、ノードの追加/削除、rebalance/reshard、手動 failover (FORCE と TAKEOVER の違い)、障害ノードの交換と --cluster fix。Sentinel: 状態と quorum、SENTINEL FAILOVER、ノードの追加/削除と SENTINEL RESET、設定変更。両方に共通: メモリ逼迫と大きなキー/ホットキーの診断。何をすべきかわからない場合はヘルスチェックから始めてください。バックアップからのリストアとセキュリティ強化は別の Redis ガイドで扱います。

構成: Redis Cluster (master 3 台以上 + replica) または Sentinel (master 1 台 + replica + Sentinel 3 台)

シナリオ

• Cluster のヘルスチェック (--cluster check、CLUSTER INFO / NODES) — 参照のみ: すべての slot がカバーされているか、ノード間で構成が一致しているか、障害 (fail) ノードや replica のない master がないかを確認します。何をすべきかわからない場合はここから始めてください。
• クラスタにノードを追加する (master または replica) — 新しいインスタンス (cluster-enabled yes、空) の準備ができている場合: master としてクラスタに参加して slot を受け取るか、ある master の replica になります。停止はありません。
• クラスタからノードを削除する (slot を空にする + del-node) — master または replica を撤去する場合: master の slot を他の master に移動してから、ノードをクラスタから削除します。停止はありません。移動中は ASK リダイレクトが発生します。
• slot を再配置する (rebalance / reshard) — master 間で slot やメモリが偏っている、新しい master に slot が割り当てられていない、または特定数の slot をある master から別の master へ移動する場合。
• 手動 failover: replica を master にする (CLUSTER FAILOVER、FORCE、TAKEOVER) — master のサーバーでメンテナンスを行う場合 (計画的、データ損失なし)、または master に到達できず自動 failover が起きなかった場合 (FORCE / TAKEOVER、データ損失のリスクあり)。
• 障害 master / ノードを交換する (FORGET、新しい replica、--cluster fix) — ノードのサーバーが完全に失われた場合: その replica が master になっていれば旧ノードを FORGET させ、代わりに新しい replica を追加します。replica がなければ slot の所有者がいなくなるため --cluster fix で埋めます (その slot のデータは失われます)。
• Sentinel の状態: master、replica、Sentinel、quorum — 参照のみ: Sentinel が認識している master のアドレス、replica、他の Sentinel、CKQUORUM、直近の failover イベント。Sentinel 構成で何をすべきかわからない場合はここから始めてください。
• Sentinel による手動 failover (SENTINEL FAILOVER) — master のサーバーでメンテナンスを行う場合: Sentinel が最適な replica を master に昇格させ、他の replica とクライアントを新 master に向けます。停止は 1〜2 秒で、master が稼働中であればデータ損失はありません。
• Sentinel 構成でノードを追加 / 削除 / 交換する (SENTINEL RESET) — replica または Sentinel を完全に撤去した、または新規に追加した場合: 新しい replica は REPLICAOF で接続し、Sentinel に残る古い登録は SENTINEL RESET で消去します。
• quorum と Sentinel の設定を変更する (SENTINEL SET) — Sentinel の台数が変わった、または failover の発動が遅すぎる/早すぎる場合: quorum、down-after-milliseconds、failover-timeout、parallel-syncs をすべての Sentinel で変更します。
• メモリ逼迫: 使用量、フラグメンテーション、eviction の診断 — used_memory が maxmemory に近づいた、'OOM command not allowed' エラーが出る、eviction が増えている、RSS が想定より大きい、または replica/AOF のバッファが膨らんだ場合。診断は参照のみで、対処方法は別途説明します。
• 大きなキーとホットキーを見つける (--bigkeys、--memkeys、--hotkeys) — 特定のノードだけメモリや CPU が高い、レイテンシのスパイクがある、DEL に時間がかかる場合: 最も大きいキーと最もアクセスの多いキーを特定し、安全に削除します (UNLINK)。

開始前の確認

• 管理サーバーに … がインストールされていて (… に同梱、/usr/bin/…)、…… インスタンスに…すべてのクラスタノードのクライアントポートとクラスタバスポート (port + 10000) の両方に…Sentinel (…) と Redis (…) に…到達できること。
• … のパスワード (requirepass / masterauth) を把握していること。ステップ内で入力を求められるか、REDIS_PASS 環境変数から取得します。ACL を使っている場合、ユーザーに +@admin (cluster/sentinel コマンド) と +@keyspace の権限が必要です。
• 変更記録を起票し、アプリケーションチームに周知済みであること。failover や slot の移動により、クライアントで短時間の MOVED/ASK リダイレクトや接続断が発生することがあります。cluster-aware なクライアントはこれらに自動で追従します。
• 新しいインスタンス … が Redis Cluster 構築ガイド のとおりに準備済みであること: 同じ … バージョン、cluster-enabled yes、同じ requirepass/masterauth、空のデータディレクトリ (古い nodes-.conf、RDB/AOF なし)、ファイアウォールでクライアントポートとバスポート (port + 10000) が開いている。

ガイドのフェーズ

• 状態: slot のカバー状況、ノード、構成の整合性 (参照のみ) — クラスタを検査する (--cluster check) · ノード、ロール、replica の配置を表示する · 結果を判断する
• 1. 診断: 新しいノードは空で到達可能か — 新しいノードとクラスタを確認する
• 2. 実施: ノードを追加する — ノードをクラスタに追加する (--cluster add-node) · slot を新しい master に配分する (rebalance) · 新しい master 用の replica を計画する
• 3. 検証 — クラスタと新しいノードを検証する
• 1. 診断: ノードは master か、slot を持っているか — 削除するノードのロールと slot を表示する
• 2. 実施: slot を空にしてノードを削除する — master の slot を他の master に移動する · ノードをクラスタから削除する (--cluster del-node) · 撤去したサーバーでサービスを無効化する
• 3. 検証 — クラスタを検証する
• 1. 診断: 現在の配置 — master ごとの slot、キー、メモリ
• 2. 実施 — …slot を均等化する (rebalance)…… 個の slot を移動する (reshard)…
• 1. 診断 — replica のロールと master とのリンクを表示する
• 2. 実施 — failover を開始する (CLUSTER FAILOVER… FORCE… TAKEOVER…)
• 3. 検証 — 新しい構成を検証する
• 1. 診断: 失われたノードと slot のカバー状況 — fail 状態のノードと所有者のいない slot を表示する
• 2. 実施: 失われたノードを FORGET させる — 失われたノードを全ノードに FORGET させる (CLUSTER FORGET) · 所有者のいない slot を埋める (--cluster fix) · 新しいノードを replica として追加する
• 3. 検証と事後作業 — クラスタを検証する
• 状態: master、replica、Sentinel (参照のみ) — Sentinel から見た master と quorum · replica と他の Sentinel を一覧表示する · Sentinel のログで直近の failover イベントを検索する
• 1. 診断 — quorum と replica の準備ができていることを確認する
• 2. 実施 — failover を開始する (SENTINEL FAILOVER)
• 3. 検証 — 新しい master と replica を検証する
• 1. 診断 — Sentinel が認識している replica と Sentinel の数
• 2. 実施 — 新しい replica を master に接続する · 撤去する replica のサービスを停止する · 新しい Sentinel を起動する · 撤去する Sentinel を停止する · すべての Sentinel で SENTINEL RESET
• 3. 検証 — 数と quorum を再確認する
• 1. 診断 — 各 Sentinel で現在の設定を表示する
• 2. 実施 — すべての Sentinel で … を … にする
• 1. 診断: メモリ、上限、eviction — メモリ使用量と上限を表示する (INFO memory) · MEMORY DOCTOR と MEMORY STATS · メモリ設定を表示する
• 2. 対処方法 — 状況別の対処
• 1. 診断: 大きなキーとホットキー — 型ごとの最大のキー (--bigkeys) · メモリ使用量が最大のキー (--memkeys) · ホットキー (--hotkeys) · キーのサイズと型を調べる
• 2. 対処 — 大きなキーを安全に削除する (UNLINK)