configuring-ip-allowlists

配置 IP 允许列表

在 CockroachDB Cloud 集群上配置并强化 IP 允许列表，将 SQL 和 DB Console 的访问限制为授权的 CIDR 范围。识别权限过于宽泛的条目（例如 0.0.0.0/0），并将其替换为具体、范围较窄的地址段。

适用场景

• 从 IP 允许列表中移除 0.0.0.0/0（对所有地址开放）
• 在集群初始设置后限制网络访问
• 将办公室、VPN 或 CI/CD 的 CIDR 范围添加到允许列表
• 检查并收紧现有的允许列表条目
• 响应安全审计中有关网络访问范围过宽的问题

前提条件

• 已安装并完成身份验证的 ccloud CLI（ccloud auth login）
• Cloud Console 角色： Cluster Admin 或 Cluster Operator
• 已知 CIDR 范围： 办公室 IP、VPN 出口 IP、CI/CD 运行器 IP 或其他授权来源
• 集群 ID： 可通过 ccloud cluster list 获取

验证访问权限：

ccloud auth whoami
ccloud cluster list

步骤

1. 列出当前允许列表条目

# List all IP allowlist entries for the cluster
ccloud cluster networking allowlist list <cluster-id> -o json

检查每个条目。以下条目属于权限过于宽泛的情况：

• 0.0.0.0/0 — 对所有 IPv4 地址开放
• /8 范围 — 超过 1,600 万个地址
• /16 范围 — 超过 65,000 个地址
• 未知或未记录的条目

完整命令语法请参阅 ccloud commands reference。

2. 了解允许列表限制

CockroachDB Cloud 集群的每个集群都有 IP 允许列表条目数量上限。如果所需条目超过上限：

• 合并条目： 在安全条件允许时使用更宽泛的 CIDR 范围（例如，将多个 /32 条目合并为一个 /24）
• 使用私有端点： 对基于 VPC 的访问，可改用私有端点，而不是使用允许列表 — 私有端点完全不受允许列表限制
• 申请提高上限： 如果合并条目和私有端点仍无法满足需求，请联系 CockroachDB Cloud 支持团队

3. 确定所需的 CIDR 范围

修改允许列表前，请记录所有合法的访问来源：

来源	CIDR	SQL 访问	UI 访问
办公室网络	203.0.113.0/24	是	是
VPN 出口	198.51.100.0/24	是	是
CI/CD 运行器	192.0.2.0/28	是	否
监控	10.0.1.5/32	是	否

4. 添加具体的 CIDR 条目

# Add a specific CIDR range (CIDR is a positional argument)
ccloud cluster networking allowlist create <cluster-name> <cidr> \
  --sql \
  --ui \
  --name "<description>"

示例：

# Office network — SQL and UI access
ccloud cluster networking allowlist create <cluster-name> 203.0.113.0/24 \
  --sql \
  --ui \
  --name "Office network"

# CI/CD runners — SQL only
ccloud cluster networking allowlist create <cluster-name> 192.0.2.0/28 \
  --sql \
  --name "CI/CD runners"

# Single IP — /32 for maximum specificity
ccloud cluster networking allowlist create <cluster-name> 198.51.100.42/32 \
  --sql \
  --ui \
  --name "Developer workstation"

5. 移除权限过于宽泛的条目

# Delete the 0.0.0.0/0 entry (or other overly broad entries)
ccloud cluster networking allowlist delete <cluster-name> 0.0.0.0/0

重要： 只有在确认具体的 CIDR 条目已添加并经过测试后，才能移除 0.0.0.0/0。

6. 验证更新后的允许列表

# Confirm the final allowlist
ccloud cluster networking allowlist list <cluster-id> -o json

从每个授权来源测试连接：

# Test SQL connection from an allowed IP
cockroach sql --url "<connection-string>" -e "SELECT 1;"

# Test from a non-allowed IP (should fail)
# Attempt connection from an IP not in the allowlist — expect connection refused

安全注意事项

风险：将自己锁在外面。 在添加当前 IP 前移除 0.0.0.0/0 会立即阻止你访问。

缓解措施：

1. 在更改前确定当前 IP： curl -s https://checkip.amazonaws.com
2. 先添加你的 IP： 在移除宽泛范围前，将当前 IP 添加为 /32 条目
3. 测试连接： 添加具体条目后、移除 0.0.0.0/0 前测试连接
4. 保留 Cloud Console 访问权限： 即使 SQL 访问被阻止，仍可通过 Cloud Console UI 修改允许列表

操作顺序：

1. 添加所有具体的 CIDR 条目
2. 验证每个允许来源的 SQL 连接
3. 只有在确认所有所需条目均已就位后，才移除 0.0.0.0/0
4. 再次测试，确认访问仍然正常

回滚

如果移除宽泛条目后无法访问：

1. Cloud Console： 登录 CockroachDB Cloud Console（Web UI）— 此操作不受 IP 允许列表限制
2. 重新添加你的 IP： 将当前 IP 添加为 /32，或临时重新添加 0.0.0.0/0
3. 排查问题： 确定缺少哪个 CIDR，并将其添加

# Emergency: re-add 0.0.0.0/0 via ccloud (if you still have ccloud access)
ccloud cluster networking allowlist create <cluster-name> 0.0.0.0/0 \
  --sql \
  --ui \
  --name "Emergency - temporary open access"

参考资料

技能参考：

• 用于 IP 允许列表的 ccloud 命令

相关技能：

• auditing-cloud-cluster-security — 执行完整的安全状况审计
• configuring-private-connectivity — 将私有端点作为 IP 允许列表的替代方案

CockroachDB 官方文档：

• 网络授权
• 私有集群
• ccloud CLI 参考