provisioning-cluster-for-production

本番環境向けクラスターのプロビジョニング

CockroachDB クラスターの作成と、本番環境へのデプロイ設定について説明します。手順を提示する前に、このスキルでは状況を確認し、適切なティアに合わせたプロビジョニング手順と、本番環境向けの強化ガイダンスを提供します。

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

• 新しい CockroachDB クラスターを作成する
• 開発／ステージング用クラスターを本番環境への移行に向けて準備する
• 本番環境への対応状況を確認するため、ハードウェアと設定を検証する
• 適切なデプロイティアとサイジングを選択する

デプロイ後のヘルスチェックについて： クラスターのヘルス確認を使用してください。 継続的な設定管理について： クラスター設定の管理を使用してください。 デプロイ後の容量変更について： クラスター容量の管理を使用してください。

---

手順 1：状況を確認する

必要な情報

質問	選択肢	重要な理由
デプロイティアは？	Self-Hosted、Advanced、BYOC、Standard、Basic	プロビジョニング手順が大きく異なります
環境は？	本番、ステージング、開発	ハードウェアのサイジングと設定の厳密さが決まります

追加情報（ティア別）

Self-Hosted の場合：

質問	選択肢	重要な理由
プラットフォームは？	ベアメタル、VM（AWS/GCP/Azure）、Kubernetes	インストール方法と起動コマンドが変わります
Kubernetes の場合：	Operator（推奨）、Helm、手動の StatefulSet	デプロイ方法が決まります
ノード数は？	3（最小）、5、9 以上	トポロジーとレプリケーションに影響します
マルチリージョンですか？	はい（リージョン数）、いいえ	ローカリティフラグとトポロジーの計画が必要です
想定されるワークロードは？	OLTP、OLTP／分析の混在、書き込み負荷が高い	ハードウェアのサイジングに影響します
セキュリティ要件は？	TLS 必須、保存データの暗号化、CMEK	証明書と暗号化の設定が決まります

Advanced または BYOC の場合：

質問	選択肢	重要な理由
プロビジョニング方法は？	Cloud Console、Cloud API、Terraform	手順が決まります
クラウドプロバイダーは？	AWS、GCP、Azure	リージョンの選択とネットワークに影響します
ノード数とサイズは？	例：8 vCPU のノード 3 台	初期容量が決まります

Standard の場合： 想定ワークロードの規模（vCPU）とストレージの見積もりを確認します。

Basic の場合： 想定される利用パターンと月間予算を確認します。

状況に応じた案内

ティア	参照先
Self-Hosted	Self-Hosted のプロビジョニング
Advanced	Advanced のプロビジョニング
BYOC	BYOC のプロビジョニング
Standard	Standard のプロビジョニング
Basic	Basic のプロビジョニング

---

Self-Hosted のプロビジョニング

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

ハードウェアのサイジング

コンポーネント	最小構成	本番環境で推奨される構成
ノード	3	3 台以上（障害ドメインごとに奇数）
CPU	4 vCPU（バースト不可）	8 vCPU 以上
RAM	16 GB	32 GB 以上
ストレージ	150 GB SSD	500 GB 以上の NVMe SSD
ネットワーク	1 Gbps	10 Gbps

メモリ計算式： --cache + --max-sql-memory <= 75% of total RAM 推奨値：--cache=.25 --max-sql-memory=.25

絶対に使用しないでください： バースト可能なインスタンス、HDD、ネットワーク接続型 HDD、共有 CPU。

クラウドインスタンスの推奨事項については、ハードウェアとインフラストラクチャのリファレンスを参照してください。

VM／ベアメタルへのデプロイ

手順 1：各ノードに CockroachDB をインストールする

curl https://binaries.cockroachdb.com/cockroach-v<version>.linux-amd64.tgz | tar -xz
cp cockroach-v<version>.linux-amd64/cockroach /usr/local/bin/

手順 2：証明書を生成する

cockroach cert create-ca --certs-dir=certs --ca-key=my-safe-directory/ca.key
cockroach cert create-node <node-hostname> <node-ip> localhost 127.0.0.1 \
  --certs-dir=certs --ca-key=my-safe-directory/ca.key
cockroach cert create-client root --certs-dir=certs --ca-key=my-safe-directory/ca.key

手順 3：ノードを起動する（各ノードで繰り返す）

cockroach start \
  --certs-dir=certs \
  --store=path=<store-path> \
  --listen-addr=<node-address>:26257 \
  --http-addr=<node-address>:8080 \
  --join=<node1-address>,<node2-address>,<node3-address> \
  --locality=region=<region>,zone=<zone> \
  --cache=.25 \
  --max-sql-memory=.25 \
  --background

手順 4：クラスターを初期化する（任意のノードから 1 回実行）

cockroach init --certs-dir=certs --host=<any-node-address>

手順 5：検証する

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

手順 3 で起動したすべてのノードについて、is_live = true となり、想定した locality が表示されていることを確認します。

Kubernetes へのデプロイ

Operator（推奨）：

kubectl apply -f https://raw.githubusercontent.com/cockroachdb/cockroach-operator/master/install/crds.yaml
kubectl apply -f https://raw.githubusercontent.com/cockroachdb/cockroach-operator/master/install/operator.yaml
# Apply CrdbCluster manifest with node count, resources, and storage

Helm：

helm repo add cockroachdb https://charts.cockroachdb.com/
helm install cockroachdb cockroachdb/cockroachdb \
  --set statefulset.replicas=3 \
  --set storage.persistentVolume.size=100Gi

本番環境の設定（セルフホスト）

クラスターの稼働開始後に、本番環境の設定を適用します。

-- Enable critical features
SET CLUSTER SETTING kv.rangefeed.enabled = true;
SET CLUSTER SETTING sql.stats.automatic_collection.enabled = true;
SET CLUSTER SETTING admission.kv.enabled = true;

-- Set timeouts
SET CLUSTER SETTING sql.defaults.idle_in_transaction_session_timeout = '300s';
SET CLUSTER SETTING sql.defaults.statement_timeout = '30s';

-- Install enterprise license (if applicable)
SET CLUSTER SETTING cluster.organization = '<org-name>';
SET CLUSTER SETTING enterprise.license = '<license-key>';

各ノードにバラストファイルを作成します：

cockroach debug ballast <store-path>/auxiliary/EMERGENCY_BALLAST --size=1GiB

ロードバランサーを設定します： すべてのノードを接続先に指定し、/health?ready=1 でヘルスチェックを行います。

本番環境への移行チェックリスト全体については、production-deployment-checklist reference を参照してください。

---

高度なプロビジョニング

対象： ティア = Advanced

Cloud Console 経由

1. cockroachlabs.cloud → Create Cluster
2. Advanced プランを選択します
3. クラウドプロバイダー（AWS、GCP、Azure）を選択します
4. リージョンを選択します
5. ノード数（最小 3）とマシンサイズ（ノードあたりの vCPU）を設定します
6. ストレージを設定します
7. 内容を確認して作成します

Cloud API 経由

curl -X POST -H "Authorization: Bearer $COCKROACH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "<cluster-name>",
    "provider": "AWS",
    "spec": {
      "dedicated": {
        "region_nodes": {"us-east-1": 3},
        "machine_type": "m6i.xlarge",
        "storage_gib": 150
      }
    }
  }' \
  "https://cockroachlabs.cloud/api/v1/clusters"

Terraform 経由

resource "cockroach_cluster" "production" {
  name           = "production"
  cloud_provider = "AWS"

  dedicated {
    num_virtual_cpus = 8
    storage_gib      = 150
    num_nodes        = 3
  }

  regions = [{
    name = "us-east-1"
  }]
}

プロビジョニング後

• IP 許可リストまたは VPC Peering／PrivateLink を設定します
• SQL ユーザーとデータベースを作成します
• メンテナンスウィンドウを設定します（performing-cluster-maintenance を参照）
• 必要に応じて、Datadog／Prometheus へのメトリクスのエクスポートを設定します

