FAQ
Onboarding and provisioning
How do we get started with BYOC?
How do we get started with BYOC?
Reach out to ClickHouse via the contact form, and the team will enable BYOC for your organization. You then prepare a dedicated cloud account (AWS account, GCP project, or Azure subscription) and follow the standard onboarding guide. We strongly recommend a dedicated account, project, or subscription used only for BYOC.
How long does infrastructure provisioning take, and what are common reasons it gets stuck?
How long does infrastructure provisioning take, and what are common reasons it gets stuck?
Expect roughly 45–90 minutes end to end. The range is wide because most of that time is the cloud provider provisioning resources (the Kubernetes cluster, load balancers, network components), which takes an inconsistent amount of time from run to run and is outside ClickHouse’s control. When provisioning stalls, the most common causes are on the account side:
- The CloudFormation template or Terraform module was modified before applying it — for example, adding a
PermissionsBoundary, or renaming the IAM role to satisfy a naming convention (on AWS, keep the defaultClickHouseManagementRolename unless ClickHouse has explicitly approved a different one). Apply the artifacts as provided — supported customizations are exposed as parameters, and any other change needs ClickHouse’s approval first. - Organization-level policies (AWS SCPs, GCP organization policies such as
iam.allowedPolicyMemberDomains, or Azure policies restricting role assignments) blocking role assumption or IAM bindings. - An external ID mismatch on the onboarding role (see the external ID question below).
- Account quota limits (for example Elastic IPs or VPCs on AWS).
What value should we use for the external ID in the onboarding template?
What value should we use for the external ID in the onboarding template?
The ClickHouse Cloud console generates an external ID for your AWS account when you start onboarding and pre-fills it in the CloudFormation link (the
ExternalID parameter); if you use Terraform, pass the same value as external_id. All BYOC infrastructures on the same AWS account share the same external ID. Don’t choose your own value: it must match what ClickHouse’s automation expects, or the cross-account role can’t be assumed and provisioning fails. See AWS external ID for details.Why is my external ID emptyid?
Why is my external ID emptyid?
BYOC infrastructures onboarded before external IDs were introduced use the placeholder value
emptyid for backward compatibility. When you add new infrastructure on an AWS account with an existing legacy deployment, the console reuses this placeholder so that all infrastructures on the account keep a consistent trust configuration. If you would like to switch to a unique external ID, contact ClickHouse Support.Can BYOC be installed into an existing Kubernetes cluster?
Can BYOC be installed into an existing Kubernetes cluster?
No. The Kubernetes cluster (EKS, GKE, or AKS) is created and fully managed by ClickHouse. This is required so that ClickHouse can operate the platform reliably and keep it upgraded.
Can we run our own workloads in the BYOC cluster or cloud account?
Can we run our own workloads in the BYOC cluster or cloud account?
In the cloud account: possible, but co-located resources always sit within ClickHouse’s permission surface to some degree — on AWS most write permissions are tag- and prefix-scoped (ClickHouse-provisioned resources carry
clickhouse-byoc=true) but a small set of EC2 actions cannot be tag-scoped, and on GCP and Azure the onboarding identities hold project- or subscription-scoped permissions. Keep your resources away from ClickHouse-provisioned ones, and prefer a dedicated account, project, or subscription on every cloud — that remains the strong recommendation.In the Kubernetes cluster: it is possible with constraints — use your own node groups with taints and tolerations, stay out of ClickHouse-managed namespaces, and do not install cluster-wide admission controllers or policy engines, which can block reconciliation of ClickHouse components. Describe your plan to support first so we can confirm there are no collisions.Compute and scaling
Can I create multiple services in a single BYOC infrastructure?
Can I create multiple services in a single BYOC infrastructure?
Yes. The infrastructure (including the Kubernetes cluster) only needs to be provisioned once for every cloud account/project/subscription and region combination, and all services you create in that region share it.
Which regions do you support for BYOC?
Which regions do you support for BYOC?
All public regions listed in our supported regions documentation are available for BYOC deployments. BYOC provisions across three availability zones, so regions with fewer than three zones and AWS Local Zones are not supported. If a region you need is not listed, contact your ClickHouse representative to discuss availability.
Will there be some resource overhead? What are the resources needed to run services other than ClickHouse instances?
Will there be some resource overhead? What are the resources needed to run services other than ClickHouse instances?
Besides the ClickHouse instances themselves (ClickHouse servers and ClickHouse Keeper), we also run supporting services such as
clickhouse-operator, the cluster autoscaler, Istio, and the monitoring stack.The resource consumption of these shared components is relatively stable and doesn’t grow linearly with the number or size of your ClickHouse services. As a rough guideline, the dedicated system node group for these workloads totals roughly 48 vCPUs and 192 GB of memory — on AWS, for example, about six 2xlarge instances. In addition, each warehouse runs a dedicated three-node ClickHouse Keeper ensemble, shared by all services in that warehouse. See the cost model for details.Does BYOC support autoscaling?
Does BYOC support autoscaling?
Service-level (vertical) autoscaling is on the roadmap. Available today: manual vertical and horizontal scaling through the console, scheduled scaling for predictable load patterns, automatic idling and wake-up for intermittent workloads, and automatic node-group scaling at the infrastructure level — you never manage nodes yourself. ClickHouse Keeper is monitored and scaled by ClickHouse.
Which instance types does BYOC run on? Can we change the instance family?
Which instance types does BYOC run on? Can we change the instance family?
BYOC runs on a curated set of node groups rather than arbitrary instance types. The workload node groups (ClickHouse servers and Keeper) run on ARM-based, memory-optimized instances by default (Graviton on AWS), while the system node group typically uses x86 instances. Different instance families, CPU-to-memory ratios, or architectures can be provisioned on request through support; spot instances are not supported. See configuration.
Can we run very small replicas to keep costs down?
Can we run very small replicas to keep costs down?
Each replica runs as one pod on its own node — node size is matched to the replica size, nodes are provisioned on demand, and multiple replicas are never packed onto one node. Very small replicas are therefore inefficient: a larger share of the hardware goes to overhead, and network and disk bandwidth scale with instance size. Sizes below what the console offers are custom requests through support.
Can we separate ingest and query workloads?
Can we separate ingest and query workloads?
Yes. Warehouses (compute-compute separation) are supported in BYOC: multiple services share the same data, so you can dedicate services to ingestion and others to querying.
Network and security
Can we limit or revoke the permissions granted during installation?
Can we limit or revoke the permissions granted during installation?
You can reduce the grants from the start on AWS and GCP: the onboarding artifacts are parameterized, so you can withhold permissions to manage your VPC’s network topology when bringing your own VPC (
IncludeVPCWritePermissions in CloudFormation, include_vpc_write_permissions in the Terraform modules). On GCP this scopes down topology management only — ClickHouse retains write access to the networking resources it owns inside the VPC, such as the Private Service Connect NAT subnet, service attachment, and ingress addresses. On AWS you can additionally — in private preview, enabled through support — manage the IAM roles yourself (IncludeIAMWritePermissions=false, see customer-managed IAM roles), and the cross-account roles are protected by an external ID against confused-deputy access. On Azure, the onboarding module grants a fixed subscription-scoped role with no scoping parameters today. Across all clouds, some permissions are required only for specific features and can be removed if you will never use those features — contact support if you need to scope down permissions beyond what the artifacts expose.After provisioning, do not remove permissions from the management identity unilaterally: ClickHouse continuously reconciles the infrastructure, and missing permissions break provisioning, upgrades, and support. To change the granted permissions or offboard entirely, coordinate with support (see the decommissioning question below).What exactly can ClickHouse do in our cloud account? Can our security team review the permissions?
What exactly can ClickHouse do in our cloud account? Can our security team review the permissions?
The privilege reference gives a high-level overview of every role and identity and its purpose on AWS, GCP, and Azure. For the onboarding (bootstrap) identity, the exact policy surface is defined by the published artifacts — the CloudFormation template and the Terraform modules — which your security team can audit directly. The additional identities ClickHouse creates after onboarding (controller roles, service accounts, and managed identities) are described per provider in the privilege reference, and because they live in your account, you can inspect their actual policies in your cloud console and see their creation and use in CloudTrail or the GCP/Azure equivalents. On AWS, most write permissions of the management role are scoped by resource tags and name prefixes such as
clickhouse-cloud-*, so it generally cannot modify resources it did not create (a small number of EC2 actions cannot be tag-scoped), and it has no object-level access to your data buckets — object access is limited to in-cluster identities scoped to the ClickHouse workloads. On GCP and Azure, the onboarding identities hold project- or subscription-scoped permissions instead — one of the reasons a dedicated project or subscription is strongly recommended. Read permissions are broader because they are required for continuous reconciliation.What access do ClickHouse employees have to our environment and data?
What access do ClickHouse employees have to our environment and data?
By default, none to your data. For troubleshooting, engineers must go through an internal just-in-time escalation process; access is time-bound, certificate-based, limited to
system.* tables (no customer data tables), logged, and audited by our security team. Any query run by a ClickHouse engineer is visible to you in your own system.query_log. For infrastructure diagnostics, the same approval-gated escalation can also grant time-bound access to the Kubernetes API server and the in-cluster monitoring stack over Tailscale. See ClickHouse data access for the data access model and network security for the connection model.Have you considered some future security controls for ClickHouse engineers to access customer infra for troubleshooting?
Have you considered some future security controls for ClickHouse engineers to access customer infra for troubleshooting?
Yes. Implementing a customer controlled mechanism where customers can approve engineers’ access to the cluster is on our roadmap. At the moment, engineers must go through our internal escalation process to gain just-in-time access to the cluster. This is logged and audited by our security team.
What data leaves our account?
What data leaves our account?
Only operational metadata: service and backup state events, usage metrics for billing, and alert notifications. Your data, backups, logs, and monitoring data stay in your account. See network security for the complete list of outbound flows.
How does the ClickHouse control plane reach the Kubernetes API in our account? Is Tailscale required?
How does the ClickHouse control plane reach the Kubernetes API in our account? Is Tailscale required?
By default, the Kubernetes API endpoint is public but restricted to ClickHouse’s NAT IP addresses — while this default is in use, do not remove the ClickHouse allowlist entries, since the control plane needs them to manage the cluster. The endpoint can instead be switched to private-only access, coordinated with the ClickHouse team: via Tailscale (outbound-only, also used for troubleshooting access) or, on AWS, via VPC Lattice (private preview) — see configuration. Note that this applies only to the Kubernetes API: cloud provider API calls (for example EKS and EC2 on AWS) originate from ClickHouse Cloud’s network via cross-account role assumption and can never be routed through Tailscale — see cloud provider APIs vs the Kubernetes API.
What is the size of the VPC/VNet IP range created?
What is the size of the VPC/VNet IP range created?
By default, we use
10.0.0.0/16 for the BYOC VPC (AWS/GCP) or VNet (Azure). We recommend reserving at least /22 for potential future scaling,
but if you prefer to limit the size, it is possible to use /23 if it is likely that you will be limited
to 30 server pods.How does network communication work between the BYOC network and object storage?
How does network communication work between the BYOC network and object storage?
On AWS, traffic between your Customer BYOC VPC and S3 uses HTTPS (port 443) via the AWS S3 API for table data, backups, and logs. This traffic goes through an S3 gateway VPC endpoint, so it remains within the AWS network, doesn’t traverse the public internet, and incurs no NAT gateway charges. On GCP, access to Google APIs similarly uses Private Google Access. On Azure, data is stored in Azure Blob Storage accounts within your subscription.
The data is in our own bucket — can we read or modify it directly?
The data is in our own bucket — can we read or modify it directly?
No. Table data blobs are stored in a shared layout without per-table paths, so objects cannot be attributed to tables, and any direct modification risks corrupting your services. Never modify bucket contents directly; if you suspect an issue, open a support ticket.
What ports are used for client and cluster communication?
What ports are used for client and cluster communication?
Client connections terminate at the load balancer on TLS ports: 8443 (HTTPS interface) and 9440 (native protocol over TLS); port 443 also routes to the HTTPS interface. The MySQL interface (port 3306) is not currently exposed in BYOC — it is on the roadmap (see the overview).Inside the network, cluster-internal communication uses the native protocol on port 9000, HTTP on port 8123, and interserver communication on port 9009 for replication and distributed queries. These internal ports and the ClickHouse Keeper ports are never exposed on any load balancer.
Are our service endpoints exposed to the public internet? Can we go private-only?
Are our service endpoints exposed to the public internet? Can we go private-only?
With a ClickHouse-managed VPC, each service gets a public load balancer protected by an IP access list by default; a private load balancer, reachable from your network and peered networks, can additionally be enabled through support. With a customer-managed VPC, the defaults are inverted and only the private load balancer is enabled. IP filtering is enforced at the ingress proxy layer, so the load balancer ports may appear open in scans while connections from unlisted sources are rejected. The public endpoint can be disabled entirely once nothing depends on it. The console’s Connection via selector shows the endpoints for each connection path enabled for your service. See connectivity.
Can we use our own DNS domain or bring our own TLS certificates?
Can we use our own DNS domain or bring our own TLS certificates?
Not today. Service endpoints are provisioned under
clickhouse-byoc.com with ClickHouse-managed certificates.How do we set up AWS PrivateLink, GCP Private Service Connect, or Azure Private Link?
How do we set up AWS PrivateLink, GCP Private Service Connect, or Azure Private Link?
Follow the network setup guides for AWS and GCP; for Azure deployments, Azure Private Link is supported — contact the ClickHouse team for setup assistance. Two things commonly missed: endpoint allowlisting is per service, so endpoints must be registered again for each new service, and DNS resolution for the private endpoint names must be configured on your side if you run your own DNS. Once set up, use the console’s Connection via selector to copy the correct private endpoint hostname.
Can we connect over PrivateLink from a different AWS region?
Can we connect over PrivateLink from a different AWS region?
Yes, but the console’s Enable private link toggle covers same-region consumers only — AWS disables cross-region access on endpoint services by default, and the ClickHouse console doesn’t manage it. Since the endpoint service lives in your BYOC account, you enable it yourself: add the consumer regions to the endpoint service’s Supported regions list in your AWS console, then create the endpoint with the cross-region option on the consumer side. ClickHouse won’t change or reset these values. See the PrivateLink setup guide for the steps; AWS cross-region data transfer rates apply.
Is there a list of endpoints we need to allow in our firewall or egress rules?
Is there a list of endpoints we need to allow in our firewall or egress rules?
There is no single published endpoint list. The cluster requires working outbound internet access (directly or via NAT) in addition to private access to cloud provider APIs — see the network connectivity requirements. If your network policy requires an explicit inventory, contact support to review your setup.
Our security tooling flagged privileged containers or host mounts in the BYOC cluster — is this expected?
Our security tooling flagged privileged containers or host mounts in the BYOC cluster — is this expected?
Some platform components legitimately require elevated privileges or host filesystem access, such as the EBS CSI driver, node configuration jobs, and the Prometheus node exporter (which reads
/proc and /sys). If your scanner raises findings, share them with support — we will confirm whether each one is by design or actionable.Do you support customer-managed encryption keys (CMEK)?
Do you support customer-managed encryption keys (CMEK)?
Not currently for BYOC. Data at rest is encrypted with cloud-provider-managed keys. See the overview for the current list of planned features.
Upgrades and maintenance
How do ClickHouse version upgrades work? Can I decide maintenance frequency?
How do ClickHouse version upgrades work? Can I decide maintenance frequency?
Upgrades work the same way as in ClickHouse Cloud: services enroll in release channels (fast, regular, slow) and honor scheduled maintenance windows — contact support to configure them. Please expect a minimum of a weekly update schedule. Upgrades are rolling, replica-by-replica (make-before-break), so there is no whole-service downtime. See operations.
Who is responsible for Kubernetes upgrades, and what impact should we expect?
Who is responsible for Kubernetes upgrades, and what impact should we expect?
ClickHouse owns and performs Kubernetes upgrades proactively, ahead of provider end-of-support dates, and coordinates the window with you through support. Control-plane upgrades are transparent; node-group upgrades roll nodes one by one with make-before-break semantics, so you may see brief connection resets as pods restart, but no data loss. See operations.
Backups and disaster recovery
Where are backups stored?
Where are backups stored?
In object storage in your own cloud account — backups never leave your environment. Backup schedule and retention are configurable; contact support to adjust them.
What is included in a backup? Are system tables backed up?
What is included in a backup? Are system tables backed up?
All user-created databases, tables, and objects, plus access entities (users, roles, settings profiles, row policies, quotas) and user-defined functions. System log tables such as
system.query_log are not included.Why am I billed for backups that are older than my retention window?
Why am I billed for backups that are older than my retention window?
Backups form chains: a full backup followed by incrementals that depend on it. The base full backup is required to restore any incremental in its chain, so it is retained (and stored) until every dependent incremental has aged out of retention.
How can we monitor backup status ourselves?
How can we monitor backup status ourselves?
Two ways: the ClickHouse Cloud API backup endpoints, and the backup metrics (initiation, completion, and failure counters) exposed by the in-cluster monitoring stack — we recommend alerting on failures in your own monitoring. See observability.
How do we meet disaster recovery requirements (RPO/RTO)?
How do we meet disaster recovery requirements (RPO/RTO)?
BYOC deploys across three availability zones, and writes are acknowledged only after object storage confirms them. Cross-region replication is not available today, so regional disaster recovery is backup-based and the achievable RPO is bounded by your backup frequency. Backup frequency and destination can be configured to match your targets, including backing up to a bucket in another region — contact support to set this up.
Observability
How do we integrate BYOC with our own monitoring and alerting?
How do we integrate BYOC with our own monitoring and alerting?
The monitoring stack (Prometheus, Grafana, AlertManager) runs inside your account, and you can consume it directly over private connectivity: query it over the PromQL API, federate it into your own Prometheus, or scrape the ClickHouse
/metrics_all endpoint per service. There is no turnkey integration for third-party platforms such as Datadog today — integrate via their Prometheus-compatible ingestion. See observability for endpoints and setup.Cost
What do we pay for with BYOC?
What do we pay for with BYOC?
Two separate bills: ClickHouse Cloud charges based on the memory allocated to your services, and your cloud provider bills you directly for the underlying infrastructure at cost, with no markup. The detailed cost reference pages currently cover AWS: see the cost model, billable AWS services, and AWS service limits.
Availability and lifecycle
Which cloud providers is BYOC available on?
Which cloud providers is BYOC available on?
AWS, GCP, and Azure are all generally available. See the overview for the supported features and regions on each cloud.
How do we decommission a BYOC environment?
How do we decommission a BYOC environment?
Terminate your services and the BYOC infrastructure from the ClickHouse console — do not start by deleting resources or revoking permissions in your cloud provider console, which severs the control-plane connection mid-flight and forces manual cleanup. Once the console-driven termination completes, remove the onboarding stack (CloudFormation stack or Terraform module) and any remaining resources. On AWS, all ClickHouse-created resources are tagged
clickhouse-byoc=true, so you can enumerate them afterwards to verify nothing is left; on GCP and Azure, the dedicated project or subscription you onboarded bounds what to review.Uptime SLAs
Does ClickHouse offer an uptime SLA for BYOC?
Does ClickHouse offer an uptime SLA for BYOC?
No, since the data plane is hosted in the customer’s cloud environment, service availability depends on resources not in ClickHouse’s control. Therefore, ClickHouse doesn’t offer a formal uptime SLA for BYOC deployments. Note that running services operate independently of the ClickHouse control plane: a control-plane outage does not take down services running in your account. If you have additional questions, please contact support@clickhouse.com.