Skip to content

api_reference.md

Latest commit

 

History

History
360 lines (248 loc) · 23.5 KB

api_reference.md

File metadata and controls

360 lines (248 loc) · 23.5 KB

API Reference

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 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 LocalObjectReference Reference to the KeeperCluster that is used for ClickHouse coordination. 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

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

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

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.
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.
Deep-merged with operator defaults via SMP. 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:

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

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

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

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:

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 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.
Deep-merged with operator defaults via SMP. 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:

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: