Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

ClickHouse Operator API reference

View as MarkdownEdit this pageReport an issueSet up docs MCP

This document provides detailed API reference for the ClickHouse Operator custom resources.

AdditionalPort

AdditionalPort declares one extra TCP port to expose on the ClickHouse Pod and the public headless Service.

Field Type Description Required Default
name string Name uniquely identifies the port within the list. Used as both the container port name and the Service port name.
This must be a DNS_LABEL.		 true
port integer Port is the TCP port number to expose. true

Appears in:

CABundleSelector

CABundleSelector selects a key holding a CA bundle from a Secret in the cluster’s namespace.

Field Type Description Required Default
name string The name of the secret in the cluster’s namespace to select from. true
key string The key of the secret to select from. Must be a valid secret key. false ca.crt

Appears in:

ClickHouseCluster

ClickHouseCluster is the Schema for the clickhouseclusters API.

API Version and Kind

apiVersion: clickhouse.com/v1alpha1
kind: ClickHouseCluster
Field Type Description Required Default
spec ClickHouseClusterSpec true
status ClickHouseClusterStatus true

Appears in:

ClickHouseClusterList

ClickHouseClusterList contains a list of ClickHouseCluster.

API Version and Kind

apiVersion: clickhouse.com/v1alpha1
kind: ClickHouseClusterList
Field Type Description Required Default
items ClickHouseCluster array true

ClickHouseClusterSpec

ClickHouseClusterSpec defines the desired state of ClickHouseCluster.

Field Type Description Required Default
replicas integer Number of replicas in the single shard. false 3
shards integer Number of shards in the cluster. false 1
keeperClusterRef KeeperClusterReference Reference to the KeeperCluster that is used for ClickHouse coordination.
When namespace is omitted, the ClickHouseCluster namespace is used.		 true
podTemplate PodTemplateSpec Parameters passed to the ClickHouse pod spec. false
containerTemplate ContainerTemplateSpec Parameters passed to the ClickHouse container spec. false
dataVolumeClaimSpec PersistentVolumeClaimSpec Specification of persistent storage for ClickHouse data. false
additionalVolumeClaimTemplates PersistentVolumeClaimTemplate array Additional per-pod PVC templates for JBOD / multi-disk storage.
Each entry is propagated in StatefulSet volumeClaimTemplate, mounted at /var/lib/clickhouse/disks/<name> and
added to the generated JBOD storage policy.
The set of disks is fixed at creation.		 false
labels object (keys:string, values:string) Additional labels that are added to resources. false
annotations object (keys:string, values:string) Additional annotations that are added to resources. false
podDisruptionBudget PodDisruptionBudgetSpec PodDisruptionBudget configures the PDB created for each shard.
When unset, the operator defaults to maxUnavailable=1 for single-replica
shards and minAvailable=1 for multi-replica shards.		 false
networkPolicy ClickHouseNetworkPolicySpec NetworkPolicy configures the NetworkPolicy managed for the cluster. false
settings ClickHouseSettings Configuration parameters for ClickHouse server. false { }
clusterDomain string ClusterDomain is the Kubernetes cluster domain suffix used for DNS resolution. false cluster.local
upgradeChannel string UpgradeChannel specifies the release channel for major version upgrade checks.
When empty, only minor updates will be proposed. Allowed values are: stable, lts or specific major.minor version (e.g. 25.8).		 false
versionProbeTemplate VersionProbeTemplate VersionProbeTemplate overrides for the version detection Job. false
externalSecret ExternalSecret ExternalSecret is an optional reference to an externally-managed Secret containing cluster secrets.
The secret must reside in the same namespace as the cluster.		 false
additionalPorts AdditionalPort array AdditionalPorts declares extra TCP ports to expose on the ClickHouse Pod and the public headless Service.
The operator only adds the ports to the Kubernetes resources, it does not configure the ClickHouse server to listen on them.		 false

Appears in:

ClickHouseClusterStatus

ClickHouseClusterStatus defines the observed state of ClickHouseCluster.

