ClickHouse - Control Plane

Overview

ClickHouse is a high-performance, column-oriented analytical database designed for real-time querying and data warehousing at scale. This template deploys ClickHouse in either single-node or cluster mode depending on how locations are configured, backed by object storage (AWS S3, GCS, Azure Blob Storage, or Hetzner Object Storage) for long-term scalable storage and a local volume for fast read caching.

Deployment Modes

Mode	Configuration	Keeper
Single-node	1 location, `replicas: 1`	Not deployed
Single-shard cluster	1 location, `replicas` > 1	Deployed
Multi-shard cluster	3+ locations	Deployed across first 3 locations

2 locations is not supported — use 1 (single-node or single-shard) or 3+.

What Gets Created

GVC — A dedicated GVC across the specified locations.
Stateful ClickHouse Server Workload — The main analytical database workload with configurable replicas per location.
Stateful ClickHouse Keeper Workload (cluster mode only) — The coordination service workload (1 replica per location, always 3 total).
Volume Sets — Persistent storage for the server (metadata, state, and system files), and for Keeper in cluster mode.
Secrets — A database config secret with credentials and cluster name, startup script secrets for ClickHouse Server and Keeper, and a storage configuration secret for the selected provider (AWS S3, GCS, Azure Blob Storage, or Hetzner Object Storage).
Identity & Policy — An identity bound to the workloads with reveal access to the template secrets, and cloud access for reading and writing to object storage.

Architecture

In cluster mode, each location maps to one ClickHouse Keeper replica, forming a 3-node quorum for distributed coordination. ClickHouse Server replicas communicate with Keeper using Control Plane’s internal DNS. In single-node mode, no Keeper is deployed. Primary data is stored in the configured object storage bucket in all modes; a local scratch volume serves as a fast read cache.

To minimize network egress costs, deploy all locations in the same cloud provider and keep your object storage bucket in the same region(s). Using 1 replica per location for the ClickHouse server workload is sufficient for most cluster deployments.

Prerequisites

Before installing this template, configure object storage access for your chosen provider.

AWS S3

Create an S3 bucket. Note the bucket name and region — you will set these as aws.bucket and aws.region in your values file.
If you do not have a Control Plane Cloud Account set up, follow the Create a Cloud Account guide. Set aws.cloudAccountName to the name of your Cloud Account.
Create an IAM policy with the following JSON, replacing YOUR_BUCKET_NAME:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:GetObject",
                "s3:PutObject",
                "s3:DeleteObject",
                "s3:ListBucket",
                "s3:GetObjectVersion",
                "s3:DeleteObjectVersion"
            ],
            "Resource": [
                "arn:aws:s3:::YOUR_BUCKET_NAME",
                "arn:aws:s3:::YOUR_BUCKET_NAME/*"
            ]
        }
    ]
}

Set aws.policyName in your values file to the name of the policy created in step 3.

GCS

ClickHouse requires S3-compatible HMAC authentication for GCS. A Control Plane Cloud Account is not required.

Create a GCS bucket. Set gcp.bucket in your values file to the bucket name.
In the GCP console, navigate to Settings > Interoperability and click Create a key for a service account.
Click Create new account, name your service account, and assign the Storage Object Admin role under Permissions.
Copy the generated HMAC key and set gcp.accessKeyId and gcp.secretAccessKey in your values file.

Alternatively, use the gcloud CLI:

gcloud config set project YOUR_PROJECT_ID

gcloud storage buckets create gs://YOUR_BUCKET_NAME --location=NAM4

gcloud iam service-accounts create clickhouse-storage

gcloud projects add-iam-policy-binding $(gcloud config get-value project) \
  --member="serviceAccount:clickhouse-storage@$(gcloud config get-value project).iam.gserviceaccount.com" \
  --role="roles/storage.objectAdmin"

gsutil hmac create clickhouse-storage@$(gcloud config get-value project).iam.gserviceaccount.com

Azure Blob Storage

ClickHouse uses Azure’s native Blob Storage SDK. A Control Plane Cloud Account is not required — authentication uses a storage account access key directly.

In the Azure Portal, go to Storage accounts → Create. Use Standard performance, LRS redundancy, and leave hierarchical namespace off.
Inside the storage account, go to Containers → + Container and create a container (e.g. clickhouse-data). Set access level to Private.
Go to Security + networking → Access keys and copy either key1 or key2.
Set the following in your values file:
- azure.storageAccount — the storage account name
- azure.container — the container name from step 2
- azure.accountKey — the access key from step 3

