Taints and Tolerations

Taints and tolerations work together to keep pods off unsuitable nodes. Node affinity attracts pods to nodes, whereas taints do the opposite: they let a node repel pods.

How it works

A taint has a key, an optional value and an effect. There are three effects:

• NoSchedule: new pods that do not tolerate the taint are not scheduled there, but running pods are not evicted.
• PreferNoSchedule: a soft version, where the scheduler tries to avoid the node but is not obliged to.
• NoExecute: non-tolerating pods are evicted as well. A toleration can add tolerationSeconds to limit how long a pod may stay.

A toleration matches with the Equal operator (key, value and effect must match) or the Exists operator (key and effect only). Kubernetes ignores every taint a pod tolerates and applies the effects of whatever remains.

A practical example

To reserve a node for GPU workloads:

kubectl taint nodes gpu-node gpu=true:NoSchedule

Only pods carrying this toleration can then be scheduled there:

tolerations:
- key: "gpu"
  operator: "Equal"
  value: "true"
  effect: "NoSchedule"

The same command with a trailing minus, kubectl taint nodes gpu-node gpu=true:NoSchedule-, removes the taint.

Common mistakes

• Assuming a toleration attracts a pod to a node. It only permits scheduling. To steer pods onto the tainted nodes, also add a nodeSelector or node affinity.
• Mismatching the effect or value, so the toleration silently does not match.
• Expecting NoSchedule to move pods that are already running. Use NoExecute for that.
• Setting .spec.nodeName directly, which bypasses the scheduler and so ignores NoSchedule taints.
• Adding taints to nodes without checking that system components and DaemonSets can still run.

When to use it and when not to

Use taints to dedicate nodes to a workload class, such as GPUs or noisy batch jobs, or to isolate environments sharing a cluster. With Karpenter, taints are set explicitly on a NodePool, and pods must tolerate them to land on those nodes. Karpenter does not add Spot taints on its own, so a team that wants to keep production services off Spot capacity must define that taint itself. For simple preferences, affinity rules are usually clearer than taints. Our Kubernetes consulting page describes how we design scheduling policy.

See also

• Node Affinity
• Karpenter
• DaemonSet
• Kubernetes