ClickHouse Operator

Databases

Official Kubernetes operator for ClickHouse

ClickHouse/clickhouse-operator Website Documentation

v0.0.8Sep 25, 202667 days after v0.0.7

View on GitHub

Part of ClickHouse

Altinity Helm Chartsrelease-0.27.4

v0.0.8

Sep 25, 2026Compare GitHub

Install using the manifest (server-side apply)

kubectl apply --server-side --force-conflicts -f https://github.com/ClickHouse/clickhouse-operator/releases/download/v0.0.8/clickhouse-operator.yaml

For clusters restricted to client-side apply, use the description-stripped CRDs:

kubectl apply -f https://github.com/ClickHouse/clickhouse-operator/releases/download/v0.0.8/clickhouse-operator-stripped-crds.yaml

CRDs only

kubectl apply --server-side --force-conflicts -f https://github.com/ClickHouse/clickhouse-operator/releases/download/v0.0.8/clickhouse-operator-crds.yaml

Client-side apply variant: clickhouse-operator-crds-stripped.yaml

Install using helmchart

helm install clickhouse-operator oci://ghcr.io/clickhouse/clickhouse-operator-helm \
   --version=0.0.8 \
   --create-namespace \
   -n clickhouse-operator-system

Changelog

🚀 Features

feat: add internal Services for interserver and operator traffic
- PR: #286
feat: gate client traffic until replica initialization completes
- PR: #287
feat: support in-cluster network policies generation
- PR: #214
feat: add periodic resync, bound ClickHouse calls, fix reconcile flow
- PR: #323
feat: add topologyMinDomains opt-in field to force AZ spreading with Karpenter/Cluster Autoscaler
- PR: #330
feat: add spec.settings.extraReloadableConfig
- PR: #338
feat: support startupProbe configuration
- PR: #340
feat: concurrent reconciles and pause-reconciliation annotation
- PR: #344

🐛 Fixes

fix: wrong defaulting of setting enableDatabaseSync to false
- PR: #275
fix: probe job oom kill with transparent_hugepage=true
- PR: #278
fix(helm): derive metrics Certificate dnsNames from resourceName helper
- PR: #291
fix: skip reconcile while the cluster is being deleted
- PR: #309
fix: Use the correct grants.query[] form over grants[].query
- PR: #312
fix(webhook): warn when extraUsersConfig carries server-tree sections
- PR: #317
fix: probe job with readonly rootfs, make it default
- PR: #343
fix(sync): recover a replica whose Keeper registration outlived its volume
- PR: #345
fix: bound log growth with saner logger and system log table defaults
- PR: #329

🧪 Tests

test: update ch version in tests, multiple changes for e2e stabilizat…
- PR: #277
test: retain e2e failure diagnostics and reports
- PR: #279
test: add e2e sharding planning step to equally distribute test spec between jobs
- PR: #280
test: improve e2e failure diagnostics report
- PR: #299
test: upgrade CH versions in tests, ensure e2e tests use pinned/prepulled images
- PR: #301
test: unify e2e utils across e2e/deployment/openshift tests
- PR: #304
test: add max CRD size check, add version probe job retries
- PR: #305
test: enforce NetworkPolicies in e2e and deploy tests
- PR: #306
test: add CR builders, unify suite bootstrap, gate waits on Healthy
- PR: #307
test: verify that controllers do not change resource on a settled clusters
- PR: #310
test: enable race detector for e2e, assert no leaked goroutines after suites
- PR: #314
test(e2e): continuous database invariant checks
- PR: #322

📚 Docs

docs: systemLogsTTLDays defaults on new clusters only; Keeper raft_logs_level follows logger.level
- PR: #348

🧹 Chores

