Pods can now exclude tainted nodes during topology spread calculations, improving placement predictability.
Kubernetes has long offered Pod Topology Spread Constraints to distribute pods evenly across failure domains. However, a notable gap persisted: the scheduler would consider , even those tainted and untolerated by the pod, while calculating skew. This often led to unexpected states, even when tolerable nodes existed.
PendingWith KEP-3094, Kubernetes v1.33 addresses this with two new optional fields:
NodeAffinityPolicyNodeTaintsPolicyThese allow fine-grained control over which nodes are considered during pod distribution.
The TopologySpreadConstraint now includes:
When set to Honor:
nodeAffinity or nodeSelector are considered.This behavior is behind the feature gate NodeInclusionPolicyInPodTopologySpread (enabled by default from v1.33).
Consider this deployment:
Without nodeTaintsPolicy: Honor, a pod might be expected to land on a node it cannot tolerate, resulting in a Pending state. With it, tainted nodes are excluded from the skew calculation unless tolerated—making scheduling behavior intuitive and predictable.
plugin_execution_duration_seconds{plugin="PodTopologySpread"} help monitor performance.This enhancement may seem minor, but it's a key step toward making Kubernetes scheduling more accurate, transparent, and user-driven. For platforms relying on strict node segregation (e.g., GPU pools, burstable zones), it eliminates a major source of scheduling surprises.
For cluster operators, enabling NodeTaintsPolicy and NodeAffinityPolicy gives finer control with no risk to existing workloads—an opt-in that brings measurable value.
KEP-3094 addresses the problem where the scheduler previously considered all nodes, including tainted or affinity-mismatched ones, when calculating Pod Topology Spread. This often led to Pending pods even if tolerable nodes were available.
These new optional fields in topologySpreadConstraints allow the scheduler to honor pod-level node affinity and taint toleration rules during skew calculations.
nodeAffinityPolicy: Honor considers only nodes that match the pod's node affinity.nodeTaintsPolicy: Honor excludes tainted nodes unless the pod tolerates them.When these policies are set to Honor, the scheduler excludes nodes the pod cannot land on from skew calculations. This ensures pods aren't marked as Pending due to unreachable nodes, resulting in more predictable and accurate scheduling.
Yes. The feature gate NodeInclusionPolicyInPodTopologySpread is enabled by default in Kubernetes v1.33. If the new fields are unset, behavior remains unchanged for backward compatibility.
It provides predictable distribution, especially in environments with node taints (e.g., GPU pools) or affinity rules. It ensures spread constraints reflect actual node eligibility, eliminating scheduling inconsistencies and reducing manual debugging.
Get new posts, tools, and tips delivered straight to your inbox.
Follow along with walkthroughs and tutorials, especially on Rancher and DevOps topics.
A small act of support goes a long way. You're helping me stay consistent and keep the content flowing.
topologySpreadConstraints:
- maxSkew: 1
topologyKey: kubernetes.io/hostname
whenUnsatisfiable: DoNotSchedule
nodeTaintsPolicy: Honor
labelSelector:
matchLabels:
foo: barNodeAffinityPolicy *NodeInclusionPolicy // "Honor" or "Ignore"
NodeTaintsPolicy *NodeInclusionPolicy // "Honor" or "Ignore"
FeaturedKubernetes 1.34 brings GA features, scheduler speedups, kubelet and networking updates, plus security and performance boosts for production clusters.
Stop waiting for schedules to debug CronJobs. Learn how to trigger them immediately, validate specs, and streamline testing in Kubernetes.
Helm upgrade failed due to Kubernetes managedFields conflict. Learn why spec looked fine, yet patching caused errors, and how to fix it.
CVE-2025-1767 exposes root-level access on nodes via a deprecated volume plugin; Kubernetes 1.33 will disable it by default
Enhance Kubernetes pod scheduling with dynamic affinity using matchLabelKeys and mismatchLabelKeys for safer rollouts and tenant isolation.
Kubernetes 1.33 ensures PV reclaim policies are honored even if PVs are deleted before PVCs, preventing storage leaks across CSI and in-tree drivers.
FeaturedKubernetes 1.34 brings GA features, scheduler speedups, kubelet and networking updates, plus security and performance boosts for production clusters.
FeaturedStep-by-step guide to RKE2 autoscaler setup with Rancher. Learn cluster autoscaler Helm deployment, scaling benefits, limits & troubleshooting.
