ClickHouse Cloud BYOC: what are the exact onboarding steps and what gets provisioned in our AWS account?

ClickHouse Cloud BYOC (bring your own cloud) lets you run fully managed ClickHouse in your own AWS account, with ClickHouse operating the control plane and you retaining ownership of the data plane resources. To make this work safely, the onboarding flow is structured, opinionated, and repeatable: you connect an AWS account via an IAM role, ClickHouse deploys a standard set of VPC resources and data plane components, and then you can start creating services in that BYOC environment.

Quick Answer: Onboarding to ClickHouse Cloud BYOC on AWS involves four main phases: preparing your AWS account, creating a BYOC environment in the ClickHouse Cloud console, establishing a cross-account IAM role and network baseline, and validating provisioning. ClickHouse then deploys and manages a dedicated VPC, subnets, security groups, ECS/EKS or equivalent compute, load balancers, S3 buckets, KMS keys (if configured), and supporting monitoring/backup resources inside your AWS account.

Why This Matters

BYOC changes the trust and operational model compared to a traditional fully hosted SaaS database. Your security team cares about who owns the VPC and the S3 buckets, your finance team wants billing visibility in your own AWS bill, and your SRE team needs to understand what exactly shows up in your account when you “turn on” ClickHouse Cloud BYOC. Having a clear picture of the onboarding flow and provisioned resources avoids surprises during security reviews, helps you line up prerequisites (VPC constraints, SCPs, guardrails), and shortens the path to running millisecond-latency analytics and AI workloads at petabyte scale, fully inside your cloud boundary.

Key Benefits:

• Security & data ownership: All data plane resources (compute, storage, network) live in your AWS account, under your policies, while ClickHouse runs the control plane and operations.
• Network and compliance control: You decide region, VPC guardrails, private connectivity, and can align with existing controls like SCPs, AWS Config, and CloudTrail.
• Cost visibility with managed operations: You see the raw AWS usage (EC2/EKS/ECS, S3, networking) on your bill, while ClickHouse handles cluster lifecycle, scaling, and reliability.

Core Concepts & Key Points

Concept	Definition	Why it's important
BYOC environment	A logical ClickHouse Cloud environment mapped to one or more AWS accounts and regions where data plane resources are created.	Defines the blast radius and where ClickHouse can provision and manage resources in your AWS.
Control plane vs. data plane	Control plane is ClickHouse-operated (outside your AWS account) for orchestration; data plane is deployed into your AWS account (compute, storage, networking).	Helps security teams understand that ClickHouse has operational access, but the data and infrastructure live inside your boundary.
Cross-account IAM role	An IAM role in your account that ClickHouse assumes, with a trust policy and permissions policy granting the required actions.	This is the primary mechanism ClickHouse uses to provision and manage VPC, subnets, compute, and storage safely.

How It Works (Step-by-Step)

At a high level, the onboarding flow looks like this:

1. Prepare your AWS account and guardrails.
2. Create a BYOC environment in ClickHouse Cloud.
3. Establish the cross-account IAM role and allow provisioning.
4. Validate resources and start creating services.

Below, I’ll walk through what happens in each step and what gets created in your AWS account.

1. Prepare Your AWS Account

This is mostly work on your side, typically owned by a platform, SRE, or cloud foundation team.

Key tasks:

• Choose the AWS account and region(s):

  • Decide which dedicated account will host ClickHouse BYOC (often a shared “data platform” or “analytics” account).
  • Confirm that the target region(s) match your latency and compliance needs.

• Align with security policies and SCPs:

  • Review existing Service Control Policies to ensure they don’t block actions ClickHouse needs (VPC, subnet, EC2/EKS/ECS, S3, IAM, KMS, ELB, CloudWatch, etc.).
  • If you restrict resource creation to specific naming patterns or tags, decide how you’ll validate that ClickHouse’s provisioned resources comply.

• Networking constraints:

  • Decide whether ClickHouse will run in a new dedicated VPC or in a pre-approved address range for your organization. BYOC typically creates its own VPC to keep blast radius and routing clear.
  • If you plan to use PrivateLink, VPC peering, or a transit gateway to connect from your application VPCs, reserve CIDR blocks and routing rules accordingly.

• Security/compliance baselines:

  • Decide on the encryption posture: default AWS-managed KMS vs. customer-managed KMS keys.
  • Ensure logging frameworks (CloudTrail, AWS Config) are enabled so provisioning can be audited.

Pro tip: Have your cloud security lead in the room for this phase. It speeds up sign-off when you later present what ClickHouse will actually create in the account.

2. Create a BYOC Environment in ClickHouse Cloud

Next, you configure BYOC from the ClickHouse Cloud console.

Steps in the console:

1. Log in to ClickHouse Cloud and navigate to the Environments or BYOC section (label can vary as the UI evolves).
2. Create a new environment and select AWS BYOC:
   • Choose the AWS region (e.g., us-east-1, eu-west-1).
   • Optionally specify environment labels (e.g., prod-analytics, compliance-region-eu).
3. The console will generate:
   • An AWS Account ID representing the ClickHouse control plane account.
   • An external ID or similar token for IAM role trust, used to protect against confused-deputy attacks.
   • A CloudFormation template or Terraform snippet describing the IAM role and any bootstrap resources required in your account.

At this point, ClickHouse Cloud is waiting for you to set up the cross-account IAM role on the AWS side.

3. Establish the Cross-Account IAM Role and Bootstrap Networking

Now you give ClickHouse the ability to manage resources in your account.

3.1. Create the IAM role

You typically do this via CloudFormation or Terraform provided by ClickHouse.

• Trust relationship:
  The role must trust the ClickHouse control plane AWS account and include the external ID, for example (illustrative):

  {
    "Version": "2012-10-17",
    "Statement": [
      {
        "Effect": "Allow",
        "Principal": { "AWS": "arn:aws:iam::CLICKHOUSE_CONTROL_PLANE_ACCOUNT_ID:root" },
        "Action": "sts:AssumeRole",
        "Condition": {
          "StringEquals": {
            "sts:ExternalId": "CLICKHOUSE_GENERATED_EXTERNAL_ID"
          }
        }
      }
    ]
  }
  

• Permissions policy:
  A managed or inline policy grants ClickHouse the ability to create and manage the required resources, typically including:

  • ec2:*Vpc*, ec2:*Subnet*, ec2:*Route*, ec2:*SecurityGroup*, ec2:*NetworkInterface*, etc.
  • elasticloadbalancing:* for ALBs/NLBs.
  • ecs:* or eks:* and autoscaling:* for compute orchestration.
  • s3:* on specific BYOC buckets for data and backups.
  • kms:Encrypt/Decrypt/GenerateDataKey on relevant keys (if using CMKs).
  • logs:* and cloudwatch:* for metrics and logging needed to operate the cluster.
  • iam:PassRole for roles ClickHouse needs to attach to compute resources.

  In practice, ClickHouse documentation provides a tightly scoped policy; you should use that as the source of truth.

• Tagging and constraints:
  If your org requires mandatory tags, apply them at the role and CloudFormation stack level so all downstream resources inherit them.

3.2. Connect the role back to ClickHouse Cloud

• In the ClickHouse Cloud console, paste the ARN of the new IAM role or confirm via an automated handshake.
• ClickHouse invokes sts:AssumeRole with the external ID to confirm it can assume the role.
• Once validated, the console marks the environment as ready to provision.

4. What Gets Provisioned in Your AWS Account

After onboarding, when you create a ClickHouse Cloud BYOC service in that environment, ClickHouse provisions (and continually manages) a standard set of resources. Exact details evolve over time, but the pattern looks like this:

4.1. Networking: VPC, subnets, security

ClickHouse typically creates a dedicated, isolated network domain for the BYOC environment:

