Skip to main content

​
What is standard onboarding?

Standard onboarding is the default, guided workflow for deploying ClickHouse in your own cloud account using BYOC. In this approach, ClickHouse Cloud provisions all of the core cloud resources required for your deployment—such as the VPC/VNet, subnets, security groups, Kubernetes (EKS/GKE/AKS) cluster, and supporting IAM roles/service accounts/service principals—within your AWS account, GCP project, or Azure subscription. This ensures consistent, secure configuration, and minimizes the manual steps required from your team. With standard onboarding, you simply provide a dedicated AWS account, GCP project, or Azure subscription, and run an initial stack (via CloudFormation or Terraform) to create the minimum permissions and trust required for ClickHouse Cloud to orchestrate further setup. All subsequent steps—including infrastructure provisioning and service launch—are managed through the ClickHouse Cloud web console. Customers are strongly recommended to prepare a dedicated AWS account, GCP project, or Azure subscription for hosting the ClickHouse BYOC deployment to ensure better isolation in terms of permissions and resources. ClickHouse will deploy a dedicated set of cloud resources (VPC/VNet, Kubernetes cluster, IAM roles/service accounts/service principals, object storage buckets, etc.) in your account. If you need a more customized setup (for example, deploying into an existing VPC), refer to the Customized Onboarding documentation.
A standard BYOC onboarding takes approximately 45–90 minutes end-to-end, measured from the time the CloudFormation or Terraform steps are launched to the time the first ClickHouse service is reachable.

​
Request access

To start the onboarding process, please contact us. Our team will guide you through the BYOC requirements, help you select the most suitable deployment options, and add your account to the allowlist.

​
Onboarding

​
Prepare an AWS account/GCP project/Azure subscription

Prepare a fresh AWS account, GCP project, or Azure subscription under your organization.
1

Choose a Cloud Provider

2

Account/project/subscription setup

The initial BYOC setup can be performed using a CloudFormation template (AWS), a Terraform module (GCP), or a Terraform module (Azure). It creates a highly privileged identity (IAM role/service account/service principal), enabling BYOC controllers from ClickHouse Cloud to manage your infrastructure.
Apply the onboarding artifacts exactly as provided. Do not change anything in the CloudFormation template or Terraform module — including renaming resources or adding parameters such as a PermissionsBoundary — without ClickHouse’s explicit approval. ClickHouse automation depends on the exact resources these artifacts create; supported customizations are exposed as parameters. In particular, on AWS the IAM role must keep its default name ClickHouseManagementRole — no prefix or suffix — unless ClickHouse has explicitly agreed to a different name beforehand. The Terraform module technically exposes a role_name input, but ClickHouse’s automation must be configured to match, so changing it without coordination (or renaming the role in the CloudFormation template, which has no such parameter) produces a stack that applies successfully while infrastructure provisioning fails, because ClickHouse cannot assume the expected role.
Storage buckets, VPC/VNet, Kubernetes cluster, and compute resources required for running ClickHouse aren’t included in this initial setup. They will be provisioned in the next step.

​
Terraform Module for AWS

If you prefer to use Terraform instead of CloudFormation for AWS deployments, use the terraform-byoc-onboarding module:
Replace <version> with the latest tag from the module’s releases page — always use the latest release.The module outputs clickhouse_management_role_arn. In the standard flow you don’t need to act on it — onboarding continues in the ClickHouse Cloud console — but keep it at hand: ClickHouse will ask for it if your setup deviates from the defaults (for example, a coordinated custom role name).
The module was previously distributed as a tarball at https://s3.us-east-2.amazonaws.com/clickhouse-public-resources.clickhouse.cloud/tf/byoc.tar.gz. That URL remains available but is deprecated — use the GitHub module above.

​
AWS external ID

On AWS, the IAM role created during setup trusts ClickHouse Cloud with an external ID (sts:ExternalId) to protect against confused-deputy attacks. The ClickHouse Cloud console generates an external ID for your AWS account when you start onboarding and pre-fills it in the CloudFormation link; if you use Terraform, pass the same value as external_id. All BYOC infrastructures on the same AWS account share the same external ID.
BYOC infrastructures onboarded before external IDs were introduced use the placeholder value emptyid for backward compatibility. The console shows this value when you add infrastructure on an AWS account with an existing legacy deployment, 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.
3

Set up BYOC infrastructure

You will be prompted to set up the infrastructure, including object storage buckets, VPC/VNet, and the Kubernetes cluster, from the ClickHouse Cloud console. Certain configurations must be determined at this stage, as they can’t be changed later. Specifically:
  • Region: All public regions listed in our supported regions documentation are available for BYOC deployments. Private regions aren’t currently supported.
  • VPC/VNet CIDR range: By default, we use 10.0.0.0/16 for the BYOC VPC (AWS/GCP) or VNet (Azure) CIDR range. If you plan to use VPC/VNet peering with another account, ensure the CIDR ranges don’t overlap. Allocate a proper CIDR range for BYOC, with a minimum size of /23 to accommodate necessary workloads. The /23 minimum accommodates only about 30 server pods — every replica consumes IP addresses, so allocate a larger range (at least /22 is recommended) if you expect the deployment to grow.
  • Availability Zones: If you plan to use VPC peering, aligning availability zones between the source and BYOC accounts can help reduce cross-AZ traffic costs. For example, in AWS, availability zone suffixes (a, b, c) may represent different physical zone IDs across accounts. See the AWS guide for details.

​
Create Your First BYOC ClickHouse Service

After your BYOC infrastructure has been provisioned, you’re ready to launch your initial ClickHouse service. Open the ClickHouse Cloud console, select your BYOC environment, and follow the prompts to create a new service. During service creation, you’ll configure the following options:
  • Service name: Enter a clear, descriptive name for your ClickHouse service.
  • BYOC infrastructure: Select the BYOC environment, including the cloud account and region, where your service will run.
  • Resource configuration: Choose the amount of CPU and memory allocated to your ClickHouse replicas.
  • Replica count: Set the number of replicas for enhanced high availability.
Last modified on August 4, 2026