ci: bump actions/setup-go from 6 to 7 in the github-actions group
- PR: #273
chores: bump the go-modules group with 18 updates
- PR: #274
chores: refactor replica state
- PR: #276
chores: bump the go-modules group with 31 updates
- PR: #282
ci: bump docker/login-action from 4.4.0 to 4.5.2 in the github-actions group
- PR: #281
chores: bump the go-modules group with 5 updates
- PR: #283
ci: bump the github-actions group with 4 updates
- PR: #284
chores: bump the go-modules group with 16 updates
- PR: #288
ci: bump the github-actions group with 4 updates
- PR: #289
chores: bump the go-modules group with 10 updates
- PR: #294
ci: bump the github-actions group with 2 updates
- PR: #296
chores: bump google.golang.org/protobuf from 1.36.12-0.20260120151049-f2248ac996af to 1.36.12
- PR: #295
chore: add role label to operator manager pods
- PR: #298
chores: bump the go-modules group with 24 updates
- PR: #303
ci: bump the github-actions group with 2 updates
- PR: #302
chores: update dependencies, tooling and test versions
- PR: #313
chores: modernize codebase with go fix (Go 1.26/1.27 idioms)
- PR: #315
ci: bump the github-actions group with 4 updates
- PR: #319
chores: bump the go-modules group with 11 updates
- PR: #318
ci: auto-regenerate manifests on dependabot bumps
- PR: #326
chores: bump the go-modules group across 1 directory with 38 updates
- PR: #331
ci: bump the github-actions group across 1 directory with 3 updates
- PR: #332
chores: bump the go-modules group with 8 updates
- PR: #336
ci: bump the github-actions group with 3 updates
- PR: #337
chores: extract app composition root and settings from cmd/main
- PR: #342

📦 Uncategorized

Reject non-positive version update intervals
- PR: #316

v0.0.7

Jul 20, 2026Compare GitHub

Install using the manifest (server-side apply)

kubectl apply --server-side --force-conflicts -f https://github.com/ClickHouse/clickhouse-operator/releases/download/v0.0.7/clickhouse-operator.yaml

For clusters restricted to client-side apply, use the description-stripped CRDs:

kubectl apply -f https://github.com/ClickHouse/clickhouse-operator/releases/download/v0.0.7/clickhouse-operator-stripped-crds.yaml

CRDs only

kubectl apply --server-side --force-conflicts -f https://github.com/ClickHouse/clickhouse-operator/releases/download/v0.0.7/clickhouse-operator-crds.yaml

Client-side apply variant: clickhouse-operator-crds-stripped.yaml

Install using helmchart

helm install clickhouse-operator oci://ghcr.io/clickhouse/clickhouse-operator-helm \
   --version=0.0.7 \
   --create-namespace \
   -n clickhouse-operator-system

Changelog

🚀 Features

feat: support encrypted storage policy generation
- PR: #269

🐛 Fixes

fix: don't drop a non-empty Atomic default database during Replicated conversion
- PR: #255
fix: reduce probe job memory footprint
- PR: #257
fix: compare Keeper replica versions numerically, not lexicographically
- PR: #260
fix: default probe ports and probe-failure rollout gating
- PR: #262
fix: hide secrets from preprocessed config
- PR: #267
fix: use resourceName helper for webhook-server-cert secret name
- PR: #270

📚 Docs

docs: extract storage related documentation as a dedicated guide
- PR: #243
docs: network policies
- PR: #246
docs: document Kubernetes events emitted by the operator
- PR: #252
docs: clarify topologyZoneKey and nodeHostnameKey semantics
- PR: #271

🧹 Chores

ci: fix changelog categories generation
- PR: #242
chores: reduce amount of reconciles, cache CH connections between reconciles
- PR: #245
ci: add Dependabot config for scheduled version updates
- PR: #249
ci: bump the github-actions group with 3 updates
- PR: #250
chores: bump the go-modules group with 50 updates
- PR: #251
chores: bump the go-modules group with 22 updates
- PR: #253
chores: bump the go-modules group with 5 updates
- PR: #259
chores: bump the go-modules group with 15 updates
- PR: #263
chores: bump github.com/go-openapi/jsonreference from 0.21.6 to 1.0.0
- PR: #264
Fix markdown parsing error
- PR: #247

v0.0.6

Jun 19, 2026Compare GitHub

Install using the manifest (server-side apply)

kubectl apply --server-side --force-conflicts -f https://github.com/ClickHouse/clickhouse-operator/releases/download/v0.0.6/clickhouse-operator.yaml

For clusters restricted to client-side apply, use the description-stripped CRDs:

kubectl apply -f https://github.com/ClickHouse/clickhouse-operator/releases/download/v0.0.6/clickhouse-operator-stripped-crds.yaml

CRDs only

kubectl apply --server-side --force-conflicts -f https://github.com/ClickHouse/clickhouse-operator/releases/download/v0.0.6/clickhouse-operator-crds.yaml

Client-side apply variant: clickhouse-operator-crds-stripped.yaml

Install using helmchart

helm install clickhouse-operator oci://ghcr.io/clickhouse/clickhouse-operator-helm \
   --version=0.0.6 \
   --create-namespace \
   -n clickhouse-operator-system

Changelog

🚀 Features

feat: add JBOD additional PVC support for ClickHouse replicas
- PR: #136
feat(release): Create PR to community-operators
- PR: #190
feat: allow exposing additional ports on ClickHouse service and pods
- PR: #197
feat: reject additionalPorts that collide with operator-managed ports
- PR: #205
feat: add ExternalSecret print column to ClickHouseCluster
- PR: #207
feat(keeper): smart-default maxUnavailable=1 for single-replica PDB
- PR: #208
feat: add prometheus port to the keeper headless service
- PR: #226
feat: warnings as a kubernetes events
- PR: #209
feat: add registry option to helm charts
- PR: #227
feat: add crds as a separate release artifact, build stripped crds to fit client-side apply
- PR: #232
feat: support distroless images in version probe
- PR: #195
feat: do not set caBundle from certificate by default, only with explicit setting
- PR: #237
Don't restart pods on some config changes
- PR: #115

🐛 Fixes

fix: strip owned resources names to fit in limits
- PR: #204
fix: override resources as whole, use the same req/limit for memory in default
- PR: #206
fix: track users reload separetely of server config
- PR: #218
fix: paginate all tags to build olm catalog
- PR: #221

🧪 Tests

test: automatic e2e tests split between parallel jobs
- PR: #200
test: fix docs linting CI jobs
- PR: #212
test: add openshift e2e smoke test
- PR: #202
test: add upgrade tests to verify operator forward compatibility
- PR: #229
test: fix flaky operator-upgrade keeper writes
- PR: #233
test: use latest supported ClickHouse versions in tests
- PR: #234

📚 Docs

docs: add monitoring & observability guide
- PR: #198
docs: prefix internal ClickHouse doc links with /core
- PR: #201
docs: document spec.additionalPorts and reserved-port validation
- PR: #210
docs: document upgradeChannel and version probe
- PR: #216
docs: document Pod disruption budget configuration
- PR: #213
docs: document spec.settings.logger server logging configuration
- PR: #220
docs: scaling guide
- PR: #222
docs: tls configuration
- PR: #223
docs: fix docs links and CI, fetch mintlify changes, actualize some docs and comments
- PR: #230
docs: update AGENTS.md, do not run tests on pure documentation changes
- PR: #231
docs: document spec.clusterDomain in configuration guide
- PR: #228
docs: expand default user password configuration
- PR: #238
Docs/external secret config
- PR: #203
Docs: add Mintlify frontmatter to docs pages
- PR: #192

🧹 Chores

chore: bump dependencies, enable clickhouse client linter, fix new linters issues
- PR: #194
build: publish per-commit bundle + catalog on 'fast' channel
- PR: #211
ci: fix paths-filter so docs-only changes actually skip CI
- PR: #239
chores: update dependencies, actions, linter config, generate helm chart with latest kubebuilder
- PR: #240
ci: bypass v1 registries.conf in opm catalog render
- PR: #241

v0.0.5

May 18, 2026Compare GitHub

Install using the manifest

kubectl apply -f https://github.com/ClickHouse/clickhouse-operator/releases/download/v0.0.5/clickhouse-operator.yaml

Install using helmchart

