#Create an instance

An instance of Alauda Data Services Analytical Database E1 is one ClickHouseInstallation (CHI) resource. The operator converts it into StatefulSets, Services, ConfigMaps and PersistentVolumeClaims.

#Prerequisites

• The operator is installed and running. It is delivered as an OLM bundle whose package name is clickhouse-operator, and the shipped install manifests place it in the operators namespace.
• A StorageClass, if you want persistent data. Without a volume claim template the data directory lives in the pod's writable layer and is lost on restart.
• A running ZooKeeper-compatible quorum, only if you need replication or ON CLUSTER DDL. See Configure a replicated cluster.

#Minimal instance

One shard, one replica, one 20 GiB data volume:

apiVersion: clickhouse.altinity.com/v1
kind: ClickHouseInstallation
metadata:
  name: e1-demo
spec:
  defaults:
    templates:
      dataVolumeClaimTemplate: data-volume
  configuration:
    clusters:
      - name: main
        layout:
          shardsCount: 1
          replicasCount: 1
  templates:
    volumeClaimTemplates:
      - name: data-volume
        spec:
          accessModes:
            - ReadWriteOnce
          resources:
            requests:
              storage: 20Gi

Apply it into the namespace where you want the database to run:

kubectl -n <namespace> apply -f e1-demo.yaml

Note what is absent from that manifest: there is no container image. Leave it out. When a pod template does not name an image, the operator uses the operand image it was configured with at install time, read from the CK_SERVER_IMAGE environment variable and prefixed with the registry from HARBOR. The operator refuses to start if CK_SERVER_IMAGE is empty, and says so by name.

#What the operator creates

For the manifest above, in namespace <namespace>:

A "host" is one shard-replica pair. shardsCount × replicasCount gives the number of hosts, and each host is its own StatefulSet holding exactly one pod — the CRD spells this out: "each replica is a separate StatefulSet which contains only one Pod". Scaling is done by adding hosts, not by raising a StatefulSet's replica count.

#Multi-shard instance

Three shards, no replication, so no ZooKeeper needed:

apiVersion: clickhouse.altinity.com/v1
kind: ClickHouseInstallation
metadata:
  name: e1-sharded
spec:
  defaults:
    templates:
      dataVolumeClaimTemplate: data-volume
      podTemplate: ch-pod
  configuration:
    clusters:
      - name: main
        layout:
          shardsCount: 3
          replicasCount: 1
  templates:
    podTemplates:
      - name: ch-pod
        spec:
          securityContext:
            runAsUser: 101
            runAsGroup: 101
            fsGroup: 101
            runAsNonRoot: true
            seccompProfile:
              type: RuntimeDefault
          containers:
            - name: clickhouse
              resources:
                requests:
                  cpu: "2"
                  memory: 8Gi
                limits:
                  cpu: "4"
                  memory: 16Gi
              securityContext:
                allowPrivilegeEscalation: false
                readOnlyRootFilesystem: true
                capabilities:
                  drop:
                    - ALL
    volumeClaimTemplates:
      - name: data-volume
        spec:
          accessModes:
            - ReadWriteOnce
          resources:
            requests:
              storage: 100Gi

The container in a pod template must be named clickhouse to be treated as the server container. The uid/gid 101 matches the user the server image is built with.

Give the server a memory limit you have sized. A limit that is too small produces OOMKilled and then CrashLoopBackOff — the operator repository ships that exact failure as an example, with a 32 MiB limit.

#Useful top-level spec fields

#Verify

Check pods and StatefulSets, not just the resource status:

kubectl -n <namespace> get chi e1-demo
kubectl -n <namespace> get statefulset,pod -l clickhouse.altinity.com/chi=e1-demo
kubectl -n <namespace> exec chi-e1-demo-main-0-0-0 -c clickhouse -- \
  clickhouse-client -q "SELECT 1"

The instance is healthy when every StatefulSet reports ReadyReplicas equal to its desired replica count — that is precisely the readiness test the operator itself uses. See Instance reports Completed while pods are unhealthy for why the status field alone is not sufficient on older releases.

ClickHouse is a registered trademark of ClickHouse, Inc. https://clickhouse.com

Alauda is an independent vendor. This product is not affiliated with, endorsed by, or sponsored by ClickHouse, Inc. All trademarks are the property of their respective owners and are used here for identification purposes only.