Alternatively, use the Azure CLI:

az storage account create \
  --name YOUR_STORAGE_ACCOUNT \
  --resource-group YOUR_RESOURCE_GROUP \
  --sku Standard_LRS

az storage container create \
  --name clickhouse-data \
  --account-name YOUR_STORAGE_ACCOUNT

az storage account keys list \
  --account-name YOUR_STORAGE_ACCOUNT \
  --resource-group YOUR_RESOURCE_GROUP \
  --query "[0].value" -o tsv

Hetzner Object Storage

Hetzner Object Storage is S3-compatible. A Control Plane Cloud Account is not required — authentication uses an access key pair. Available regions:

Region	Location
`nbg1`	Nuremberg, Germany
`hel1`	Helsinki, Finland
`fsn1`	Falkenstein, Germany

In the Hetzner Cloud console, go to Object Storage and create a bucket. Note the bucket name and region.
Go to Security → S3 Credentials and click Generate credentials. Save the access key and secret key immediately — the secret will not be shown again.
Set the following in your values file:
- hetzner.bucket — the bucket name
- hetzner.region — the region code (e.g. nbg1)
- hetzner.accessKeyId — the access key from step 2
- hetzner.secretAccessKey — the secret key from step 2

Installation

To install, follow the instructions for your preferred method:

UI

Browse, install, and manage templates visually

CLI

Manage templates from your terminal

Terraform

Declare templates in your Terraform configurations

Pulumi

Declare templates in your Pulumi programs

Configuration

The default values.yaml for this template:

gvc:
  name: clickhouse-gvc
  # Single-node mode: exactly 1 location with replicas: 1 — no Keeper, uses S3/GCS for storage
  # Single-shard cluster: 1 location with replicas > 1 — Keeper required
  # Multi-shard cluster: 3 or more locations — Keeper required
  # Note: 2 locations is not supported
  locations:
    - name: aws-us-east-2
      replicas: 1
    - name: aws-us-west-2
      replicas: 1
    - name: aws-us-east-1
      replicas: 1

provider: aws # Options: aws, gcp, azure, or hetzner

aws: # If enabled, all fields below are required - See prerequisites for guidance
  bucket: clickhouse-s3-bucket # Name of your S3 bucket
  region: us-east-1 # Region of your S3 bucket
  cloudAccountName: clickhouse-s3-cloudaccount # Name of your Cloud Account
  policyName: clickhouse-s3-policy # Name of your pre-created policy to allow access to the S3 bucket

gcp: # If enabled, all fields below are required - See prerequisites for guidance
  bucket: clickhouse-gcs-bucket # Name of your GCS bucket
  accessKeyId: gcs-access-key-id # Access key ID for your GCS service account
  secretAccessKey: gcs-secret-access-key # Secret access key for your GCS service account

azure: # If enabled, all fields below are required - See prerequisites for guidance
  storageAccount: myclickhousestorage # Name of your Azure Storage Account
  container: clickhouse-data # Name of your Blob Storage container
  accountKey: my-azure-storage-account-key # Access key for your Azure Storage Account

hetzner: # If enabled, all fields below are required - See prerequisites for guidance
  bucket: clickhouse-hetzner-bucket # Name of your Hetzner Object Storage bucket
  region: nbg1 # Region of your bucket. Options: nbg1, hel1, fsn1
  accessKeyId: my-hetzner-access-key-id # Access key ID for your Hetzner Object Storage
  secretAccessKey: my-hetzner-secret-access-key # Secret access key for your Hetzner Object Storage

clusterName: my_cluster # Used in cluster mode only

database: # Automatically create a database on initialization using the default user
  name: mydatabase
  password: mypassword

volumeset:
  server:
    capacity: 10 # initial capacity in GiB (minimum is 10)
  keeper:
    capacity: 10 # initial capacity in GiB (minimum is 10) - cluster mode only

server:
  image: clickhouse/clickhouse-server:25.10
  resources:
    cpu: 2
    memory: 2Gi
  internal_access:
    type: same-gvc # options: same-gvc, same-org, workload-list
    workloads:  # Note: can only be used if type is same-gvc or workload-list
      #- //gvc/GVC_NAME/workload/WORKLOAD_NAME

