reviewing-cluster-health

クラスターの健全性の確認

CockroachDB クラスターの包括的な健全性チェックを実行します。診断を開始する前に、このスキルではデプロイメントの状況を確認し、運用担当者のティアに適したクエリとツールを提供します。

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

• 毎日またはシフト開始時の運用健全性チェック
• メンテナンス開始前（Self-Hosted、Advanced、BYOC）
• インシデント後の復旧確認
• 本番環境への準備状況の検証
• 容量とパフォーマンスの監視

実行中のクエリに関する問題の場合： triaging-live-sql-activity を使用してください。 バックグラウンドジョブの場合： monitoring-background-jobs を使用してください。 レンジ分析の場合： analyzing-range-distribution を使用してください。

---

ステップ 1：状況の確認

必須情報

質問	選択肢	重要な理由
デプロイメントティアは？	Self-Hosted、Advanced、BYOC、Standard、Basic	利用可能な診断と運用担当者の責任範囲を決定します
健全性チェックの理由は？	毎日のチェック、メンテナンス前、インシデント後、アップグレード前	どの項目を優先して確認するかを決定します

ティア別の追加情報

Self-Hosted の場合：

質問	選択肢	重要な理由
利用可能なアクセス方法は？	SQL + CLI、SQL のみ	使用できるツールを決定します
クラウドプロバイダーは？	AWS、GCP、Azure、オンプレミス	インフラストラクチャレベルのチェックに影響します
Kubernetes デプロイメントですか？	はい（Operator、Helm、手動）、いいえ	CLI コマンドと監視方法が変わります
ノード数とリージョン数は？	例：9 ノード、3 リージョン	クエリ結果の想定値を定めます

Advanced または BYOC の場合：

質問	選択肢	重要な理由
クラウドプロバイダーは？（BYOC のみ）	AWS、GCP、Azure	ご利用のクラウドアカウントでインフラストラクチャレベルの監視を行うため

Standard の場合：

質問	選択肢	重要な理由
現在プロビジョニングされている vCPU 数は？	数値	コンピューティング使用率を評価する際の状況把握に役立ちます

Basic の場合： 追加情報は必要ありません。

状況に応じた案内

ティア	移動先
Self-Hosted	Self-Hosted の健全性チェック
Advanced	Advanced の健全性チェック
BYOC	BYOC の健全性チェック
Standard	Standard の健全性チェック
Basic	Basic の健全性チェック

---

Self-Hosted の健全性チェック

適用条件： ティア = Self-Hosted

Self-Hosted のノードレベルの健全性は、主に cockroach node status（CLI）と DB Console で確認します。クラスター設定とジョブは、パブリック SQL（SHOW ALL CLUSTER SETTINGS、SHOW JOBS）で確認します。クラスターのトポロジー、ストレージ、証明書を扱う crdb_internal 仮想テーブルは本番環境での使用を目的としていません。本番環境で安全に使用できるテーブルの一覧については、ドキュメントを参照してください。

チェック 1：ノードの稼働状況、バージョン、レプリケーション

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

主な列：

• is_live — false の場合は直ちに調査が必要です
• is_draining、is_decommissioning、membership — 進行中のライフサイクル操作を示します
• started_at — 複数回の実行結果を比較して、ノードの再起動（フラッピング）を確認します
• build — ノードごとのバージョンです。単一の値（またはローリングアップグレード中の 2 つの値）である必要があります
• ranges_underreplicated — 0 以外の場合、ゾーンの num_replicas を下回るレプリカ数のレンジがあることを示します

レンジの詳細な内訳を確認するには、DB Console の Replication ページを使用してください。

チェック 2：ストレージ容量

ストアごとの容量を公開する、本番環境で安全に使用できる SQL ビューはありません。以下を使用してください。

• DB Console の Overview → Storage でノードごとの使用量を確認します
• 各ノードの Prometheus メトリクスエンドポイント：curl -ks https://<node>:8080/_status/vars | grep '^capacity'（capacity、capacity_used、capacity_available）

チェック 3：証明書の有効期限

ノード証明書の有効期限を公開する SQL ビューはありません。以下のいずれかを使用してください。

• cockroach cert list --certs-dir=<certs-dir> を使用して、各ノードで証明書をローカルに確認します
• 単一の証明書ファイルには openssl x509 -in <cert.crt> -noout -enddate を使用します
• Prometheus メトリクスエンドポイント：curl -ks https://<node>:8080/_status/vars | grep '^security_certificate_expiration_'（UNIX タイムスタンプの秒数。node、ca、client_ca、ui_ca）

90 日以内のものはすべて EXPIRING_SOON として扱います。

チェック 4：重要な設定

SELECT variable, value FROM [SHOW ALL CLUSTER SETTINGS]
WHERE variable IN (
  'kv.rangefeed.enabled', 'sql.stats.automatic_collection.enabled',
  'server.time_until_store_dead', 'admission.kv.enabled',
  'cluster.preserve_downgrade_option'
) ORDER BY variable;

gc.ttlseconds はクラスター設定ではなく、ゾーン設定のパラメーターです。関連するテーブル、データベース、またはレンジに対して SHOW ZONE CONFIGURATION FOR ... を実行し、有効な値を確認してください。

チェック 5：概要の集約

DB Console の Cluster Overview ページには、稼働中／停止中のノード数、バージョンの分布、レンジ数、ストレージがまとめて表示されます。CLI では次のようにします。

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

その後、シェルで対象の列を集計します。クラスターの論理バージョンは SQL で取得できます。

SELECT value AS cluster_version FROM [SHOW CLUSTER SETTING version];

理由がメンテナンス前の場合は、実行中のジョブも確認してください。

WITH j AS (SHOW JOBS)
SELECT job_type, COUNT(*) FROM j WHERE status = 'running' GROUP BY job_type;

チェック 6：本番環境への準備状況の評価

クラスターが本番ワークロードに対応できる状態か確認するとき、または定期的な運用レビューで使用します。

# Node count, liveness, and locality diversity
cockroach node status --decommission --certs-dir=<certs-dir> --host=<any-live-node>

出力で is_live = true の行数を数え（本番環境では 3 以上が必要）、locality に複数のリージョン／ゾーンが表示されていることを確認してください。

-- Critical production settings check
SELECT variable, value,
  CASE
    WHEN variable = 'kv.rangefeed.enabled' AND value = 'true' THEN 'OK'
    WHEN variable = 'kv.rangefeed.enabled' AND value = 'false' THEN 'WARN: should be true for CDC'
    WHEN variable = 'sql.stats.automatic_collection.enabled' AND value = 'true' THEN 'OK'
    WHEN variable = 'sql.stats.automatic_collection.enabled' AND value = 'false' THEN 'WARN: should be true'
    WHEN variable = 'admission.kv.enabled' AND value = 'true' THEN 'OK'
    WHEN variable = 'admission.kv.enabled' AND value = 'false' THEN 'WARN: recommended for production'
    WHEN variable = 'cluster.preserve_downgrade_option' AND value != '' THEN 'INFO: finalization pending'
    ELSE 'OK'
  END AS assessment
FROM [SHOW ALL CLUSTER SETTINGS]
WHERE variable IN (
  'kv.rangefeed.enabled', 'sql.stats.automatic_collection.enabled',
  'admission.kv.enabled', 'cluster.preserve_downgrade_option',
  'server.time_until_store_dead'
) ORDER BY variable;

-- Enterprise license status (Self-Hosted only)
SELECT value AS organization FROM [SHOW CLUSTER SETTING cluster.organization];

本番環境への準備状況を確認する完全なチェックリストについては、production-readiness reference を参照してください。

---

高度なヘルスチェック

適用対象： Tier = Advanced

Advanced クラスターは、Cockroach Labs が管理する専用のシングルテナントクラスターです。Cloud Console と SQL の両方からノードレベルの可視性を得られます。

Cloud Console での確認

1. Cluster Overview — すべてのノードが稼働中であることを確認し、ノード数を確認します
2. Metrics — CPU 使用率、QPS、P99 レイテンシー、ストレージ使用率を確認します
3. Alerts — 有効なアラートがないか確認します

CLI と SQL での確認

# Node liveness, version, and replication status
cockroach node status --decommission --certs-dir=<certs-dir> --host=<any-live-node>

ノードごとの is_live、build、ranges_underreplicated を確認します。

-- Recent failed jobs
WITH j AS (SHOW JOBS)
SELECT job_type, status, COUNT(*) FROM j
WHERE status IN ('running', 'failed') AND created > now() - INTERVAL '24 hours'
GROUP BY job_type, status;

Cloud API

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

---

BYOC ヘルスチェック

適用対象： Tier = BYOC

BYOC クラスターは専用で、お客様のクラウドアカウント内で稼働します。Advanced と同じ CockroachDB の可視性に加えて、基盤となるインフラストラクチャに直接アクセスできます。

CockroachDB の健全性

高度なヘルスチェックの手順をすべて実行します。

クラウドプロバイダーのインフラストラクチャ確認

AWS の場合：

aws ec2 describe-instance-status --filters "Name=tag:cockroach-cluster,Values=<cluster-name>"

GCP の場合：

gcloud compute instances list --filter="labels.cockroach-cluster=<cluster-name>"

Azure の場合：

az vm list --resource-group <rg> --query "[?tags.cockroachCluster=='<cluster-name>']"

BYOC の追加確認

• VPC／ネットワーク接続（PrivateLink、PSC、VPC Peering）を確認します
• IAM ロールを確認します。CRL サービスアカウントの権限が引き続き有効であることを確認します
• クラウドプロバイダーのモニタリングを確認し、インフラストラクチャレベルの異常がないか調べます