---

BYOC プロビジョニング

対象： ティア = BYOC

高度なプロビジョニングの手順に従ってください。BYOC では、同じ Cloud Console、API、Terraform インターフェースを使用します。

BYOC の追加手順：

• お使いのクラウドアカウントが CRL の前提条件（サービスアカウント、VPC、IAM ロール）を満たしていることを確認します
• プライベート接続用に PrivateLink／PSC を設定します
• CRL サービスアカウントの権限を確認します

---

Standard のプロビジョニング

対象： ティア = Standard

1. cockroachlabs.cloud → Create Cluster
2. Standard プランを選択します
3. クラウドプロバイダーとリージョンを選択します
4. 想定されるワークロードに基づいて、プロビジョニング済みのコンピューティングリソース（vCPU）を設定します
5. 作成します

プロビジョニング後：

• SQL ユーザーとデータベースを作成します
• IP 許可リストを設定します
• セッションレベルのデフォルト値を設定します：

  ALTER ROLE ALL SET statement_timeout = '30s';
  ALTER ROLE ALL SET idle_in_transaction_session_timeout = '300s';
  

---

Basic のプロビジョニング

対象： ティア = Basic

1. cockroachlabs.cloud → Create Cluster
2. Basic プランを選択します
3. クラウドプロバイダーとリージョンを選択します
4. 作成します（自動スケーリングされるため、サイズ設定は不要です）

プロビジョニング後：

• 支出上限を設定します（Cloud Console → Cluster → Settings）
• SQL ユーザーとデータベースを作成します
• IP 許可リストを設定します

---

安全上の考慮事項

操作	ティア	リスク
cockroach init	SH	安全です — 一度だけ実行され、以降の呼び出しでは何も行われません
証明書の生成	SH	CA キーを安全に保管してください。紛失すると新しい証明書を作成できません
クラウドクラスターの作成	ADV/BYOC/STD/BAS	安全です — 設定を誤った場合は削除できます
本番環境の設定変更	SH	managing-cluster-settings を参照してください

重要（セルフホスト）：

• 本番環境では --insecure を絶対に使用せず、必ず TLS を使用してください
• 本番ワークロードにバースト可能なインスタンスを絶対に使用しないでください
• 複数ノードのクラスターでは、必ず --locality フラグを設定してください
• 必ず --cache と --max-sql-memory を設定してください（デフォルト値では低すぎます）
• 本番環境に移行する前に、必ずバラストファイルを作成してください

トラブルシューティング

問題	ティア	対処方法
cockroach init が失敗する	SH	すべてのノードが起動しており、ポート 26257 で接続できることを確認します
ノードがクラスターに参加できない	SH	--join アドレスを確認し、ポート 26257、8080 のファイアウォールルールを確認します
「clock offset」エラー	SH	NTP でクロックを同期し、--max-offset の設定を確認します
TLS ハンドシェイクに失敗する	SH	証明書が一致していることを確認し、すべてのノードで同じ CA を使用しているか確認します
クラウドクラスターが「Creating」のまま進まない	ADV/BYOC	15 分待ち、進展がない場合はサポートに問い合わせます
作成後に接続できない	ALL	IP 許可リストを確認し、接続文字列を確認して、root ユーザーで試します

参考資料

スキルの参考資料：

• ハードウェアとインフラストラクチャ
• 本番環境へのデプロイチェックリスト

関連スキル：

• reviewing-cluster-health — デプロイ後のヘルスチェック
• managing-cluster-settings — 本番環境の設定
• managing-certificates-and-encryption — TLS のセットアップ
• managing-cluster-capacity — デプロイ後のスケーリング

CockroachDB 公式ドキュメント：

• CockroachDB をインストールする
• クラスターを起動する
• Kubernetes にデプロイする
• 本番環境チェックリスト
• 高度なクラスターを作成する
• Cloud API