performing-cluster-maintenance

クラスターのメンテナンスの実施

すべてのデプロイメント階層で、計画的なクラスターのメンテナンスを管理します。Self-Hosted では、個々のノードをドレインして再起動します。Advanced／BYOC では、CRL に適用されるパッチのメンテナンスウィンドウを設定および管理します。Standard と Basic では、メンテナンスは完全に管理されており、お客様による操作は不要です。

このスキルを使用する場面

• OS のパッチ適用、ハードウェアの変更、または構成の更新を計画する場合（Self-Hosted）
• メンテナンスウィンドウを設定または変更する場合（Advanced、BYOC）
• パッチの延期ポリシーを設定する場合（Advanced、BYOC）
• CRL が管理するメンテナンスイベント中に監視する場合（Advanced、BYOC）
• メンテナンス前の検証チェックを実行する場合（Self-Hosted、Advanced、BYOC）
• メンテナンスがアプリケーションに及ぼす影響を把握する場合（すべての階層）
• メンテナンスイベントに備えてアプリケーションを準備する場合（すべての階層）

ノードを恒久的に削除する場合： managing-cluster-capacity を使用してください。 メンテナンス前のヘルスチェックを行う場合： reviewing-cluster-health を使用してください。 バージョンをアップグレードする場合： upgrading-cluster-version を使用してください。

---

ステップ 1：コンテキストを収集する

必要なコンテキスト

質問	選択肢	重要な理由
デプロイメント階層は？	Self-Hosted、Advanced、BYOC、Standard、Basic	メンテナンス手順を決定します
目的は？	メンテナンスの計画、メンテナンスウィンドウの設定、パッチの延期、メンテナンス中の監視、アプリケーションの準備	適切な手順へ案内します

追加のコンテキスト（階層別）

Self-Hosted の場合：

質問	選択肢	重要な理由
メンテナンスの種類は？	OS のパッチ適用、ハードウェアの変更、バイナリのアップグレード、構成の変更、計画的な再起動	順序とメンテナンス後の手順に影響します
デプロイメントプラットフォームは？	ベアメタル、VM、Kubernetes（Operator／Helm／手動）	ドレインおよび再起動コマンドが変わります
プロセスマネージャーは？	systemd、手動、コンテナオーケストレーター	停止／起動コマンドが変わります
対象ノード ID は？	ノード ID	ドレインコマンドに必要です
長時間実行されるクエリが想定されますか？	はい（ドレインのタイムアウトを延長）、いいえ（デフォルトのタイムアウト）	ドレイン待機パラメーターを決定します

Advanced または BYOC の場合：

質問	選択肢	重要な理由
メンテナンスウィンドウは設定済みですか？	はい（スケジュールは？）、いいえ	ウィンドウの設定が必要かどうかを判断します
保留中のパッチはありますか？	はい、いいえ、わからない	緊急度を判断します
クラウドプロバイダーは？（BYOC のみ）	AWS、GCP、Azure	インフラストラクチャレベルの監視に使用します

Standard または Basic の場合： コンテキストは不要です。メンテナンスは完全に管理されています。

コンテキストに基づく案内

階層	移動先
Self-Hosted	Self-Hosted ノードのメンテナンス
Advanced	Advanced のメンテナンス管理
BYOC	BYOC のメンテナンス管理
Standard	Standard のメンテナンス
Basic	Basic のメンテナンス

---

Self-Hosted ノードのメンテナンス

適用対象： 階層 = Self-Hosted

Self-Hosted の運用担当者は、すべてのメンテナンスを直接管理します。基本となる操作は、ノードを停止する前にリースと接続を安全に移動できるよう、ノードをドレインすることです。

メンテナンス前の確認

メンテナンス作業の前に、すべての確認を実行してください。確認に失敗した場合は中止してください。

確認 1～3、5（ノードの稼働状態、ドレイン状態、レプリケーション、バージョンの整合性）：

cockroach node status --decommission --certs-dir=<certs-dir> --host=<any-live-node>

出力で以下の条件が確認された場合は中止してください。

• is_live = false がある（確認 1）
• is_draining = true がある（確認 2）
• ranges_underreplicated > 0 がある（確認 3）
• build 列に異なる値が複数ある（確認 5）

確認 4：実行中の中断を伴うジョブがないこと（続行前に WAIT または一時停止）：

WITH j AS (SHOW JOBS)
SELECT job_id, job_type, status, now() - created AS running_for FROM j
WHERE status IN ('running', 'paused')
  AND job_type IN ('SCHEMA CHANGE', 'BACKUP', 'RESTORE', 'IMPORT', 'NEW SCHEMA CHANGE');

確認 6：ストレージ使用率が安全であること（いずれかのノードが 70% を超える場合は警告）：

本番環境で安全に使用できる SQL ビューでは、ストアごとの容量を確認できません。DB コンソールの 概要 → ストレージ ページを使用するか、ノードごとの Prometheus エンドポイントをスクレイピングしてください。

curl -ks https://<node>:8080/_status/vars | grep -E '^capacity( |_used|_available)'

中止条件： ノードが稼働していない、レンジのレプリケーションが不足している、別のノードがドレイン中、またはローリングアップグレード中の場合は、メンテナンスを続行しないでください。実行中のジョブが完了するまで待つか、一時停止してください。

統合された事前確認スクリプトについては、メンテナンス前確認のリファレンスを参照してください。

ドレインの実行

プラットフォームがベアメタルまたは VM の場合：

cockroach node drain --self --certs-dir=<certs-dir> --host=<node-address>

長時間実行されるクエリが予想される場合：

cockroach node drain --self --certs-dir=<certs-dir> --host=<node-address> --drain-wait=60s

プラットフォームが Kubernetes の場合：

# Operator handles drain automatically during pod eviction
kubectl delete pod <pod-name>
# Or for rolling restart:
kubectl rollout restart statefulset cockroachdb

停止、メンテナンス、再起動

プロセスマネージャーが systemd の場合：

sudo systemctl stop cockroachdb
# ... perform maintenance ...
sudo systemctl start cockroachdb

プロセスマネージャーが手動の場合：

kill -TERM $(pgrep -f 'cockroach start')
# ... perform maintenance ...
cockroach start --certs-dir=<certs-dir> --store=<path> --join=<addresses> --background

プロセスが SIGTERM に応答しない場合を除き、kill -9 は使用しないでください。

再起動後の確認

cockroach node status --certs-dir=<certs-dir> --host=<any-live-node>

再起動したノードでは、is_live = true と表示されます。そのノードの replicas_leaseholders 列は、数分かけてリースが再割り当てされるにつれて増加します。

ドレインのフェーズ、タイムアウト設定、高度なモニタリングについては、ドレインの詳細に関するリファレンスを参照してください。

ストレージのメンテナンス

セルフホストクラスターの定期的なストレージメンテナンス：

バラストファイルの検証：

ls -lh <store-path>/auxiliary/EMERGENCY_BALLAST
# If missing, create: cockroach debug ballast <store-path>/auxiliary/EMERGENCY_BALLAST --size=1GiB

ディスク使用率の確認：

DB コンソールの 概要 → ストレージ ページを使用するか、ノードごとの Prometheus エンドポイントを確認してください。

curl -ks https://<node>:8080/_status/vars | grep -E '^capacity( |_used|_available)'

使用率が 70% を超えるノードは、メンテナンス前に対処してください。ノードをドレインすると、残りのノードの負荷が一時的に増加します。

---

高度なメンテナンス管理

適用対象： Tier = Advanced

Advanced クラスターは Cockroach Labs が管理します。CRL は、設定されたメンテナンスウィンドウ中にパッチを適用し、インフラストラクチャのメンテナンスを実施します。ノードのドレインや再起動は不要です。CRL がローリング再起動で対応します。

メンテナンスウィンドウの設定

1. Cloud Console → Cluster → Settings → Maintenance
2. 週 1 回、6 時間のウィンドウを設定します
   • 曜日を選択します（例：日曜日）
   • 開始時刻を UTC で選択します（例：02:00 UTC）
   • ウィンドウの長さは 6 時間です

ウィンドウを設定していない場合、CRL が任意の時刻にパッチを適用します。

現在のメンテナンスウィンドウの表示

Cloud Console → Cluster → Settings → Maintenance で現在のスケジュールを確認できます。

Cloud API：

curl -s -H "Authorization: Bearer $COCKROACH_API_KEY" \
  "https://cockroachlabs.cloud/api/v1/clusters/<cluster-id>" | jq '.maintenance_window'

パッチの延期

保留中のパッチを延期する必要がある場合（例：テストのため）：

1. Cloud Console → Cluster → Settings → Upgrades
2. 延期期間を選択します：30、60、または 90 日

延期されたパッチも、延期期間の終了時に適用されます。延期は適用を遅らせるだけで、スキップするものではありません。

メンテナンス中の動作

1. CRL がローリング再起動を使用してパッチを適用します。ノードは一度に 1 台です。
2. 各ノードはドレイン（接続とリースを移動）され、更新後に再起動されます。
3. メンテナンス中も、クラスターは利用可能な状態を維持します（複数ノードのクラスター）。
4. 一時的に容量が減少するため、ウィンドウ中はパフォーマンスがわずかに低下する場合があります。

単一ノードのクラスターでは、メンテナンス中にダウンタイムが発生します。本番ワークロードでは、3 台以上のノードへのスケールを検討してください。

メンテナンス中のモニタリング

Cloud Console：

• クラスターの概要に、ローリング再起動中のノードの状態が表示されます
• メトリクスページに QPS と容量の一時的な低下が表示されます
• 一時的なノードの利用不可により、アラートが発生する場合があります

メンテナンス中：

# Check which nodes are currently live and what version they're on
cockroach node status --decommission --certs-dir=<certs-dir> --host=<any-live-node>

ベストプラクティス

• トラフィックが最も少ない時間帯にスケジュールします
• メンテナンス時間帯の前後と最中に P99 レイテンシを監視します
• 本番環境に適用する前に、ステージングクラスターでパッチをテストします
• テストやリリースのサイクルに合わせて、延期機能を使用します
• メンテナンス時間帯にも通知されるよう、アラートを設定します
• アプリケーションで指数バックオフによる接続再試行を実装します

---

BYOC のメンテナンス管理

適用対象： Tier = BYOC

BYOC のメンテナンスには、Advanced と同じ CRL 管理のプロセスが適用されます。メンテナンス時間帯の設定、パッチの延期、監視については、Advanced のメンテナンス管理のすべての手順に従ってください。

クラウドプロバイダーでの可視性

BYOC クラスターはお客様のクラウドアカウントで稼働するため、メンテナンス操作を直接確認できます。

AWS の場合：

• EC2 コンソールに、ローリングパッチ中のインスタンス再起動が表示されます
• CloudWatch メトリクスに、ノードの入れ替え中の短時間の低下が表示されます
• インスタンスの状態変化を通知する CloudWatch アラームを設定します

GCP の場合：

• Compute Engine コンソールに、VM の再起動が表示されます
• Cloud Monitoring に、インスタンスレベルのイベントが表示されます
• インスタンスの稼働時間に関するアラートポリシーを設定します

Azure の場合：

• Azure ポータルに、VM の入れ替えが表示されます
• Azure Monitor に、インスタンスの再起動イベントが記録されます
• VM の可用性に関する Azure アラートを設定します

BYOC インフラストラクチャのメンテナンス

CRL が管理していないクラウドアカウント内のインフラストラクチャ（VPC、セキュリティグループ、IAM、DNS）を変更する場合：

• クラスターに影響する可能性のある変更を行う前に、CRL と調整してください
• CRL が管理するリソース（インスタンス、ディスク、ネットワークインターフェイス）は変更しないでください
• インフラストラクチャの変更は、まずステージング BYOC クラスターでテストしてください
• ネットワーク（PrivateLink、PSC、VPC Peering）の変更には、CRL との調整が必要になる場合があります