helm install clickhouse-operator oci://ghcr.io/clickhouse/clickhouse-operator-helm \
   --version=0.0.5 \
   --create-namespace \
   -n clickhouse-operator-system

Changelog

🚀 Features

Added metrics logs so the built-in dashboard displays proper values. Otherwise, it feels broken at cluster installation.
- PR: #167
feat: support keeper on a different namespace
- PR: #173
feat: add clickhouse-cluster helm chart
- PR: #183
feat: correctly handle IPv4-only envs
- PR: #185
feat(helm): Regenerate helm chart with latest kubebuilder
- PR: #159
feat: drop all capabilities by default, remove restricted security settings in OpenShift installations
- PR: #184

🐛 Fixes

fix: cache version probe result to prevent reconciliation deadlock
- PR: #175
fix: respect user-provided container capabilities under PodSecurity restricted
- PR: #176
fix: set Healthy/Ready to Unknown if pods are running, but the operator can't connect to the server
- PR: #186
fix: requeue reconciliation after replica update
- PR: #189

📦 Uncategorized

test: support suppressing crd-comptat-check
- PR: #177
Docs: restructure for Mintlify sync workflow
- PR: #187

v0.0.4

Apr 17, 2026Compare GitHub

Install using the manifest

kubectl apply -f https://github.com/ClickHouse/clickhouse-operator/releases/download/v0.0.4/clickhouse-operator.yaml

Install using helmchart

helm install clickhouse-operator oci://ghcr.io/clickhouse/clickhouse-operator-helm \
   --version=0.0.4 \
   --create-namespace \
   -n clickhouse-operator-system

Changelog

🚀 Features

feat: allow to disable PDB management
- PR: #164
feat(helm): allow specifying operator image digest
- PR: #146
feat: apply pod/container overrides via strategic merge patch
- PR: #150
feat: support more container/pod fields overrides, enchance default security context and probes
- PR: #151
feat: add default resource for version probe job, recreate it only on significant changes
- PR: #152

feat: add version probe job overrides
- PR: #153

feat: named collections in keeper with key encryption
- PR: #111
feat: support externally managed secret
- PR: #168

📦 Uncategorized

test: added functional tests for ClickHouse commander
- PR: #123
fix: image tag in installer, changelog categories, main build images versions
- PR: #124
fix(docs): .containerTemplate.resources docstring
- PR: #135
fix(helm): support not secure metrics in helmchart servicemonitor, fix serverName
- PR: #137
Bump google.golang.org/grpc from 1.79.1 to 1.79.3
- PR: #138
fix(reconcile): refactor pvc reconcillation, add conflict retries
- PR: #139
test: update CH test versions to the latest supported releases
- PR: #147
fix: calcucation of the supported versions
- PR: #148
test(e2e):Run controller in e2e tests process, dump namespace obejcts and pod logs on failure.
- PR: #140
chores: update dependecies, fix new linting issues, apply new golang syntax everywhere, regenerate helmchart with new generator
- PR: #149
Bump go.opentelemetry.io/otel/sdk from 1.42.0 to 1.43.0
- PR: #155
chores: unify extra config behaviour, mount keeper extra config as separate cofile
- PR: #156
chore: add CI runner disk space cleanup, fix flaky tests
- PR: #157
ci: package and push helm chart in release-main workflow
- PR: #154
chores: add AGENTS.md
- PR: #158
build: version local dependencies in Makefile
- PR: #160
chores: split reconcilerBase on more specialized helpers
- PR: #162
chores: refactor reconcillation pipeline supporting blocking without error
- PR: #163
test: pre pull clickhouse images in e2e test, test campatible versions only with manifests installation
- PR: #165
chores: update dependencies
- PR: #166

v0.0.3

Mar 11, 2026Compare GitHub

Install using the manifest

kubectl apply -f https://github.com/ClickHouse/clickhouse-operator/releases/download/v0.0.3/clickhouse-operator.yaml

Install using helmchart

helm install clickhouse-operator oci://ghcr.io/clickhouse/clickhouse-operator-helm \
   --version=0.0.3 \
   --create-namespace \
   -n clickhouse-operator-system

