diff --git a/api/v1alpha1/common.go b/api/v1alpha1/common.go
index 1119a62..e3ecd7c 100644
--- a/api/v1alpha1/common.go
+++ b/api/v1alpha1/common.go
@@ -240,16 +240,25 @@ type PodTemplateSpec struct {
SecurityContext *corev1.PodSecurityContext `json:"securityContext,omitempty"`
// 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"
+ // 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".
// +optional
TopologyZoneKey *string `json:"topologyZoneKey,omitempty"`
// 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"
+ // 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".
// +optional
NodeHostnameKey *string `json:"nodeHostnameKey,omitempty"`
diff --git a/config/crd/bases/clickhouse.com_clickhouseclusters.yaml b/config/crd/bases/clickhouse.com_clickhouseclusters.yaml
index 9b9f935..8e7a3cb 100644
--- a/config/crd/bases/clickhouse.com_clickhouseclusters.yaml
+++ b/config/crd/bases/clickhouse.com_clickhouseclusters.yaml
@@ -3934,8 +3934,12 @@ spec:
description: |-
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"
+ 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".
type: string
nodeSelector:
additionalProperties:
@@ -4437,9 +4441,14 @@ spec:
topologyZoneKey:
description: |-
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"
+ 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".
type: string
volumes:
description: |-
diff --git a/config/crd/bases/clickhouse.com_keeperclusters.yaml b/config/crd/bases/clickhouse.com_keeperclusters.yaml
index 1c79cd2..3e630b1 100644
--- a/config/crd/bases/clickhouse.com_keeperclusters.yaml
+++ b/config/crd/bases/clickhouse.com_keeperclusters.yaml
@@ -3623,8 +3623,12 @@ spec:
description: |-
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"
+ 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".
type: string
nodeSelector:
additionalProperties:
@@ -4126,9 +4130,14 @@ spec:
topologyZoneKey:
description: |-
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"
+ 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".
type: string
volumes:
description: |-
diff --git a/dist/chart/templates/crd/clickhouseclusters.clickhouse.com.yaml b/dist/chart/templates/crd/clickhouseclusters.clickhouse.com.yaml
index 170315f..83738ae 100644
--- a/dist/chart/templates/crd/clickhouseclusters.clickhouse.com.yaml
+++ b/dist/chart/templates/crd/clickhouseclusters.clickhouse.com.yaml
@@ -3937,8 +3937,12 @@ spec:
description: |-
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"
+ 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".
type: string
nodeSelector:
additionalProperties:
@@ -4440,9 +4444,14 @@ spec:
topologyZoneKey:
description: |-
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"
+ 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".
type: string
volumes:
description: |-
diff --git a/dist/chart/templates/crd/keeperclusters.clickhouse.com.yaml b/dist/chart/templates/crd/keeperclusters.clickhouse.com.yaml
index 3140e4a..fe4caca 100644
--- a/dist/chart/templates/crd/keeperclusters.clickhouse.com.yaml
+++ b/dist/chart/templates/crd/keeperclusters.clickhouse.com.yaml
@@ -3626,8 +3626,12 @@ spec:
description: |-
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"
+ 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".
type: string
nodeSelector:
additionalProperties:
@@ -4129,9 +4133,14 @@ spec:
topologyZoneKey:
description: |-
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"
+ 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".
type: string
volumes:
description: |-
diff --git a/docs/reference/api-reference.mdx b/docs/reference/api-reference.mdx
index 8a55bc9..b05ab7e 100644
--- a/docs/reference/api-reference.mdx
+++ b/docs/reference/api-reference.mdx
@@ -427,8 +427,8 @@ PodTemplateSpec describes the pod configuration overrides for the cluster's pods
| `runtimeClassName` | string | RuntimeClassName is the name of the RuntimeClass to use for the pod. | false | |
| `volumes` | [Volume](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#volume-v1-core) 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](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#podsecuritycontext-v1-core) | 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 | |
+| `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](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#container-v1-core) 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:
diff --git a/docs/styles/config/vocabularies/ClickHouse/accept.txt b/docs/styles/config/vocabularies/ClickHouse/accept.txt
index 56822e4..26328ae 100644
--- a/docs/styles/config/vocabularies/ClickHouse/accept.txt
+++ b/docs/styles/config/vocabularies/ClickHouse/accept.txt
@@ -38,3 +38,4 @@ keypair
Cilium
Calico
CNI
+maxSkew