BYOC Network Security

​

Connections between ClickHouse Control Plane and Your BYOC VPC

The ClickHouse Cloud control plane maintains several types of connections to operate and support your BYOC deployment:

​

Cloud provider APIs vs the Kubernetes API

Two distinct control paths are easy to conflate. They differ in where the traffic originates, how it authenticates, and whether Tailscale applies: In short: only Kubernetes API and troubleshooting traffic can use Tailscale. The management calls described above always originate from ClickHouse Cloud’s network and terminate at the provider’s endpoints — routing them through Tailscale isn’t possible, because they never enter your network in the first place. Cloud provider APIs are also called from the other direction, by controllers running inside your own cluster — the load balancer controller, CSI driver, autoscaler, DNS controller, and cert-manager. Those calls use in-cluster identities and leave through your own egress path, so they appear in your audit trail under a different identity and a different source address than the management calls. See Outbound connections.

​

Network-origin permission boundaries

If your organization restricts IAM role assumption or cloud API calls by network origin (for example, AWS SCPs or role trust conditions using aws:SourceIp or aws:SourceVpc), those conditions will block ClickHouse’s automation: the calls legitimately originate from ClickHouse Cloud’s network, not yours. Exempt the ClickHouse-created roles from such conditions, or contact ClickHouse for the current egress IP ranges if you must allowlist by origin. The following section describes how the Tailscale private network is used for troubleshooting and optional management access.

​

Tailscale Private Network

Tailscale provides a zero-trust, private network connection between ClickHouse Cloud’s management services and your BYOC deployment. This secure channel enables ClickHouse engineers to perform troubleshooting and management operations without requiring inbound public network access or complex VPN configurations; the agents themselves make outbound-only connections and need outbound internet access to reach the Tailscale coordination service.

​

Overview

Tailscale creates an encrypted, private network tunnel between the ClickHouse control plane (in ClickHouse’s VPC) and your BYOC data plane (in your VPC). This connection is used exclusively for:

• Management operations: ClickHouse management services coordinating with your BYOC infrastructure
• Troubleshooting access: ClickHouse engineers accessing Kubernetes API servers and ClickHouse system tables for diagnostics
• Metrics access: ClickHouse’s centralized monitoring dashboards access metrics from the Prometheus stack deployed within your BYOC VPC, providing ClickHouse engineers observability into the environment.

​

How Tailscale Works in BYOC

For each service or endpoint that needs to be accessed via Tailscale, ClickHouse BYOC deploys:

1. Tailnet Address Registration: Each endpoint registers a unique tailnet address (e.g., k8s.xxxx.us-east-1.aws.byoc.clickhouse-prd.com for the Kubernetes API server)
2. Tailscale Agent Container: A Tailscale agent container runs in your Kubernetes cluster, responsible for:
   • Connecting to the Tailscale coordination server
   • Registering services to make them discoverable
   • Coordinating network setup with Nginx pods
3. Nginx Pod: An Nginx pod that:
   • Terminates TLS traffic from Tailscale
   • Routes traffic to the appropriate IPs within your Kubernetes cluster

​

Network Connection Process

The Tailscale connection establishment follows these steps:

1. Initial Connection:
   • Tailscale agents on both ends (ClickHouse engineer’s environment and your BYOC Kubernetes cluster) connect to the Tailscale coordination server
   • The cluster agent registers the Kubernetes service to make it discoverable
   • ClickHouse engineers must escalate internally to gain visibility to the service
2. Connection Mode:
   • Direct Mode: Agents attempt to establish a direct connection via NAT traversal tunnel
   • Relay Mode: If direct mode fails, communication falls back to relay mode through a Tailscale DERP (Distributed Encrypted Relay Protocol) server
3. Encryption:
   • All communication is encrypted end-to-end
   • Each Tailscale agent generates its own public-private key pair (similar to PKI)
   • Traffic remains encrypted regardless of whether it uses direct or relay mode

​

Security features

Outbound-only connections:

• Tailscale agents in your Kubernetes cluster initiate outbound connections to the Tailscale coordination/relay servers
• No inbound connections are required — no security group rules need to allow inbound traffic to Tailscale agents
• This reduces the attack surface and simplifies network security configuration

Access control:

• Engineers must request access through an internal approval workflow before Tailscale can route them to a customer endpoint
• Access is time-bound and automatically expires
• All access is audited and logged

For the full data access policy — what engineers can see, certificate-based authentication, and customer-side auditing — see ClickHouse data access.

​

