Skip to main content
Skip to main content
Edit this page

AWS customized setup

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​

  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​

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​

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​

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.

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​

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​

In the ClickHouse Cloud console, navigate to the BYOC setup page 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​

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.