Architecture

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

## Key concepts[​](#key-concepts "Direct link to Key concepts")

The diagram below illustrates how ClickHouse Cloud organizations, cloud accounts, and BYOC infrastructure relate to each other.

BYOC organization hierarchy showing the relationship between organizations, cloud accounts, regions, and BYOC infrastructureClickHouse Cloud OrgClickHouse BYOC OrgUsersAWS Account 1123456789012AWS Account 2987654321098GCP Project 1my-gcp-projectus-east-1us-west-2us-west-2europe-west1BYOC Infra 1VPC | K8s Cluster | S3 BucketsClickHouse Service 1ClickHouse Service 2ClickHouse Service 3BYOC Infra 2VPC | K8s Cluster | S3 BucketsClickHouse Service 4ClickHouse Service 5BYOC Infra 3VPC | K8s Cluster | S3 BucketsClickHouse Service 6BYOC Infra 4VPC | GKE Cluster | GCS BucketsClickHouse Service 7Cloud Account / ProjectRegionBYOC InfrastructureClickHouse ServiceOrganization
  

- **ClickHouse Cloud organization:** The top-level entity in ClickHouse Cloud that manages users, billing, and non-BYOC ClickHouse services. Users within an organization can access both standard Cloud services and BYOC services.
- **ClickHouse BYOC organization:** A separate organization dedicated to managing BYOC deployments. It shares users with the Cloud organization but is linked to one or more cloud accounts where BYOC infrastructure is deployed.
- **Cloud account / project:** The customer-owned AWS account or GCP project where BYOC infrastructure is provisioned. Each account or project can host BYOC deployments in one or more regions. A dedicated account or project per BYOC deployment is recommended for isolation.
- **BYOC infrastructure:** The set of cloud resources deployed within a specific region of a cloud account, including a VPC, Kubernetes cluster (EKS/GKE), storage buckets, IAM roles, and supporting services. A single cloud account can contain multiple BYOC infrastructures across different regions.
- **ClickHouse Service:** An individual ClickHouse cluster running within a BYOC infrastructure. Multiple services can run within the same BYOC infrastructure.

Note

Mixing of AWS accounts and GCP projects under the same organization is only possible for customers who are not set up through a [cloud service provider marketplace](/docs/cloud/marketplace/marketplace-billing).

## Glossary[​](#glossary "Direct link to Glossary")

- **ClickHouse VPC:** The VPC owned by ClickHouse Cloud.
- **Customer BYOC VPC:** The VPC, owned by the customer's cloud account, is provisioned and managed by ClickHouse Cloud and dedicated to a ClickHouse Cloud BYOC deployment.
- **Customer VPC:** Other VPCs owned by the customer cloud account used for applications that need to connect to the Customer BYOC VPC.

## Technical architecture[​](#architecture "Direct link to Technical architecture")

BYOC separates the **ClickHouse control plane**, which runs in the ClickHouse VPC, from the **data plane**, which runs entirely in your cloud account. The ClickHouse VPC hosts the ClickHouse Cloud Console, authentication, user management, APIs, billing, infrastructure management components such as the BYOC controller, and alerting/incident tooling. These services orchestrate and monitor your deployment, but they don't store your data.

In your **Customer BYOC VPC**, ClickHouse provisions a Kubernetes cluster (for example, Amazon EKS) that runs the ClickHouse data plane. As shown in the diagram, this includes the ClickHouse cluster itself, the ClickHouse operator, and supporting services such as ingress, DNS, certificate management, state exporters, and scrapers. A dedicated monitoring stack (Prometheus, Grafana, AlertManager, and Thanos) also runs within your VPC, ensuring that metrics and alerts originate from and remain in your environment.

  
  

The main cloud resources ClickHouse Cloud will deploy in your account are:

- **VPC:** A Virtual Private Cloud dedicated to your ClickHouse deployment. This can be managed either by ClickHouse or by you, the customer, and is typically peered with your application VPCs.
- **IAM roles and policies:** Roles and permissions necessary for Kubernetes, ClickHouse services, and the monitoring stack. These can be provisioned by ClickHouse or supplied by the customer.
- **Storage buckets:** Used for storing data parts, backups, and (optionally) long-term metrics and log archives.
- **Kubernetes cluster:** This can be Amazon EKS, Google GKE, or Azure AKS, depending on your cloud provider, and hosts the ClickHouse servers and supporting services shown in the architecture diagram.

By default, ClickHouse Cloud provisions a new, dedicated VPC and sets up the necessary IAM roles to ensure secure operation of Kubernetes services. For organizations with advanced networking or security needs, there is also the option to manage the VPC and IAM roles independently. This approach allows for greater customization of network configurations and more precise control over permissions. However, choosing to self-manage these resources will increase your operational responsibilities.

### Data Storage[​](#data-storage "Direct link to Data Storage")

All ClickHouse data, backups, and observability data stay in your cloud account. Data parts and backups are stored in your object storage (for example, Amazon S3), while logs are stored on the storage volumes attached to your ClickHouse nodes. In a future update, logs will be written to LogHouse, a ClickHouse-based logging service that also runs inside your BYOC VPC. Metrics can be stored locally or in an independent bucket in your BYOC VPC for long-term retention. Control-plane connectivity between the ClickHouse VPC and your BYOC VPC is provided over a secure, tightly scoped channel (for example, via Tailscale as shown in the diagram); this is used only for management operations, not for query traffic.

### Control Plane communication[​](#control-plane-communication "Direct link to Control Plane communication")

The ClickHouse VPC communicates with your BYOC VPC over HTTPS (port 443) for service management operations including configuration changes, health checks, and deployment commands. This traffic carries only control plane data for orchestration. Critical telemetry and alerts flow from your BYOC VPC to the ClickHouse VPC to enable resource utilization and health monitoring.

## Key Requirements for BYOC[​](#key-requirements "Direct link to Key Requirements for BYOC")

The BYOC deployment model requires two essential components to ensure reliable operations, ease of maintenance, and security:

### Cross-account IAM permissions[​](#cross-account-iam-permissions "Direct link to Cross-account IAM permissions")

ClickHouse Cloud needs cross-account IAM permissions to provision and manage resources within your cloud account. This enables ClickHouse to:

- **Provision infrastructure**: Create and configure VPCs, subnets, security groups, and other networking components
- **Manage Kubernetes clusters**: Deploy and maintain EKS/GKE clusters, node groups, and cluster components
- **Create storage resources**: Provision S3 buckets or equivalent object storage for data and backups
- **Manage IAM roles**: Create and configure IAM roles for Kubernetes service accounts and supporting services
- **Operate supporting services**: Deploy and manage monitoring stacks, ingress controllers, and other infrastructure components

These permissions are granted through a cross-account IAM role (AWS) or service account (GCP) that you create during the initial onboarding process. The role follows the principle of least privilege, with permissions scoped to only what's necessary for BYOC operations.

For detailed information about the specific permissions required, see the [BYOC Privilege Reference](/docs/cloud/reference/byoc/reference/privilege).

### Tailscale Private Network Connection[​](#tailscale-private-network "Direct link to Tailscale Private Network Connection")