managing-cluster-capacity

管理集群容量

管理所有 CockroachDB 部署层级的集群容量。不同层级对“容量”的定义各不相同：Self-Hosted 管理单个节点，Advanced/BYOC 管理节点数量和机器规格，Standard 管理预置的 vCPU，Basic 则会自动扩缩容并提供成本控制。

何时使用此技能

• 永久从集群中移除节点（Self-Hosted）
• 添加节点以提升容量（Self-Hosted）
• 扩缩集群节点数量或机器规格（Advanced、BYOC）
• 调整预置的计算资源（Standard）
• 管理无服务器集群的成本（Basic）
• 更换硬件或迁移基础设施（Self-Hosted、BYOC）
• 更换故障或失效的节点（Self-Hosted）
• 管理存储利用率和磁盘压力（Self-Hosted）

临时维护（不涉及容量变更）： 使用 performing-cluster-maintenance。 操作前健康检查： 使用 reviewing-cluster-health。

---

第 1 步：收集上下文

必需上下文

问题	选项	重要原因
部署层级？	Self-Hosted、Advanced、BYOC、Standard、Basic	不同层级使用不同的容量模型
扩缩方向？	扩容（增加容量）、缩容（减少容量）	决定操作流程

其他上下文（按层级）

如果是 Self-Hosted（缩容）：

问题	选项	重要原因
要移除多少个节点？	1 个、多个	多节点退役应同时进行
目标节点 ID？	从 cockroach node status 获取的节点 ID	CLI 命令必需
节点处于运行状态还是已失效？	运行中、已失效	已失效节点需要采用不同的流程
部署平台？	裸机、VM、Kubernetes	会影响 CLI 和清理步骤
当前复制因子？	3、5、自定义	剩余节点数量必须足够
当前节点数量？	数量	用于验证剩余容量
存储利用率？	低（<60%）、中（60-80%）、高（>80%）	决定紧迫程度，以及是否需要进行存储维护

如果是 Advanced 或 BYOC：

问题	选项	重要原因
扩缩容方式？	Cloud Console、API、Terraform	决定操作流程
当前和目标配置？	例如，5 个节点 → 3 个节点，或 4 vCPU → 8 vCPU	用于验证约束
云服务商？（仅限 BYOC）	AWS、GCP、Azure	会影响基础设施验证

如果是 Standard：

问题	选项	重要原因
当前预置的 vCPU 数量？	数量	为扩缩容决策提供背景
目标 vCPU 数量？	数量	用于验证工作负载能否承载

如果是 Basic： 收集成本管理目标。Basic 会自动扩缩容，不提供手动容量控制。

根据上下文选择流程

层级	前往
Self-Hosted	Self-Hosted 容量管理
Advanced	Advanced 扩缩容
BYOC	BYOC 扩缩容
Standard	Standard 计算资源管理
Basic	Basic 成本管理

---

Self-Hosted 容量管理

适用条件： 层级 = Self-Hosted

缩容：退役节点

退役前验证

# All nodes live, version-consistent, with replication and per-node range counts
cockroach node status --decommission --certs-dir=<certs-dir> --host=<any-live-node>

检查输出，确认：

• 每个节点的 is_live = true
• 所有节点的 ranges_underreplicated 均为 0（所有范围都已完整复制）

-- Replication factor (and other zone-level settings)
SHOW ZONE CONFIGURATION FOR RANGE default;

如需查看每个存储的容量（以便确认在吸收已退役节点的数据后，剩余节点的利用率不会超过 60%），请使用 DB Console 的 Overview → Storage 页面，或抓取 Prometheus 指标端点：

curl -ks https://<node>:8080/_status/vars | grep '^capacity'

退役后的节点数量必须 ≥ 区域的 num_replicas。

如果节点处于运行状态：先排空，再退役

# Step 1: Drain
cockroach node drain <node_id> --certs-dir=<certs-dir> --host=<any-live-node>

# Step 2: Decommission (single node)
cockroach node decommission <node_id> --certs-dir=<certs-dir> --host=<any-live-node>

# Step 2: Decommission (multiple nodes — more efficient, do simultaneously)
cockroach node decommission <id_1> <id_2> <id_3> --certs-dir=<certs-dir> --host=<any-live-node>

如果节点已失效：替换失效节点

当节点失效时间超过 server.time_until_store_dead（默认值为 5m）时，CockroachDB 会自动将其数据重新复制到存活节点。使用此流程清理失效节点，并可选择添加替代节点。

第 1 步：确认节点已失效且数据安全

# Confirm the dead node and verify replication has caught up
cockroach node status --decommission --certs-dir=<certs-dir> --host=<any-live-node>

在输出中，失效节点应显示 is_live = false，且每个存活节点都应显示 ranges_underreplicated = 0。如需查看存活节点的每个存储容量，请使用 DB Console 的 Overview → Storage 页面。

如果存在副本不足的范围，请等待重新复制完成后再继续。

第 2 步：停用失效节点（清理元数据）

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

第 3 步：添加替代节点（建议）

如果剩余节点的利用率超过 60%，请按照纵向扩展：添加节点流程配置替代节点。

**多个节点失效：**同时停用所有失效节点：

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

详细的故障场景和恢复流程，请参阅 replacing-failed-nodes reference。

监控停用进度

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

等待 gossiped_replicas = 0 且 membership = 'decommissioned'。然后停止已停用节点上的进程。

取消停用

cockroach node recommission <node_id> --certs-dir=<certs-dir> --host=<any-live-node>

仅在仍处于 decommissioning 状态时有效。

纵向扩展：添加节点

1. 配置与现有节点规格相同的新硬件／VM
2. 安装相同版本的 CockroachDB（运行 cockroach version 进行确认）
3. 启动节点，并使用 --join 指定现有集群节点
4. 验证节点加入情况并监控重新均衡：

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

   新节点应在输出中显示为 is_live = true。随着数据重新均衡到新节点，ranges 列的值会逐渐增加。

扩展后验证

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

预期每个节点的 ranges_underreplicated = 0，且各节点的 ranges 数量均衡。如需查看每个存储的容量利用率，请使用 DB Console 的 Overview → Storage 页面。

---

高级扩展

**适用条件：**层级 = Advanced

高级集群由 Cockroach Labs 管理。通过更改节点数量或机器规格来调整容量。

通过 Cloud Console

1. Cluster → Capacity
2. 调整节点数量或机器类型（每个节点的 vCPU 数量）
3. CRL 会安全地处理所有节点操作（排空、停用、配置）
4. 在 Cloud Console 中监控进度

通过 Cloud API

# Scale node count
curl -X PATCH -H "Authorization: Bearer $COCKROACH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"config": {"num_nodes": <new_count>}}' \
  "https://cockroachlabs.cloud/api/v1/clusters/<cluster-id>"

通过 Terraform

resource "cockroach_cluster" "example" {
  dedicated {
    num_virtual_cpus = 8     # vCPUs per node
    storage_gib      = 150
    num_nodes        = 5     # total nodes
  }
}

扩展前检查

-- Ensure no disruptive jobs are running before scaling down
WITH j AS (SHOW JOBS)
SELECT job_type, status, COUNT(*) FROM j WHERE status = 'running' GROUP BY 1, 2;

限制

• **最小配置：**3 个节点 x 4 个 vCPU（共 12 个 vCPU）
• **缩容：**数据必须能容纳在剩余节点上；区域配置必须满足要求
• **扩容：**可在计划限额内添加节点

---

BYOC 扩展

**适用条件：**层级 = BYOC

请遵循所有高级扩展步骤。BYOC 扩展通过相同的 Cloud Console/API/Terraform 接口管理。

云服务提供商验证（缩容后）

如果是 AWS：

aws ec2 describe-instances --filters "Name=tag:cockroach-cluster,Values=<cluster-name>" \
  --query 'Reservations[].Instances[].{ID:InstanceId,State:State.Name}'

如果是 GCP：

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

如果是 Azure：

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

BYOC 其他注意事项

• 扩展后验证安全组／防火墙规则
• 更新预留实例或承诺使用折扣分配
• 验证网络连接（PrivateLink/PSC/VPC Peering）未受影响
• 检查云账单是否反映了新的实例数量

---

标准计算资源管理

**适用条件：**层级 = Standard

Standard 是一项多租户托管服务，没有单独的节点。通过调整已配置的计算资源（vCPU）来管理容量。

调整已配置的 vCPU

1. Cloud Console → Cluster → Capacity
2. 增加或减少已配置的 vCPU
3. 更改立即生效，无需停机

缩容前

• 在 Cloud Console 中查看 CPU 利用率，确保工作负载能在减少后的计算资源内运行
• 存储按使用量计费，不受计算资源变更影响

扩容后

在 Cloud Console 中监控 P99 延迟和 QPS，持续 24-48 小时。如果缩容后延迟上升，请调高计算资源。

---

基本成本管理

适用条件： Tier = Basic

Basic 是一项无服务器服务，可自动扩缩容。无需管理节点或预置计算资源。容量会根据需求自动扩展。可通过支出控制来管理成本。

管理支出

• 设置支出限额： Cloud Console → Cluster → Settings → 配置每月支出上限
• 查看用量： Cloud Console 会显示一段时间内的请求单元（RU）消耗情况
• 优化查询： 通过调整查询和创建索引来降低 RU 消耗
• 归档数据： 删除未使用的表或数据库，以降低存储成本

何时考虑升级

如果需要明确控制计算容量（保证 vCPU 数量），可考虑升级到 Standard。如果需要专用基础设施，可考虑 Advanced。

---

安全注意事项

操作	Tier	可逆？
cockroach node decommission	SH	仅可在完成前重新启用
停止已停用的节点	SH	否（必须作为新节点重新加入）
向集群添加节点	SH	是（可通过停用来移除）
通过 Console/API 扩缩容	ADV/BYOC	联系支持人员以撤销
调整预置 vCPU 数量	STD	是（可缩回）
设置支出限额	BAS	是（可随时调整）

关键事项（自托管）：

• 切勿将节点停用到低于复制因子
• 停用前务必先排空（针对运行中的节点）
• 同时停用多个节点（不要按顺序逐个停用）
• 确认剩余容量能够容纳这些数据
• 对于已宕机的节点：等待重新复制完成后再停用
• 监控存储利用率——节点利用率超过 80% 时可能导致性能下降

故障排除

问题	Tier	解决方法
停用操作卡住	SH	检查区域配置约束；排查停滞的范围
重新启用失败	SH	节点已完全停用；必须作为新节点重新加入
新节点未重新平衡	SH	等待自动重新平衡；检查 range_count
缩容请求被拒绝	ADV/BYOC	容量低于最低要求，或数据无法容纳
缩减后延迟飙升	STD	调高预置 vCPU 数量
云实例未清理	BYOC	联系支持人员；在云控制台中确认
已宕机节点未重新复制	SH	检查 server.time_until_store_dead；确认存活节点有足够容量
缩容后存储利用率偏高	SH	添加替换节点或增大磁盘容量

参考资料

技能参考资料：

• 替换故障节点
• 存储管理

相关技能：

• reviewing-cluster-health — 健康状况检查（操作前后）
• performing-cluster-maintenance — 排空流程（SH）
• upgrading-cluster-version — 升级和生命周期

CockroachDB 官方文档：

• cockroach node decommission
• Node Shutdown
• Manage Advanced Cluster
• Manage Standard Cluster
• Cloud API