Skip to main content

​
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.
1

Configure your existing VPC

  1. Tag the VPC with clickhouse-byoc="true".
  2. Allocate exactly 3 private subnets across 3 different availability zones for ClickHouse Cloud to use.
  3. Ensure each subnet has a minimum CIDR range of /25 (e.g., 10.0.0.0/25). A /25 supports roughly 10 ClickHouse server nodes per availability zone; /24 is recommended for most deployments, and larger subnets for deployments you expect to grow. Pod IP addresses are allocated from the subnet itself, so every replica consumes subnet addresses.
  4. Add the tag kubernetes.io/role/internal-elb=1 and clickhouse-byoc="true" to each subnet to enable proper load balancer configuration.
2

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

Ensure network connectivity

Outbound Internet Access Your VPC must permit at least outbound internet access, either directly or via a NAT gateway. Two things depend on it:
  • Tailscale. ClickHouse BYOC components register with the Tailscale control plane, which provides secure, zero-trust networking for private management operations without requiring inbound public access. Initial registration and setup require public internet connectivity.
  • Container images. Some images the deployment runs are not mirrored into the BYOC registry, including community images, and are pulled from their upstream registries.
A VPC with no outbound path will not finish provisioning. There is no single published endpoint list; if your network policy requires an explicit inventory, contact support to review your setup.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.
4

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 or a Terraform module (see below).
The IAM role name is a hard requirement. The role must keep its default name ClickHouseManagementRole — no prefixes, suffixes, or renaming to satisfy an organizational naming convention — unless ClickHouse has explicitly agreed to a different name beforehand (the Terraform role_name input must only be changed in coordination with ClickHouse). A renamed role applies successfully but provisioning then fails because ClickHouse cannot assume the expected role. More generally, do not change anything in the provided template or module without ClickHouse’s explicit approval; supported customizations are exposed as parameters.
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.
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.

​
Terraform module

If you prefer to use Terraform instead of CloudFormation, 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 external_id value is generated by the ClickHouse Cloud console and is shared by all BYOC infrastructures on the same AWS account. See AWS external ID for details, including the legacy emptyid placeholder.
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.
5

Set up BYOC infrastructure

When you click Set up Infrastructure, ClickHouse Cloud automatically runs pre-flight validation before provisioning. If your customized VPC or account doesn’t meet the requirements, setup is halted with the specific issues to fix.
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.
New region setup can take up to 40 minutes.

​
Shared subnets from another account (AWS RAM)

You can run BYOC in a spoke account on subnets shared from a hub account with AWS Resource Access Manager (RAM), which lets you keep networking centralized. The setup is the same as above, with two differences that follow from how RAM shares behave:
  • Apply the tags from the spoke account. RAM-shared resources have a per-account tag view, so tags applied in the hub account are not visible to the spoke. Apply clickhouse-byoc="true" to the VPC, and kubernetes.io/role/internal-elb=1 together with clickhouse-byoc="true" to each shared subnet, from the spoke account. Without this, pre-flight validation reports missing tags and provisioning fails.
  • Routing stays with the hub account. Route tables for shared subnets remain owned by the hub account, which is therefore responsible for NAT and egress routing, and for the S3 gateway endpoint since that is a VPC-level resource. Confirm the shared subnets still satisfy the outbound connectivity requirement above.
Everything else is unchanged: three private subnets across three availability zones, a minimum /25 CIDR per subnet, and the ClickHouseManagementRole setup in the spoke account where the BYOC infrastructure runs.

​
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.
Customer-managed IAM roles are in private preview. Contact ClickHouse Support to enable this capability for your organization before following the steps below.
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
Both modules below take the external_id generated by the ClickHouse Cloud console; all BYOC infrastructures on the same AWS account share the same external ID. See AWS external ID for details, including the legacy emptyid placeholder.
1

Configure the management role without IAM write permissions

When performing the initial BYOC setup, disable IAM write permissions on the management role. With the CloudFormation template, set the IncludeIAMWritePermissions parameter to false. With the Terraform module:
Replace <version> with the latest tag from the module’s releases page — always use the latest release.
2

Create the per-infrastructure IAM 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 per-infra module:
Replace <version> with the latest tag from the module’s releases page — always use the latest release.
3

Keep the per-infrastructure roles up to date

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.
For information about the IAM roles that ClickHouse Cloud creates by default, see the BYOC Privilege Reference.
Last modified on September 15, 2026