How to Use Toleration in Pod in Kubernetes

In Kubernetes, use tolerations in a pod spec to allow the pod to be scheduled on nodes with matching taints. Add a tolerations section under spec in the pod YAML with keys, operators, and effects that match the node taints.

Syntax

The tolerations field is an array under the pod's spec. Each toleration has these parts:

• key: The taint key to match.
• operator: How to match the key, usually Exists or Equal.
• value: The taint value to match (used with Equal).
• effect: The taint effect to tolerate, like NoSchedule, PreferNoSchedule, or NoExecute.
• tolerationSeconds: Optional, how long to tolerate a NoExecute taint.

yaml

spec:
  tolerations:
  - key: "key1"
    operator: "Equal"
    value: "value1"
    effect: "NoSchedule"
  - key: "key2"
    operator: "Exists"
    effect: "NoExecute"
    tolerationSeconds: 3600

Example

This example shows a pod that tolerates a node taint with key example-key, value example-value, and effect NoSchedule. This allows the pod to be scheduled on nodes with that taint.

yaml

apiVersion: v1
kind: Pod
metadata:
  name: tolerant-pod
spec:
  containers:
  - name: nginx
    image: nginx
  tolerations:
  - key: "example-key"
    operator: "Equal"
    value: "example-value"
    effect: "NoSchedule"

Output

Pod "tolerant-pod" created and can be scheduled on nodes tainted with example-key=example-value:NoSchedule

Common Pitfalls

Common mistakes when using tolerations include:

• Not matching the key, value, or effect exactly with the node taint.
• Using operator: Equal without specifying a value.
• Forgetting that Exists operator ignores the value and only matches the key.
• Not adding tolerations for NoExecute taints if the pod should keep running on tainted nodes.

Example of wrong and right toleration:

yaml

# Wrong: operator Equal but no value
spec:
  tolerations:
  - key: "example-key"
    operator: "Equal"
    effect: "NoSchedule"

# Right: operator Equal with value
spec:
  tolerations:
  - key: "example-key"
    operator: "Equal"
    value: "example-value"
    effect: "NoSchedule"

Quick Reference

Field	Description	Example
key	Taint key to match	"example-key"
operator	Match method: Equal or Exists	"Equal" or "Exists"
value	Taint value to match (with Equal)	"example-value"
effect	Taint effect to tolerate	"NoSchedule", "NoExecute", "PreferNoSchedule"
tolerationSeconds	Seconds to tolerate NoExecute taint	3600

Key Takeaways

Add tolerations in pod spec to allow scheduling on tainted nodes.

Match key, operator, value, and effect exactly with node taints.

Use operator Exists to tolerate any value for a key.

Include tolerationSeconds for temporary toleration of NoExecute taints.

Without matching tolerations, pods cannot schedule on tainted nodes.