Standard Onboarding

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, subnets, security groups, Kubernetes (EKS/GKE) cluster, and supporting IAM roles/service accounts—within your AWS account/GCP project. 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, and run an initial stack (via CloudFormation or Terraform) to create the minimum IAM 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 or GCP project 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, Kubernetes cluster, IAM roles, S3 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.

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

Prepare a fresh AWS account or GCP project under your organization. Visit our web console: https://console.clickhouse.cloud/byocOnboarding to continue the setup.

Choose a Cloud Provider

Account/Project setup

The initial BYOC setup can be performed using either a CloudFormation template(AWS) or a Terraform module(GCP). It creates a high priviledged IAM role, enabling BYOC controllers from ClickHouse Cloud to manage your infrastructure.

Примечание

Storage buckets, VPC, Kubernetes cluster, and compute resources required for running ClickHouse are not included in this initial setup. They will be provisioned in the next step.

Alternative Terraform Module for AWS

If you prefer to use Terraform instead of CloudFormation for AWS deployments, we also provide a Terraform module for AWS.

Usage:

module "clickhouse_onboarding" {
  source   = "https://s3.us-east-2.amazonaws.com/clickhouse-public-resources.clickhouse.cloud/tf/byoc.tar.gz"
  byoc_env = "production"
}

Set up BYOC infrastructure

You will be prompted to set up the infrastructure, including S3 buckets, VPC, and the Kubernetes cluster, from the ClickHouse Cloud console. Certain configurations must be determined at this stage, as they cannot be changed later. Specifically:

• Region: All public regions listed in our supported regions documentation are available for BYOC deployments. Private regions are not currently supported.

• VPC CIDR range: By default, we use 10.0.0.0/16 for the BYOC VPC CIDR range. If you plan to use VPC peering with another account, ensure the CIDR ranges do not overlap. Allocate a proper CIDR range for BYOC, with a minimum size of /22 to accommodate necessary workloads.

• 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.