Field Type Description Required Default
conditions Condition array false
readyReplicas integer ReadyReplicas Total number of replicas ready to serve requests. false
configurationRevision string ConfigurationRevision indicates target configuration revision for every replica. true
statefulSetRevision string StatefulSetRevision indicates target StatefulSet revision for every replica. true
currentRevision string CurrentRevision indicates latest applied ClickHouseCluster spec revision. true
updateRevision string UpdateRevision indicates latest requested ClickHouseCluster spec revision. true
observedGeneration integer ObservedGeneration indicates latest generation observed by controller. true
version string Version indicates the version reported by the container image. false
versionProbeRevision string VersionProbeRevision is the image hash of the last successful version probe.
When this matches the current image hash, the cached Version is used directly.		 false

Appears in:

ClickHouseNetworkPolicySpec

ClickHouseNetworkPolicySpec configures the NetworkPolicy managed for the ClickHouse cluster. The managed policy covers cluster-internal traffic:

  • Inter replica connectivity
  • Access from the operator to the cluster Any other ingress, including client connections and metrics scraping, requires user-defined NetworkPolicies.
Field Type Description Required Default
policy NetworkPolicyPolicy Policy controls whether the operator manages a NetworkPolicy restricting ingress to the cluster Pods.
Defaults to “Disabled” when unset.		 false Disabled

Appears in:

ClickHouseSettings

ClickHouseSettings defines ClickHouse server settings options.

Field Type Description Required Default
defaultUserPassword DefaultPasswordSelector Specifies source and type of the password for default ClickHouse user. false
logger LoggerConfig Configuration of ClickHouse server logging. false
tls ClusterTLSSpec TLS settings, allows to configure secure endpoints and certificate verification for ClickHouse server. false
encryption EncryptionSettings Encryption, when set, enables at-rest encryption of table data through a dedicated storage policy.
Opt in per table with SETTINGS storage_policy = '<policyName>'.		 false
enableDatabaseSync boolean Enables synchronization of ClickHouse databases to the newly created replicas and cleanup of stale replicas
after scale down.
Supports only Replicated and integration databases.		 false true
extraConfig RawExtension Additional ClickHouse configuration that will be merged with the default one. false
extraUsersConfig RawExtension Additional ClickHouse users configuration that will be merged with the default one. false

Appears in:

ClusterTLSSpec

ClusterTLSSpec defines cluster TLS configuration.

Field Type Description Required Default
enabled boolean Enabled indicates whether TLS is enabled, determining if secure ports should be opened. false false
required boolean Required specifies whether TLS must be enforced for all connections. Disables not secure ports. false false
serverCertSecret LocalObjectReference ServerCertSecret is a reference to a TLS Secret containing the server certificate.
It is expected that the Secret has the same structure as certificates generated by cert-manager,
with the certificate and private key stored under “tls.crt” and “tls.key” keys respectively.		 false
caBundle CABundleSelector CABundle is a reference to a Secret key holding a CA bundle used to verify peer certificates.
If empty, the system trusted CA bundle is used.
Key is defaulted to “ca.crt” if not specified.		 false

Appears in:

ConfigMapKeySelector

ConfigMapKeySelector selects a key of a ConfigMap.

Field Type Description Required Default
name string The name of the ConfigMap in the cluster’s namespace to select from. true
key string The key of the ConfigMap to select from. Must be a valid key. true

Appears in:

ContainerImage

ContainerImage defines a container image with repository, tag or hash.

Field Type Description Required Default
repository string Container image registry name
Example: docker.io/clickhouse/clickhouse		 false
tag string Container image tag, mutually exclusive with ‘hash’.
Example: 25.3		 false
hash string Container image hash, mutually exclusive with ‘tag’. false

Appears in:

ContainerTemplateSpec

ContainerTemplateSpec describes the container configuration overrides for the cluster’s containers.

Field Type Description Required Default
image ContainerImage Image is the container image to be deployed. true
imagePullPolicy PullPolicy ImagePullPolicy for the image, which defaults to IfNotPresent. false
resources ResourceRequirements Resources is the resource requirements for the server container.
Applied as a whole: operator defaults are used only when all resource fields are empty.		 false
volumeMounts VolumeMount array VolumeMounts is the list of volume mounts for the container.
Concatenated with operator-generated mounts. Entries sharing a mountPath with an operator
mount are merged into a projected volume.		 false
env EnvVar array Env is the list of environment variables to set in the container.
Merged with operator defaults by name.		 false
securityContext SecurityContext SecurityContext defines the security options the container should be run with.
A non-nil SecurityContext fully replaces operator defaults; the user owns the
entire struct. When nil, operator defaults are preserved.
More info: https://kubernetes.io/docs/tasks/configure-pod-container/security-context/		 false
livenessProbe Probe LivenessProbe overrides the operator’s default liveness probe. false
readinessProbe Probe ReadinessProbe overrides the operator’s default readiness probe. false

Appears in:

DefaultPasswordSelector

DefaultPasswordSelector selects the source for the default user’s password.

Field Type Description Required Default
passwordType string Type of the provided password. Consider documentation for possible values https://clickhouse.com/docs/operations/settings/settings-users#user-namepassword true password
secret SecretKeySelector Select password value from a Secret key false
configMap ConfigMapKeySelector Select password value from a ConfigMap key false

Appears in:

EncryptionSettings

EncryptionSettings enables at-rest encryption of table data. When present, the operator generates an encrypted ClickHouse storage policy wrapping every data disk; tables opt in via SETTINGS storage_policy. Encryption cannot be disabled once enabled.

Field Type Description Required Default
policyName string PolicyName is the name of the generated encrypted storage policy. false encrypted

Appears in:

ExternalSecret

ExternalSecret is a reference to a Secret in the same namespace.

Field Type Description Required Default
name string Name of the Secret. true
policy ExternalSecretPolicy Policy controls how the operator treats the secret’s content.
Observe (default): blocks reconciliation if any required key is missing.
Manage: generates missing required keys into the existing secret.		 false Observe

Appears in:

ExternalSecretPolicy

ExternalSecretPolicy controls how the operator treats the external secret’s content.

Field Description
Observe ExternalSecretPolicyObserve is the default policy: the operator reads and validates the secret;
reconciliation is blocked if any required key is absent.
Missing required keys and their expected formats are reported via the ExternalSecretValid status condition at runtime.
Manage ExternalSecretPolicyManage is the policy where the operator fills in any missing required keys by generating
values for them. The secret is updated but never owned or deleted by the operator.

Appears in:

KeeperCluster

KeeperCluster is the Schema for the keeperclusters API.

API Version and Kind

apiVersion: clickhouse.com/v1alpha1
kind: KeeperCluster
Field Type Description Required Default
spec KeeperClusterSpec true
status KeeperClusterStatus true

Appears in:

KeeperClusterList

KeeperClusterList contains a list of KeeperCluster.

API Version and Kind

apiVersion: clickhouse.com/v1alpha1
kind: KeeperClusterList
Field Type Description Required Default
items KeeperCluster array true

KeeperClusterReference

KeeperClusterReference identifies the KeeperCluster used by a ClickHouseCluster.

Field Type Description Required Default
name string Name of the KeeperCluster resource. true
namespace string Namespace of the KeeperCluster resource.
When omitted, the ClickHouseCluster namespace is used.		 false

Appears in:

KeeperClusterSpec

KeeperClusterSpec defines the desired state of KeeperCluster.

Field Type Description Required Default
replicas integer Number of replicas in the cluster false 3
podTemplate PodTemplateSpec Parameters passed to the Keeper pod spec. false
containerTemplate ContainerTemplateSpec Parameters passed to the Keeper container spec. false
dataVolumeClaimSpec PersistentVolumeClaimSpec Specification of persistent storage for ClickHouse Keeper data. false
labels object (keys:string, values:string) Additional labels that are added to resources. false
annotations object (keys:string, values:string) Additional annotations that are added to resources. false
podDisruptionBudget PodDisruptionBudgetSpec PodDisruptionBudget configures the PDB created for the Keeper cluster.
When unset, the operator defaults to maxUnavailable=replicas/2
(preserving quorum for a 2F+1 cluster); single-replica clusters use maxUnavailable=1.		 false
networkPolicy KeeperNetworkPolicySpec NetworkPolicy configures the NetworkPolicy managed for the Keeper cluster. false
settings KeeperSettings Configuration parameters for ClickHouse Keeper server. false
clusterDomain string ClusterDomain is the Kubernetes cluster domain suffix used for DNS resolution. false cluster.local
upgradeChannel string UpgradeChannel specifies the release channel for major version upgrade checks.
When empty, only minor updates will be proposed. Allowed values are: stable, lts or specific major.minor version (e.g. 25.8).		 false
versionProbeTemplate VersionProbeTemplate VersionProbeTemplate overrides for the version detection Job.
Deprecated: Keeper version probe Jobs are not used; this field is retained for backward compatibility.		 false

