configuring-ip-allowlists

用途

本技能用于配置和加固 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 范围 — 1600 万以上地址
/16 范围 — 65,000 以上地址
未知或未记录的条目

完整命令语法参见 ccloud 命令参考。

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 会立即阻断你的访问。

缓解步骤：

更改前确定当前 IP：curl -s https://checkip.amazonaws.com
先以 /32 条目添加你的 IP，再移除宽泛范围
添加具体条目后、移除 0.0.0.0/0 前测试连接
保留 Cloud Console 访问——即使 SQL 访问被阻断，Cloud Console UI 仍可修改允许列表

操作顺序：

添加所有具体 CIDR 条目
验证每个允许来源的 SQL 连接
仅在确认所有必要条目就位后移除 0.0.0.0/0
再次测试确认访问仍然正常

回滚

如果在移除宽泛条目后失去访问：

Cloud Console：登录 CockroachDB Cloud Console（Web UI）——它不使用 IP 允许列表
重新添加你的 IP：将当前 IP 添加为 /32，或临时重新添加 0.0.0.0/0
排查：确定缺失的 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"

参考

技能参考：

ccloud commands for IP allowlists