> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-vortex-format.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# BYOC FAQ

> Frequently asked questions about ClickHouse Bring Your Own Cloud (BYOC)

<h2 id="faq">
  FAQ
</h2>

<h3 id="onboarding-and-provisioning">
  Onboarding and provisioning
</h3>

<Accordion title="How do we get started with BYOC?">
  Reach out to ClickHouse via the [contact form](https://clickhouse.com/cloud/bring-your-own-cloud), 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](/products/bring-your-own-cloud/onboarding/standard). We strongly recommend a dedicated account, project, or subscription used only for BYOC.
</Accordion>

<Accordion title="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 default `ClickHouseManagementRole` name 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).

  Provisioning retries automatically and self-heals once the underlying issue is fixed. If your infrastructure remains stuck for more than a couple of hours, contact support.
</Accordion>

<Accordion title="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](/products/bring-your-own-cloud/onboarding/standard#aws-external-id) for details.
</Accordion>

<Accordion title="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.
</Accordion>

<Accordion title="Can BYOC use an existing VPC? What about shared VPCs?">
  On AWS and GCP, you can deploy into an existing VPC that lives in the **same** account or project as the BYOC infrastructure. See the customization guides for [AWS](/products/bring-your-own-cloud/onboarding/customization-aws) and [GCP](/products/bring-your-own-cloud/onboarding/customization-gcp). On GCP, a **Shared VPC** from a separate host project is also supported: the [onboarding module](https://github.com/ClickHouse/terraform-byoc-onboarding/tree/main/modules/gcp) accepts the host project and subnet directly — see its "Shared VPC" section for the setup and prerequisites. Bringing your own VNet on Azure is coming soon.

  On AWS, subnets shared from another account (AWS RAM) are not supported — use a dedicated account connected to your existing network via VPC peering or PrivateLink instead. Note that with a customer-managed VPC, only the private load balancer is enabled by default (see [configuration](/products/bring-your-own-cloud/configuration/configurations)).
</Accordion>

<Accordion title="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.
</Accordion>

<Accordion title="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.
</Accordion>

<h3 id="compute">
  Compute and scaling
</h3>

<Accordion title="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.
</Accordion>

<Accordion title="Which regions do you support for BYOC?">
  All **public regions** listed in our [supported regions](/products/cloud/reference/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.
</Accordion>

<Accordion title="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](/products/bring-your-own-cloud/reference/cost-model-aws) for details.
</Accordion>

<Accordion title="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.
</Accordion>

<Accordion title="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](/products/bring-your-own-cloud/configuration/configurations).
</Accordion>

<Accordion title="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.
</Accordion>

<Accordion title="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.
</Accordion>

<h3 id="network-and-security">
  Network and security
</h3>

<Accordion title="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](/products/bring-your-own-cloud/onboarding/customization-aws)), 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).
</Accordion>

<Accordion title="What exactly can ClickHouse do in our cloud account? Can our security team review the permissions?">
  The [privilege reference](/products/bring-your-own-cloud/reference/privilege) 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](https://s3.us-east-2.amazonaws.com/clickhouse-public-resources.clickhouse.cloud/cf-templates/byoc_v2.yaml) and the [Terraform modules](https://github.com/ClickHouse/terraform-byoc-onboarding) — 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.
</Accordion>

<Accordion title="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](/products/bring-your-own-cloud/reference/clickhouse-data-access) for the data access model and [network security](/products/bring-your-own-cloud/reference/network-security) for the connection model.
</Accordion>

<Accordion title="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.
</Accordion>

<Accordion title="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](/products/bring-your-own-cloud/reference/network-security) for the complete list of outbound flows.
</Accordion>

<Accordion title="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](/products/bring-your-own-cloud/configuration/configurations). 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](/products/bring-your-own-cloud/reference/network-security#cloud-api-vs-kubernetes-api).
</Accordion>

<Accordion title="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.
</Accordion>

<Accordion title="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.
</Accordion>

<Accordion title="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.
</Accordion>

<Accordion title="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](/products/cloud/guides/infrastructure/deployment-options/byoc/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.
</Accordion>

<Accordion title="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](/products/bring-your-own-cloud/configuration/connect#connection-via) shows the endpoints for each connection path enabled for your service. See [connectivity](/products/bring-your-own-cloud/configuration/connect).
</Accordion>

<Accordion title="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.
</Accordion>

<Accordion title="How do we set up AWS PrivateLink, GCP Private Service Connect, or Azure Private Link?">
  Follow the network setup guides for [AWS](/products/bring-your-own-cloud/onboarding/network-aws) and [GCP](/products/bring-your-own-cloud/onboarding/network-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](/products/bring-your-own-cloud/configuration/connect#connection-via) to copy the correct private endpoint hostname.
</Accordion>

<Accordion title="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](/products/bring-your-own-cloud/onboarding/network-aws#setup-privatelink) for the steps; AWS cross-region data transfer rates apply.
</Accordion>

<Accordion title="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](/products/bring-your-own-cloud/onboarding/customization-aws#ensure-network-connectivity). If your network policy requires an explicit inventory, contact support to review your setup.
</Accordion>

<Accordion title="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.
</Accordion>

<Accordion title="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](/products/cloud/guides/infrastructure/deployment-options/byoc/overview) for the current list of planned features.
</Accordion>

<h3 id="upgrades-and-maintenance">
  Upgrades and maintenance
</h3>

<Accordion title="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](/products/bring-your-own-cloud/configuration/operations).
</Accordion>

<Accordion title="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](/products/bring-your-own-cloud/configuration/operations).
</Accordion>

<h3 id="backups-and-disaster-recovery">
  Backups and disaster recovery
</h3>

<Accordion title="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.
</Accordion>

<Accordion title="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.
</Accordion>

<Accordion title="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.
</Accordion>

<Accordion title="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](/products/bring-your-own-cloud/reference/observability-aws).
</Accordion>

<Accordion title="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.
</Accordion>

<h3 id="observability">
  Observability
</h3>

<Accordion title="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](/products/bring-your-own-cloud/reference/observability-aws) for endpoints and setup.
</Accordion>

<h3 id="cost">
  Cost
</h3>

<Accordion title="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](/products/bring-your-own-cloud/reference/cost-model-aws), [billable AWS services](/products/bring-your-own-cloud/reference/billable-aws-services), and [AWS service limits](/products/bring-your-own-cloud/reference/aws-service-limits).
</Accordion>

<h3 id="availability-and-lifecycle">
  Availability and lifecycle
</h3>

<Accordion title="Which cloud providers is BYOC available on?">
  AWS, GCP, and Azure are all generally available. See the [overview](/products/cloud/guides/infrastructure/deployment-options/byoc/overview) for the supported features and regions on each cloud.
</Accordion>

<Accordion title="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.
</Accordion>

<h3 id="uptime-sla">
  Uptime SLAs
</h3>

<Accordion title="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](mailto:support@clickhouse.com).
</Accordion>