---

Standard のメンテナンス

適用対象： Tier = Standard

Standard は、マルチテナント型のマネージドサービスです。ノードはなく、設定するメンテナンス時間帯も、延期するパッチもありません。すべてのメンテナンスは Cockroach Labs が透過的に管理します。

想定される動作

• CRL が選択した低トラフィック時間帯にパッチが適用されます
• メンテナンス中にダウンタイムはありません
• 通常のパッチ適用について、顧客への通知は不要です
• メジャーバージョンのアップグレードも自動的に行われます

アプリケーションの準備

• 指数バックオフによる接続再試行ロジックを実装します
• 短時間のレイテンシ変動を適切に処理します
• サービスに関する通知がないか、Cloud Console を監視します

---

Basic のメンテナンス

適用対象： Tier = Basic

Basic はサーバーレスサービスです。すべてのメンテナンスは Cockroach Labs によって完全に管理されます。サーバーレスアーキテクチャは、ダウンタイムなしでメンテナンスできるように設計されています。

想定される動作

• すべてのパッチとアップグレードは透過的に適用されます
• 顧客側での対応は不要です
• メンテナンス通知は不要です

アプリケーションの準備

• 接続再試行ロジックを実装します（本番アプリケーションではすべて推奨）
• アイドル状態のクラスターはゼロまでスケールする場合があります。非アクティブ状態からの最初の再接続では、レイテンシが高くなることがあります（これはメンテナンスとは無関係です）

---

安全に関する考慮事項

読み取り専用の監視クエリは、すべての階層で安全です。

セルフホストノードのメンテナンス：

• 一度にドレインするノードは 1 つだけにしてください
• ドレインは開始後にキャンセルできません
• アプリケーションには接続再試行ロジックが必要です
• ロードバランサーは、/health?ready=1 がエラーを返すことで、ドレインされたノードを検出します
• プロセスが SIGTERM に応答しない場合を除き、SIGKILL は使用しないでください

Advanced／BYOC のメンテナンス時間帯：

• シングルノードクラスターは、メンテナンス中にダウンタイムが発生します
• パッチの延期が長すぎるとセキュリティ修正が遅れるため、CVE の影響を評価してください
• メンテナンス時間帯中に、CRL が管理するインフラストラクチャを変更しないでください

Standard／Basic： CRL によって完全に管理されるため、顧客側でのメンテナンスリスクはありません。

詳細なリスクマトリックスについては、安全ガイドのリファレンスを参照してください。

トラブルシューティング

問題	階層	対処方法
ドレインが非常に遅い	SH	SHOW CLUSTER STATEMENTS を確認し、停止しているクエリがないか調べます
ドレインが停止する	SH	ログを確認し、応答がない場合は SIGTERM を送信します
再起動後にノードが再参加しない	SH	--join フラグを確認し、ネットワーク接続を調べます
リースがノードに戻らない	SH	5～10 分待ち、lease_count を監視します
クライアントが再接続しない	SH	ロードバランサーのヘルスチェックが成功していることを確認します
メンテナンスウィンドウを逃した	ADV/BYOC	サポートにお問い合わせください
メンテナンスウィンドウ外で予期しないメンテナンスが発生した	ADV/BYOC	緊急パッチはウィンドウ外に適用される場合があります。Cloud Console の通知を確認してください
メンテナンス中のレイテンシー	ADV/BYOC	想定される事象です。一時的に容量が減少します。監視し、ウィンドウ終了後に復旧したことを確認してください

参考資料

スキルの参考資料：

• ドレインのフェーズとタイムアウト
• メンテナンス前の確認
• 安全ガイド

関連スキル：

• クラスターヘルスの確認
• クラスター容量の管理
• クラスターのバージョンアップ

CockroachDB 公式ドキュメント：

• ノードのシャットダウン
• cockroach node drain
• Advanced クラスターの管理
• Cloud のアップグレードポリシー