AWS customized setup

[Edit this page](https://github.com/ClickHouse/clickhouse-docs/blob/main/docs/cloud/guides/infrastructure/01_deployment_options/byoc/03_onboarding/02_customization/01_aws.md)

## Customer-managed VPC (BYO-VPC) for AWS[​](#customer-managed-vpc-aws "Direct link to Customer-managed VPC (BYO-VPC) for AWS")

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.

Configure your existing VPC

### Configure your existing VPC[​](#configure-existing-vpc "Direct link to Configure your 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.

Configure S3 Gateway Endpoint

### Configure S3 Gateway Endpoint[​](#configure-s3-endpoint "Direct link to Configure S3 Gateway 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.

Ensure network connectivity

### Ensure network connectivity[​](#ensure-network-connectivity "Direct link to 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.

Configure your AWS account

### Configure your AWS account[​](#configure-aws-account "Direct link to Configure your 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.

#### Alternative Terraform module[​](#terraform-module-aws "Direct link to Alternative Terraform module")

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

```
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
}
```

Set up BYOC infrastructure

### Set up BYOC infrastructure[​](#set-up-byoc-infrastructure "Direct link to Set up BYOC infrastructure")

In the ClickHouse Cloud console, navigate to the [BYOC setup page](https://console.clickhouse.cloud/byocOnboarding) and configure the following:

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 **Setup Infrastructure** to begin provisioning.

Note

New region setup can take up to 40 minutes.

## Customer-managed IAM roles[​](#customer-managed-iam-roles "Direct link to Customer-managed IAM roles")

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.

References

Customer-managed IAM roles are in private preview. If you require this capability, contact ClickHouse Support to discuss your specific requirements and timeline.

When available, this feature will allow you to:

- Provide pre-configured IAM roles for ClickHouse Cloud to use
- Remove write permissions to IAM related permissions for `ClickHouseManagementRole` used for cross-account access
- Maintain full control over role permissions and trust relationships

For information about the IAM roles that ClickHouse Cloud creates by default, see the [BYOC Privilege Reference](/docs/cloud/reference/byoc/reference/privilege).

- [Customer-managed VPC (BYO-VPC) for AWS](#customer-managed-vpc-aws)
  - [Configure your existing VPC](#configure-existing-vpc)- [Configure S3 Gateway Endpoint](#configure-s3-endpoint)- [Ensure network connectivity](#ensure-network-connectivity)- [Configure your AWS account](#configure-aws-account)- [Set up BYOC infrastructure](#set-up-byoc-infrastructure)- [Customer-managed IAM roles](#customer-managed-iam-roles)

Was this page helpful?