Appears in:

KeeperClusterStatus

KeeperClusterStatus defines the observed state of KeeperCluster.

Field Type Description Required Default
conditions Condition array false
readyReplicas integer ReadyReplicas Total number of replicas ready to serve requests. false
configurationRevision string ConfigurationRevision indicates target configuration revision for every replica. true
statefulSetRevision string StatefulSetRevision indicates target StatefulSet revision for every replica. true
currentRevision string CurrentRevision indicates latest applied KeeperCluster spec revision. true
updateRevision string UpdateRevision indicates latest requested KeeperCluster spec revision. true
observedGeneration integer ObservedGeneration indicates latest generation observed by controller. true
version string Version indicates the version reported by the Keeper server. false
versionProbeRevision string VersionProbeRevision is the image hash of the last successful version probe.
Deprecated: Keeper version probe Jobs are not used; this field is retained for backward compatibility.		 false

Appears in:

KeeperNetworkPolicySpec

KeeperNetworkPolicySpec configures the NetworkPolicy managed for the Keeper cluster. The managed policy covers cluster-internal traffic:

  • Inter replica connectivity
  • Access from the operator to the cluster
  • Access from ClickHouse clusters referencing this Keeper cluster Any other ingress, including metrics scraping, requires user-defined NetworkPolicies.
Field Type Description Required Default
policy NetworkPolicyPolicy Policy controls whether the operator manages a NetworkPolicy restricting ingress to the Keeper Pods.
Defaults to “Disabled” when unset.		 false Disabled

Appears in:

KeeperSettings

KeeperSettings defines ClickHouse Keeper server configuration.

Field Type Description Required Default
logger LoggerConfig Configuration of ClickHouse Keeper server logging. false
tls ClusterTLSSpec TLS settings, allows to configure secure endpoints and certificate verification for ClickHouse Keeper server. false
extraConfig RawExtension Additional ClickHouse Keeper configuration that will be merged with the default one. false

Appears in:

LoggerConfig

LoggerConfig defines server logging configuration.

Field Type Description Required Default
logToFile boolean If false then disable all logging to file. false true
jsonLogs boolean If true, then log in JSON format. false false
level string Server logger verbosity level. false trace
size string Maximum log file size. false 1000M
count integer Maximum number of log files to keep. false 50

Appears in:

NamedTemplateMeta

NamedTemplateMeta defines supported metadata settings for template objects that require a name.

Field Type Description Required Default
name string Name is the resource identifier. true
labels object (keys:string, values:string) Labels are labels applied to the template objects. false
annotations object (keys:string, values:string) Annotations are annotations applied to the template objects. false

Appears in:

NetworkPolicyPolicy

NetworkPolicyPolicy controls whether the operator manages a NetworkPolicy for the cluster.

Field Description
Enabled NetworkPolicyEnabled makes the operator manage a NetworkPolicy restricting ingress to the cluster Pods.
Disabled NetworkPolicyDisabled disables the managed NetworkPolicy, the operator deletes it if present.

Appears in:

PDBPolicy

PDBPolicy controls whether PodDisruptionBudgets are created.

Field Description
Enabled PDBPolicyEnabled enables PodDisruptionBudgets creation by the operator.
Disabled PDBPolicyDisabled disables PodDisruptionBudgets, operator will delete resource with matching labels.
Ignored PDBPolicyIgnored ignores PodDisruptionBudgets, operator will not create or delete any PDBs, existing PDBs will be left unchanged.

