> ## Documentation Index
> Fetch the complete documentation index at: https://docs.controlplane.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ClickHouse

> Deploy ClickHouse on Control Plane using the Template Catalog. Covers configuration, volumes, scaling, and ClickHouse Keeper coordination with S3, GCS, Azure Blob Storage, or Hetzner Object Storage.

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

<Note>
  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.
</Note>

## Prerequisites

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

### AWS S3

1. Create an S3 bucket. Note the bucket name and region — you will set these as `aws.bucket` and `aws.region` in your values file.

2. If you do not have a Control Plane Cloud Account set up, follow the [Create a Cloud Account](https://docs.controlplane.com/guides/create-cloud-account) guide. Set `aws.cloudAccountName` to the name of your Cloud Account.

3. Create an IAM policy with the following JSON, replacing `YOUR_BUCKET_NAME`:

```json theme={null}
{
    "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/*"
            ]
        }
    ]
}
```

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

1. Create a GCS bucket. Set `gcp.bucket` in your values file to the bucket name.

2. In the GCP console, navigate to **Settings > Interoperability** and click **Create a key for a service account**.

3. Click **Create new account**, name your service account, and assign the **Storage Object Admin** role under Permissions.

4. Copy the generated HMAC key and set `gcp.accessKeyId` and `gcp.secretAccessKey` in your values file.

Alternatively, use the `gcloud` CLI:

```bash theme={null}
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.

1. In the [Azure Portal](https://portal.azure.com), go to **Storage accounts → Create**. Use **Standard** performance, **LRS** redundancy, and leave hierarchical namespace off.

2. Inside the storage account, go to **Containers → + Container** and create a container (e.g. `clickhouse-data`). Set access level to **Private**.

3. Go to **Security + networking → Access keys** and copy either `key1` or `key2`.

4. 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:

```bash theme={null}
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 |

1. In the Hetzner Cloud console, go to **Object Storage** and create a bucket. Note the bucket name and region.

2. Go to **Security → S3 Credentials** and click **Generate credentials**. Save the access key and secret key immediately — the secret will not be shown again.

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

<CardGroup cols={2}>
  <Card title="UI" href="/template-catalog/install-manage/ui" icon="laptop">
    Browse, install, and manage templates visually
  </Card>

  <Card title="CLI" href="/template-catalog/install-manage/cli" icon="terminal">
    Manage templates from your terminal
  </Card>

  <Card title="Terraform" href="/template-catalog/install-manage/terraform" icon={<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128"><g fill-rule="evenodd"><path d="M77.941 44.5v36.836L46.324 62.918V26.082zm0 0" fill="#5c4ee5"/><path d="M81.41 81.336l31.633-18.418V26.082L81.41 44.5zm0 0" fill="#4040b2"/><path d="M11.242 42.36L42.86 60.776V23.941L11.242 5.523zm0 0M77.941 85.375L46.324 66.957v36.82l31.617 18.418zm0 0" fill="#5c4ee5"/></g></svg>}>
    Declare templates in your Terraform configurations
  </Card>

  <Card
    title="Pulumi"
    href="/template-catalog/install-manage/pulumi"
    icon={<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" id="Pulumi-Icon--Streamline-Svg-Logos" height="24" width="24">
    <desc>
        Pulumi Icon Streamline Icon: https://streamlinehq.com
    </desc>
    <path fill="#f26e7e" d="M4.683025 13.3318c0.869125 -0.5018 0.870575 -2.1264 0.003225 -3.62865s-2.27504 -2.313275 -3.1441725 -1.811475C0.672945 8.3935 0.6715 10.0181 1.53885 11.52035c0.86735 1.502275 2.27505 2.313275 3.144175 1.81145Zm0.0052 3.2167c0.86735 1.502275 0.865925 3.126875 -0.003225 3.628675 -0.86915 0.5018 -2.2768275 -0.309225 -3.144175 -1.81145 -0.8673525 -1.50225 -0.8659075 -3.126875 0.003225 -3.628675 0.8691325 -0.5018 2.276825 0.309225 3.144175 1.81145Zm5.922875 3.4243c0.86735 1.50225 0.8659 3.126775 -0.003225 3.62875 -0.869125 0.501775 -2.27685 -0.309325 -3.1442 -1.81155 -0.867325 -1.50225 -0.865875 -3.12685 0.00325 -3.628675 0.869125 -0.5018 2.276825 0.309225 3.144175 1.811475Zm-0.001925 -6.845275c0.86735 1.50225 0.8659 3.12685 -0.003225 3.628675 -0.869125 0.5018 -2.276825 -0.309225 -3.144175 -1.811475 -0.86735 -1.50225 -0.8659 -3.12685 0.003225 -3.62865 0.869125 -0.501825 2.276825 0.3092 3.144175 1.81145Z" stroke-width="0.25"></path>
    <path fill="#8a3391" d="M22.45775 11.524125c0.86725 -1.502225 0.865925 -3.12685 -0.003225 -3.62865 -0.869125 -0.501825 -2.276825 0.3092 -3.144175 1.811475 -0.86735 1.50225 -0.8659 3.126825 0.003225 3.62865 0.869125 0.501825 2.276825 -0.3092 3.144175 -1.811475Zm0.000175 3.2151c0.869075 0.5018 0.870625 2.1264 0.003225 3.62865 -0.86735 1.50225 -2.27505 2.313275 -3.144175 1.81145 -0.869125 -0.5018 -0.870575 -2.126425 -0.003225 -3.62865 0.86735 -1.50225 2.27505 -2.313275 3.144175 -1.81145ZM16.536225 18.157875c0.86915 0.501825 0.8706 2.126425 0.00325 3.628675 -0.86735 1.502125 -2.275075 2.313225 -3.1442 1.81145 -0.869125 -0.50175 -0.870575 -2.126425 -0.003225 -3.62865 0.867375 -1.502275 2.27505 -2.3133 3.144175 -1.811475Zm-0.003325 -6.843775c0.869125 0.5018 0.870575 2.126425 0.003225 3.628675s-2.27505 2.313275 -3.1442 1.811475c-0.869125 -0.501825 -0.870575 -2.126425 -0.003225 -3.628675 0.86735 -1.502275 2.27505 -2.313275 3.1442 -1.811475Z" stroke-width="0.25"></path>
    <path fill="#f7bf2a" d="M15.138225 2.06721c0 1.003615 -1.40625 1.817215 -3.14095 1.817215 -1.7347 0 -3.14095 -0.8136 -3.14095 -1.817215C8.856325 1.06359 10.262575 0.25 11.997275 0.25c1.7347 0 3.14095 0.81359 3.14095 1.81721ZM9.2166 5.482375c0 1.003625 -1.40625 1.8172 -3.14095 1.8172 -1.7347 0 -3.14095 -0.813575 -3.14095 -1.8172s1.40625 -1.817225 3.14095 -1.817225c1.7347 0 3.14095 0.8136 3.14095 1.817225Zm8.71005 1.8172c1.7347 0 3.14095 -0.813575 3.14095 -1.8172s-1.40625 -1.817225 -3.14095 -1.817225c-1.7347 0 -3.14095 0.8136 -3.14095 1.817225s1.40625 1.8172 3.14095 1.8172Zm-2.788425 1.605625c0 1.003625 -1.40625 1.8172 -3.14095 1.8172 -1.7347 0 -3.14095 -0.813575 -3.14095 -1.8172 0 -1.0036 1.40625 -1.8172 3.14095 -1.8172 1.7347 0 3.14095 0.8136 3.14095 1.8172Z" stroke-width="0.25"></path>
    </svg>}
  >
    Declare templates in your Pulumi programs
  </Card>
</CardGroup>

## Configuration

The default `values.yaml` for this template:

```yaml theme={null}
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
```

<Note>
  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.
</Note>

### 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.**

<Note>
  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`).
</Note>

### 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:

```bash theme={null}
clickhouse-client --host $WORKLOAD_NAME --password $PASSWORD
```

## External References

<CardGroup cols={2}>
  <Card title="ClickHouse Documentation" icon="book" href="https://clickhouse.com/docs/">
    Official ClickHouse documentation
  </Card>

  <Card title="ClickHouse with S3" icon="aws" href="https://clickhouse.com/docs/integrations/s3">
    Integrating ClickHouse with AWS S3
  </Card>

  <Card title="ClickHouse with GCS" icon="google" href="https://clickhouse.com/docs/integrations/gcs">
    Integrating ClickHouse with Google Cloud Storage
  </Card>

  <Card title="ClickHouse with Azure Blob Storage" icon="microsoft" href="https://clickhouse.com/docs/integrations/azure-data-lake-storage">
    Integrating ClickHouse with Azure Blob Storage
  </Card>

  <Card title="ClickHouse with S3-Compatible Storage" icon="database" href="https://clickhouse.com/docs/integrations/s3#s3-compatible-storage">
    Integrating ClickHouse with S3-compatible providers including Hetzner
  </Card>

  <Card title="Cloud Accounts" icon="key" href="https://docs.controlplane.com/guides/create-cloud-account">
    Create a Control Plane Cloud Account for AWS access
  </Card>

  <Card title="ClickHouse Template" icon="github" href="https://github.com/controlplane-com/templates/tree/main/clickhouse">
    View the source files, default values, and chart definition
  </Card>
</CardGroup>