Management Services Access

By default, ClickHouse management services reach your BYOC Kubernetes cluster over the API server’s public endpoint, which each cloud gates differently — on AWS by an IP allow list containing only ClickHouse’s NAT gateway addresses, on GCP and Azure by cloud IAM. See Kubernetes API server exposure for the per-cloud detail. Optional Private Endpoint Configuration:

• You can configure the Kubernetes API server to use only a private endpoint
• In this case, management services access the API server via Tailscale (similar to human troubleshooting access) or, on AWS, via VPC Lattice (see Kubernetes API Private Connection)
• By default, the public endpoint is kept as a backup mechanism for emergency investigation and support needs; once private access is verified, it can be disabled entirely in coordination with ClickHouse

​

Network Traffic Flow

Tailscale Connection Flow:

1. Tailscale agent in your Kubernetes cluster → Tailscale coordination server (outbound)
2. Tailscale agent on engineer’s machine → Tailscale coordination server (outbound)
3. Direct or relayed connection established between agents
4. Encrypted traffic flows through the established tunnel
5. Nginx pod in your Kubernetes cluster terminates TLS and routes to internal services

No Customer Data Transmission:

• Tailscale connections are used only for management and troubleshooting
• Query traffic and customer data never flow through Tailscale
• All customer data remains in your own cloud account

For more technical details about how Tailscale is implemented in BYOC, see the Building ClickHouse BYOC on AWS blog post. For what ClickHouse engineers can read once connected and how ClickHouse audits that access, see ClickHouse data access.

​

Network boundaries

This section is the firewall view of a BYOC deployment: every connection that crosses the boundary of your BYOC network, in either direction. It applies to AWS, GCP, and Azure; where the clouds behave differently, the cloud is named explicitly. Terms used throughout:

• Inbound: traffic entering your BYOC network — a VPC on AWS, a VPC network on GCP, or a VNet on Azure.
• Outbound: traffic originating in your BYOC network and sent to an external destination.
• Public: an endpoint reachable from the public internet.
• Private: an endpoint reachable only over a private path — VPC/VNet peering, AWS PrivateLink, GCP Private Service Connect, Azure Private Link, or Tailscale.

​

Provider equivalents

The rest of this page uses cloud-neutral names. This table maps them to each provider: Egress to the public internet leaves your BYOC network through a small, fixed set of NAT addresses on every cloud, so you can pin them in your own egress controls. Ask your ClickHouse team for the current values for your deployment. On AWS and GCP, traffic to the provider’s own storage APIs is the exception: it takes the private path in the row above and never reaches the NAT gateway.

​

Inbound connections

Two ports are sometimes visible on these load balancers but are not client-facing: TCP 15021 serves the provider’s own health checks against the ingress gateway and carries no query traffic, and the MySQL interface (port 3306) is not currently exposed in BYOC — see the FAQ. The ingress gateway’s certificate is issued by cert-manager from a public ACME certificate authority (Let’s Encrypt) using DNS-01 validation, and is stored as a Kubernetes secret inside your own cluster. Traffic between the ingress gateway and the ClickHouse pods stays inside your BYOC network — see Intra-network traffic. Which of the two load balancers is enabled by default depends on your networking model. With a ClickHouse-managed VPC, each service gets the public load balancer, protected by an IP access list, and the private load balancer can be enabled alongside it. With a customer-managed VPC the defaults invert: only the private load balancer is enabled, and your services have no public ingress surface unless you add one. See Connect to your BYOC service. Wherever the public path is enabled, we strongly recommend configuring an IP filter, and you can add a private path — see Private networking setup — and then disable public access entirely. Note that IP filtering is enforced at the ingress proxy layer, so the load balancer ports may appear open in a scan while connections from unlisted sources are rejected.

​

Kubernetes API server exposure

How ClickHouse management services reach the Kubernetes API server, and what restricts that access, differs by cloud:

• AWS (EKS): the public endpoint is restricted to ClickHouse’s egress CIDR ranges through the cluster’s public access CIDR list. It can be switched to private-only access via Tailscale or VPC Lattice — see Kubernetes API Private Connection.
• GCP (GKE): nodes are always private. The control plane is reached over its DNS-based endpoint (*.gke.goog), authorized by the container.clusters.connect IAM permission on the impersonated service account rather than by an IP allow list. The request terminates at Google’s frontend rather than inside your VPC network, but it is still an access path into your cluster’s control plane, so review it as inbound access. The separate IP-based public endpoint can be disabled.
• Azure (AKS): the API server is reached over its public FQDN and authorized by Microsoft Entra ID together with Azure RBAC. API-server authorized IP ranges are not applied by default; contact ClickHouse if your policy requires them.

