Node Labels and Node Taints

How to configure and use Kubernetes node labels and taints with Talos.

Talos supports configuring node labels and node taints, both of which influence scheduling and workload placement in Kubernetes.

Kubernetes restricts which labels and taints a node can modify on its own Node object.
These restrictions are enforced by the Kubernetes NodeRestriction admission controller, which is enabled by default in Talos and cannot be disabled.

NodeRestriction prevents a node (via its kubelet identity) from modifying anything outside a small, whitelisted set of fields. This ensures worker nodes cannot escalate privileges or assign sensitive labels or taints to themselves.

nodeLabels

Talos can propagate labels from machine.nodeLabels to the Kubernetes Node object.
These labels are written using the node’s kubelet identity and therefore must comply with NodeRestriction rules.

Allowed labels

Only a limited set of labels may be modified by the node itself, such as:

• topology.kubernetes.io/region
• topology.kubernetes.io/zone
• kubernetes.io/hostname
• kubernetes.io/arch
• kubernetes.io/os
• some node.kubernetes.io/* labels

Labels outside this set—including the conventional Kubernetes role labels node-role.kubernetes.io/<role>—are rejected by the API server when applied by the node.

This prevents worker nodes from assigning themselves privileged roles.

Apply nodeLabels

You can add labels to a node by specifying them in a KubeNodeConfig document:

apiVersion: v1alpha1
kind: KubeNodeConfig
labels:
  topology.kubernetes.io/zone: "pve03"
  topology.kubernetes.io/region: "Region-1"

On Talos versions earlier than v1.14, use the older configuration field:

machine:
  nodeLabels:
    topology.kubernetes.io/zone: "pve03"
    topology.kubernetes.io/region: "Region-1"

After applying the machine config, verify the labels with:

kubectl describe node <node-name>

Role labels

To assign Kubernetes role labels such as:

• node-role.kubernetes.io/worker
• node-role.kubernetes.io/ingress
• node-role.kubernetes.io/control-plane

You must apply them using a cluster-admin Kubernetes account:

kubectl label node <node-name> node-role.kubernetes.io/worker=""

Alternatively, you can use the Talos Cloud Controller Manager or your own controller to translate custom domain labels into the conventional node-role.kubernetes.io/* form if required.

Node taints

Kubernetes taints let you prevent workloads from being scheduled on a node unless they have matching tolerations. You can learn more in the official Taints and Tolerations documentation.

Due to NodeRestriction, worker nodes cannot modify taints on their Node object after they have joined the cluster. This includes adding, removing, or updating taints.

Attempting to do so results in errors such as: <node-name> is not allowed to modify taints.

This behaviour is expected and required for Kubernetes hardening.

Apply taints

Talos can manage node taints through the KubeNodeConfig document. These taints are reconciled by Talos onto the Node object.

These must be configured under:

apiVersion: v1alpha1
kind: KubeNodeConfig
taints:
  <key>: <value>:<effect>

On Talos versions earlier than v1.14, use the older configuration field:

machine:
  nodeTaints:
    node.kubernetes.io/assignment: infra:NoSchedule

Example: Add a NoSchedule taint to a worker node

To add a taint to a worker node, create a patch with this example NoSchedule taint:

apiVersion: v1alpha1
kind: KubeNodeConfig
taints:
  node.kubernetes.io/assignment: infra:NoSchedule

Apply this patch to your worker node’s configuration file.

Modify taints after bootstrap

After a node has joined the cluster, taints must be managed using a cluster-admin identity:

kubectl taint nodes <node-name> key=value:NoSchedule

Worker nodes cannot modify their own taints in any way after registration, and Talos does not permit disabling the admission controller to bypass this.