configuring-ip-allowlists

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Configuring IP Allowlists

配置IP允许列表

Configures and hardens IP allowlists on CockroachDB Cloud clusters to restrict SQL and DB Console access to authorized CIDR ranges. Identifies overly permissive entries (such as

0.0.0.0/0

) and replaces them with specific, narrow ranges.

为CockroachDB Cloud集群配置并强化IP允许列表，将SQL和DB Console的访问限制在授权的CIDR范围内。识别过度宽松的条目（如

0.0.0.0/0

），并将其替换为具体的窄范围。

When to Use This Skill

何时使用该技能

Removing
```
0.0.0.0/0
```
(open to all) from the IP allowlist
Restricting network access after initial cluster setup
Adding office, VPN, or CI/CD CIDR ranges to the allowlist
Reviewing and tightening existing allowlist entries
Responding to a security audit finding about overly broad network access

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

Prerequisites

前提条件

ccloud CLI installed and authenticated (
```
ccloud auth login
```
)
Cloud Console role: Cluster Admin or Cluster Operator
Known CIDR ranges: Office IPs, VPN egress IPs, CI/CD runner IPs, or other authorized sources
Cluster ID: Available from
```
ccloud cluster list
```

Verify access:

bash

ccloud auth whoami
ccloud cluster list

已安装并认证ccloud CLI（执行
```
ccloud auth login
```
）
云控制台角色：集群管理员或集群操作员
已知CIDR范围：办公网络IP、VPN出口IP、CI/CD运行器IP或其他授权来源
集群ID：可通过
```
ccloud cluster list
```
获取

验证访问权限：

bash

ccloud auth whoami
ccloud cluster list

Steps

操作步骤

1. List Current Allowlist Entries

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

bash

undefined

bash

undefined

List all IP allowlist entries for the cluster

列出集群的所有IP允许列表条目

ccloud cluster networking allowlist list <cluster-id> -o json


Review each entry. Flag any of these as overly permissive:
- `0.0.0.0/0` — Open to all IPv4 addresses
- `/8` ranges — 16 million+ addresses
- `/16` ranges — 65,000+ addresses
- Unknown or undocumented entries

See [ccloud commands reference](references/ccloud-commands.md) for full command syntax.

ccloud cluster networking allowlist list <cluster-id> -o json


检查每个条目，标记以下过度宽松的条目：
- `0.0.0.0/0` — 对所有IPv4地址开放
- `/8`范围 — 包含1600多万个地址
- `/16`范围 — 包含65000多个地址
- 未知或未记录的条目

查看[ccloud命令参考](references/ccloud-commands.md)获取完整命令语法。

2. Understand Allowlist Limits

2. 了解允许列表限制

CockroachDB Cloud clusters have a maximum number of IP allowlist entries per cluster. If you need more entries than the limit allows:

Consolidate entries: Use broader CIDR ranges where security permits (e.g., combine several
```
/32
```
entries into a
```
/24
```
)
Use private endpoints: Switch to private endpoints instead of allowlists for VPC-based access — private endpoints bypass the allowlist entirely
Request a limit increase: Contact CockroachDB Cloud support if consolidation and private endpoints are not sufficient

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

合并条目：在安全允许的情况下使用更宽泛的CIDR范围（例如，将多个
```
/32
```
条目合并为一个
```
/24
```
）
使用私有端点：对于基于VPC的访问，改用私有端点替代允许列表 — 私有端点完全绕过允许列表
请求提升限制：如果合并和私有端点都无法满足需求，请联系CockroachDB Cloud支持团队

3. Identify Required CIDR Ranges

3. 确定所需CIDR范围

Before modifying the allowlist, document all legitimate access sources:

Source	CIDR	SQL Access	UI Access
Office network	`203.0.113.0/24`	Yes	Yes
VPN egress	`198.51.100.0/24`	Yes	Yes
CI/CD runners	`192.0.2.0/28`	Yes	No
Monitoring	`10.0.1.5/32`	Yes	No

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

来源	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. Add Specific CIDR Entries

4. 添加具体CIDR条目

bash

undefined

bash

undefined

Add a specific CIDR range (CIDR is a positional argument)

添加具体CIDR范围（CIDR为位置参数）

ccloud cluster networking allowlist create <cluster-name> <cidr>
--sql
--ui
--name "<description>"


**Examples:**
```bash

ccloud cluster networking allowlist create <cluster-name> <cidr>
--sql
--ui
--name "<description>"


**示例：**
```bash

Office network — SQL and UI access

办公网络 — 允许SQL和UI访问

ccloud cluster networking allowlist create <cluster-name> 203.0.113.0/24
--sql
--ui
--name "Office network"

CI/CD runners — SQL only

CI/CD运行器 — 仅允许SQL访问

ccloud cluster networking allowlist create <cluster-name> 192.0.2.0/28
--sql
--name "CI/CD runners"

