Skip to content

docs: clarify topologyZoneKey and nodeHostnameKey semantics #271

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
GrigoryPervakov merged 2 commits into from
Jul 20, 2026
Merged

docs: clarify topologyZoneKey and nodeHostnameKey semantics #271

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b583b52
docs: clarify topologyZoneKey and nodeHostnameKey semantics
GrigoryPervakov Jul 20, 2026
7f85bb8
docs: add maxSkew to Vale vocabulary
GrigoryPervakov Jul 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 14 additions & 5 deletions api/v1alpha1/common.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"`

Expand Down
19 changes: 14 additions & 5 deletions config/crd/bases/clickhouse.com_clickhouseclusters.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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: |-
Expand Down
19 changes: 14 additions & 5 deletions config/crd/bases/clickhouse.com_keeperclusters.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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: |-
Expand Down
19 changes: 14 additions & 5 deletions dist/chart/templates/crd/clickhouseclusters.clickhouse.com.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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: |-
Expand Down
19 changes: 14 additions & 5 deletions dist/chart/templates/crd/keeperclusters.clickhouse.com.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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: |-
Expand Down
4 changes: 2 additions & 2 deletions docs/reference/api-reference.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.<br />More info: https://kubernetes.io/docs/concepts/storage/volumes<br />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.<br />A non-nil SecurityContext fully replaces operator defaults; the user owns the<br />entire struct. When nil, operator defaults are preserved. | false | |
| `topologyZoneKey` | string | TopologyZoneKey is the key of node labels.<br />Nodes that have a label with this key and identical values are considered to be in the same topology zone.<br />Set it to enable default TopologySpreadConstraints and Affinity rules to spread pods across zones.<br />Recommended to be set to "topology.kubernetes.io/zone" | false | |
| `nodeHostnameKey` | string | NodeHostnameKey is the key of node labels.<br />Nodes that have a label with this key and identical values are considered to be on the same node.<br />Set it to enable default AntiAffinity rules to spread replicas from the different shards across nodes.<br />Recommended to be set to "kubernetes.io/hostname" | false | |
| `topologyZoneKey` | string | TopologyZoneKey is the key of node labels.<br />Nodes that have a label with this key and identical values are considered to be in the same topology domain,<br />e.g. the same availability zone for "topology.kubernetes.io/zone" or the same node for "kubernetes.io/hostname".<br />Set it to balance pods holding the same data (replicas of one shard for ClickHouse, all replicas for Keeper)<br />across domains: a required TopologySpreadConstraint (maxSkew 1, DoNotSchedule) plus a preferred PodAntiAffinity rule.<br />Pods of different shards may share a domain, so multiple pods per domain are allowed.<br />With fewer domains than replicas, several replicas share a domain, still evenly balanced.<br />ClickHouse pods additionally prefer domains hosting the Keeper pods they use.<br />Recommended to be set to "topology.kubernetes.io/zone". | false | |
| `nodeHostnameKey` | string | NodeHostnameKey is the key of node labels.<br />Nodes that have a label with this key and identical values are considered to be on the same node.<br />Set it to enforce exclusive node occupancy: a required PodAntiAffinity rule across all pods of the cluster,<br />at most one pod per node regardless of shard. Requires at least as many nodes as pods;<br />with fewer nodes the excess pods stay Pending.<br />To spread replicas of the same shard across nodes while packing several pods per node,<br />set TopologyZoneKey to "kubernetes.io/hostname" instead.<br />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.<br />Merged with operator defaults by name.<br />with the same name. | false | |

Appears in:
Expand Down
1 change: 1 addition & 0 deletions docs/styles/config/vocabularies/ClickHouse/accept.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,3 +38,4 @@ keypair
Cilium
Calico
CNI
maxSkew
Loading