Installing EDB Postgres AI for ClickHouse on Kubernetes v26.3

The EDB ClickHouse Kubernetes operator manages ClickHouse deployments on Kubernetes, handling cluster provisioning, configuration, upgrades, and scaling.

When installed via the Helm chart, it creates:

• Four CustomResourceDefinitions (CRDs):
  • clickhouseinstallations (abbreviated chi)
  • clickhouseinstallationtemplates
  • clickhouseoperatorconfigurations
  • clickhousekeeperinstallations (abbreviated chk)
• A Deployment running the operator and metrics-exporter sidecar (2/2 Ready).
• A ServiceAccount, Role, ClusterRole, and bindings the operator needs to manage ClickHouse resources cluster-wide.

Prerequisites

• A running Kubernetes cluster (1.26 or later)
• kubectl configured to talk to your cluster
• Helm 3.8 or later
• An EDB subscription token, available from the EDB customer portal. You'll use this both in the Helm chart repo URL and as the Docker password when Kubernetes pulls images.

Creating the image pull secret

Kubernetes needs credentials to pull EDB container images from docker.enterprisedb.com. Create a docker-registry secret in the namespace you'll install the operator into:

export EDB_SUBSCRIPTION_TOKEN=<your-token>
kubectl create namespace clickhouse
kubectl create secret docker-registry cs-pull \
  --namespace=clickhouse \
  --docker-server=docker.enterprisedb.com \
  --docker-username=clickhouse \
  --docker-password="$EDB_SUBSCRIPTION_TOKEN"

You'll reference cs-pull in the Helm install so the operator pod can pull its own images, and in every ClickHouseInstallation so the ClickHouse pods can pull edb-clickhouse-server.

Installing the operator

1. Add the EDB Helm repository:

   → WrapCopy

   helm repo add edb \
     "https://dl.cloudsmith.io/$EDB_SUBSCRIPTION_TOKEN/enterprisedb/clickhouse/helm/charts/"
   helm repo update edb

2. Install the chart:

   → WrapCopy

   helm upgrade --install clickhouse-operator \
     edb/edb-clickhouse-operator-chart \
     --version 0.27.1+1edb1 \
     --namespace clickhouse \
     --set 'imagePullSecrets[0].name=cs-pull'

3. Verify the operator is running:

   → WrapCopy

   kubectl get pods -n clickhouse

   The operator pod reports 2/2 Ready within about 30 seconds — the two containers are the operator and the metrics-exporter sidecar.

4. Confirm the CRDs registered:

   → WrapCopy

   kubectl get crds | grep clickhouse

   All four CRDs listed above appear in the output.

Creating a ClickHouse cluster

The operator watches for ClickHouseInstallation resources and reconciles them into running ClickHouse pods. Create a file named clickhouse-installation.yaml:

apiVersion: clickhouse.altinity.com/v1
kind: ClickHouseInstallation
metadata:
  name: my-clickhouse
  namespace: clickhouse
spec:
  configuration:
    clusters:
      - name: my-cluster
        templates:
          podTemplate: edb-clickhouse
        layout:
          shardsCount: 1
          replicasCount: 1
  templates:
    podTemplates:
      - name: edb-clickhouse
        spec:
          imagePullSecrets:
            - name: cs-pull
          containers:
            - name: clickhouse
              image: docker.enterprisedb.com/clickhouse/edb-clickhouse-server:26.3.13.31-1edb1
              ports:
                - name: http
                  containerPort: 8123
                - name: client
                  containerPort: 9000

Note that imagePullSecrets appears inside the pod template — this applies to the ClickHouse pods the operator creates, not the operator pod itself. Both need it.

Check your release notes for the edb-clickhouse-server version compatible with your operator version.

Apply the resource and watch the cluster come up:

kubectl apply -f clickhouse-installation.yaml
kubectl get chi -n clickhouse -w

Wait until STATUS shows Completed, which takes about 60 to 90 seconds.

Connecting to ClickHouse

The operator creates a headless Service per cluster. Connect via the Service name using port forwarding:

kubectl port-forward -n clickhouse svc/clickhouse-my-clickhouse 9000:9000

Then in another terminal:

clickhouse-client --host 127.0.0.1 --port 9000

Or run a one-shot query inside the cluster:

kubectl exec -it -n clickhouse \
  "$(kubectl get pods -n clickhouse -l clickhouse.altinity.com/chi=my-clickhouse -o name | head -1)" \
  -- clickhouse-client --query "SELECT version()"

The version returned includes the (EDB Build) suffix, confirming you're running the EDB distribution.

Uninstalling

kubectl delete chi my-clickhouse -n clickhouse        # operator deletes pods and services
helm uninstall clickhouse-operator -n clickhouse      # removes the operator Deployment; CRDs survive
kubectl delete secret cs-pull -n clickhouse           # optional

CRDs are intentionally not deleted by helm uninstall. Deleting CRDs deletes every dependent ClickHouseInstallation, including any in other namespaces. Remove them only if you have no other operator instances in the cluster:

kubectl delete crd \
  clickhouseinstallations.clickhouse.altinity.com \
  clickhouseinstallationtemplates.clickhouse.altinity.com \
  clickhouseoperatorconfigurations.clickhouse.altinity.com \
  clickhousekeeperinstallations.clickhouse-keeper.altinity.com