Skip to content

Clarify that node-label is re-applied on every start - #619

Merged
brandond merged 1 commit into
k3s-io:mainfrom
izmal:docs-node-label-reapplied
Nov 13, 2026
Merged

brandond merged 1 commit into
k3s-io:mainfrom
izmal:docs-node-label-reapplied

Conversation

@izmal

@izmal izmal commented Nov 12, 2026

Copy link
Copy Markdown
Contributor

The "Node Labels and Taints" sections in advanced.md and cli/agent.md say that both --node-label and --node-taint are only applied at registration time. That is true for taints, but not for labels:

  • --node-taint is passed to the kubelet as --register-with-taints and only takes effect when the node registers.
  • --node-label is also patched onto the Node object every time K3s starts (configureNode -> updateMutableLabels in pkg/agent/run.go). Labels are added or updated, never removed.

In practice this means a label removed or changed with kubectl comes back on the next K3s restart if it is still in the configuration, and a label removed from the configuration stays on the node. The CLI help text already hints at the difference ("Registering and starting kubelet with set of labels" vs "Registering kubelet with set of taints").

This PR describes both options separately in cli/agent.md, adds a short summary with a link in advanced.md, and notes that labels changed with kubectl must also be changed in the K3s configuration.

The same fix for the RKE2 docs: rancher/rke2-docs#700

--node-taint is only applied at registration, but --node-label is patched
onto the Node object every time K3s starts (configureNode ->
updateMutableLabels). Labels are added or updated, never removed. Describe
both options separately and note that labels changed with kubectl must also
be changed in the K3s configuration.

Signed-off-by: Anton Plaksin <onton.p@gmail.com>
@brandond
brandond merged commit ec22f1b into k3s-io:main Nov 13, 2026
3 of 4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants