Last reviewed: November 12, 2026 (Asia/Shanghai); official Kubernetes references checked November 11 UTC.
Direct answer
Review Kubernetes taints and tolerations by comparing every taint on a candidate node with the Pod’s effective tolerations, then testing scheduling and eviction separately. Check the key, value, operator, and effect; explain any wildcard; and state how long a Pod may remain bound when a matching NoExecute taint appears. A toleration permits the scheduler to consider a tainted node. It neither requires placement there nor proves that the node has capacity.
The Kubernetes taints and tolerations reference describes the evaluation as filtering out tolerated taints and applying the effects of those left unmatched. One new toleration can therefore leave another scheduling exclusion in force, while an overly broad entry can remove exclusions the workload owner intended to keep.
Who this is for
Use this workflow when a coding agent changes spec.tolerations, a controller’s Pod template, chart values, overlays, or infrastructure code that sets node taints. It focuses on ordinary application workloads using the default scheduler and the established Equal and Exists operators. The current documentation also describes feature-gated numeric operators; changes using those require a version and feature-configuration review beyond these examples.
Give the agent the approved node pools, taint inventory, supported cluster version, and intended response to node problems. Ask for a rendered change and an acceptance plan. The examples below are review fixtures and proposed checks; this article reports no executed cluster tests or deployment outcomes.
Key takeaways
- Evaluate every node taint; tolerating one does not tolerate the others.
NoScheduleexcludes new placements without evicting Pods already running there.PreferNoScheduleis a soft preference;NoExecutealso affects existing Pods.- An empty key with
Exists, or an omitted effect, broadens the matching rule. - A toleration permits placement; use approved node-selection rules when placement must be restricted to a pool.
tolerationSecondsapplies toNoExecute, and omission means indefinite tolerance of the matching taint.- Review admitted Pods, controller-added tolerations, and actual node state alongside the source template.
Sources checked
Three primary Kubernetes pages were retrieved successfully on November 11, 2026 UTC:
- Taints and Tolerations documents matching, combined taint evaluation, effects, dedicated-node use, default tolerations, and taint-based eviction. Its displayed modification date is July 27, 2026.
- Node API reference
defines
spec.taintsand theTaintfields, including key, value, effect, andtimeAdded. Its displayed modification date is August 26, 2026. - Toleration API reference
defines wildcard matching, the default operator, allowed effects, and
tolerationSeconds. Its displayed modification date is August 26, 2026.
These maintained concept and API references support an evergreen review task. The generated API pages identify their update as Kubernetes v1.37. Match fields and behavior to the target cluster version and configuration; a current documentation fetch does not establish the configuration of a particular cluster.
Contract details to verify
Define the pool and retention policy before changing the manifest
Start with the owner’s intended behavior: which pools may accept this workload, whether it must use one pool exclusively, and what should happen to existing Pods when a node becomes unsuitable. Record the candidate revision, renderer and inputs, namespace, workload controller, scheduler, and cluster version.
Render every affected environment. Inventory all tolerations in the resulting Pod template, then compare them with an admitted Pod created through the actual controller path. Admission and controllers can add entries that are absent from source YAML. The concept reference documents automatic not-ready and unreachable tolerations, normally with 300-second durations unless explicitly supplied. It also documents different additions for DaemonSet Pods. Do not infer the effective list from the agent’s diff alone.
Read the taints on the actual eligible nodes. A label and a taint with similar names are independent settings; one does not establish the other. Keep resource and quota constraints visible using the requests and limits review workflow when a scheduling failure may have several causes.
Translate each effect into an observable consequence
Use the Node API’s taint definition and the concept reference to distinguish these cases for an unmatched taint:
| Effect | New Pod considered by the scheduler | Pod already running on the node |
|---|---|---|
NoSchedule | Node is excluded | This taint alone does not evict it |
PreferNoSchedule | Scheduler tries to avoid the node | This taint alone does not evict it |
NoExecute | Node is excluded | Pod is subject to taint-based eviction |
A soft preference can be unmet. A test that requires an unmatched PreferNoSchedule Pod to remain Pending asserts a stronger rule than Kubernetes provides. Likewise, adding NoSchedule to a node does not establish a migration plan for existing Pods.
Check every remaining taint after matching. If the Pod tolerates the dedicated-pool taint but not a second NoSchedule taint, that node remains excluded. A failed placement is therefore a reason to inspect the full node and Pod state before expanding the toleration list.
Also inspect spec.nodeName. The concept reference explains that assigning it directly bypasses the scheduler, including its NoSchedule evaluation. A fixture pinned this way cannot prove that scheduler filtering worked. Use selection rules and normal scheduling for the scheduling tests below.
Review the complete matching rule, including empty fields
For Equal, the key, value, and effect must match, subject to the documented wildcard behavior. The operator defaults to Equal. With Exists, the value is a wildcard and should be empty. The Toleration API reference
specifies that an empty key requires Exists and matches all keys; an empty effect matches all effects.
Consider a node taint workload.example.com/dedicated=batch:NoSchedule:
| Candidate toleration | Does it match this taint? | Scope to review |
|---|---|---|
Same key, Equal, value batch, effect NoSchedule | Yes | One key/value/effect combination |
Same key, Equal, value interactive, effect NoSchedule | No | Wrong value |
Same key, Exists, effect NoSchedule | Yes | Every value for that key and effect |
Same key, Equal, value batch, effect omitted | Yes | All effects for that key/value |
Key omitted, Exists, effect NoSchedule | Yes | All keys and values with that effect |
Key and effect omitted, Exists | Yes | Every node taint |
Have the agent explain the necessary scope of each broad entry. An empty field can be valid Kubernetes configuration while exceeding the workload’s placement or failure policy. Compare inherited entries too: a narrow new toleration does not make the overall list narrow.
For a workload restricted to a labeled batch pool, this illustrative Pod-spec fragment combines selection with an explicit toleration:
nodeSelector:
workload.example.com/pool: batch
tolerations:
- key: workload.example.com/dedicated
operator: Equal
value: batch
effect: NoSchedule
The selector restricts eligible nodes by their label; the toleration handles the separate taint. Derive both settings from the cluster owner’s policy. The node-affinity review guide covers selection logic and label ownership when the patch also changes that boundary. A toleration alone cannot require use of the dedicated pool.
Make the NoExecute duration an explicit recovery decision
The Toleration API defines tolerationSeconds only for NoExecute; the field is ignored for other effects. Omitting it means the matching taint does not cause eviction for expiry of a toleration. Zero and negative values are treated as zero. Review the accepted duration against the application’s recovery needs instead of copying a number from an unrelated workload.
For example, an additional toleration could be:
- key: maintenance.example.com/review
operator: Equal
value: planned
effect: NoExecute
tolerationSeconds: 60
This is an illustrative 60-second tolerance of a custom fixture taint. The concept reference describes a running Pod remaining bound for the configured interval after the matching taint is added, with eviction avoided if the taint is removed before expiry. Review the entire toleration list and the enabled eviction-controller configuration before predicting behavior for the fixture.
The interval is not a promise that the old process has stopped and a replacement is ready exactly 60 seconds later. Controller processing, termination, replacement scheduling, and readiness are separate observations. The concept reference also warns that during a network partition, deletion decisions may not reach the isolated kubelet and old processes may continue running. Application ownership and recovery must account for that possibility where duplicate activity matters.
Capture effective state and test each changed boundary
Node taints affect a cluster-scoped object. Use approved disposable nodes and a custom fixture taint, with the platform owner’s permitted mutation procedure. Establish a healthy baseline and record the initial taints before each case.
These read-only captures assume kubectl and jq; replace the example context, namespace, node, and Pod with the actual fixture identities:
kubectl --context review-cluster get node worker-a -o json |
jq '{name: .metadata.name, uid: .metadata.uid,
labels: .metadata.labels, taints: .spec.taints}'
kubectl --context review-cluster --namespace agent-review \
get pod toleration-check -o json |
jq '{name: .metadata.name, uid: .metadata.uid,
nodeName: .spec.nodeName, schedulerName: .spec.schedulerName,
nodeSelector: .spec.nodeSelector, affinity: .spec.affinity,
tolerations: .spec.tolerations,
deletionTimestamp: .metadata.deletionTimestamp,
conditions: .status.conditions}'
kubectl --context review-cluster --namespace agent-review \
describe pod toleration-check
Check command exit statuses and retain the full relevant scheduler diagnostics. For a refusal test, constrain eligible nodes so an untainted alternative cannot hide the result. Hold capacity and other policies constant, and keep a matching Pod as a positive control. A Pending Pod alone cannot attribute failure to an untolerated taint.
Run the following proposed checks through the approved disposable-cluster workflow, restoring the baseline between cases:
| Controlled case | Evidence to require |
|---|---|
Exact Equal match on the only eligible tainted node | Scheduler assigns the Pod; admitted toleration and node taint agree |
| Same fixture with the toleration’s value changed | Pod stays unscheduled; scheduler diagnostic identifies the untolerated taint |
Matching first taint plus a second unmatched NoSchedule taint | Second taint still excludes placement |
NoSchedule added after a healthy Pod is running | Original Pod UID remains; test separately verifies exclusion of an unmatched new Pod |
Custom NoExecute taint with the finite toleration | Taint-addition time, original Pod deletion, and any replacement have distinct recorded identities and times |
| Same timed case with the taint removed well before expiry | Original Pod remains through an observation window beyond the original expiry, with no unrelated deletion |
For the timed cases, keep the node reachable and verify that taint-based eviction is enabled. Watch the original Pod from before the taint change so deletion evidence is not lost. If a controller creates a replacement, distinguish its new UID and placement from the original Pod’s lifecycle. Record readiness and a harmless application check separately from eviction.
When a toleration edit changes a Deployment’s Pod template, attach the Deployment rollout evidence as well. Successful placement of one fixture does not establish that every replacement replica can schedule within the release’s availability policy.
Failure modes
The agent adds Exists without a key to clear Pending Pods. Review the newly tolerated keys and effects. Obtain the owner’s intended scope before accepting the broader policy.
A matching entry is treated as proof of placement. Inspect every other taint, node selection, and available capacity. Tolerance removes an exclusion rather than selecting a destination.
A NoSchedule change is expected to remove old Pods. Test existing and new Pod behavior separately and define the intended migration procedure.
A duration is added to the wrong effect. tolerationSeconds is ignored outside NoExecute. Review the effect and timer together.
A pinned fixture produces a misleading success. Remove direct nodeName assignment from scheduler tests and capture the actual scheduler result.
A replacement is mistaken for the original surviving Pod. Bind observations to UIDs, taint snapshots, and timestamps rather than reusing a familiar Pod name.
FAQ
Does a toleration force a Pod onto a tainted node?
No. It permits consideration of that node when the corresponding taint would otherwise exclude it. Other scheduling constraints still apply. Use the approved selector or required affinity when the workload must stay in a specific pool.
Can an omitted effect broaden a toleration?
Yes. The API defines an empty effect as matching all taint effects. Review that expansion even when the key and value remain unchanged.
Does tolerationSeconds delay a NoSchedule decision?
No. The API says the field is ignored unless the toleration effect is NoExecute.
Do all Pods receive identical node-failure tolerations?
No. Explicit settings and controller behavior matter. The concept reference documents default node-failure tolerations and additional DaemonSet behavior. Inspect the actual admitted Pod and its controller.
Reader next step
Choose one agent-written toleration change. Render its complete Pod template, list every taint on the intended nodes, and explain each matching rule and effect. In the approved disposable environment, run an exact-match case, a targeted mismatch, and the relevant existing-Pod or timed-eviction case. Attach the admitted tolerations, node snapshots, scheduler diagnostic, Pod UIDs, and observation times to the pull request before approving the change.