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

# Standard onboarding

> Deploy ClickHouse on your own cloud infrastructure

export const Image = ({img, alt, size = "lg", background}) => {
  const normalizedSize = ["sm", "md", "lg"].includes(size) ? size : "lg";
  const backgroundColor = background === "white" ? "white" : background === "black" ? "rgb(31 31 28)" : undefined;
  return <div className={`ch-image-${normalizedSize}`}>
      <Frame>
        <img src={img} alt={alt} style={{
    backgroundColor
  }} />
      </Frame>
    </div>;
};

<h2 id="what-is-standard-onboarding">
  What is standard onboarding?
</h2>

**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](/products/bring-your-own-cloud/onboarding/customization-aws) documentation.

<Note>
  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.
</Note>

<h2 id="request-access">
  Request access
</h2>

To start the onboarding process, please [contact us](https://clickhouse.com/cloud/bring-your-own-cloud). Our team will guide you through the BYOC requirements, help you select the most suitable deployment options, and add your account to the allowlist.

<h2 id="onboarding-process">
  Onboarding
</h2>

<h3 id="prepare-an-aws-account">
  Prepare an AWS account/GCP project/Azure subscription
</h3>

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

<Steps>
  <Step title="Choose a Cloud Provider" id="choose-cloud-provider">
    <Image img="https://mintcdn.com/private-7c7dfe99-trino-dialect/wrAOYL3DquclMwbQ/images/cloud/reference/byoc-onboarding-1.webp?fit=max&auto=format&n=wrAOYL3DquclMwbQ&q=85&s=a6b94d9f4e2e84782e2ce1cad935b24d" size="lg" alt="BYOC choose CSP" background="black" width="1182" height="944" data-path="images/cloud/reference/byoc-onboarding-1.webp" />
  </Step>

  <Step title="Account/project/subscription setup" id="account-setup">
    The initial BYOC setup can be performed using a [CloudFormation template (AWS)](https://s3.us-east-2.amazonaws.com/clickhouse-public-resources.clickhouse.cloud/cf-templates/byoc_v2.yaml), a [Terraform module (GCP)](https://github.com/ClickHouse/terraform-byoc-onboarding/tree/main/modules/gcp), or a [Terraform module (Azure)](https://github.com/ClickHouse/terraform-byoc-onboarding/tree/main/modules/azure). It creates a highly privileged identity (IAM role/service account/service principal), enabling BYOC controllers from ClickHouse Cloud to manage your infrastructure.

    <Warning>
      **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.
    </Warning>

    <Image img="https://mintcdn.com/private-7c7dfe99-trino-dialect/wrAOYL3DquclMwbQ/images/cloud/reference/byoc-onboarding-2.webp?fit=max&auto=format&n=wrAOYL3DquclMwbQ&q=85&s=4517b457d58fa14a822a5f4608cc1a7e" size="lg" alt="BYOC initialize account" background="black" width="1182" height="316" data-path="images/cloud/reference/byoc-onboarding-2.webp" />

    <Note>
      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.
    </Note>

    <h4 id="terraform-module-aws">
      Terraform Module for AWS
    </h4>

    If you prefer to use Terraform instead of CloudFormation for AWS deployments, use the [terraform-byoc-onboarding](https://github.com/ClickHouse/terraform-byoc-onboarding) module:

    ```hcl theme={null}
    module "clickhouse_onboarding" {
      source      = "github.com/ClickHouse/terraform-byoc-onboarding.git//modules/aws?ref=<version>"
      external_id = "<external-id-provided-by-clickhouse>"
    }
    ```

    Replace `<version>` with the latest tag from the module's [releases page](https://github.com/ClickHouse/terraform-byoc-onboarding/releases) — 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).

    <Note>
      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.
    </Note>

    <h4 id="aws-external-id">
      AWS external ID
    </h4>

    On AWS, the IAM role created during setup trusts ClickHouse Cloud with an [external ID](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user_externalid.html) (`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.

    <Note>
      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.
    </Note>
  </Step>

  <Step title="Set up BYOC infrastructure" id="setup-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](/products/cloud/reference/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. The minimum size differs by cloud:

      * **AWS**: `/23`
      * **Azure**: `/23`
      * **GCP**: `/20`

      These are floors, not recommendations: every replica consumes IP addresses, so larger deployments need a larger range.

    * **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](https://docs.aws.amazon.com/prescriptive-guidance/latest/patterns/use-consistent-availability-zones-in-vpcs-across-different-aws-accounts.html) for details.

    <Image img="https://mintcdn.com/private-7c7dfe99-trino-dialect/wrAOYL3DquclMwbQ/images/cloud/reference/byoc-onboarding-3.webp?fit=max&auto=format&n=wrAOYL3DquclMwbQ&q=85&s=ae5d4ae59e0dddcb873a0d05879c8c59" size="lg" alt="BYOC set up infrastructure" background="black" width="1182" height="1406" data-path="images/cloud/reference/byoc-onboarding-3.webp" />

    <h4 id="preflight-validation">
      Pre-flight validation
    </h4>

    When you click **Set up Infrastructure**, ClickHouse Cloud runs a set of **read-only** pre-flight checks against your account before creating any resources. If everything passes, provisioning continues. If a check fails, setup is paused and the console shows exactly what's wrong, so you can fix it before any resources are created.

    The checks confirm that:

    * **Permissions** — the management identity (IAM role / service account / service principal) holds the permissions ClickHouse Cloud needs to provision and operate your deployment.
    * **Enabled services** *(GCP)* — the required Google Cloud APIs (Compute Engine, Kubernetes Engine, Cloud Storage, Network Connectivity, IAM) are enabled on your project.
    * **Network** *(AWS bring-your-own-VPC)* — your VPC and subnets meet the [network requirements](/products/bring-your-own-cloud/onboarding/customization-aws#configure-existing-vpc): subnet sizes, required tags, availability-zone spread, outbound connectivity, and available IP addresses.
    * **Quotas and guardrails** *(AWS)* — your account has sufficient service quotas (VPCs, NAT gateways, Elastic IPs, EKS clusters, vCPUs) and no organization policy (SCP) blocks a required action.

    When checks fail, each one is listed with the action it maps to and the reason it failed (for example, `iam:CreateRole · explicitDeny`). Expand **Show passed checks** to review everything that succeeded.

    <Image img="https://mintcdn.com/private-7c7dfe99-trino-dialect/HVVNl4vu1ZT30V-H/images/cloud/reference/byoc-onboarding-preflight-failed.png?fit=max&auto=format&n=HVVNl4vu1ZT30V-H&q=85&s=de520286d9727431016ba1f722e8178b" size="lg" alt="BYOC pre-flight validation reporting failed cloud-setup checks" background="black" width="1358" height="1724" data-path="images/cloud/reference/byoc-onboarding-preflight-failed.png" />

    To resolve the failures, re-run the latest ClickHouse CloudFormation or Terraform stack — or grant the reported actions to the management identity (IAM role / service account / service principal) — then choose one of:

    * **Re-verify** — re-runs the pre-flight checks. Use this after fixing the reported issues to confirm your setup is ready before provisioning.
    * **Proceed anyway** — continues provisioning despite the failed checks. Only use this if you're confident a reported failure is a false positive; otherwise provisioning is likely to fail partway through.

    Use the table below to resolve common failures.

    | Validation error                                                                                                                                                             | Likely cause                                                                                                                                    | How to resolve                                                                                                                                           |
    | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | **Cannot assume the management role** *(AWS)*                                                                                                                                | The onboarding stack wasn't completed, or the role or external ID doesn't match                                                                 | Re-run the latest onboarding stack and confirm the [external ID](#aws-external-id) shown in the console matches the one in your trust policy             |
    | **Cannot impersonate the management service account** *(GCP)*                                                                                                                | The onboarding Terraform wasn't completed, or the `clickhouse-management` service account is missing or does not grant ClickHouse impersonation | Re-run the latest onboarding Terraform and confirm the `clickhouse-management` service account exists and grants ClickHouse permission to impersonate it |
    | **Missing permission** (e.g. create VPC, create IAM role, create Kubernetes cluster)                                                                                         | The management identity lacks a required permission — often from a customized or outdated stack                                                 | Re-run the latest onboarding stack, which grants the full permission set; if you intentionally restrict permissions, add the reported one                |
    | **Required API not enabled** *(GCP)*                                                                                                                                         | A required Google Cloud service API is disabled on the project                                                                                  | Enable it, for example `gcloud services enable compute.googleapis.com --project <your-project>`                                                          |
    | **Subnet or VPC configuration issue** *(AWS bring-your-own-VPC)* — CIDR too small, missing tag, too few availability zones, no outbound egress, or too few free IP addresses | The provided VPC does not meet the BYOC network requirements                                                                                    | Adjust the VPC to satisfy the [network requirements](/products/bring-your-own-cloud/onboarding/customization-aws#configure-existing-vpc)                 |
    | **Insufficient service quota** *(AWS)*                                                                                                                                       | Your account's quota for a required resource is too low                                                                                         | Request a quota increase from your cloud provider; see [AWS service limits](/products/bring-your-own-cloud/reference/aws-service-limits)                 |
    | **Blocked by organization policy / SCP** *(AWS)*                                                                                                                             | An organization guardrail denies a required action for the account                                                                              | Work with your cloud administrator to allow the action for the BYOC account                                                                              |
  </Step>
</Steps>

<h3 id="create-clickhouse-service">
  Create Your First BYOC ClickHouse Service
</h3>

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.

<Image img="https://mintcdn.com/private-7c7dfe99-trino-dialect/wrAOYL3DquclMwbQ/images/cloud/reference/byoc-new-service-1.webp?fit=max&auto=format&n=wrAOYL3DquclMwbQ&q=85&s=e5862ee54425953f7f12af7c1daab7e8" size="md" alt="BYOC create new service" width="732" height="881" data-path="images/cloud/reference/byoc-new-service-1.webp" />

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.