• VPC:

  • A new VPC with a CIDR block you either accept by default or pre-approve during setup.
  • Configured with route tables and gateways appropriate for your connectivity model:
    • Internet gateway and NAT gateways if public egress is needed.
    • Or strictly private routing if you prefer outbound through a central egress VPC.

• Subnets:

  • Multi-AZ private subnets (e.g., one per availability zone) for ClickHouse compute nodes and internal services.
  • Optionally, limited public subnets for load balancers, depending on whether you expose endpoints publicly or via PrivateLink.

• Security groups:

  • Groups for ClickHouse nodes, load balancers, and any supporting agents.
  • Inbound rules typically restrict the database ports to:
    • Load balancers or PrivateLink endpoints.
    • Optional jump-hosts or bastions if you use them.
  • Outbound rules allow necessary connections for:
    • S3 (data and backups).
    • Control plane coordination channels.
    • Observability endpoints if you export metrics/logs externally.

4.2. Compute: ClickHouse clusters and orchestration

To serve millisecond-latency queries over billions of rows, ClickHouse runs multiple data plane components:

• Compute layer (EC2/ECS/EKS):

  • Worker nodes running ClickHouse server processes, often orchestrated via ECS or EKS plus an autoscaling group.
  • Placement across multiple AZs for resiliency.
  • Instance families tuned for OLAP workloads: high CPU and memory, strong network throughput.

• Autoscaling & lifecycle:

  • Auto Scaling Groups or node groups that ClickHouse Cloud scales up/down based on:
    • Query load (via metrics from ClickHouse’s own system.query_log and internal metrics).
    • Ingestion pressure (batches, merge backlog).
  • Health checks tied to both AWS (EC2/ECS/EKS) and ClickHouse-native health indicators.

4.3. Storage: S3 buckets, volumes, backups

ClickHouse’s columnar format and compression are central to the cost profile. In BYOC, the underlying storage is yours:

• S3 buckets:

  • Data storage buckets where MergeTree parts and related metadata are persisted (in cloud-native storage mode).
  • Separate buckets or prefixes for:
    • Primary data.
    • Backups / snapshots.
    • Logs or diagnostic artifacts (if configured).
  • You can see these in your AWS console and apply your own lifecycle policies, subject to ClickHouse guidance.

• Block storage (EBS):

  • EBS volumes for local caches, temporary data, and ephemeral working directories for merge and mutation operations.
  • Types and sizes tuned for throughput and latency expected by ClickHouse’s vectorized engine.

• Backups and retention:

  • Scheduled backups configured from the ClickHouse Cloud console translate into:
    • S3 snapshots or incremental backups stored in your bucket.
    • Associated metadata managed by the control plane so you can restore via the console.
  • You can inspect these via the AWS S3 console and CloudTrail.

4.4. Security and observability: KMS, logging, metrics

To keep compliance teams happy while still operating at OLAP speed, BYOC leverages AWS security primitives:

• KMS keys:

  • AWS-managed keys by default.
  • Optionally, customer-managed keys for S3, EBS, and secrets:
    • ClickHouse’s IAM role must have kms:Encrypt, kms:Decrypt, kms:GenerateDataKey, and kms:DescribeKey.

• Secrets and configuration:

  • IAM roles attached to compute nodes for access to S3 and KMS.
  • Optionally, AWS Secrets Manager or SSM Parameter Store for additional secrets, depending on your integration model.

• Logging and metrics:

  • CloudWatch log groups for:
    • ClickHouse server logs and system logs.
    • Orchestration and agent logs.
  • CloudWatch metrics for:
    • Compute utilization.
    • Network throughput.
    • Storage usage and error rates.

From an operator’s perspective, you can combine AWS-native metrics with ClickHouse’s own system tables (system.query_log, system.parts, system.merges) for a complete picture of performance and health.

5. Validation and First Service Creation

Once the environment is set up and resources begin to appear:

1. Validate resource footprint:

   • In AWS:
     • Confirm the new VPC, subnets, security groups, and load balancers exist and are tagged as expected.
     • Inspect S3 buckets, KMS key usage, and CloudWatch log groups.
   • In ClickHouse Cloud:
     • Check that the BYOC environment status is “Ready” or equivalent.

2. Create your first ClickHouse service in BYOC:

   • In the ClickHouse Cloud console, create a service (e.g., prod-logs, realtime-analytics, or vector-search-ai).
   • Choose:
     • Service size and storage profile.
     • Backup policy (frequency and retention).
     • Connectivity options (public, PrivateLink, or internal-only).

3. Run initial validation queries:

   • Connect via the SQL console or your preferred client.
   • Verify core performance and observability:

     -- Check query log is enabled and receiving entries
     SELECT
         event_time,
         query_id,
         query_kind,
         read_rows,
         query_duration_ms
     FROM system.query_log
     WHERE event_time > now() - INTERVAL 10 MINUTE
     ORDER BY event_time DESC
     LIMIT 10;
     
     -- Inspect parts to confirm healthy ingestion patterns
     SELECT
         table,
         partition,
         count() AS parts,
         sum(rows) AS total_rows
     FROM system.parts
     WHERE active
     GROUP BY table, partition
     ORDER BY parts DESC
     LIMIT 10;
     

   • Use these to ensure merges are healthy and queries return with the millisecond latency you’re targeting.

Common Mistakes to Avoid

• Under-scoped IAM permissions:
  If the IAM role is missing actions (e.g., for certain EC2, S3, or KMS operations), provisioning will fail or partially succeed, leading to confusing errors. Always start from the policy documented by ClickHouse and let security review that specific list rather than building a custom one from memory.

• Networking assumptions that block connectivity:
  Overly restrictive NACLs, misconfigured route tables, or denied egress can prevent ClickHouse from coordinating with its control plane or S3. Validate that:

  • The BYOC VPC has the necessary outbound connectivity.
  • Your application VPCs have a clear path (Peering, PrivateLink, or TGW) to the ClickHouse endpoints.

Real-World Example

When we migrated our observability backend to ClickHouse Cloud BYOC, our security team insisted on a dedicated AWS account and customer-managed KMS keys. During onboarding, we:

1. Created a new “analytics-prod” account with CloudTrail and AWS Config enabled.
2. Used the ClickHouse-provided CloudFormation to create an IAM role with the exact trust relationship and permissions they required.
3. Let ClickHouse provision a dedicated VPC and subnets across three AZs, with S3 buckets named and tagged according to our standards.
4. Connected our existing observability stack via VPC peering, then validated ingestion and query performance with system.query_log and system.parts.

The entire process—from initial IAM role creation to running millisecond queries over live metrics—took a few hours of coordinated work, and every resource that appeared in our account was auditable via CloudTrail and matched our tagging policies.

Pro Tip: Before you hand the IAM role ARN to ClickHouse Cloud, run an internal review that includes security, networking, and finance. Share a short one-pager summarizing exactly what ClickHouse will create (VPC, subnets, load balancers, compute, S3 buckets, KMS usage); it dramatically reduces back-and-forth once provisioning starts.

Summary

ClickHouse Cloud BYOC on AWS gives you a managed, high‑performance OLAP database while keeping all data plane resources—VPC, compute, storage—inside your AWS account. Onboarding is structured into four phases: prepare your AWS account and policies, create the BYOC environment in ClickHouse Cloud, establish a cross-account IAM role with the required permissions, and then let ClickHouse provision and operate the VPC, subnets, load balancers, compute clusters, S3 buckets, KMS integrations, and observability pipelines needed to run ClickHouse at scale. Understanding these steps and the resulting resource footprint sets you up to pass security review, control costs, and quickly start serving real-time analytics and AI workloads with millisecond query latency.

Next Step

Get Started