Kubernetes taints and tolerations control which Pods may use a Node: a taint repels Pods that lack a matching toleration, while a toleration permits a Pod to pass that taint. Permission is not placement, however—the scheduler still checks resources, affinity, topology, and other constraints.
What are taints and tolerations?
A taint is attached to a Node and consists of a key, an optional value, and an effect. A toleration is declared in a Pod specification and describes which taint it can tolerate. The Node API reference documents the taint fields; the Kubernetes taints and tolerations guide explains how they affect scheduling and eviction.
As an Amazon Associate I earn from qualifying purchases.
Think of taints as a filter, not a destination selector. Kubernetes considers a Node’s taints and ignores the ones matched by the Pod’s tolerations. The effects of any unmatched taints still apply. A Pod can tolerate one taint and remain unable to schedule because another taint repels it—or because a different scheduling requirement is unmet.
What do the three taint effects do?
The effect determines whether a taint affects new placement, Pods already running on the Node, or both.
#1 Best Overall
| Effect | New scheduler placement | Pods already on the Node |
|---|---|---|
NoSchedule |
Blocks placement of Pods that do not tolerate the taint. | Not evicted by this effect. |
PreferNoSchedule |
The scheduler tries to avoid placement of non-tolerating Pods, but may still place them. | No eviction behavior is specified by this effect. |
NoExecute |
Blocks placement of Pods that do not tolerate the taint. | Non-tolerating Pods are evicted; a matching toleration can delay eviction. |
These distinctions describe taint behavior, not a promise that a tolerating Pod will run. Scheduling still depends on the rest of the Pod’s requirements and cluster state.
How does Kubernetes match a toleration?
A toleration can match a taint by key, value, operator, and, when specified, effect. The guide’s two main matching patterns are:
Equalmatches a key and value. For example, a toleration with keydedicated, valuebatch, and operatorEqualmatches a taint with those same key and value.Existsmatches a key regardless of its value. It can be used when the Pod should tolerate a taint for that key without requiring a particular value.
If a toleration specifies an effect, that effect must match as well. If it omits the effect, it can match taints with that key and operator regardless of effect. Check all taints on the candidate Node: a single unmatched NoSchedule taint is enough to reject ordinary scheduler placement.
Recommended Free Tools
How do you add a taint or toleration?
Add a taint to a Node
The kubectl taint form is key=value:effect. For example, to mark a Node for batch workloads:
kubectl taint nodes node1 dedicated=batch:NoScheduleThis taint prevents scheduler placement of Pods that lack a matching toleration. To remove that taint, append a minus sign to its key/effect form:
kubectl taint nodes node1 dedicated=batch:NoSchedule-Add a matching toleration to a Pod template
For a workload managed by a controller, add the toleration under the Pod template’s spec. This example permits matching the taint above:
Rank #3
spec:
template:
spec:
tolerations:
- key: "dedicated"
operator: "Equal"
value: "batch"
effect: "NoSchedule"Apply the updated workload configuration using your normal deployment process. The toleration permits the Pod to be considered for the Node; it does not select that Node. Use node affinity or another placement rule if the workload should prefer or require a particular set of Nodes.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsHow long does a Pod stay with a NoExecute taint?
A matching NoExecute toleration without tolerationSeconds lets a Pod remain on the Node without a time limit from that taint. With tolerationSeconds, the value is the number of seconds the Pod can remain after the taint is added. If the taint is removed before that duration elapses, the Pod is not evicted for that taint.
For example, to tolerate a matching taint for 3,600 seconds:
tolerations:
- key: "maintenance"
operator: "Equal"
value: "planned"
effect: "NoExecute"
tolerationSeconds: 3600The duration is not a guarantee that a Pod will remain for the full interval if another event or constraint causes it to stop running.
Why can a Pod stay Pending even though it tolerates a taint?
A toleration removes only the obstacle created by a taint it matches. The scheduler can still reject a Node for other reasons, including insufficient resources, node affinity or selector rules, topology constraints, or another unmatched taint. Tolerations also do not attract a Pod to a Node; they merely allow it past matching taints.
- Confirm the Pod’s toleration matches the taint’s key, value, operator, and effect.
- Inspect all taints on candidate Nodes, not just the one you expected the Pod to tolerate.
- Check the Pod’s resource requests and its affinity, selectors, and topology requirements.
- Distinguish scheduler placement from direct binding: setting
.spec.nodeNamebypasses the scheduler, so a Pod may bind despite aNoScheduletaint. ANoExecutetaint can still cause the kubelet to evict a Pod without an appropriate toleration.
How do Node health taints affect Pods?
The control plane communicates certain Node conditions to scheduling through taints; the scheduler checks taints rather than evaluating Node conditions directly. For example, disk pressure maps to node.kubernetes.io/disk-pressure, and memory pressure maps to node.kubernetes.io/memory-pressure. The official guide also documents automatic tolerations for some workloads: Pods outside the BestEffort QoS class automatically tolerate memory-pressure taints, and DaemonSet Pods receive several automatic tolerations.
Best Value
The guide documents 300-second automatic tolerations for the not-ready and unreachable taints unless configured otherwise. DaemonSet Pods have indefinite NoExecute tolerations for those taints. These defaults affect how Pods respond to taints; they do not make an unhealthy Node suitable for every workload.
For Kubernetes versions after 1.29, the guide says taint-based eviction moved from the node controller to the separate taint-eviction-controller. The controller can be disabled with --controllers=-taint-eviction-controller in kube-controller-manager. Because this is version-sensitive control-plane behavior, verify it against the documentation for your cluster release before changing controller settings.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
Free tools Windows power users keep installed
One-click scans. No signup required.