---

標準ヘルスチェック

適用対象： Tier = Standard

Standard はマルチテナントのマネージドサービスです。監視対象となる個別のノードはありません。インフラストラクチャ、レプリケーション、容量はすべて Cockroach Labs が管理します。ヘルスチェックでは、ワークロードのパフォーマンスとプロビジョニング済みコンピューティングリソースに重点を置きます。

Cloud Console での確認

1. Cluster Overview — クラスターの状態が RUNNING であることを確認します
2. SQL Activity — ステートメントとトランザクションのレイテンシー、エラー率を確認します
3. Storage — 現在の使用量を確認します
4. Compute — プロビジョニング済み vCPU の使用率を確認します

SQL での確認

-- Verify connectivity
SELECT 1;

-- Current version
SELECT version();

-- Recent failed jobs
WITH j AS (SHOW JOBS)
SELECT job_type, status, description FROM j
WHERE status = 'failed' AND created > now() - INTERVAL '24 hours';

監視項目

• SQL の P99 レイテンシー — Cloud Console の Metrics で追跡します
• エラー率 — ステートメントエラーの急増がないか確認します
• ストレージの増加 — 使用傾向に基づいて計画します
• コンピューティング使用率 — 使用率が継続的に高い場合は、プロビジョニング済み vCPU を増やします

注： Standard ではノードレベルの可視性を利用できません。インフラストラクチャの健全性を監視するには、Cloud Console を使用してください。

---

基本的なヘルスチェック

適用対象： Tier = Basic

Basic は自動スケーリングされるサーバーレスのサービスです。監視対象となるノードやプロビジョニング済みのコンピューティングリソースはありません。インフラストラクチャはすべて Cockroach Labs が管理します。ヘルスチェックでは、接続性、消費量、支出に重点を置きます。

Cloud Console での確認

1. クラスターの概要 — 状態が RUNNING であることを確認します
2. リクエストユニット — 消費率と残りの予算
3. ストレージ — 現在の使用量（10 GiB まで無料）
4. 支出制限 — 想定外の請求を避けるため、制限が設定されていることを確認します

SQL による確認

-- Verify connectivity
SELECT 1;

-- Current version
SELECT version();

-- Recent failed jobs
WITH j AS (SHOW JOBS)
SELECT job_type, status, description FROM j
WHERE status = 'failed' AND created > now() - INTERVAL '24 hours';

監視対象

• リクエストユニット（RU）の消費量 — 支出制限内に収まるよう、Cloud Console で追跡します
• ストレージ使用量 — 10 GiB の無料枠に対する増加を監視します
• クエリ効率 — RU を過剰に消費するクエリを最適化します
• コールドスタート時のレイテンシー — Basic クラスターは非アクティブ時にゼロまでスケールできるため、アイドル状態の後の最初の接続ではレイテンシーが高くなることがあります

---

安全に関する考慮事項

このスキルのチェックはすべて読み取り専用です。データは変更されません。

• セルフホスト： cockroach node status には CLI アクセスが必要です（内部テーブルにフォールバックする場合は、管理者 SQL 権限が必要です）。ほとんどのノードレベルのヘルスチェック用クエリには、本番環境で安全に使用できる SQL の代替手段はありません。
• Advanced/BYOC： cockroach node status は同じように動作します。証明書の検査は Cockroach Labs が管理します。
• Standard/Basic： 設計上、ノードレベルの情報は確認できません。Cloud Console を使用してください。

トラブルシューティング

問題	Tier	対処方法
cockroach node status で権限拒否のエラーが発生する	SH	admin または VIEWCLUSTERMETADATA 権限を持つ証明書を使用します
cockroach node status の出力にノードが表示されない	SH	ノードのプロセスを確認し、--join アドレスを検証します
Standard/Basic の SQL ではノードテーブルを参照できない	STD/BAS	これは想定どおりです。Cloud Console を使用してください
Cloud Console に degraded と表示される	ADV/BYOC	Cloud のステータスページを確認し、サポートに問い合わせます
RU の消費量が多い	BAS	クエリをプロファイリングし、支出制限を設定します
Cloud API が 401 を返す	ADV/BYOC	API キーを再生成します
最初の接続時にレイテンシーが高い	BAS	アイドル状態の後のコールドスタートとして想定される動作です

参考資料

スキルの参考資料：

• 本番環境対応チェックリスト

関連スキル：

• upgrading-cluster-version
• managing-cluster-capacity
• performing-cluster-maintenance
• monitoring-background-jobs

CockroachDB 公式ドキュメント：

• モニタリングとアラート
• cockroach node status
• 本番環境チェックリスト
• Cloud Console のモニタリング
• メトリクスのエクスポート（Advanced）