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):

   • 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
     

2. 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
     

3. 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

• Kubebuilder Documentation
• ClickHouse Documentation
• Slack channel