chmonitorConnect a firewalled ClickHouse or Postgres (Cloud)
Connect a firewalled ClickHouse or Postgres to chmonitor Cloud — Cloudflare Tunnel (recommended), dedicated egress IPs for allowlisting, jump host, and why allowlisting Cloudflare's shared ranges does not work.
chmonitor Cloud (dash.chmonitor.dev) runs entirely on Cloudflare Workers. When your ClickHouse (or Postgres) is behind a firewall, the Worker has to reach it — and because Workers do not have a single fixed public IP by default, a plain "allowlist our IP" is not straightforward. Pick the option that fits, ranked below by how well it works with chmonitor.
What IP should I allowlist?
There is no single stable IP to allowlist. Cloudflare Workers egress from a large, shared, rotating pool, so any IP you capture today can change tomorrow. In order of recommendation:
- Cloudflare Tunnel (recommended) — no IP at all; the connector makes outbound-only connections, so there is nothing to allowlist.
- Dedicated egress IPs — an enterprise add-on that gives chmonitor's HTTP traffic (ClickHouse) a stable IP. It does not cover Postgres (raw TCP).
- A static-IP proxy / jump host you run and control — works for both ClickHouse and Postgres, at the cost of running the proxy yourself.
Do not allowlist Cloudflare's public IP ranges
Cloudflare's published IP ranges are shared by every Cloudflare customer. Allowlisting them authorizes the entire Cloudflare fleet, not just chmonitor — it is not a real allowlist.
Self-hosting? You don't need any of this
Self-hosted chmonitor (Docker / Kubernetes / your own Worker) runs inside your network, so it reaches ClickHouse directly. This page is only for connecting a firewalled ClickHouse to the hosted Cloud.
Recommended: Cloudflare Tunnel + Access service token
A Cloudflare Tunnel runs a small cloudflared connector next to your ClickHouse. It makes only outbound connections to Cloudflare, so you open no inbound ports and allowlist no IPs. You then protect the tunnel's public hostname with Cloudflare Access and give chmonitor a service token so only chmonitor can reach it.
Create the tunnel
Install cloudflared (2025.7.0+) on a host that can reach ClickHouse, then create a tunnel with a public hostname pointing at ClickHouse's HTTP port (8123 / 8443):
cloudflared tunnel create chmonitor
cloudflared tunnel route dns chmonitor ch.example.comProtect it with an Access service token
Add an Access application on ch.example.com with a service token policy, then copy the generated Client ID and Client Secret.
Add the host in chmonitor
Add the host with URL https://ch.example.com and paste the service-token Client ID / Secret into the connection's headers (CF-Access-Client-Id / CF-Access-Client-Secret).
Why this is the default: no inbound firewall hole, no IP allowlist to maintain, the token is per-connection and revocable, and traffic is TLS end-to-end. It works today (not beta) on free/standard Zero Trust tiers.
Other options
If a tunnel doesn't fit your environment, choose the path that matches your constraint.
Use this when a security team requires a literal firewall allowlist. chmonitor talks to ClickHouse over HTTP (@clickhouse/client-web, i.e. Worker fetch()), and Cloudflare's Dedicated Egress IPs do apply to Workers fetch() — Cloudflare's docs state connections created with connect() (raw TCP) do not use them. That gives ClickHouse traffic a stable source IP you can allowlist; it does not cover Postgres, which chmonitor reaches over raw TCP (see below).
Caveats:
- It is an enterprise add-on on chmonitor's Cloudflare account — contact us if your deployment needs it.
- The IP is shared across chmonitor's account egress, so the allowlist authorizes "traffic from chmonitor," not a single tenant. Always pair it with TLS + a least-privilege ClickHouse user.
Do not allowlist Cloudflare's public IP ranges
Cloudflare publishes its IP ranges, but Worker egress over those ranges is shared by every Cloudflare customer. Allowlisting them authorizes the entire Cloudflare fleet — it is not a real allowlist. Use a tunnel or dedicated egress IPs instead.
Run a small reverse proxy (nginx / HAProxy) on a VM with a static public IP that forwards to ClickHouse, and allowlist only that proxy. chmonitor then connects to the proxy over HTTPS with auth. This always works and is fully under your control, but you own the proxy's uptime, TLS, and hardening.
Workers VPC (currently beta) lets a Worker reach a private service through a Cloudflare Tunnel with no public hostname at all — the cleanest private-connectivity story. We will adopt it for Cloud once it reaches general availability.
Firewalled Postgres
chmonitor Cloud can also monitor Postgres sources (behind the CHM_FEATURE_POSTGRES_SOURCE flag). Postgres uses the wire protocol over raw TCP, not fetch(), so it needs its own plan:
Dedicated egress IPs do not cover Postgres
Cloudflare's Dedicated Egress IPs apply only to Workers fetch()/HTTP traffic. Postgres connections go over raw TCP (connect()), which Cloudflare explicitly excludes from dedicated egress IP coverage — so this option gives you no stable IP for Postgres, even on the enterprise add-on.
- Jump host / TCP proxy (recommended for firewalled Postgres today) — run
pgbounceror a plain TCP proxy (HAProxy, stunnel) on a VM with a static public IP, and allowlist that IP. chmonitor connects to the proxy, the proxy forwards to Postgres. This is the same jump-host pattern as ClickHouse, just proxying the Postgres port (5432) instead of HTTP. - The
cloudflared access tcpTunnel mode does not apply here. It forwards raw TCP for a client machine (a human's laptop runningcloudflaredlocally) — it requirescloudflaredon both ends, so a server-side Worker like chmonitor's cannot use it directly. - Cloudflare Hyperdrive (roadmap) — Hyperdrive can connect Workers to a private Postgres through a Cloudflare Tunnel (Hyperdrive itself is the component that speaks to the tunnel), which would give chmonitor's Postgres traffic a private, non-public-internet path with no allowlist needed. chmonitor does not use Hyperdrive today; treat this as a roadmap item, not a current option — do not build around it yet.
Troubleshooting
Hyperdrive does not front ClickHouse today
Cloudflare Hyperdrive supports PostgreSQL and MySQL, not ClickHouse, so it cannot front a ClickHouse connection. It's on our roadmap as a private-connectivity option for Postgres sources (see above) — not yet adopted.
Related
Connect a firewalled ClickHouse in 5 minutes
The Cloudflare Tunnel setup, and why allowlisting Cloudflare's ranges does not work.
ClickHouse requirements
The least-privilege monitoring user chmonitor needs.
Connection errors
Diagnose 'Test connection' failures kind by kind.
Proxy & SSO auth setup
Put chmonitor behind Cloudflare Access, oauth2-proxy, or Traefik.
Self-host
Run inside your network and reach ClickHouse directly — no tunnel needed.
Alerting to Slack and Discord
Wire chmonitor's health sweep to a Slack or Discord incoming webhook so your team gets notified the moment a check crosses a threshold — no polling the dashboard required.
Connection errors
Fix "Test connection" failures in chmonitor — host not allowed, invalid URL, authentication failed, missing permissions, DNS, refused, TLS, and timeout errors.