Altinity ClickHouse Operator: Managing ClickHouse Clusters as Kubernetes Custom Resources

What the Altinity ClickHouse Operator Actually Replaces

Running ClickHouse on Kubernetes without an operator means writing StatefulSets, Services, ConfigMaps and Secrets by hand, then keeping them in sync when the cluster shape changes. This operator moves that work into a custom resource. The README states the project "creates, configures and manages ClickHouse clusters running on Kubernetes," and the feature list is essentially the list of things you would otherwise script: storage provisioning through VolumeClaim templates, pod and service templates, ClickHouse configuration management, user management, scaling with automatic schema propagation, version upgrades, and Prometheus metrics export.

The audience is narrow and specific. You need Kubernetes 1.25 or newer and ClickHouse 21.11 or later; the README says older ClickHouse versions require operator 0.23.7 or earlier. That version floor matters because the operator is not a wrapper around a CLI. It is a controller that watches custom resources and reconciles cluster state, so it inherits the Kubernetes API versioning story. Teams on managed Kubernetes that lag several releases behind will find the requirement binding.

The project is Apache-2.0 licensed and sponsored by Altinity, which also states it is the basis of Altinity.Cloud. That dual role is worth naming plainly: the operator is open source, and it is also the foundation of a commercial product. Nothing in the README suggests the open source path is restricted, but the commercial support links at the bottom of the README tell you where paid help lives.

How the Controller Reconciles a ClickHouseInstallation Resource

The unit of configuration is a custom resource. The README links a specification document called "ClickHouse Installation Custom Resource specification" at docs/custom_resource_explained.md, and the repository ships example manifests under docs/chi-examples, including 99-clickhouseinstallation-max.yaml, which the README references as the maximal example. The naming convention points at a resource kind abbreviated CHI.

Internally the operator is a Go controller built on sigs.k8s.io/controller-runtime v0.18.7 and k8s.io/client-go v0.30.14, according to go.mod. It carries github.com/go-zookeeper/zk v1.0.3 as a direct dependency, which lines up with the replication documentation: setting up ZooKeeper is a separate page from setting up the cluster. It also depends on github.com/mailru/go-clickhouse/v2, a ClickHouse client library, so the operator talks to ClickHouse directly rather than only manipulating Kubernetes objects. That is how user management and schema propagation can happen at all.

Metrics export uses the OpenTelemetry Go SDK with a Prometheus exporter (go.opentelemetry.io/otel/exporters/prometheus v0.64.0), and the README lists a metrics-exporter image alongside the operator image. Note the FIPS detail: the README says the operator and metrics-exporter images are FIPS 140-3 compatible with GOFIPS140=v1.0.0 and GODEBUG=fips140=on by default, and that an optional ACVP responder exists behind a -tags acvp_wrapper build. The README points to docs/security_hardening.md for the FIPS scope and prerequisites, which is the right place to check before assuming the default build satisfies a compliance requirement.

Installing the Operator and Creating a First ClickHouseInstallation

The README does not inline installation commands. It points to a Quick Start Guide (docs/quick_start.md) and to Detailed Operator Installation Instructions (docs/operator_installation_details.md), with operator configuration covered separately in docs/operator_configuration.md. The repository also contains a deploy/ directory and a config/ directory at the top level, which is where Kubernetes manifests for the operator itself conventionally live. Because the README does not print the exact manifest URLs, treat the Quick Start Guide as the authoritative source for the install step rather than copying YAML from a blog post.

What the documentation structure does tell you is the shape of the workflow. You install the operator into the cluster, then you apply a custom resource describing the ClickHouse cluster you want. The maximal example is referenced as chi_max_yaml, and the CRD specification page is docs/custom_resource_explained.md. The README does not print a minimal manifest, and the repository files given here do not contain one either, so there is no code block to copy at this step. Read docs/custom_resource_explained.md and docs/chi-examples/99-clickhouseinstallation-max.yaml before writing your first resource.

After the operator is running and the resource is accepted, the operator creates the underlying StatefulSet, Services and ConfigMaps. For a replicated cluster you need ZooKeeper first; docs/zookeeper_setup.md and docs/replication_setup.md cover that, and docs/chi_update_add_replication.md describes adding replication to a cluster that already exists. Monitoring is a separate install: docs/prometheus_setup.md and docs/grafana_setup.md, with a grafana-dashboard/ directory in the repository holding the dashboard assets.

Where the Operator Gets in the Way

