Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

Install the ClickHouse Operator with kubectl

View as MarkdownEdit this pageReport an issueSet up docs MCP

This guide covers installing the ClickHouse Operator using kubectl and manifest files.

Prerequisites

  • Kubernetes cluster v1.28.0 or later
  • kubectl v1.28.0 or later
  • Cluster admin permissions

Install from Release Manifests

Install the operator and CRDs from the latest release:

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

Server-side apply is required because the combined CRDs exceed the client-side apply size limit. For environments that only support client-side apply, use the description-stripped CRD variant:

kubectl apply -f https://github.com/ClickHouse/clickhouse-operator/releases/latest/download/clickhouse-operator-stripped-crds.yaml

This will:

  1. Create the clickhouse-operator-system namespace
  2. Install CustomResourceDefinitions (CRDs) for ClickHouseCluster and KeeperCluster
  3. Create necessary ServiceAccounts, Roles, and RoleBindings
  4. Deploy the operator controller manager
  5. Register webhooks for resource validation and defaulting
  6. Configure SSL certificates using cert-manager
  7. Enable metrics endpoint

Verify Installation

Check that the operator is running:

kubectl get pods -n clickhouse-operator-system

Expected output:

NAME                                                 READY   STATUS    RESTARTS   AGE
clickhouse-operator-controller-manager-xxxxxxxxxx    1/1     Running   0          1m

Verify the CRDs are installed:

kubectl get crd | grep clickhouse.com

Expected output:

clickhouseclusters.clickhouse.com    2025-01-06T00:00:00Z
keeperclusters.clickhouse.com        2025-01-06T00:00:00Z

Configure Custom Deployment Options

If you want to configure operator deployment options, follow the steps below.

Clone the Repository

git clone https://github.com/ClickHouse/clickhouse-operator.git
cd clickhouse-operator

Configure installation options

Edit config/default/kustomization.yaml to enable/disable features as needed.

  • To disable webhooks, comment out the [WEBHOOK] and [CERTMANAGER] sections.
  • To enable secure metrics endpoint, comment out [METRICS] sections and uncomment [METRICS SECURE] and [CERTMANAGER] sections.
  • To enable ServiceMonitor for Prometheus Operator, uncomment the [PROMETHEUS] section.
  • To enable operator network policies, uncomment the [NETWORK POLICY] section.

Build and Deploy

Build the operator manifests and apply them:

make build-installer VERSION=<required operator version> [IMG=<custom registry path>]
kubectl apply --server-side --force-conflicts -f dist/install.yaml
Navigation