Deploying ClickHouse with the official Kubernetes operator: when it fits
A platform team that already runs Kubernetes and needs self-managed ClickHouse replicas should consider the official ClickHouse Operator, because it lets that team describe the database in the same declarative manifests, GitOps flows and storage classes it uses for everything else. The operator manages two custom resources: a ClickHouseCluster for ClickHouse server pods and a KeeperCluster for the coordination service. ClickHouse server is open source under the Apache License 2.0, so the operator is a deployment mechanism, not a licensing decision. Confirm the operator's own license and maturity in its repository before you adopt it, since this topic's facts describe a 0.0.x release line that is still early.
Coordination matters because ReplicatedMergeTree tables depend on ClickHouse Keeper, which replaces ZooKeeper, to agree on replica state. The operator creates the Keeper ensemble as its own resource, so you can size, place and upgrade it separately from the data nodes. The replication guide recommends at least three Keeper nodes on dedicated hosts in production, and you should check that your Kubernetes scheduling rules and node pools can honor that placement. Decide early whether Keeper pods share failure domains with ClickHouse pods, because a single node loss should never remove quorum for both.
Prefer Linux packages when you want the simplest host-level control over a small number of servers, and prefer Docker when you run a single node or a lab. Choose the operator when you need many replicas, repeatable rollouts across environments and a team that already operates Kubernetes well. Teams without that Kubernetes depth should first weigh the operational cost of owning a stateful operator on top of the database. An illustrative check: if your Kubernetes platform team cannot yet restore a persistent volume claim in a test cluster, the operator adds risk before it adds convenience.
Choosing Helm, kubectl or OLM to install the operator
Helm suits platform teams that already manage cluster add-ons as Helm releases and want their values files kept in Git next to other configuration. The chart packages the operator Deployment, its RBAC and the custom resource definitions, and Helm records the installed release so that upgrades and rollbacks follow one command path. The team still decides which chart version reaches each cluster and which values override the defaults.
- Values files: Storage classes, TLS secret names and resource requests live in version-controlled values files, which makes changes reviewable before they are applied.
- CRD handling: Helm installs CRDs from a chart's crds directory but does not update them on upgrade in the usual way, so confirm how this chart ships CRD schema changes before you run an upgrade.
- Pinning: Pin the chart to an exact version and record the operator image tag it deploys, because the chart version and the operator version are separate numbers.
- Source trust: Confirm the chart repository, any signing practice it follows, and that your internal mirror or air-gapped registry holds the same artifacts you tested.
Before promoting a chart version, check that its values schema matches your overrides and that your GitOps tool renders the chart the way your test environment did.
Plain manifests suit teams that want every object visible as a file, with no templating layer or package manager between them and the cluster. You apply the operator's manifests, which declare the CRDs, RBAC, the operator Deployment and supporting objects, then create ClickHouseCluster and KeeperCluster resources. Each upgrade is another apply with a new manifest set, so the team owns the diffing, the ordering and the record of what is running.
- Full visibility: Every object is reviewable as YAML, which helps security reviewers check service accounts, cluster roles and namespace scope.
- Manual ordering: Apply the CRDs first, then the operator, then ClickHouseCluster and KeeperCluster resources, and keep that sequence in a script or pipeline.
- Upgrade diffing: Compare the new manifest set with the running objects, paying attention to CRD schema changes that can affect existing cluster resources.
- No release record: kubectl does not track installed versions, so record the version and a checksum of each manifest file in your change system or in a Git tag.
- Artifact origin: Confirm the manifests come from the project's published release artifacts, and keep a copy in your internal repository for rebuilds in restricted networks.
Also check that your cluster version falls within the range the operator supports, using the Kubernetes version skew policy as the reference for control plane and node versions.
Operator Lifecycle Manager suits clusters run by an operations team that already uses OLM for subscriptions and wants operator upgrades governed by catalog channels and approval settings. Installing the operator means creating a subscription in a namespace, after which OLM resolves the bundle, installs the CRDs and reports status on the install plan. Whether the operator is available depends on the catalog sources your cluster can reach, so confirm that before you plan the rollout.
- Catalog dependency: OLM must be installed in the cluster, and the operator must appear in a catalog the cluster can read. Confirm both, including for mirrored catalogs in restricted networks.
- Approval mode: Subscriptions can require manual approval, so each update waits for a platform owner to approve the InstallPlan before it lands.
- Channels: Check which update channels the bundle publishes, which one you subscribe to, and how quickly that channel moves relative to your test cycle.
- Namespace scope: Confirm whether the operator watches a single namespace or all namespaces, since that changes its RBAC footprint and the blast radius of a misconfigured resource.
- Platform support: Confirm which OLM version your Kubernetes distribution ships, because OLM is not included in every cluster by default.
Record the catalog image digest, the channel and the approval mode in writing before the first subscription is created.
Configuration options and when each fits
This table compares the main decisions when you deploy ClickHouse and Keeper with the operator: replica count, Keeper placement, storage, TLS and resource requests. Read each row for the condition that favors an option and the cost it adds to operations. Use it to shortlist choices before you write the ClickHouseCluster and KeeperCluster resources.
| Decision | When it fits | Trade-off |
|---|---|---|
| Replicas per shard | Use two or more replicas for data you cannot rebuild from source, since replication keeps a copy on another node | Each extra replica adds CPU, memory and disk to every shard and must be sized and upgraded too |
| Single replica per shard | Acceptable for disposable test data or a pre-production environment where loss is tolerable | A failed pod or node leaves that shard's data unavailable until it returns, and replication does not protect against human error |
| Keeper placement on dedicated nodes | Recommended for production, as the replication guide advises dedicated hosts for Keeper | Requires spare node capacity and anti-affinity rules, which raises the infrastructure footprint |
| Keeper co-located with ClickHouse pods | Possible for small evaluation clusters where node count is limited | Keeper competes with query memory and disk, so a busy ClickHouse node can destabilize coordination |
| Storage class and volume size | Pick a class that matches your latency needs and confirm it supports the access mode and expansion you plan to use | Volume size is hard to shrink later, so confirm growth paths and retention needs before you create the claims |
| cert-manager issued certificates | Fits when your cluster already runs cert-manager and you want automatic renewal and a clear issuer chain | Adds a dependency on cert-manager and issuer configuration that your platform team must operate |
| Self-issued certificates | Fits when your organization has an internal CA process you must follow or cert-manager is not permitted | Your team owns generation, distribution and rotation, so renewal failures are a manual risk |
| Resource requests and limits | Set requests close to what ClickHouse and Keeper need under load so the scheduler places pods on suitable nodes | Limits set too low cause restarts under merges or queries, while limits set too high reduce packing efficiency |
Setup sequence for a ClickHouseCluster with Keeper
This sequence takes an empty Kubernetes cluster to a replicated ClickHouse cluster coordinated by a Keeper ensemble, with TLS and a restricted default user. Each step ends with a check you can run before moving on, so problems surface while the deployment is still small.
Prepare namespaces and Pod Security settings
The platform team creates separate namespaces for the operator, Keeper and ClickHouse workloads, then applies Pod Security Standards labels to each one at the level your policy requires. Confirm that level before you rely on it, because ClickHouse and Keeper pods may need settings a restrictive profile blocks. Check the labels on each namespace and run a throwaway pod that the admission controller should accept or reject as intended. The step is done when every namespace reports the enforce level you approved.
Install cert-manager and the ClickHouse Operator
The platform team installs cert-manager first, then the ClickHouse Operator, using the Helm, kubectl or OLM method your organization has approved. Confirm the compatible version pairing in the operator's own release notes, because this guide does not fix versions. Check that the cert-manager pods are running, the operator deployment reports ready, and the custom resource definitions for ClickHouseCluster and KeeperCluster are registered. The step is done when both resource types appear in the cluster's API resource list.
Deploy KeeperCluster and confirm quorum
Create a KeeperCluster with at least three nodes, since the replication guide recommends three or more Keeper nodes, and place them on dedicated hosts or with anti-affinity rules where production is planned. The replication guide suggests about 4 GB of RAM per Keeper node, so size the nodes accordingly. Keeper coordinates ReplicatedMergeTree tables, so ClickHouse should not be deployed against an ensemble that lacks quorum. Check that all Keeper pods are ready and that the ensemble has elected a leader, using the status interface your Keeper version exposes. The step is done when every member reports healthy and a leader is stable across a few checks.
Deploy the ClickHouseCluster with TLS
Apply the ClickHouseCluster resource with a reference to the Keeper ensemble, the replica count, the storage class and volume size, and TLS certificates issued through cert-manager. The storage class affects replacement time and disk performance, so confirm it supports the volume mode and expansion your plan requires. Check that each ClickHouse pod reaches ready state, that the operator reports the cluster as available, and that the events for each pod show no mount or certificate errors. The step is done when every replica is running, connects to Keeper, and answers a test query over TLS.
Verify replicas sync and survive a restart
Create a ReplicatedMergeTree table on the cluster, insert test rows through one replica, and read them from the others. Stop one replica pod and confirm that writes still succeed on the remaining replicas. When the pod returns, the replication guide describes a recovered replica syncing missing data from a healthy one without manual steps, so verify that it does. Check the system.replicas table for read-only flags, queue length and replica delay. The step is done when all replicas return the same row count and none stays read-only.
Restrict the default user and confirm access
The default user starts with all permissions, so create named administrative and application users with roles, then restrict or disable the default account as the access control documentation describes. Decide which external authenticator your organization will use, such as LDAP, Kerberos, X.509 certificates or JWT, and plan it before go-live. Check that a login with the default account is refused and that a role-limited user can run only the queries its role permits. The step is done when those access tests pass and the decision is recorded for audit.
Storage classes and TLS decisions that are hard to change later
The storage class, volume size and persistent volume reclaim policy are the decisions most expensive to reverse once ClickHouse data arrives. The storage class determines the disk type, performance and whether the volume can be expanded later, so confirm with your platform team which classes your cluster offers and whether they allow volume expansion before you write the ClickHouseCluster resource. Size the volumes for the retention window and merge overhead you expect, and leave headroom, because resizing depends on the storage driver. Set the reclaim policy deliberately: a Delete policy removes the underlying volume when the claim is deleted, so an accidental removal of a cluster or namespace can destroy data that no replica still holds. Test the reclaim behavior in a pre-production cluster and keep backups independent of the volumes (see the backup topic in this pillar).
Kubernetes Secrets are stored unencrypted in etcd by default, and ClickHouse deployments put credentials there: user passwords, Keeper configuration and TLS private keys. Before go-live, confirm that encryption at rest for etcd is enabled on your control plane, and restrict list and watch on Secrets through least-privilege RBAC so that only the operator's service account and the people who need them can read them. If your policy rules out storing key material in etcd at all, the Secrets Store CSI Driver can pull credentials from an external store at pod start, but the operator and your certificate workflow must then support that mount pattern, which you should verify in a test namespace rather than assume. Ask your Kubernetes provider or platform team to confirm which of these controls already exist.
TLS needs a decision on issuer and trust before the first node starts. With cert-manager, an Issuer or ClusterIssuer signs certificates for ClickHouse HTTP and native interfaces and for the inter-node and Keeper connections. Choose whether your internal CA is a self-managed root, an intermediate under your enterprise PKI, or a tool such as OpenBao, and record the certificate names, the subject alternative names for each pod and service, and the renewal window. Keeper nodes need their own certificates and must trust the same chain as the ClickHouse servers, so a mismatch surfaces as a failed quorum rather than a clear TLS error. Plan how certificate rotation will restart or reload pods, and confirm the exact certificate fields and reload behavior in the operator documentation for your release.
Security and operational considerations on Kubernetes
Running ClickHouse and Keeper on Kubernetes adds a control plane, a secrets store and a set of pod-level permissions to the database's own access model. The cards below cover the layers that need a decision before the first cluster goes live, and the checks to run against each one.
Kubernetes API and etcd backup posture
The ClickHouse resources are only as recoverable as the cluster that holds them. Kubernetes stores cluster state in etcd, and the project recommends a five-member etcd cluster in production with a backup plan that uses etcdctl snapshot save and etcdutl for restores. Confirm who owns etcd snapshots, how often they run, and whether a restore has been rehearsed on a spare cluster. A ClickHouse data backup does not replace this, because the cluster definition lives in etcd.
Secrets handling
Kubernetes Secrets are stored unencrypted in etcd by default. For a ClickHouse deployment, that covers user passwords, object storage keys for backups, and TLS private keys issued through cert-manager. Configure encryption at rest for the API server, restrict list and watch access with least-privilege RBAC, and decide whether secrets come from an external store through the Secrets Store CSI Driver. Ask who can read secrets in the ClickHouse namespace before granting access to operators.
Pod Security Standards
ClickHouse and Keeper pods run stateful workloads that need persistent volumes and fixed network identities, so the namespace policy has to allow what the database needs and nothing more. Apply a Pod Security Standard level to the namespace, review any privileged settings the operator or sysctl tuning requires, and confirm that containers do not run with host networking or host paths unless a documented reason exists. Test the policy on a non-production cluster first, because a blocked pod shows up as a failed rollout.
Default ClickHouse user and access control
ClickHouse ships with a default user that starts with all permissions. Before application traffic reaches the cluster, restrict or disable that user, create named users with roles, and use settings profiles and quotas for workload limits. Row policies handle tenant or team separation inside shared tables. The access control documentation recommends managing these through SQL, so decide early whether those statements are applied through operator configuration, migrations or a reviewed change process.
External authenticators
ClickHouse can delegate sign-in to LDAP directories, Kerberos, SSL X.509 certificates, an HTTP authenticator and JWT tokens. Choose one method per access path, for example certificates for service accounts and directory groups for analysts, and confirm that the identity source is reachable from the pods. Test failure behavior, since a directory outage should not lead operators to re-enable a shared password. Document which method each client uses before issuing credentials.
CIS Kubernetes Benchmark as a reference
The CIS Kubernetes Benchmark gives a set of configuration checks for control plane, worker nodes and policies. Use it as a reference list to check the cluster hosting ClickHouse, rather than as a certificate of compliance. Map each relevant check to an owner and record the result, including accepted deviations. Ask your Kubernetes distribution or hardening partner which benchmark version they test against, and whether the results are repeatable after upgrades.
Backups and upgrades still need a plan on Kubernetes
Running ClickHouse on Kubernetes does not change the fact that replication is not a backup. The ClickHouse backup documentation is explicit that replication alone does not protect against human error or corruption: a faulty DROP TABLE or a bad mutation is copied to every replica within seconds. Plan BACKUP and RESTORE as a separate job that runs against the ClickHouseCluster, with a destination you choose from the supported targets: local disk, S3-compatible storage or Azure Blob Storage. Decide where the backup credentials live, how they are rotated, and whether the bucket or container is in a separate failure domain from the cluster. Storage on a PersistentVolumeClaim inside the same cluster protects against very little.
A backup that has never been restored is an assumption. The backup documentation warns that a backup never test-restored will probably not restore properly when needed. Schedule restores into a spare ClickHouseCluster, ideally in a separate namespace or cluster, and record the time to restore and whether row counts and checksums match. Confirm with your own team how often this runs and who signs off on the result, because that record is also the evidence an auditor will ask for.
Version choice comes first. The ClickHouse production FAQ recommends stable releases for most production use and LTS releases for teams that want a longer support window, since LTS releases ship twice a year and are supported for a year. The security policy lists the currently supported versions, and anything outside that list receives no security updates. Set the spec.containers[].image tag in the ClickHouseCluster deliberately and never float to latest. Read the changelog for every version between your current and target release, because minor backward-incompatible changes can occur, and rehearse the upgrade on a pre-production cluster with representative data and queries.
The Kubernetes side has its own constraints. The version skew policy requires the kube-apiserver to be upgraded one minor version at a time, before the kube-controller-manager, kube-scheduler and kubelets, and allows kubelets to be up to three minor versions older than the API server. Check the operator's release notes for the Kubernetes versions it supports before you move the control plane, and confirm which Kubernetes lines your distribution maintains. Upgrade ClickHouse replicas one at a time and verify replication health and Keeper quorum between steps.
Questions teams ask before running the ClickHouse operator
Is the ClickHouse Kubernetes operator production ready at 0.0.x?
A 0.0.x version number means the operator is early in its release life, so it should not be treated as a settled production dependency by default. Whether it fits your environment depends on the features you need, how often the project publishes changes and how much breakage you can absorb. Check the operator's release notes and issue tracker for known gaps, then test your exact topology, including Keeper, storage class behavior and certificate rotation, in a pre-production cluster with representative data. Ask your implementation partner to document which operator version is pinned, how upgrades are tested and what fallback exists if a release fails. The ClickHouse server is a separate track with its own production guidance, so assess the operator and the server versions separately.
What does running ClickHouse on Kubernetes cost, and what drives it?
Cost has three parts: the infrastructure your cloud account or data center charges for, the labor to design and build the deployment, and the ongoing operation after handover. Infrastructure depends on the number of ClickHouse replicas, the Keeper nodes (the ClickHouse replication guide recommends at least three, on dedicated hosts in production, with about 4 GB of RAM each), the storage volume, retention and network traffic. Build labor depends on scope: the number of clusters and environments, TLS and identity integration, and backup targets. DeployOpen works from fixed-scope written agreements, so the quote should list deliverables, environments and assumptions. Ask which items are one-time and which recur, what support hours are included, and who pays for upgrades and restore tests. DeployOpen does not publish a price list.
How long does setup take, and what does it depend on?
The duration should come from a written scope, because it depends mainly on the work your environment needs. The main factors are how many clusters and environments are involved, whether the Kubernetes platform already exists and is current, whether storage classes and cert-manager are ready, whether identity and backup targets are available, and how much pre-production testing with representative data is required. Teams that already run Kubernetes with working storage and certificates usually move faster than teams starting from a bare cluster. Ask the partner to break the timeline into phases: platform checks, installation, data and access setup, backup and restore testing and handover. Also ask which steps depend on your approvals or access, because those waits often decide the calendar more than the build itself.
What must our team provide before the operator is installed?
Your team must provide a supported Kubernetes cluster, people who understand it, storage and a certificate path. The Kubernetes project maintains its three most recent minor releases, and as of September 2026 these were 1.37, 1.36 and 1.35, so choose a version inside that window. Plan minor upgrades one step at a time, with the control plane first, as the version skew policy describes. You also need storage classes that meet ClickHouse's disk needs, cert-manager or another source for TLS certificates, and a safe way to store secrets. Kubernetes stores Secrets unencrypted in etcd by default, so confirm that encryption at rest is configured and that list and watch access is restricted by RBAC. Ask the partner for a written prerequisite checklist with a named owner on your side for each item.
Can our own platform team run ClickHouse on Kubernetes after handover?
Yes, if the team has Kubernetes operations skills and time to own the deployment, but it should not be expected to learn ClickHouse operations from a handover document alone. Routine work includes watching replica and Keeper health, reviewing ClickHouse release notes, applying upgrades and running restore tests. Replicas that recover automatically sync missing data from a healthy replica, but backups still need an owner, because replication does not protect against human error or corruption. Ask for a runbook covering alerts, restore steps, scaling and certificate renewal. Ask also for a session in which your engineers perform a restore on a spare cluster. Decide in advance whether your team will operate alone, keep a support retainer or split duties between the two.
How are ClickHouse and operator upgrades handled?
Upgrades follow two release tracks: the ClickHouse server version and the operator version. ClickHouse ships stable releases roughly monthly, backports fixes to the three latest stable releases and publishes LTS releases twice a year, each supported for a year after release. Its security policy currently lists 26.9, 26.8, 26.7 and 26.3 as supported, so older lines should be retired on a schedule. The production guidance recommends testing in a pre-production environment with representative data and reading the changelog first, because minor backward-incompatible changes can occur. Ask the partner how each upgrade is rehearsed, how replicas and Keeper nodes are rolled one at a time and what rollback looks like if a health check fails. Confirm who approves each change and how the decision is recorded.
How do we protect cluster data, and what must we test?
Replication keeps copies of data available, but it is not a backup. ClickHouse BACKUP and RESTORE support full and incremental backups of tables, partitions or databases to local disk, S3-compatible storage or Azure Blob Storage. The backup documentation warns that a backup never test-restored will probably not restore when you need it. Plan a backup target outside the cluster, a retention period set by your policy and scheduled restore tests on a spare cluster. Confirm the encryption and access controls for backup storage as well, because backups hold the same sensitive data as the cluster. Ask the partner to show a completed restore, how long it took and who signs off on the result.
Does DeployOpen support ClickHouse on Kubernetes after go-live?
Yes, DeployOpen offers ongoing support, upgrades and continuous testing as retainers. Most engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts. DeployOpen deploys inside your own cloud accounts, data centers or air-gapped networks, so your team keeps control of the cluster and the data. Write the support terms down: which environments are covered, response expectations, who handles upgrades, restore tests and certificate renewal. DeployOpen prepares systems, controls and evidence for compliance assessments, but independent auditors and certification bodies issue the reports and certifications. DeployOpen is not a ClickHouse or Kubernetes partner, reseller or certified provider. Ask for the support terms in the written quote.
How DeployOpen scopes and delivers a ClickHouse operator deployment
A DeployOpen engagement for the ClickHouse Operator starts with a fixed scope agreed in writing before any cluster is touched. The written scope names the ClickHouseCluster and KeeperCluster resources to be built, the Kubernetes clusters and namespaces they run in, the storage classes and TLS arrangement, the ClickHouse version to be deployed, and the systems that will ingest data and query it. Each deliverable is listed with its acceptance check: the target architecture with Keeper placement and replica layout, the configured custom resources as code in your repository, the cert-manager issuer and certificate setup, storage class and volume settings, a verification report, and an operations runbook. Because the operator is at a 0.0.x release, the scope should also state which features are in use and which are left out, so that the deliverables match what the project currently supports. A quote follows from this written scope, and it should be compared against your own team's estimate for the same list of items.
Before anything is promoted, the configuration is tested on a pre-production cluster loaded with representative data and realistic queries. This is where the team checks pod rescheduling, Keeper quorum behavior when one node is removed, replica resync after a restart, and certificate rotation. The ClickHouse production guidance recommends this kind of pre-production environment and reading the changelog before every upgrade, so the test plan should also include the target version's release notes. Plan for the one-time work of building the test environment and the recurring work of keeping it aligned with production. Ongoing support is handled separately under a retainer, which can cover operator and ClickHouse upgrades, a tested restore drill, and continuous checks against the configuration. Ask for the retainer scope, response expectations and upgrade responsibilities in writing so that they are not assumed. DeployOpen does not claim partner status or certification for this work.
