ClickHouse Operator API reference

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

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

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

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
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
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

Appears in:

• ClickHouseCluster

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:

• ClickHouseCluster

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
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:

• ClickHouseClusterSpec

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	ServerCertSecretRef 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	SecretKeySelector	CABundle is a reference to a TLS Secret containing the CA bundle. If empty and ServerCertSecret is specified, the CA bundle from certificate will be used. Otherwise, system trusted CA bundle will be used. Key is defaulted to “ca.crt” if not specified.	false

Appears in:

• ClickHouseSettings
• KeeperSettings

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:

• DefaultPasswordSelector

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

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. Deep-merged with operator defaults via SMP. Individual limits and requests override only matching keys; unset fields preserve operator defaults.	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:

• ClickHouseClusterSpec
• KeeperClusterSpec

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:

• ClickHouseSettings

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:

• ClickHouseClusterSpec

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:

• ExternalSecret

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

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:

• ClickHouseClusterSpec

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).	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.	false

Appears in:

• KeeperCluster

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	CurrentRevision 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 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:

• KeeperCluster

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:

• KeeperClusterSpec

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:

• ClickHouseSettings
• KeeperSettings

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:

• PodDisruptionBudgetSpec

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:

• ClickHouseClusterSpec
• KeeperClusterSpec

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 zone. Set it to enable default TopologySpreadConstraints and Affinity rules to spread pods across zones. 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 enable default AntiAffinity rules to spread replicas from the different shards across nodes. 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:

• ClickHouseClusterSpec
• KeeperClusterSpec

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:

• ClusterTLSSpec
• DefaultPasswordSelector

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:

• VersionProbePodTemplate
• VersionProbeTemplate

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:

• VersionProbePodSpec

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:

• VersionProbeTemplate

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

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:

• VersionProbeJobSpec

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:

• ClickHouseClusterSpec
• KeeperClusterSpec