kubectl taint nodes: Usage, Options & Common CI Errors
Repel pods from a node unless they explicitly tolerate it.
kubectl taint nodes marks a node so only pods with a matching toleration may schedule there. It dedicates nodes to specific workloads - and is a frequent cause of mysteriously Pending pods in a test cluster.
What it does
kubectl taint nodes NODE key=value:EFFECT adds a taint; the trailing key=value:EFFECT- (or key:EFFECT-) form removes it. EFFECT is NoSchedule (block new pods), PreferNoSchedule (soft preference), or NoExecute (also evict running pods that do not tolerate it). Pods need a matching tolerations entry to land on a tainted node.
Common usage
kubectl taint nodes gpu-1 dedicated=gpu:NoSchedule
kubectl taint nodes gpu-1 dedicated=gpu:NoSchedule- # remove it
kubectl taint nodes node-1 maintenance=true:NoExecute # evict + block
kubectl taint nodes node-1 maintenance:NoExecute- # clear by keyCommon errors in CI
After tainting a node, ordinary pods land Pending with "node(s) had untolerated taint {dedicated: gpu}" - expected, but it breaks pipelines that assumed scheduling, so either taint a dedicated node or give the test pod a matching toleration. A NoExecute taint evicts non-tolerating pods immediately, which can knock out workloads you did not mean to move. "error: at least one taint update is required" means you passed no taint spec. Forgetting to remove a test taint leaves the node effectively cordoned for normal work; clean it up with the key=value:EFFECT- form.