kubectl taint: Repel Pods From Nodes
kubectl taint adds a taint to a node so pods without a matching toleration are kept off (or evicted from) it.
Taints reserve nodes for specific workloads or mark them for maintenance. The effect (NoSchedule, PreferNoSchedule, NoExecute) decides how strict it is.
What it does
kubectl taint sets a key=value:effect on a node. NoSchedule blocks new pods lacking a toleration, PreferNoSchedule is a soft preference, and NoExecute also evicts already-running pods that do not tolerate it. Appending - to the taint removes it.
Common usage
kubectl taint nodes node-1 dedicated=ci:NoSchedule
# evict non-tolerating pods too
kubectl taint nodes node-1 maintenance=true:NoExecute
# remove a taint (note the trailing -)
kubectl taint nodes node-1 dedicated=ci:NoSchedule-Options
| Syntax / Flag | What it does |
|---|---|
| <key>=<value>:NoSchedule | Block scheduling of non-tolerating pods |
| <key>=<value>:NoExecute | Also evict running non-tolerating pods |
| <key>=<value>:PreferNoSchedule | Soft preference to avoid the node |
| <key>:<effect>- | Remove the taint with that key and effect |
| --overwrite | Replace an existing taint value for the key |
| -l, --selector | Taint all nodes matching a label |
In CI
Pods need a matching toleration to land on a tainted node, so taint and toleration are edited together; tainting a node without updating the workloads will leave pods Pending. NoExecute is disruptive: it evicts immediately, so combine it with a PodDisruptionBudget-aware drain for graceful maintenance.
Common errors in CI
"error: Node node-1 already has dedicated taint(s) with same key and effect" means the taint exists; add --overwrite to change the value or remove it first. "error: ... not found" for the key on removal means the taint was not present. Pods stuck Pending with "node(s) had untolerated taint" confirm the taint is doing its job but the workload lacks a toleration.
Using this in CI
A runner has no kubeconfig, no cached context, and no interactive auth. Every kubectl invocation in CI needs the context supplied explicitly, and most confusing CI failures here are the command running against the wrong cluster or no cluster at all.
# never rely on the ambient context on a runner
kubectl --context "$KUBE_CONTEXT" -n "$NAMESPACE" get pods
# confirm what you are actually connected to before mutating anything
kubectl config current-context
kubectl cluster-info
# fail fast instead of hanging on an unreachable API server
kubectl --request-timeout=30s get nodes