Quantrail Data

In the previous article, we discussed why running ClickHouse® on Kubernetes requires an operator and how it introduces a higher-level abstraction over infrastructure.

If you missed the part 1, you can read it here.

Operating ClickHouse on Kubernetes

The official documentation from Altinity explains how to install the operator and deploy a cluster.

This article focuses on a different objective:

Understanding what happens after deployment.

Specifically:

• How the operator interprets your definition
• What Kubernetes resources are created
• Where configuration comes from

A Minimal ClickHouseInstallation

Consider the following ClickHouseInstallation (CHI) resource:

apiVersion: "clickhouse.altinity.com/v1"
kind: "ClickHouseInstallation"
metadata:
  name: cluster01
spec:
  templates:
    podTemplates:
      - name: clickhouse-pod-template
        spec:
          containers:
            - name: clickhouse
              image: altinity/clickhouse-server:25.8.16.10001.altinitystable

  configuration:
    clusters:
      - name: cluster01
        layout:
          shardsCount: 1
          replicasCount: 1
        templates:
          podTemplate: clickhouse-pod-template

Apply the resource:

kubectl apply -f chi.yaml

This single definition represents the entire database cluster. No StatefulSets, Services, or configuration files are defined explicitly.

The Role of the Custom Resource

The ClickHouseInstallation is not a native Kubernetes object.

It is a Custom Resource Definition (CRD) introduced by the Altinity operator.

This has an important implication:

• Kubernetes stores the resource
• Kubernetes does not act on it directly

The operator watches for these resources and is responsible for:

• Interpreting the specification
• Creating the required Kubernetes objects
• Continuously reconciling the system state

In practical terms:

The CHI resource is not an instruction to Kubernetes.
It is an instruction to the operator.

Without the operator running, applying this resource would have no effect.

Interpreting Pod Identity

After deployment:

kubectl get pods

Example output:

chi-cluster01-cluster01-0-0-0

This naming convention encodes topology:

<chi-name>-<cluster-name>-<shard>-<replica>-<index>

From this, you can determine:

• Shard index
• Replica index
• Logical placement of the node

This detail is essential for debugging purpose.

Resource Translation by the Operator

Although only a single resource was applied, the operator creates multiple Kubernetes objects.

Inspect:

kubectl get statefulsets
kubectl get pvc
kubectl get svc

You will observe:

• StatefulSets managing pod lifecycle
• PersistentVolumeClaims for storage
• Services for internal communication

This is the operator’s core function:

Translating a high-level cluster definition into Kubernetes primitives.

This translation is not a one-time action.
It is continuously maintained through reconciliation.

Configuration Generation and Injection

The CHI definition does not include:

• Cluster configuration files
• Replication settings
• Node-specific identifiers

However, these are required for ClickHouse® to operate correctly.

The operator generates and injects configuration into each node.

To inspect:

kubectl exec -it -n <namespace> <pod-name> -- bash

Then:

ls /etc/clickhouse-server/config.d/

Example output:

01-clickhouse-01-listen.xml  01-clickhouse-03-query_log.xml  01-clickhouse-05-trace_log.xml     chop-generated-settings.xml
01-clickhouse-02-logger.xml  01-clickhouse-04-part_log.xml   chop-generated-remote_servers.xml

You will find generated configuration files defining:

• Cluster topology
• Shard and replica identity
• Internal communication endpoints

This eliminates the need to manually manage configuration across nodes.

Separation of Concerns: Configuration and Templates

The CHI resource separates intent into two layers:

• configuration – defines cluster topology
• templates – defines how nodes are constructed

In this example:

templates:
  podTemplates:

The pod template specifies the container image and runtime configuration.

It is referenced here:

templates:
  podTemplate: clickhouse-pod-template

This design allows:

• Reuse across nodes
• Consistent configuration
• Simplified updates

Storage Characteristics

Each node is provisioned with its own persistent storage.

Verify:

kubectl get pvc

Example output:

• Storage is not shared between nodes
• Each node maintains its own data
• Replication is handled at the database level

This distinction is important when designing for reliability and scaling.

Key Observations

From a minimal CHI definition, the system derives:

• Topology-aware pod identities
• Persistent storage per node
• Network configuration for inter-node communication
• Complete ClickHouse® cluster configuration

The operator is not simply deploying containers.

It is implementing a distributed system based on a declarative specification.

Exploring ClickHouse® for Your Analytics?

At Quantrail Data, we help teams run ClickHouse® reliably for real-time analytics – from Kubernetes deployments and migrations to performance tuning in production.

We see these challenges firsthand while supporting demanding analytics workloads. In one recent engagement, a customer achieved near bare-metal performance with ClickHouse® in production – a story we’ve shared here:
Success Story: Quantrail Bare-Metal ClickHouse® Deployment

If you’re evaluating ClickHouse® or trying to get more out of an existing setup, we’re happy to share practical lessons from real-world deployments.

Contact
Quantrail Data

Conclusion

The ClickHouseInstallation resource serves as the control interface for defining a ClickHouse® cluster on Kubernetes.

The operator translates this definition into:

• Kubernetes infrastructure
• Runtime configuration
• A consistent and recoverable system state

Understanding this translation is essential for effective debugging and operation.

References

https://docs.altinity.com/altinitykubernetesoperator

https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources