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

# AWS customized setup

> Deploy ClickHouse BYOC into your existing AWS VPC

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

<h2 id="customer-managed-vpc-aws">
  Customer-managed VPC (BYO-VPC) for AWS
</h2>

If you prefer to use an existing VPC to deploy ClickHouse BYOC instead of having ClickHouse Cloud provision a new VPC, follow the steps below. This approach provides greater control over your network configuration and allows you to integrate ClickHouse BYOC into your existing network infrastructure.

<Steps>
  <Step title="Configure your existing VPC" id="configure-existing-vpc">
    1. Tag the VPC with `clickhouse-byoc="true"`.
    2. Allocate at least 3 private subnets across 3 different availability zones for ClickHouse Cloud to use.
    3. Ensure each subnet has a minimum CIDR range of `/23` (e.g., 10.0.0.0/23) to provide sufficient IP addresses for the ClickHouse deployment.
    4. Add the tag `kubernetes.io/role/internal-elb=1` and `clickhouse-byoc="true"` to each subnet to enable proper load balancer configuration.

    <Image img="https://mintcdn.com/private-7c7dfe99-detect-table-modification/m2_tVxhtEg5OHgtu/images/cloud/reference/byoc-subnet-1.webp?fit=max&auto=format&n=m2_tVxhtEg5OHgtu&q=85&s=9376b0d596d953fd3178b8348b27b852" size="lg" alt="BYOC VPC Subnet" width="1600" height="827" data-path="images/cloud/reference/byoc-subnet-1.webp" />

    <Image img="https://mintcdn.com/private-7c7dfe99-detect-table-modification/m2_tVxhtEg5OHgtu/images/cloud/reference/byoc-subnet-2.webp?fit=max&auto=format&n=m2_tVxhtEg5OHgtu&q=85&s=d79f2903034647bf5bf00062e7a21acd" size="lg" alt="BYOC VPC Subnet Tags" width="1600" height="406" data-path="images/cloud/reference/byoc-subnet-2.webp" />
  </Step>

  <Step title="Configure S3 Gateway Endpoint" id="configure-s3-endpoint">
    If your VPC doesn't already have an S3 Gateway Endpoint configured, you'll need to create one to enable secure, private communication between your VPC and Amazon S3. This endpoint allows your ClickHouse services to access S3 without going through the public internet. Please refer to the screenshot below for an example configuration.

    <Image img="https://mintcdn.com/private-7c7dfe99-detect-table-modification/m2_tVxhtEg5OHgtu/images/cloud/reference/byoc-s3-endpoint.webp?fit=max&auto=format&n=m2_tVxhtEg5OHgtu&q=85&s=17764eec817e4d6923d9515ef62d0ae3" size="lg" alt="BYOC S3 Endpoint" width="1711" height="1559" data-path="images/cloud/reference/byoc-s3-endpoint.webp" />
  </Step>

  <Step title="Ensure network connectivity" id="ensure-network-connectivity">
    **Outbound Internet Access**
    Your VPC must permit at least outbound internet access so that ClickHouse BYOC components can communicate with the Tailscale control plane. Tailscale is used to provide secure, zero-trust networking for private management operations. Initial registration and setup with Tailscale require public internet connectivity, which can be achieved either directly or via a NAT gateway. This connectivity is required to maintain both the privacy and security of your BYOC deployment.

    **DNS Resolution**
    Ensure your VPC has working DNS resolution and doesn't block, interfere with, or overwrite standard DNS names. ClickHouse BYOC relies on DNS to resolve Tailscale control servers and ClickHouse service endpoints. If DNS is unavailable or misconfigured, BYOC services may fail to connect or operate properly.
  </Step>

  <Step title="Configure your AWS account" id="configure-aws-account">
    The initial BYOC setup creates a privileged IAM role (`ClickHouseManagementRole`) that enables BYOC controllers from ClickHouse Cloud to manage your infrastructure. This can be performed using either a [CloudFormation template](https://s3.us-east-2.amazonaws.com/clickhouse-public-resources.clickhouse.cloud/cf-templates/byoc.yaml) or a [Terraform module](https://s3.us-east-2.amazonaws.com/clickhouse-public-resources.clickhouse.cloud/tf/byoc.tar.gz).

    When deploying for a `BYO-VPC` setup, set the `IncludeVPCWritePermissions` parameter to `false` to ensure ClickHouse Cloud doesn't receive permissions to modify your customer-managed VPC.

    <Note>
      Storage buckets, Kubernetes cluster, and compute resources required for running ClickHouse aren't included in this initial setup. They will be provisioned in a later step. While you control your VPC, ClickHouse Cloud still requires IAM permissions to create and manage the Kubernetes cluster, IAM roles for service accounts, S3 buckets, and other essential resources in your AWS account.
    </Note>

    <h4 id="terraform-module-aws">
      Alternative Terraform module
    </h4>

    If you prefer to use Terraform instead of CloudFormation, use the following module:

    ```hcl theme={null}
    module "clickhouse_onboarding" {
      source                     = "https://s3.us-east-2.amazonaws.com/clickhouse-public-resources.clickhouse.cloud/tf/byoc.tar.gz"
      byoc_env                   = "production"
      include_vpc_write_permissions = false
    }
    ```
  </Step>

  <Step title="Set up BYOC infrastructure" id="set-up-byoc-infrastructure">
    In the ClickHouse Cloud console, configure the following when setting up new infrastructure:

    1. Under **VPC configuration**, select **Use existing VPC**.
    2. Enter your **VPC ID** (e.g., `vpc-0bb751a5b888ad123`).
    3. Enter the **Private subnet IDs** for the 3 subnets you configured earlier.
    4. Optionally, enter **Public subnet IDs** if your setup requires public-facing load balancers.
    5. Click **Set up Infrastructure** to begin provisioning.

    <Image img="https://mintcdn.com/private-7c7dfe99-detect-table-modification/I0yKDIFW2QfsHJIe/images/cloud/reference/byoc-aws-existing-vpc-ui.webp?fit=max&auto=format&n=I0yKDIFW2QfsHJIe&q=85&s=9e01ca2b5adca2056c7b96c6e8576a78" size="lg" alt="ClickHouse Cloud BYOC setup UI with Use existing VPC selected" width="1392" height="1598" data-path="images/cloud/reference/byoc-aws-existing-vpc-ui.webp" />

    <Note>
      New region setup can take up to 40 minutes.
    </Note>
  </Step>
</Steps>

<h2 id="customer-managed-iam-roles">
  Customer-managed IAM roles
</h2>

For organizations with advanced security requirements or strict compliance policies, you can provide your own IAM roles instead of having ClickHouse Cloud create them. This approach gives you complete control over IAM permissions and allows you to enforce your organization's security policies.

<Info>
  Customer-managed IAM roles are in private preview. Contact ClickHouse Support to enable this capability for your organization before following the steps below.
</Info>

With customer-managed IAM roles, you:

* Pre-create the per-infrastructure IAM roles that ClickHouse Cloud would otherwise create
* Remove IAM write permissions from the `ClickHouseManagementRole` used for cross-account access
* Maintain full control over role permissions and trust relationships

<Steps>
  <Step title="Configure the management role without IAM write permissions" id="byo-iam-management-role">
    When performing the [initial BYOC setup](/cloud/reference/byoc/onboarding/standard), disable IAM write permissions on the management role. With the CloudFormation template, set the `IncludeIAMWritePermissions` parameter to `false`. With the Terraform 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>"
      include_iam_write_permissions = false
    }
    ```

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

  <Step title="Create the per-infrastructure IAM roles" id="byo-iam-per-infra-roles">
    Before each BYOC infrastructure is provisioned, create its required IAM roles (EKS pod identity roles, the ClickHouse S3 access role, and the data-plane management role) with the [terraform-byoc-onboarding](https://github.com/ClickHouse/terraform-byoc-onboarding) per-infra module:

    ```hcl theme={null}
    module "clickhouse_per_infra_iam" {
      source = "github.com/ClickHouse/terraform-byoc-onboarding.git//modules/aws-per-infra-iam?ref=<version>"

      spoken_name = "<spoken-name-provided-by-clickhouse>"
      region      = "<aws-region-of-the-infrastructure>"
      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.
  </Step>

  <Step title="Keep the per-infrastructure roles up to date" id="byo-iam-keep-up-to-date">
    <Warning>
      ClickHouse periodically adds roles and permissions required by new platform capabilities. When ClickHouse notifies you of an update, re-apply the per-infra module at the latest release — running an outdated version can cause provisioning and upgrades of your BYOC infrastructure to fail.
    </Warning>
  </Step>
</Steps>

For information about the IAM roles that ClickHouse Cloud creates by default, see the [BYOC Privilege Reference](/products/bring-your-own-cloud/reference/privilege).