Toleration Seconds and Eviction Grace Period
What you'll learn: How to control exactly how long a pod can remain on a node after a NoExecute taint is applied, giving workloads time for graceful shutdown.
The Time-Limited Pass
Remember that NoExecute taints actively evict pods from nodes? By default, pods with matching tolerations stay indefinitely. But what if you want to give a pod a temporary pass—allowing it to remain on a tainted node for a specific duration before eviction?
The tolerationSeconds field lets you do exactly that. It specifies how many seconds a pod can tolerate a NoExecute taint before Kubernetes evicts it.
How It Works
When you add tolerationSeconds to a toleration, you're essentially saying: "This pod can handle this taint, but only for X seconds." Once that time expires, Kubernetes will evict the pod, even though it has a matching toleration.
Common use case: Node maintenance or degradation. You might taint a node with NoExecute because it's experiencing issues, but allow critical pods to finish their work gracefully over the next 300 seconds before forcing them off.
tolerations:
- key: "node.kubernetes.io/unreachable"
operator: "Exists"
effect: "NoExecute"
tolerationSeconds: 300
This toleration says: "If the node becomes unreachable, let this pod stay for 5 minutes before evicting it."
The Eviction Grace Period
Without tolerationSeconds, pods with matching tolerations stay indefinitely. With it set, the countdown begins when the taint is applied. After expiration, Kubernetes triggers pod eviction using the pod's terminationGracePeriodSeconds for cleanup.
Key Takeaway: Use tolerationSeconds with NoExecute taints to give pods a time-limited grace period on problematic nodes, enabling controlled, gradual eviction instead of immediate removal.