Appears in:

PersistentVolumeClaimTemplate

PersistentVolumeClaimTemplate is a named template for a per-replica PersistentVolumeClaim.

Field Type Description Required Default
metadata NamedTemplateMeta Refer to Kubernetes API documentation for fields of metadata. true
spec PersistentVolumeClaimSpec Spec defines the desired characteristics of a volume requested by a pod author.
More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#persistentvolumeclaims		 true

Appears in:

PodDisruptionBudgetSpec

PodDisruptionBudgetSpec configures the PDB created for the cluster. Exactly one of MinAvailable or MaxUnavailable may be set. When neither is set, the operator picks a safe default based on replica count.

Field Type Description Required Default
policy PDBPolicy Policy controls whether the operator creates PodDisruptionBudgets.
Defaults to “Enabled” when unset. Set it to “Disabled” to skip PDB creation (e.g. for development environments).		 false Enabled
minAvailable IntOrString MinAvailable is the minimum number of pods that must remain available during a disruption. false
maxUnavailable IntOrString MaxUnavailable is the maximum number of pods that can be unavailable during a disruption. false
unhealthyPodEvictionPolicy UnhealthyPodEvictionPolicyType UnhealthyPodEvictionPolicy defines the criteria for when unhealthy pods
should be considered for eviction.
Valid values are “IfReady” and “AlwaysAllow”.		 false

Appears in:

PodTemplateSpec

PodTemplateSpec describes the pod configuration overrides for the cluster’s pods.

Field Type Description Required Default
terminationGracePeriodSeconds integer Optional duration in seconds the pod needs to terminate gracefully. May be decreased in delete request.
Value must be non-negative integer. The value zero indicates stop immediately via
the kill signal (no opportunity to shut down).
If this value is nil, the default grace period will be used instead.
The grace period is the duration in seconds after the processes running in the pod are sent
a termination signal and the time when the processes are forcibly halted with a kill signal.
Set this value longer than the expected cleanup time for your process.
Defaults to 30 seconds.		 false
topologySpreadConstraints TopologySpreadConstraint array TopologySpreadConstraints describes how a group of pods ought to spread across topology
domains. Scheduler will schedule pods in a way which abides by the constraints.
All topologySpreadConstraints are ANDed.
Merged with operator defaults by topologyKey.		 false
imagePullSecrets LocalObjectReference array ImagePullSecrets is an optional list of references to secrets in the same namespace to use for pulling any of the images used by this PodSpec.
If specified, these secrets will be passed to individual puller implementations for them to use.
More info: https://kubernetes.io/docs/concepts/containers/images#specifying-imagepullsecrets-on-a-pod
Merged with operator defaults by name.		 false
nodeSelector object (keys:string, values:string) NodeSelector is a selector which must be true for the pod to fit on a node.
Selector which must match a node’s labels for the pod to be scheduled on that node.
More info: https://kubernetes.io/docs/concepts/configuration/assign-pod-node/		 false
affinity Affinity If specified, the pod’s scheduling constraints.
Appended to operator defaults: scheduling term lists are concatenated.		 false
tolerations Toleration array If specified, the pod’s Tolerations. false
schedulerName string If specified, the pod will be dispatched by specified scheduler.
If not specified, the pod will be dispatched by default scheduler.		 false
serviceAccountName string ServiceAccountName is the name of the ServiceAccount to use to run this pod.
More info: https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/		 false
priorityClassName string PriorityClassName is the name of the PriorityClass to use for the pod. false
runtimeClassName string RuntimeClassName is the name of the RuntimeClass to use for the pod. false
volumes Volume array Volumes defines the list of volumes that can be mounted by containers belonging to the pod.
More info: https://kubernetes.io/docs/concepts/storage/volumes
Merged with operator defaults by name; a user volume replaces any operator volume with the same name.		 false
securityContext PodSecurityContext SecurityContext holds pod-level security attributes and common container settings.
A non-nil SecurityContext fully replaces operator defaults; the user owns the
entire struct. When nil, operator defaults are preserved.		 false
topologyZoneKey string TopologyZoneKey is the key of node labels.
Nodes that have a label with this key and identical values are considered to be in the same topology domain,
e.g. the same availability zone for “topology.kubernetes.io/zone” or the same node for “kubernetes.io/hostname”.
Set it to balance pods holding the same data (replicas of one shard for ClickHouse, all replicas for Keeper)
across domains: a required TopologySpreadConstraint (maxSkew 1, DoNotSchedule) plus a preferred PodAntiAffinity rule.
Pods of different shards may share a domain, so multiple pods per domain are allowed.
With fewer domains than replicas, several replicas share a domain, still evenly balanced.
ClickHouse pods additionally prefer domains hosting the Keeper pods they use.
Recommended to be set to “topology.kubernetes.io/zone”.		 false
nodeHostnameKey string NodeHostnameKey is the key of node labels.
Nodes that have a label with this key and identical values are considered to be on the same node.
Set it to enforce exclusive node occupancy: a required PodAntiAffinity rule across all pods of the cluster,
at most one pod per node regardless of shard. Requires at least as many nodes as pods;
with fewer nodes the excess pods stay Pending.
To spread replicas of the same shard across nodes while packing several pods per node,
set TopologyZoneKey to “kubernetes.io/hostname” instead.
Recommended to be set to “kubernetes.io/hostname”.		 false
initContainers Container array InitContainers is the list of init containers to run before the main server container starts.
Merged with operator defaults by name.
with the same name.		 false

Appears in:

SecretKeySelector

SecretKeySelector selects a key of a Secret.

Field Type Description Required Default
name string The name of the secret in the cluster’s namespace to select from. true
key string The key of the secret to select from. Must be a valid secret key. true

Appears in:

TemplateMeta

TemplateMeta defines supported metadata settings for template objects.

Field Type Description Required Default
labels object (keys:string, values:string) Labels are labels applied to the template objects. false
annotations object (keys:string, values:string) Annotations are annotations applied to the template objects. false

Appears in:

VersionProbeContainer

VersionProbeContainer defines container-level overrides for the version probe. Field names and JSON tags match corev1.Container so that SMP merges by name.

Field Type Description Required Default
name string Name of the container. If empty, the operator sets it to the version probe container name. true version-probe
resources ResourceRequirements Resources are the compute resource requirements for the version probe container.
Deep-merged with operator defaults via SMP.		 false
securityContext SecurityContext SecurityContext defines the security options for the version probe container.
Deep-merged with operator defaults via SMP.		 false

Appears in:

VersionProbeJobSpec

VersionProbeJobSpec defines Job-level overrides for the version probe.

Field Type Description Required Default
ttlSecondsAfterFinished integer TTLSecondsAfterFinished limits the lifetime of a completed Job. false
template VersionProbePodTemplate Template describes the pod that will be created for the version probe Job. false

Appears in:

VersionProbePodSpec

VersionProbePodSpec defines Pod-level overrides for the version probe. Field names and JSON tags match corev1.PodSpec for strategic merge patch compatibility.

Field Type Description Required Default
nodeSelector object (keys:string, values:string) NodeSelector constrains the version probe Pod to nodes with matching labels. false
tolerations Toleration array Tolerations for the version probe Pod. false
securityContext PodSecurityContext SecurityContext holds pod-level security attributes for the version probe Pod. false
containers VersionProbeContainer array Containers overrides for the version probe Pod.
The name field is optional — the operator fills it with default container.
Additional container with the different name may be specified.		 false

Appears in:

VersionProbePodTemplate

VersionProbePodTemplate describes overrides for the version probe Pod.

Field Type Description Required Default
metadata TemplateMeta Refer to Kubernetes API documentation for fields of metadata. false
spec VersionProbePodSpec Specification of the desired behavior of the version probe Pod. false

Appears in:

VersionProbeTemplate

VersionProbeTemplate defines overrides for the version detection Job. The structure mirrors batchv1.JobTemplateSpec, exposing only supported fields.

Field Type Description Required Default
metadata TemplateMeta Refer to Kubernetes API documentation for fields of metadata. false
spec VersionProbeJobSpec Specification of the desired behavior of the version probe Job. false

Appears in:

Navigation