keeper: # cluster mode only
  image: clickhouse/clickhouse-keeper:25.10
  resources:
    cpu: 2
    memory: 2Gi
  internal_access:
    type: same-gvc # options: same-gvc, same-org, workload-list
    workloads:  # Note: can only be used if type is same-gvc or workload-list
      #- //gvc/GVC_NAME/workload/WORKLOAD_NAME

This template creates a GVC with a default name defined in the values file. If you plan to deploy multiple instances, you must assign a unique GVC name for each deployment.

Provider and Object Storage

Set provider to aws, gcp, azure, or hetzner, then fill in the corresponding section. Only the active provider’s fields are used. AWS S3

Field	Description
`aws.bucket`	Name of the S3 bucket
`aws.region`	AWS region where the bucket resides
`aws.cloudAccountName`	Name of the Control Plane Cloud Account with S3 access
`aws.policyName`	Name of the IAM policy granting access to the bucket

GCS

Field	Description
`gcp.bucket`	Name of the GCS bucket
`gcp.accessKeyId`	HMAC access key ID for the GCS service account
`gcp.secretAccessKey`	HMAC secret access key for the GCS service account

Azure Blob Storage

Field	Description
`azure.storageAccount`	Name of the Azure Storage Account
`azure.container`	Name of the Blob Storage container
`azure.accountKey`	Storage account access key (`key1` or `key2`)

Hetzner Object Storage

Field	Description
`hetzner.bucket`	Name of the Hetzner Object Storage bucket
`hetzner.region`	Bucket region — `nbg1`, `hel1`, or `fsn1`
`hetzner.accessKeyId`	S3-compatible access key ID
`hetzner.secretAccessKey`	S3-compatible secret access key

Cluster and Database

clusterName — The name used for distributed DDL queries. Only relevant in cluster mode.
database.name — Database created automatically on first initialization.
database.password — Password for the default ClickHouse user. Change before deploying to production.

These values are only applied on first initialization when the data directory is empty. Updating them after the initial deployment will have no effect on the running cluster. To change credentials or the database name on an existing instance, use ClickHouse’s native commands (e.g. ALTER USER, RENAME DATABASE).

Images

server.image — ClickHouse Server container image.
keeper.image — ClickHouse Keeper container image. Only used in cluster mode.

Resources and Storage

server.resources / keeper.resources — CPU and memory allocated to each workload.
volumeset.server.capacity — Persistent volume size in GiB for server state (minimum 10).
volumeset.keeper.capacity — Persistent volume size in GiB for Keeper state (minimum 10). Only used in cluster mode.

Internal Access

Both server.internal_access and keeper.internal_access control which workloads can reach each component:

Type	Description
`same-gvc`	Allow access from all workloads in the same GVC
`same-org`	Allow access from all workloads in the same organization
`workload-list`	Allow access only from specific workloads listed in `workloads`

Connecting to ClickHouse

Once deployed, connect using the ClickHouse client from a workload in the same GVC:

clickhouse-client --host $WORKLOAD_NAME --password $PASSWORD

External References

ClickHouse Documentation

Official ClickHouse documentation

ClickHouse with S3

Integrating ClickHouse with AWS S3

ClickHouse with GCS

Integrating ClickHouse with Google Cloud Storage

ClickHouse with Azure Blob Storage

Integrating ClickHouse with Azure Blob Storage

ClickHouse with S3-Compatible Storage

Integrating ClickHouse with S3-compatible providers including Hetzner

Cloud Accounts

Create a Control Plane Cloud Account for AWS access

ClickHouse Template

View the source files, default values, and chart definition

​Overview

​Deployment Modes

​What Gets Created

​Architecture

​Prerequisites

​AWS S3

​GCS

​Azure Blob Storage

​Hetzner Object Storage

​Installation

UI

CLI

Terraform

Pulumi

​Configuration

​Provider and Object Storage

​Cluster and Database

​Images

​Resources and Storage

​Internal Access

​Connecting to ClickHouse

​External References

ClickHouse Documentation

ClickHouse with S3

ClickHouse with GCS

ClickHouse with Azure Blob Storage

ClickHouse with S3-Compatible Storage

Cloud Accounts

ClickHouse Template

Overview

Deployment Modes

What Gets Created

Architecture

Prerequisites

AWS S3

GCS

Azure Blob Storage

Hetzner Object Storage

Installation

Configuration

Provider and Object Storage

Cluster and Database

Images

Resources and Storage

Internal Access

Connecting to ClickHouse

External References