Skip to main content
This tutorial walks you through deploying ClickHouse Private on Microsoft Azure using Azure Kubernetes Service (AKS), step by step. By the end, you will have a running ClickHouse cluster with Azure Blob Storage-backed storage, local NVMe SSD caching, and the ClickHouse operator managing the deployment. For detailed infrastructure specifications, see reference/infrastructure-requirements.md. For an overview of how the operator works, see explanation/architecture.md.

Prerequisites

Before you begin, ensure you have the following tools installed:
  • Azure CLI (az) — installed and authenticated to your subscription
  • kubectl — compatible with your target AKS version
  • Helm v3.x
  • skopeo — for copying container images between registries
  • AWS CLI (aws) — with read access to the ClickHouse private ECR (<<SOURCE_ECR_ACCOUNT_ID>>.dkr.ecr.us-east-1.amazonaws.com; access details provided by ClickHouse during onboarding), used only for the image copy step
You will also need:
  • An Azure subscription with permissions to create AKS clusters, Azure Container Registry, Storage Accounts, Virtual Networks, and Managed Identities
  • A resource group for all ClickHouse resources (or reuse an existing one)
  • The version tags for your deployment (provided by ClickHouse):
    • <<SERVER_TAG>> — ClickHouse server image tag
    • <<KEEPER_TAG>> — ClickHouse keeper image tag
    • <<OPERATOR_TAG>> — Operator image and Helm chart tag
    • <<CR_HELM_TAG>> — Cluster Helm chart tag

Step 1: Create the Azure Container Registry

Create an Azure Container Registry (ACR) to hold the ClickHouse images and Helm charts, then log in:
The rest of this guide refers to the registry host as $ACR_HOST:

Step 2: Copy Container Images

Use skopeo to copy images from the ClickHouse ECR into your ACR. The --all flag preserves all architectures (amd64, arm64).
Verify the copy:

Step 3: Create the Virtual Network

Create a VNet with a subnet for AKS nodes.
See reference/infrastructure-requirements.md for detailed networking requirements.

Step 4: Create the AKS Cluster

Create the AKS cluster with OIDC issuer and Workload Identity enabled (required for Step 6). Associate it with the VNet subnet from Step 3. The initial system node pool (Standard_D4s_v3) runs cluster-internal workloads and the ClickHouse operator.
Capture the OIDC issuer URL (needed for Workload Identity in Step 6):

Step 5: Create Node Pools

Add two dedicated node pools for ClickHouse.
Arm deploymentsThis guide uses x86 machine types (server.arm64=false / keeper.arm64=false in Step 9). Azure also offers Arm-based VMs (Standard_D*ps_v5 series). To run on Arm, create the node pools with an Arm machine type, use distinct labels such as clickhouseGroup: server-arm64 / keeper-arm64, point the Step 9 nodeSelector values at them, and set server.arm64=true / keeper.arm64=true.

Keeper Node Pool

Server Node Pool

The server pool uses the Standard_D*ds_v5 family. Setting --node-osdisk-type Ephemeral places the OS on the small local disk. Azure automatically mounts the larger local SSD at /mnt. The ClickHouse cache uses this disk via a hostPath volume pointing at /mnt.
In Step 9, set server.ssdCacheConfiguration.hostPathBaseDirectory="/mnt" (this also disables isOnEmptyDir automatically).

Step 6: Create the Storage Account and Managed Identity

Storage Account

Create an Azure Storage Account and a Blob container for ClickHouse data. Place it in the same region as the AKS cluster.
Do not create Blob Lifecycle Management rules on this containerClickHouse manages its own data in Blob Storage. Lifecycle Management policies (deletion, tiering, abort incomplete uploads with short timeouts) will delete or transition objects that ClickHouse still depends on, causing data loss and cluster outages. To manage data retention, use ClickHouse TTL rules and partition operations instead. See Manage data lifecycle.

Managed Identity and Workload Identity

Workload Identity alignment:

Step 7: Install Kubernetes Prerequisites

Install VolumeSnapshot CRDs

These CRDs are required by the ClickHouse operator.

StorageClass

No manual StorageClass setup is required. The Helm chart creates the premium-ssd-v2 StorageClass automatically when you set storageClass.create=true in Step 9. This StorageClass uses the pre-installed Azure Disk CSI driver (disk.csi.azure.com) with PremiumV2_LRS disks (skuName: PremiumV2_LRS, fstype: ext4, cachingMode: None).

Step 8: Install the Operator

Log into ACR from Helm, then install the operator. Set the availability zones to match your cluster’s zones.

Step 9: Deploy a ClickHouse Cluster

Naming Your Cluster

Each ClickHouse cluster needs a unique name within the AKS cluster. Use the convention $DESCRIPTOR-$LETTERS-$ORDINAL:
  • $DESCRIPTOR — descriptive name using letters only
  • $LETTERS — reserved, use xx for simplicity
  • $ORDINAL — incrementing ordinal starting with 01
  • Example: default-xx-01

Generate Password Hash and Deploy

Chart values referenceThis install sets only the values an Azure deployment needs. For the full list of configurable values and their defaults, review the README of the onprem-clickhouse-cluster Helm chart.
Monitor the rollout (the operator creates server pods after keepers are healthy):

Step 10: Verify Installation

Port-forward the ClickHouse Service

This forwards port 9000 to your local machine.

Connect and Run a Query

Run a simple query:
Expected output:

Next Steps


Appendix: AWS to Azure Component Mapping

Last modified on August 7, 2026