ClickHouse/clickhouse-operator: Official Kubernetes Operator for ClickHouse®

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:

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

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

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

1. Deploy a sample cluster:

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

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

1. Verify the deployment:

kubectl get clickhouseclusters
   kubectl get keeperclusters
   kubectl get pods

Deploy from the sources

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

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

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

To Uninstall

make uninstall

UnDeploy the controller from the cluster:

make undeploy

Documentation