Agent Skill · Cockroach Labs

configuring-ip-allowlists

Configures and hardens IP allowlists for CockroachDB Cloud clusters to restrict network access to authorized CIDR ranges. Use when tightening network security, removing overly permissive allowlist entries like 0.0.0.0/0, or setting up allowlists for a new cluster.

View SKILL.md on GitHub → Source repository Provider profile

Provider: Cockroach Labs Path in repo: skills/cockroachdb-security-and-governance/configuring-ip-allowlists/SKILL.md

Skill body

Configuring IP Allowlists

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.

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

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:

ccloud auth whoami
ccloud cluster list

Steps

1. List Current Allowlist Entries

# List all IP allowlist entries for the cluster
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 for full command syntax.

2. Understand Allowlist Limits

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

3. Identify Required CIDR Ranges

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

4. Add Specific CIDR Entries

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

Examples:

# 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. Remove Overly Permissive Entries

# 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

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

6. Verify the Updated Allowlist

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

Test connectivity from each authorized source:

# 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

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

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

# 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"

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:

Skill frontmatter

compatibility: Requires ccloud CLI with Cluster Admin or Cluster Operator role. metadata: {"author" => "cockroachdb", "version" => "1.0"}