Skip to main content
In this lesson you’ll learn how to control which pods the Kubernetes scheduler can place on which nodes using taints and tolerations. This is a scheduling mechanism—not a security control—that lets you repel most pods from specific nodes while allowing selected pods to land there. Analogy: imagine a pod as a bug approaching a person (the node). We spray the person with a repellent (a taint). Some bugs cannot tolerate the smell and are repelled; others are tolerant and can land. Two things determine whether a pod can be placed on a node: the taint applied to the node, and the pod’s tolerations for that taint.
  • The person = node
  • The bug = pod
  • The spray = taint applied to the node
  • Pod tolerations = whether a pod can tolerate that node’s taint
Consider a cluster with three worker nodes (Node 1, Node 2, Node 3) and four pods (A, B, C, D). With no restrictions, the scheduler balances pods across nodes. If you want to reserve Node 1 for a specific application, add a taint (for example, app=blue) to Node 1. By default, pods do not tolerate taints, so they will be prevented from scheduling onto the tainted node. To allow a specific pod onto Node 1, add a matching toleration to that pod’s spec.
A Kubernetes diagram titled "Taints and Tolerations" showing three node cards (Node 1, Node 2, Node 3) with hexagonal pod icons labeled A, B, C, and D. A "Taint → Blue" control is shown at the bottom, and Node 1 appears highlighted.

​
How taints and tolerations work

  • Taints are applied to nodes; they mark nodes to repel pods that do not tolerate them.
  • Tolerations are applied to pods; they allow pods to be scheduled onto nodes with matching taints.
  • Taints/tolerations restrict acceptance of pods by a node but do not force the scheduler to place a pod on a particular node. Use node selectors or node affinity when you want to direct pods to specific nodes.

​
1) Add a taint to a node

Use kubectl taint nodes to add a taint:
  • <key>=<value> — the taint key and value
  • <effect> — one of: NoSchedule, PreferNoSchedule, NoExecute
Example: taint node1 so it won’t accept pods that don’t tolerate app=blue:
To remove the taint later, append a trailing - to the effect:
You can inspect taints on a node with kubectl describe:
Or list taints for all nodes:

​
Effects explained

​
2) Add a toleration to a pod

Tolerations go in the pod spec under spec.tolerations. They must match the taint’s key, value (if used), and effect to allow scheduling onto the tainted node. Example pod manifest that tolerates app=blue:NoSchedule:
Notes:
  • Values are strings; quote them in YAML to avoid parsing issues.
  • operator can be Equal (key and value must match) or Exists (only the key is required).
  • If you use Exists, omit value.

​
NoExecute in more depth

NoExecute affects both new and existing pods:
  • New pods without a matching toleration are prevented from scheduling.
  • Existing pods without a matching toleration are evicted when the taint is applied.
You can allow a pod to remain on the node for a grace period by adding tolerationSeconds to the toleration:
In this example the pod tolerates the NoExecute taint for 300 seconds before being evicted.

​
Important distinctions

  • Taints are node properties; tolerations are pod properties.
  • Taints/tolerations control node acceptance of pods—they do not force placement onto a node.
  • For forcing or preferring particular nodes, use:
    • nodeSelector
    • nodeAffinity / podAffinity / podAntiAffinity
Taints/tolerations control whether a node will accept a pod. To direct pods toward specific nodes, use nodeSelector or nodeAffinity instead.

​
Master (control-plane) node taint — a caution

Most clusters apply a taint to control-plane (master) nodes to prevent general workloads from being scheduled there (it keeps control-plane components isolated). You can remove or change this taint, but doing so may expose control-plane resources to user workloads.
Control-plane nodes are typically tainted (for example, node-role.kubernetes.io/master:NoSchedule). Avoid scheduling application workloads on control-plane nodes unless you understand the operational impact.
Example: view the default master taint
Different distributions may use node-role.kubernetes.io/control-plane:NoSchedule or another key.

​
Summary

  • Use kubectl taint nodes to mark nodes so they repel pods without matching tolerations.
  • Add tolerations to pod specs to allow pods to land on tainted nodes.
  • Choose the appropriate effect (NoSchedule, PreferNoSchedule, NoExecute) depending on whether you want to block scheduling, prefer avoidance, or evict existing pods.
  • For directing pods to particular nodes, prefer nodeSelector or nodeAffinity rather than relying solely on taints/tolerations.
Further reading and references:

Watch Video

Practice Lab