kubectl taint: Usage, Options & Common CI Errors
Repel pods from a node unless they explicitly tolerate it.
kubectl taint marks a node so that only pods with a matching toleration may schedule (or stay) there. It is how you dedicate nodes to specific workloads - and a frequent cause of mysteriously Pending pods.
What it does
kubectl taint nodes NODE key=value:EFFECT adds a taint; the trailing key=value:EFFECT- form removes it. EFFECT is NoSchedule (block new pods), PreferNoSchedule (soft), or NoExecute (also evict running pods without the toleration). Pods need a matching tolerations entry in their spec 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 + blockCommon errors in CI
After tainting a node in a test, ordinary pods land Pending with "node(s) had untolerated taint {dedicated: gpu}" - expected, but it breaks pipelines that assumed the pod would schedule; either taint a dedicated node or give the test pod a matching toleration. A NoExecute taint immediately evicts non-tolerating pods, which can knock out workloads you did not intend to move. Forgetting to remove a test taint leaves the node effectively cordoned for normal work; clean it up with the key=value:EFFECT- form.