upgrading-cluster-version

クラスターのバージョンアップグレード

CockroachDB のバージョンアップグレードをエンドツーエンドで案内します。手順を提示する前に、このスキルではデプロイの状況を確認し、オペレーターのティアに関連する手順だけを提示します。

このスキルを使用するタイミング

• バージョンアップグレードを計画または実行するとき（Self-Hosted）
• Cloud Console からメジャーバージョンアップグレードを開始するとき（Advanced、BYOC）
• パッチの適用方法を設定するとき（Advanced、BYOC）
• アップグレードの完了を確認するとき（すべてのティア）
• 確定するかロールバックするかを判断するとき（Self-Hosted）

アップグレード前のヘルスチェックについて： reviewing-cluster-health を使用してください。 Self-Hosted のアップグレード中のノードドレインについて： performing-cluster-maintenance を使用してください。 メンテナンスウィンドウの設定について： performing-cluster-maintenance を使用してください。

---

ステップ 1：コンテキストの収集

必須コンテキスト

質問	選択肢	重要な理由
デプロイのティアは？	Self-Hosted、Advanced、BYOC、Standard、Basic	ティアごとにアップグレード手順がまったく異なります
現在のバージョンは？	例：v24.2.5	アップグレードパスと互換性を検証します

追加のコンテキスト（ティア別）

Self-Hosted の場合：

質問	選択肢	重要な理由
アップグレードの種類は？	メジャー（例：24.2→24.3）、パッチ（例：24.2.5→24.2.8）	メジャーアップグレードでは確定が必要ですが、パッチでは不要です
ターゲットバージョンは？	例：v24.3.1	バージョンが利用可能で、順次アップグレードできることを確認します
デプロイプラットフォームは？	ベアメタル、VM、Kubernetes（Operator／Helm／手動）	バイナリの置き換えと再起動の手順が変わります
プロセスマネージャーは？	systemd、手動、コンテナーオーケストレーター	停止／起動コマンドが変わります
ノード数は？	数値	アップグレードの順序に影響します

Advanced または BYOC の場合：

質問	選択肢	重要な理由
アップグレードの種類は？	メジャーバージョン、パッチ	メジャーアップグレードは Console からの開始が必要で、パッチではメンテナンスウィンドウを使用します
クラウドプロバイダーは？（BYOC のみ）	AWS、GCP、Azure	アップグレード中のインフラストラクチャレベルの監視に使用します
リリースチャネルは？	Regular、Innovation	Innovation では最新機能を利用できますが、サポート期間は短くなります

Standard または Basic の場合： 追加のコンテキストは不要です。アップグレードはすべて自動で行われます。

コンテキストに基づくルーティング

ティア	移動先
Self-Hosted	Self-Hosted のアップグレード
Advanced	Advanced のアップグレード
BYOC	BYOC のアップグレード
Standard	Standard のアップグレード
Basic	Basic のアップグレード

---

Self-Hosted のアップグレード

該当条件： ティア = Self-Hosted

メジャーアップグレードとパッチ

項目	メジャー（例：24.2→24.3）	パッチ（例：24.2.5→24.2.8）
確定が必要	はい	いいえ
ロールバック可能	確定前	常に可能（バイナリの入れ替え）
自動確定	デフォルトで有効（無効化を推奨）	該当なし

アップグレード前の検証

# All nodes live, version-consistent, fully replicated
cockroach node status --decommission --certs-dir=<certs-dir> --host=<any-live-node>

出力では、すべてのノードで is_live = true が表示され、build 列の値が 1 つだけであり、すべてのノードで ranges_underreplicated が 0 になっていることを確認してください。

-- No bulk operations running
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');

-- No pending finalization from a previous upgrade
SHOW CLUSTER SETTING cluster.preserve_downgrade_option;

自動確定を無効化する（メジャーバージョン — 推奨）

SET CLUSTER SETTING cluster.preserve_downgrade_option = '<current_version>';
-- Example: SET CLUSTER SETTING cluster.preserve_downgrade_option = '24.2';

ノードのローリングアップグレード（ノードごとに繰り返す）

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

cockroach node drain --self --certs-dir=<certs-dir> --host=<node-address>
sudo systemctl stop cockroachdb
cp /path/to/new/cockroach /usr/local/bin/cockroach
cockroach version  # verify new binary
sudo systemctl start cockroachdb

Kubernetes（Operator）の場合：

kubectl patch crdbcluster <name> --type merge -p '{"spec":{"cockroachDBVersion":"<new-version>"}}'
# Operator handles rolling restart automatically

Kubernetes（Helm）の場合：

helm upgrade cockroachdb cockroachdb/cockroachdb --set image.tag=<new-version>

Kubernetes（手動の StatefulSet）の場合：

kubectl set image statefulset/cockroachdb cockroachdb=cockroachdb/cockroach:<new-version>

次のノードに進む前に、各ノードを検証してください：

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

対象ノードで、新しい build に対して is_live = true が表示される必要があります。

進行状況の監視

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

すべての行で build 列を比較してください。旧バージョンのままのノードは保留中です。すべての行に新しいバージョンが表示されると、ローリングアップグレードは完了です。

完了（メジャーバージョンのみ — 元に戻せません）

cockroach node status で build 列の値が 1 つだけになっていること（すべてのノードがアップグレード済みであること）を確認します。その後、次を実行します。

RESET CLUSTER SETTING cluster.preserve_downgrade_option;
SHOW CLUSTER SETTING version;  -- Monitor until updated

ロールバック（完了処理の前のみ）