​

Troubleshooting access

Inbound, Private ClickHouse Cloud engineers reach your deployment for troubleshooting over Tailscale only, never the public internet, on every cloud. Access is just-in-time and certificate-based: an engineer requests it through an internal approval workflow, the platform mints a short-lived per-engineer credential, and it expires automatically. There is no shared administrative identity and no standing access. See ClickHouse data access for the full policy, including which tables engineers can read.

​

Outbound connections

​

Billing scraper

Outbound, Private The billing scraper collects usage data from ClickHouse and sends it to a bucket owned by ClickHouse Cloud — S3 on AWS, Cloud Storage on GCP, Blob Storage on Azure. It runs as a sidecar alongside the ClickHouse server container and periodically scrapes CPU and memory metrics from ClickHouse system tables. Records are keyed by an opaque service identifier and pod name. Same-region requests take the private path to the provider’s storage APIs listed in Provider equivalents, so this traffic does not traverse the public internet on AWS or GCP.

​

Alerts

Outbound, Public AlertManager is configured to send alerts to ClickHouse Cloud when your ClickHouse cluster is unhealthy. BYOC alert payloads are deliberately reduced to an alert name and a service identifier. The full monitoring dataset stays in your own account on every cloud. Distinguish two things here, because they have different boundaries:

• Continuously exported. The reduced usage and health telemetry described under Billing scraper, plus these alert payloads, is the only observability data written into ClickHouse-owned systems. Prometheus remote-write to ClickHouse Cloud is disabled in BYOC builds.
• Read in place. ClickHouse’s monitoring dashboards and, on approved escalation, its engineers query the in-cluster Prometheus stack and your logs over Tailscale — see Tailscale Private Network. Query results necessarily reach ClickHouse-side tooling to be displayed, but nothing is persisted there and the underlying data never leaves your account.

Metrics use a Prometheus and Thanos stack running in your cluster, with optional long-term retention in a bucket in your own account; where you enable that retention, the writes leave your BYOC network for the provider’s storage API, but the data stays within your account. Logs are currently written to the node volumes attached to your ClickHouse nodes; in a future update they will be written to LogHouse, a ClickHouse-based log store that also runs inside your BYOC network.

​

Service state

Outbound, Public The state exporter sends ClickHouse service and backup state information — operational status events, not backup contents — to a queue owned by ClickHouse Cloud: SQS on AWS, Pub/Sub on GCP, Service Bus on Azure. This is what lets the ClickHouse Cloud console show the status of a service running in your account.

​

Intra-network traffic

Traffic between components inside the cluster — ClickHouse to ClickHouse Keeper, the operator, ingress to ClickHouse pods, monitoring scrapes — never leaves your BYOC network. Each provider encrypts traffic between its own instances at the network layer: see AWS, GCP, and Azure. Egress is unrestricted at the security group, firewall rule, and network security group layer by default; the destinations actually contacted are the ones in Outbound connections. An optional per-service egress firewall can enforce a destination allowlist instead — contact your ClickHouse team if you need it.

​

Auditing the boundary

Because the whole data plane runs in your own account, the flows on this page are observable with your own tooling. Some sources are on by default; others you enable yourself:

• Cloud audit trail (CloudTrail, Cloud Audit Logs, or the Azure Activity log): every role assumption, service account impersonation, or service principal sign-in by ClickHouse automation, and every cloud API call made with it.
• Flow logs (VPC Flow Logs, VPC flow logs, or NSG flow logs): the connections above that traverse your own network — client ingress, every outbound flow, and the Tailscale channel. Enable these yourself if you want them retained. Management access to the Kubernetes API server is the exception: while the public endpoint is in use it terminates at your provider’s managed control-plane endpoint rather than inside your network, so it does not appear in your flow logs. Look for it in the Kubernetes audit logs and your cloud audit trail instead; it shows up in flow logs only once the API server is switched to a private endpoint.
• Kubernetes audit logs: on AWS, EKS control-plane logs including the audit log are delivered to a CloudWatch log group in your account; on GCP and Azure, contact support to confirm or enable control-plane audit logging for your cluster.
• Object storage access logs on your data and backup buckets, and on the long-term monitoring retention bucket where you have that enabled.
• Your own system.query_log: every statement run by ClickHouse automation or by an engineer, with the identity attached.