Changelog

📦 Uncategorized

Fix WATCH_NAMESPACE typo in helm chart
- PR: #86
Set default bundle channel to stable. Set correct image annotation in bundle.
- PR: #87
Add explicit default cluster defenition with internal_replication=1 and generated cluster secret
- PR: #89
fix wrong value key and bad spacing
- PR: #96
Helmchart enhancements
- PR: #97
Collect all e2e test runs in single report
- PR: #100
Fix bool defaulting logic, make logToFile pointer to distinguish false and not set
- PR: #101
Add crd-schema-checker to prevent backward incompatible changes
- PR: #102
Generate api reference
- PR: #105
fix rows.Err handling in commands
- PR: #107
chore add rows.Err check in tests
- PR: #108
Bump go.opentelemetry.io/otel/sdk from 1.39.0 to 1.40.0
- PR: #109
Add grant option to default user
- PR: #110
feat: Add configurable PodDisruptionBudget to ClickHouseCluster CRD
- PR: #104
Fix spec modification issue, add spec fuzzing tests. Relax default anti-affinity rules.
- PR: #113
support pre-release kubeversion
- PR: #114
Add server version in the Status. Add warnings on replica version divergence.
- PR: #116
Unify replica resources logic. Delete Pod in error state if STS stuck
- PR: #117
chore: make error and log messages more consistent, use query parameters, bump ch version for tests, pin e2e k8s version, add action linter
- PR: #121
feat: Add version upgrade availability checks
- PR: #120

v0.0.2

Feb 16, 2026Compare GitHub

Install using the manifest

kubectl apply -f https://github.com/ClickHouse/clickhouse-operator/releases/download/v0.0.2/clickhouse-operator.yaml

Install using helmchart

helm install clickhouse-operator oci://ghcr.io/clickhouse/clickhouse-operator-helm \
   --version=0.0.2 \
   --create-namespace \
   -n clickhouse-operator-system

Changelog

📦 Uncategorized

Lower kubernetes version to v1.30+
- PR: #64
chore: Fix Go mod to be correct
- PR: #67
Remove commit status checks and minor README changes
- PR: #72
fix: correct array index in logger toFields to prevent panic
- PR: #69
fix: use correct separator for container image digest references
- PR: #70
fix: add nil checks before dereferencing Shards pointers in webhook
- PR: #71
Bump github.com/cert-manager/cert-manager from 1.19.2 to 1.19.3
- PR: #73
Add Pod and Container security context overrides
- PR: #74
feat: add clusterDomain field to support custom Kubernetes DNS domains
- PR: #77
Adjust default health probes paramenters. Fix clickhouse liveness probe
- PR: #78
Add default AccessModes to data disk. Allow custom data disk mounts.
- PR: #79
fix: helm chart use wrong values field for manager container security…
- PR: #80
Add build information to manger
- PR: #81
Support all installModes, selection of watched namespaces
- PR: #83
Upgrade go version to 1.26, upgrade dependecies and fix usage of recently deprecated APIs
- PR: #84
Minimal k8s version
- PR: #85

v0.0.1

Jan 29, 2026GitHub

Install using the manifest

kubectl apply -f https://github.com/ClickHouse/clickhouse-operator/releases/download/v0.0.1/clickhouse-operator.yaml

Install using helmchart

helm install clickhouse-operator oci://ghcr.io/clickhouse/clickhouse-operator-helm \
   --version=0.0.1 \
   --create-namespace \
   -n clickhouse-operator-system

Changelog

no changes, initial release

Website Apache 2.0 License

ClickHouse Operator

The ClickHouse Operator is a Kubernetes operator that automates the deployment, configuration, and management of ClickHouse clusters and ClickHouse Keeper clusters on Kubernetes. It provides declarative cluster management through custom resources, enabling users to easily create highly-available ClickHouse deployments.

The Operator handles the full lifecycle of ClickHouse clusters, including scaling, upgrades, and configuration management.

Features

