kubectl-taint

Apply taint to a node

$ kubectl taint [[no|nodes]] [node_name] [label_key]=[label_value]:[effect]

$ kubectl taint [[no|nodes]] [node_name] [label_key]:[effect]-

$ kubectl taint [[no|nodes]] [node_name] [label_key]-

kubectl taint (node|nodes) NAME KEY_1=VALUE_1:EFFECT_1 [KEY_2=VALUE_2:EFFECT_2...] [KEY_N:EFFECT_N-|KEY_N-] [--overwrite] [--all] [--dry-run=strategy] [--help]

NAME
    The name of the node(s) to apply or remove taints from. Can be a single node name or multiple names separated by spaces.

KEY=VALUE:EFFECT
    Specifies a taint to add or update. The format is key=value:effect. Multiple taints can be specified in a single command.

KEY:EFFECT-
    Specifies a taint to remove. The format is key:effect-. This removes a taint with a specific key and effect. If the value differs, it will still match.

KEY-
    Specifies a taint to remove by its key, regardless of its value or effect. This removes all taints that share the specified key.

--all
    If true, taints all nodes in the cluster. This option cannot be used when specific node NAMEs are provided.

--overwrite
    If true, allows existing taints to be overwritten or updated. If a taint with the same key already exists but has a different value or effect, it will be modified. If false, the command will skip applying a new taint if one with the same key already exists.

--dry-run=strategy
    If true, only print the object that would be sent to the API server, without actually sending it. Possible values for strategy are 'client', 'server', or 'none'. Defaults to 'client'.

--help, -h
    Provides help information for the taint command.

The kubectl taint command allows administrators to add, update, or remove taints on one or more Kubernetes nodes.

Taints are key-value pairs associated with an effect (e.g., NoSchedule, PreferNoSchedule, NoExecute) that are applied to nodes. They are used to repel a set of pods from nodes that do not tolerate them. This mechanism, combined with tolerations defined in pod specifications, enables flexible scheduling policies.

When a node has a taint, Kubernetes will not schedule any pod on that node unless the pod has a matching toleration. This command provides a straightforward way to manage these crucial scheduling directives, ensuring pods are placed on appropriate nodes based on cluster policies and node conditions.

Incorrect use of taints can lead to pods failing to schedule, an unbalanced cluster, or unexpected pod evictions. It is crucial to understand the implications of each taint effect (NoSchedule, PreferNoSchedule, NoExecute) before applying them. Removing taints does not automatically re-schedule existing pods that were previously evicted by a NoExecute taint; instead, new pods will be scheduled based on the updated node conditions.

There are three primary effects that can be applied to a taint:
NoSchedule: New pods without a matching toleration will not be scheduled on the node. Existing pods already running on the node are not affected.
PreferNoSchedule: Kubernetes attempts to avoid placing pods without a matching toleration on the node, but it is not a strict enforcement rule. This is a 'soft' version of NoSchedule.
NoExecute: New pods without a matching toleration will not be scheduled on the node. Additionally, any existing pods already running on the node that do not tolerate this taint will be evicted. Pods with a matching toleration may remain on the node, or be evicted based on their `tolerationSeconds` field if specified.

Taints can be removed by appending a hyphen (-) to the taint specification. For example, to remove a specific taint with a key, value, and effect (e.g., key=value:effect), use key=value:effect-. To remove all taints with a specific key regardless of their value or effect, use the shorthand key-.

The concept of Taints and Tolerations was introduced in Kubernetes version 1.6 as a beta feature, becoming stable in later releases. The kubectl taint command was subsequently added as a convenient and direct way to manage these node properties, simplifying the process of applying and removing scheduling constraints without requiring direct manipulation of node manifests.

kubectl describe(1), kubectl get(1), kubectl cordon(1), kubectl uncordon(1), kubectl drain(1)