The most obvious limitation is the dependency chain for replication. ClickHouse itself can run replicated without an external coordinator in recent versions, but this operator's documentation treats ZooKeeper setup as a prerequisite page, and go.mod carries a ZooKeeper client as a direct dependency. If your goal is a small replicated cluster and you do not want to operate a coordination service, that is a real cost, not a footnote.

The second constraint is the version floor. Kubernetes 1.25+ and ClickHouse 21.11+ are hard requirements per the README, and the fallback for older ClickHouse is to pin operator 0.23.7 or earlier. That means an upgrade of either side is a coupled decision. The operator's own upgrade path has its own document, docs/operator_upgrade.md, and the ClickHouse version upgrade path has another, docs/chi_update_clickhouse_version.md. Two separate upgrade documents is a signal: neither upgrade is a no-op.

The third is scope. The README lists schema migration, storage configuration, replication setup and monitoring as separate documentation pages, which is honest but also tells you the operator does not make those problems disappear. Automatic schema propagation is listed as a scaling feature, not a general schema management system. If you need controlled, reviewed DDL changes, docs/schema_migration.md is where the operator's answer lives, and it is worth reading before assuming the controller handles it.

Finally, the operator is the wrong tool outside Kubernetes. Every feature in the list is expressed through custom resources, pod templates and volume claim templates. Running it against a bare-metal ClickHouse install is not a supported configuration in anything the README describes.

Operator Versus Helm Chart: Different Layers, Not Competitors

People search for "clickhouse operator helm" and "clickhouse operator vs altinity operator," and the second query is a category error worth untangling. A Helm chart is a templating and release tool. It renders YAML once per install or upgrade and hands it to the Kubernetes API server. It does not watch anything afterward. The Altinity operator is a controller: it holds a reconciliation loop, watches the custom resource, and reacts to drift and to changes in the resource. That is why the feature list can include automatic schema propagation and version upgrades; a chart cannot do either, because a chart has no runtime presence.

The practical difference shows up when something changes outside the release. If a pod template is edited by hand, a chart-based deployment has no mechanism to notice. The operator does. The trade-off is the opposite direction: a chart is a static artifact you can diff and review, while a controller introduces a running component with its own RBAC, its own image, and its own upgrade cadence. You are adding a control plane process to your cluster, and it needs to be maintained like one.

A fair comparison target is not another ClickHouse operator but the plain StatefulSet approach. Writing the manifests yourself gives you complete control and no extra controller, at the cost of doing the reconciliation manually. For a single-node ClickHouse used as a cache, that is probably the better choice. For a replicated cluster that needs to scale and upgrade, the manual path gets expensive quickly.

Maintenance, Upgrade Cost and Licence Position

The repository is not archived, and the most recent push recorded is 2026-09-27. Releases are frequent: release-0.27.4 on 2026-09-24, release-0.27.3 on 2026-08-12, and release-0.27.2 on 2026-07-23. A roughly monthly release cadence means you should expect to track versions rather than install once and forget. The CHANGELOG.md at the repository root is where release-by-release changes are recorded.

Upgrade cost has two dimensions. The operator itself has docs/operator_upgrade.md, and the CHANGELOG.md is the record of what changed between versions. The custom resource definitions are the part that bites: a CRD schema change can require attention before the new controller image is rolled out, and the operator's own version floor interacts with your Kubernetes version. The second dimension is ClickHouse itself, covered by docs/chi_update_clickhouse_version.md. Budget for both.

On licensing, the operator is Apache-2.0, with LICENSE and NOTICE at the repository root and third-party Go attributions in THIRD_PARTY_NOTICES.md. Apache-2.0 is permissive and includes a patent grant, but the NOTICE file and the third-party notices exist for a reason: if you redistribute the operator or a derivative, those attribution requirements travel with it. This is not legal advice, and the interaction between the NOTICE file and your own distribution obligations is worth a look from whoever handles licensing on your team. Separately, the README uses the ClickHouse and Altinity trademarks, and trademark rights are not granted by the Apache licence even though the code is.

Editorial conclusion

Adopt it if you already run Kubernetes 1.25 or newer, need ClickHouse configuration, users, storage and version upgrades expressed as versioned YAML, and can operate ZooKeeper for replicated setups. Do not adopt it if you want a single-node ClickHouse without Kubernetes, or if you cannot commit to the CRD upgrade path, since the operator documentation devotes a separate page to updating the operator version. Before rolling it into production, verify the ClickHouse image tag you intend to use is 21.11 or later, confirm the ClickHouseInstallation custom resource is accepted by your cluster's API server, and read docs/operator_upgrade.md for the supported upgrade sequence.

Frequently asked questions

Official sources

1. Altinity/clickhouse-operator on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases