ClickHouse Operator configuration guide

[Edit this page](https://github.com/ClickHouse/clickhouse-docs/blob/main/docs/kubernetes-operator/03_guides/02_configuration.mdx)

This guide covers how to configure ClickHouse and Keeper clusters using the operator.

## ClickHouseCluster configuration[​](#clickhousecluster-configuration "Direct link to ClickHouseCluster configuration")

### Basic configuration[​](#basic-configuration "Direct link to Basic configuration")

```
apiVersion: clickhouse.com/v1alpha1
kind: ClickHouseCluster
metadata:
  name: my-cluster
spec:
  replicas: 3           # Number of replicas per shard
  shards: 2             # Number of shards
  keeperClusterRef:
    name: my-keeper     # Reference to KeeperCluster
  dataVolumeClaimSpec:
    accessModes:
      - ReadWriteOnce
    resources:
      requests:
        storage: 10Gi
```

### Replicas and shards[​](#replicas-and-shards "Direct link to Replicas and shards")

- **Replicas**: Number of ClickHouse instances per shard (for high availability)
- **Shards**: Number of horizontal partitions (for scaling)

```
spec:
  replicas: 3  # Default: 3
  shards: 2    # Default: 1
```

A cluster with `replicas: 3` and `shards: 2` will create 6 ClickHouse pods total.

### Keeper integration[​](#keeper-integration "Direct link to Keeper integration")

Every ClickHouse cluster must reference a KeeperCluster for coordination:

```
spec:
  keeperClusterRef:
    name: my-keeper  # Name of the KeeperCluster in the same namespace
```

## KeeperCluster configuration[​](#keepercluster-configuration "Direct link to KeeperCluster configuration")

```
apiVersion: clickhouse.com/v1alpha1
kind: KeeperCluster
metadata:
  name: my-keeper
spec:
  replicas: 3  # Must be odd: 1, 3, 5, 7, 9, 11, 13, or 15
  dataVolumeClaimSpec:
    accessModes:
      - ReadWriteOnce
    resources:
      requests:
        storage: 5Gi
```

## Storage configuration[​](#storage-configuration "Direct link to Storage configuration")

Configure persistent storage:

```
spec:
  dataVolumeClaimSpec:
    storageClassName: fast-ssd  # Optional: consider your storage class based on the installed CSI
    accessModes:
      - ReadWriteOnce
    resources:
      requests:
        storage: 100Gi
```

Note

Operator can modify existing PVC only if the underlying storage class supports volume expansion.

## Pod configuration[​](#pod-configuration "Direct link to Pod configuration")

### Automatic topology spread and affinity[​](#automatic-topology-spread-and-affinity "Direct link to Automatic topology spread and affinity")

Distribute pods across availability zones:

```
spec:
  podTemplate:
    topologyZoneKey: topology.kubernetes.io/zone
    nodeHostnameKey: kubernetes.io/hostname
```

Note

Ensure your Kubernetes cluster has enough nodes in different zones to satisfy the spread constraints.

### Manual configuration[​](#manual-configuration "Direct link to Manual configuration")

Arbitrary pod affinity/anti-affinity rules and topology spread constraints can be specified.

```
spec:
  podTemplate:
    affinity:
      <your-affinity-rules-here>
    topologySpreadConstraints:
      <your-topology-spread-constraints-here>
```

### See [API Reference](/docs/clickhouse-operator/reference/api-reference#podtemplatespec) for all supported Pod template options.[​](#see-api-reference-for-all-supported-pod-template-options "Direct link to see-api-reference-for-all-supported-pod-template-options")

## Container configuration[​](#container-configuration "Direct link to Container configuration")

### Custom image[​](#custom-image "Direct link to Custom image")

Use a specific ClickHouse image:

```
spec:
  containerTemplate:
    image:
      repository: clickhouse/clickhouse-server
      tag: "25.12"
    imagePullPolicy: IfNotPresent
```

### Container resources[​](#container-resources "Direct link to Container resources")

Configure CPU and memory for ClickHouse containers:

```
# default values
spec:
  containerTemplate:
    resources:
      requests:
        cpu: "250m"
        memory: "256Mi"
      limits:
        cpu: "1"
        memory: "1Gi"
```

### Environment variables[​](#environment-variables "Direct link to Environment variables")

Add custom environment variables:

```
spec:
  containerTemplate:
    env:
    - name: CUSTOM_ENV_VAR
      value: "1"
```

### Volume mounts[​](#volume-mounts "Direct link to Volume mounts")

Add additional volume mounts:

```
spec:
  containerTemplate:
    volumeMounts:
    - name: custom-config
      mountPath: /etc/clickhouse-server/config.d/custom.xml
      subPath: custom.xml
```

Note

It is allowed to specify multiple volume mounts to the same `mountPath`.
Operator will create projected volume with all specified mounts.

### See [API Reference](/docs/clickhouse-operator/reference/api-reference#containertemplatespec) for all supported Container template options.[​](#see-api-reference-for-all-supported-container-template-options "Direct link to see-api-reference-for-all-supported-container-template-options")

## TLS/SSL configuration[​](#tls-ssl-configuration "Direct link to TLS/SSL configuration")

### Configure secure endpoints[​](#configure-secure-endpoints "Direct link to Configure secure endpoints")

Pass a reference to a Kubernetes Secret containing TLS certificates to enable secure endpoints

```
spec:
  settings:
    tls:
      enabled: true
      required: true # Insecure ports are disabled if set
      serverCertSecret:
        name: <certificate-secret-name>
```

### SSL certificate secret format[​](#ssl-certificate-secret-format "Direct link to SSL certificate secret format")

It is expected that the Secret contains the following keys:

- `tls.crt` - PEM encoded server certificate
- `tls.key` - PEM encoded private key
- `ca.crt` - PEM encoded CA certificate chain

Note

This format is compatible with cert-manager generated certificates.

### ClickHouse-Keeper communication over TLS[​](#clickhouse-keeper-communication-over-tls "Direct link to ClickHouse-Keeper communication over TLS")

If KeeperCluster has TLS enabled, ClickHouseCluster would use secure connection to Keeper nodes automatically.

ClickHouseCluster should be able to verify Keeper nodes certificates.
If ClickHouseCluster has TLS enabled, is uses `ca.crt` bundle for verification. Otherwise, default CA bundle is used.

User may provide a custom CA bundle reference:

```
spec:
    settings:
        tls:
          caBundle:
            name: <ca-certificate-secret-name>
            key: <ca-certificate-key>
```

## ClickHouse settings[​](#clickhouse-settings "Direct link to ClickHouse settings")

### Default user password[​](#default-user-password "Direct link to Default user password")

Set the default user password:

```
spec:
  settings:
    defaultUserPassword:
      passwordType: <password-type> # Default: password
      <secret|configMap>:
        name: <resource name>
        key: <password>
```

Note

It isn't recommended to use ConfigMap to store plain text passwords.

Create the secret:

```
kubectl create secret generic clickhouse-password --from-literal=password='your-secure-password'
```

#### Using ConfigMap for user passwords[​](#using-configmap-for-user-passwords "Direct link to Using ConfigMap for user passwords")

You can also use ConfigMap for non-sensitive default passwords:

```
spec:
  settings:
    defaultUserPassword:
      passwordType: password_sha256_hex
      configMap:
        name: clickhouse-config
        key: default_password
```

### Custom users in configuration[​](#custom-users-in-configuration "Direct link to Custom users in configuration")

Configure additional users in configuration files.

Create a ConfigMap and Secret for user:

```
apiVersion: v1
kind: ConfigMap
metadata:
  name: user-config
data:
  reader.yaml: |
    users:
      reader:
        password:
          - '@from_env': READER_PASSWORD
        profile: default
        grants:
          - query: "GRANT SELECT ON *.*"
---
apiVersion: v1
kind: Secret
metadata:
  name: reader-password
data:
  password: "c2VjcmV0LXBhc3N3b3Jk"  # base64("secret-password")
```

Add custom configuration to ClickHouseCluster: