Installing EDB Postgres AI for ClickHouse on Kubernetes

Installing EDB Postgres AI for ClickHouse on Kubernetes#

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 .

Note

The username must match the repository you're pulling from. Docker stores credentials keyed by registry with no distinction between repositories, so each login overwrites the previous one. If you need to pull images from a different repository on docker.enterprisedb.com , log in again with the appropriate username.

Installing the operator#

  1. Add the EDB Helm repository:

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

  1. Install the chart:

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

  1. Verify the operator is running:

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.

  1. Confirm the CRDs registered:

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. The default password for the default user is admin123 :

clickhouse-client --host 127.0.0.1 --port 9000 --password admin123

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 --password admin123 --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
Contents