Single IP — /32 for maximum specificity

单个IP — 使用/32实现最高 specificity

ccloud cluster networking allowlist create <cluster-name> 198.51.100.42/32
--sql
--ui
--name "Developer workstation"

undefined

ccloud cluster networking allowlist create <cluster-name> 198.51.100.42/32
--sql
--ui
--name "Developer workstation"

undefined

5. Remove Overly Permissive Entries

5. 移除过度宽松的条目

bash

undefined

bash

undefined

Delete the 0.0.0.0/0 entry (or other overly broad entries)

删除0.0.0.0/0条目（或其他过宽的条目）

ccloud cluster networking allowlist delete <cluster-name> 0.0.0.0/0


**Important:** Only remove `0.0.0.0/0` after confirming your specific CIDR entries are in place and tested.

ccloud cluster networking allowlist delete <cluster-name> 0.0.0.0/0


**重要提示：** 仅在确认已添加并测试好具体CIDR条目后，再移除`0.0.0.0/0`。

6. Verify the Updated Allowlist

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

bash

undefined

bash

undefined

Confirm the final allowlist

确认最终的允许列表

ccloud cluster networking allowlist list <cluster-id> -o json


Test connectivity from each authorized source:
```bash

ccloud cluster networking allowlist list <cluster-id> -o json


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

Test SQL connection from an allowed IP

从允许IP测试SQL连接

cockroach sql --url "<connection-string>" -e "SELECT 1;"

Test from a non-allowed IP (should fail)

从不允许IP测试（应失败）

Attempt connection from an IP not in the allowlist — expect connection refused

从未在允许列表中的IP尝试连接 — 预期会被拒绝连接

undefined

undefined

Safety Considerations

安全注意事项

Risk: Locking yourself out. Removing

0.0.0.0/0

before adding your current IP will immediately block your access.

Mitigation steps:

Identify your current IP before making changes:
```
curl -s https://checkip.amazonaws.com
```
Add your IP first as a
```
/32
```
entry before removing broad ranges
Test connectivity after adding specific entries but before removing
```
0.0.0.0/0
```
Keep Cloud Console access — the Cloud Console UI can modify allowlists even if SQL access is blocked

Order of operations:

Add all specific CIDR entries
Verify SQL connectivity from each allowed source
Remove
```
0.0.0.0/0
```
only after verifying all needed entries are in place
Test again to confirm access still works

风险：被锁定在外。 在添加当前IP之前移除

0.0.0.0/0

会立即阻止你的访问。

缓解步骤：

修改前确认当前IP：执行
```
curl -s https://checkip.amazonaws.com
```
获取当前IP
先添加你的IP：在移除宽范围条目之前，先添加你的IP作为
```
/32
```
条目
添加具体条目后测试连接：在移除
```
0.0.0.0/0
```
之前，测试连接是否正常
保留云控制台访问权限：即使SQL访问被阻止，云控制台UI仍可修改允许列表

操作顺序：

添加所有具体CIDR条目
验证每个授权来源的SQL连接
仅在确认所有必要条目已添加后，再移除
```
0.0.0.0/0
```
再次测试以确认访问仍正常

Rollback

回滚方案

If you lose access after removing a broad entry:

Cloud Console: Log into the CockroachDB Cloud Console (web UI) — this does not use the IP allowlist
Re-add your IP: Add your current IP as a
```
/32
```
or re-add
```
0.0.0.0/0
```
temporarily
Investigate: Determine which CIDR was missing and add it

bash

undefined

如果移除宽范围条目后失去访问权限：

云控制台：登录CockroachDB Cloud控制台（网页UI）— 该访问不使用IP允许列表
重新添加你的IP：将当前IP添加为
```
/32
```
条目，或临时重新添加
```
0.0.0.0/0
```
排查问题：确定缺失的CIDR范围并添加

bash

undefined

Emergency: re-add 0.0.0.0/0 via ccloud (if you still have ccloud access)

紧急操作：通过ccloud重新添加0.0.0.0/0（如果仍有ccloud访问权限）

ccloud cluster networking allowlist create <cluster-name> 0.0.0.0/0
--sql
--ui
--name "Emergency - temporary open access"

undefined

ccloud cluster networking allowlist create <cluster-name> 0.0.0.0/0
--sql
--ui
--name "Emergency - temporary open access"

undefined

References

参考资料

Skill references:

ccloud commands for IP allowlists

Related skills:

auditing-cloud-cluster-security — Run a full security posture audit
configuring-private-connectivity — Private endpoints as an alternative to IP allowlists

Official CockroachDB Documentation:

技能参考：

IP允许列表的ccloud命令

相关技能：

auditing-cloud-cluster-security — 执行完整的安全态势审计
configuring-private-connectivity — 使用私有端点替代IP允许列表

官方CockroachDB文档：