ClickHouse Cluster Management: Create and manage ClickHouse clusters
ClickHouse Keeper Integration: Built-in support for ClickHouse Keeper clusters for distributed coordination
Storage Provisioning: Customizable persistent volume claims with storage class selection
High Availability: Fault-tolerant installations for ClickHouse and Keeper clusters
Security: Built-in security features TLS/SSL support for secure cluster communication
Monitoring: Prometheus metrics integration for observability

Getting Started

Prerequisites

go version v1.27.0+
docker version 17.03+
kubectl version v1.28.0+
Access to a Kubernetes v1.28.0+ cluster
cert-manager installed in the cluster (for webhook certificates)

Quick Start

For users who want to quickly try the operator:

Install the Custom Resource Definitions(CRD) and operator (Requires cert-manager to issue webhook certificates):

Using pre-built manifests:

kubectl apply --server-side --force-conflicts -f https://github.com/ClickHouse/clickhouse-operator/releases/latest/download/clickhouse-operator.yaml

Using helm chart

helm install clickhouse-operator oci://ghcr.io/clickhouse/clickhouse-operator-helm \
   --create-namespace \
   -n clickhouse-operator-system

Deploy a sample cluster:

Using raw manifests:

kubectl apply -f https://raw.githubusercontent.com/ClickHouse/clickhouse-operator/refs/heads/main/examples/minimal.yaml

Using the helm chart:

helm install ch oci://ghcr.io/clickhouse/clickhouse-cluster-helm \
   --create-namespace \
   -n clickhouse

Verify the deployment:

kubectl get clickhouseclusters
kubectl get keeperclusters
kubectl get pods

Deploy from the sources

Build and push your image to the location specified by IMG:

make docker-build docker-push IMAGE_REPO=<some-registry>

NOTE: This image ought to be pushed to the personal registry you specified. And it is required to have access to pull the image from the working environment. Make sure you have the proper permission to the registry if the above commands don’t work.

Install the Custom Resource Definitions(CRD) into the cluster:

make install

Deploy the Manager to the cluster with the image specified by IMG:

make deploy IMAGE_REPO=<some-registry>

NOTE: If you encounter RBAC errors, you may need to grant yourself cluster-admin

privileges or be logged in as admin.

Examples

The examples/ directory contains various ClickHouse cluster configurations:

minimal.yaml: Basic ClickHouse cluster with Keeper (2 replicas, 1 shard)
cluster_with_ssl.yaml: ClickHouse cluster with TLS/SSL enabled. Requires cert-manager to issue certificates.
aws_eks_gp3.yaml: Configuration for AWS EKS with gp3 storage
gcp_gke_ssd.yaml: Configuration for GCP GKE with SSD storage
custom_configuration.yaml: ClickHouse cluster with configuration overrides
prometheus_secure_metrics_scraper.yaml: Configuration for secure operator metrics scraping. Requires Prometheus operator and enabled secure metrics endpoint

To deploy any example:

kubectl apply -f examples/<example-file>.yaml

To Uninstall

Delete the APIs(CRDs) from the cluster:

make uninstall

UnDeploy the controller from the cluster:

make undeploy

Documentation

For more detailed information, see the documentation.

Contributing

We welcome contributions to the ClickHouse Operator project! Here's how you can help:

Bug Reports: Open an issue describing the bug and steps to reproduce
Feature Requests: Submit an issue with your feature proposal and use case
Pull Requests: Fork the repository, make your changes, and submit a PR
Documentation: Help improve documentation and examples
Testing: Test the operator in different environments and report issues

Before contributing, please ensure:

All tests pass: make test
Code follows Go conventions and passes linting: make lint
Commits are well-documented

Useful Links

View the full README on GitHub

Part of ClickHouse

Release history

v0.0.8

v0.0.7

v0.0.6

v0.0.5

v0.0.4

v0.0.3

v0.0.2

v0.0.1

README

ClickHouse Operator

Features

Getting Started

Prerequisites

Quick Start

Deploy from the sources

Examples

To Uninstall

Documentation

Contributing

Useful Links