cluster.preserve_downgrade_option が引き続き旧バージョンを返すことを確認し、各ノードのバイナリを以前のバージョンに置き換えて再起動します。すべてのノードが元に戻った後、次を実行します。

RESET CLUSTER SETTING cluster.preserve_downgrade_option;

---

高度なアップグレード

適用条件： Tier = Advanced

Advanced クラスターは Cockroach Labs によって管理されます。メジャーアップグレードはお客様が開始し、パッチは自動的に適用されます。

メジャーバージョンのアップグレード

1. Cloud Console → Cluster → Settings → Upgrade
2. 対象バージョンを選択します
3. CRL がノード全体にローリングアップグレードを自動的に実行します
4. Cloud Console で進行状況を監視します
5. テスト完了後、Cloud Console でアップグレードを完了します

アップグレード中の確認：

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

build 列を集計して、新旧それぞれのバージョンを実行しているノード数を確認します。

パッチアップグレード

パッチは、設定済みのメンテナンスウィンドウ中に自動的に適用されます。メンテナンスウィンドウの設定とパッチの延期については、performing-cluster-maintenance を参照してください。

リリースチャネル

• Regular： 安定性を重視し、サポート期間が長い
• Innovation： 最新機能を提供し、サポート期間は短く、スキップできる

Cloud Console → Cluster → Settings → Upgrades で設定します。

サポート終了前のアップグレード

現在のバージョンがサポート終了（EOS）を迎える前にメジャーアップグレードを開始する責任はお客様にあります。EOS 前にアップグレードしない場合、SLA の保証に影響する可能性があります。

Cloud API

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

---

BYOC のアップグレード

適用条件： Tier = BYOC

BYOC のアップグレード手順は Advanced と同じです。高度なアップグレードのすべての手順に従ってください。

アップグレード中のクラウドプロバイダーの監視

BYOC クラスターはお客様のクラウドアカウントで稼働するため、インフラストラクチャ上でローリングアップグレードを確認できます。

AWS の場合： EC2 コンソールにインスタンスの再起動が表示されます。CloudWatch メトリクスでは、ノードの切り替え中に一時的な低下が確認できます。

GCP の場合： Compute Engine コンソールに VM の再起動が表示されます。Cloud Monitoring ではインスタンスレベルのイベントを確認できます。

Azure の場合： Azure portal に VM の再起動が表示されます。Azure Monitor でインスタンスイベントを記録できます。

BYOC に関するその他の考慮事項

• アップグレード中も PrivateLink/PSC/VPC Peering 接続が正常に維持されることを確認してください
• 予約済みインスタンスと確約利用割引には影響しません（インスタンスタイプは変更されません）

---

Standard のアップグレード

適用条件： Tier = Standard

Standard はマルチテナント型のマネージドサービスです。お客様が管理するノードやインフラストラクチャはありません。メジャーバージョンとパッチの両方を含むすべてのアップグレードは、Cockroach Labs によって自動的に適用されます。

• Regular リリースのみ（Innovation チャネルなし）
• メンテナンスウィンドウの設定なし
• 延期機能なし
• アップグレード中のダウンタイムなし

アップグレード後

1. Cloud Console でアップグレード通知を監視します
2. リリースノートで動作の変更を確認します
3. アプリケーションとの互換性を確認します。

   SELECT version();
   

---

Basic のアップグレード

適用条件： Tier = Basic

Basic はサーバーレスサービスです。すべてのアップグレードは完全に管理され、透過的に実行されます。サーバーレスアーキテクチャは、お客様による操作なしでダウンタイムゼロのアップグレードを実現するように設計されています。

アップグレード後

1. リリースノートで動作の変更を確認します
2. 必要に応じてバージョンを確認します：SELECT version();

---

安全上の考慮事項

操作	Tier	元に戻せますか？
preserve_downgrade_option の設定	SH	はい
ノードバイナリの置き換え	SH	はい（完了前に元に戻す）
アップグレードの完了	SH	いいえ — 元に戻せません
Cloud Console でアップグレードを開始	ADV/BYOC	サポートに連絡して相談してください
自動アップグレード	STD/BAS	該当なし（CRL が管理）

重要：

• メジャーバージョンをスキップしないでください（SH）—アップグレードは順番に行う必要があります
• テスト前に完了しないでください（SH）—完了処理は元に戻せません
• アップグレード中にクラスター設定を変更しないでください（SH、ADV、BYOC）

トラブルシューティング

問題	ティア	対処方法
preserve_downgrade_option を設定できない	SH	値は SHOW CLUSTER SETTING version の出力と一致している必要があります
ファイナライズが停止している	SH	停止したノードをデコミッションし、稼働中のすべてのノードがアップグレードされていることを確認してください
自動ファイナライズが早期に実行された	SH	元に戻すことはできません。新しいバージョンでアプリケーションをテストしてください
Console でアップグレードが利用できない	ADV/BYOC	リリーススケジュールを確認し、サポートにお問い合わせください
自動アップグレード後に動作が変わった	STD/BAS	リリースノートを確認し、サポートにお問い合わせください

参考資料

関連スキル：

• reviewing-cluster-health — アップグレード前後の健全性
• performing-cluster-maintenance — ノードのドレイン（SH）とメンテナンスウィンドウ（ADV/BYOC）
• managing-cluster-settings — preserve_downgrade_option

CockroachDB 公式ドキュメント：

• セルフホスト環境のアップグレード
• クラウドクラスターのアップグレード
• クラウドのアップグレードポリシー
• Kubernetes でのアップグレード