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
- 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:$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).
Step 3: Create the Virtual Network
Create a VNet with a subnet for AKS nodes.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.
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 theStandard_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.
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.Managed Identity and Workload Identity
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 thepremium-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, usexxfor simplicity$ORDINAL— incrementing ordinal starting with01- Example:
default-xx-01
Generate Password Hash and Deploy
Step 10: Verify Installation
Port-forward the ClickHouse Service
9000 to your local machine.
Connect and Run a Query
Next Steps
- FIPS / government compliance: See tutorials/deploy-government.md to apply FIPS 140-3 certificates and TLS configuration on top of this infrastructure.
- Compute-Compute separation: See how-to/configure-compute-compute-separation.md to set up multiple compute groups with separate endpoints sharing a single dataset.
- Management API: See tutorials/install-api.md to install the optional Private API for backups and scaling operations.
- Monitoring and alerting: See how-to/configure-alerting.md to set up alerting for your deployment.
- Troubleshooting: See troubleshooting.md for common issues and solutions.