Try It Out

This guide installs a single cluster-wide ClickHouse Operator in a dedicated test or development cluster.

• A running Kubernetes cluster (v1.21 or higher is recommended)
• Helm v3.8 or higher for OCI support (Installation instructions)
• kubectl installed and configured

Step 1: Start Cluster

If you have a cluster to work with, skip this step. Otherwise, start a Minikube cluster. Deployment instructions

Add the Helm chart to your local Helm client.

helm repo add altinity https://helm.altinity.com
helm repo update

Note that the Altinity Helm repository offers 2 different charts for deploying the operator, depending on the scope:

• altinity/altinity-clickhouse-operator deploys only the Operator image
• clickhouse/clickhouse deploys the full ClickHouse stack including the Operator, Keeper, and metrics-exporter on a test cluster

The recommended production pattern is to install the operator once per cluster, then deploy ClickHouse separately—either with a ClickHouseInstallation custom resource or via the clickhouse/clickhouse chart with operator.enabled: false in your values file. The key is to avoid running two operators.

Create a namespace:

kubectl create ns clickhouse

Save the file below as values.yaml

crdHook:
  enabled: true
  image:
    repository: reg.mini.dev/kubectl
    tag: latest

operator:
  image:
    repository: reg.mini.dev/clickhouse-operator
    tag: latest

metrics:
  enabled: true
  image:
    repository: reg.mini.dev/clickhouse-metrics-exporter
    tag: latest

Render the chart locally with the overrides to confirm Minimus images will be deployed:

helm template clickhouse-operator -f values.yaml altinity/altinity-clickhouse-operator | grep "image:" | sort -u

Deploy the cluster-wide operator:

helm upgrade --install clickhouse-operator altinity/altinity-clickhouse-operator -f values.yaml -n clickhouse-operator

Wait a minute and check that the operator pod is up and running:

kubectl -n clickhouse-operator get po

Confirm that Minimus images were deployed:

kubectl -n clickhouse-operator describe pods | grep Image:

Check operator logs to confirm it started successfully:

kubectl -n clickhouse-operator logs -l app.kubernetes.io/instance=clickhouse-operator --all-containers --tail=20

To deploy a ClickHouse cluster next, follow the Keeper or Metrics-Exporter guides, making sure to set operator.enabled: false in your values file.

Uninstall the chart and clean up:

helm uninstall clickhouse-operator -n clickhouse-operator
kubectl delete ns clickhouse-operator

Technical Considerations

The ClickHouse-Operator image provided by Minimus is a slim, security-hardened alternative to the public image from Docker Hub. The images are largely interchangeable, with a few differences as noted below.

Terms & Info

This catalog is published by Minimus. All product names, logos, and marks, other than those belonging to Minimus, shown are owned by their respective rights holders and appear here only to identify the open source software each image contains. Minimus claims no ownership of those marks and implies no affiliation with, endorsement by, certification by, or sponsorship by any rights holder.

Images are provided "as-is" without warranty of any kind. "Hardened" refers to the security configuration applied at the time of build and does not constitute a guarantee of ongoing security or absence of vulnerabilities. The free tier is provided without support, SLA, or guaranteed patching timelines. Security updates may be applied to paid subscriptions before or instead of free tier images. By pulling or using any image you agree to our Terms of Use.