Document CSI node ID annotations by carlory · Pull Request #54035 · kubernetes/website

carlory · 2026-01-16T03:37:34Z

Summary

Documents csi.alpha.kubernetes.io/node-id annotation used on VolumeAttachments for finding node identifiers when CSINode object is unavailable
Documents csi.volume.kubernetes.io/nodeid deprecated annotation previously used on Nodes

🤖 Generated with Claude Code

k8s-ci-robot · 2026-01-16T03:37:48Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign salaxander for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

content/en/docs/OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

carlory · 2026-01-16T03:40:44Z

/cc @lmktfy @jsafrane

carlory · 2026-01-16T03:41:15Z

/hold
util kubernetes/kubernetes#135676 is merged

netlify · 2026-01-16T03:47:00Z

✅ Pull request preview available for checking

Built without sensitive environment variables

Name	Link
🔨 Latest commit	`da7a70a`
🔍 Latest deploy log	https://app.netlify.com/projects/kubernetes-io-main-staging/deploys/69a1045e4c176c0008c8b4e0
😎 Deploy Preview	https://deploy-preview-54035--kubernetes-io-main-staging.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

lmktfy · 2026-01-16T09:45:45Z

It's actually OK to mark both of these deprecated right away, because the paradigm of putting "alpha" or "beta" in the key is deprecated, and any label or annotation using the old way can be marked deprecated on those grounds.

Also we can mark things deprecated even if we don't have a plan to migrate to a different key.

The text should briefly explain the situation to readers though; they might wonder what persistent storage to use if non-CSI is deprecated and CSI depends on using a deprecated annotation.

I think this is fine though; various important subparts of Kubernetes were technically in alpha at the 1.0 release and were still alpha come (eg) v1.17, and the world Did Not End.

carlory · 2026-01-16T10:55:28Z

It's actually OK to mark both of these deprecated right away

@lmktfy we can not deprecated the csi.alpha.kubernetes.io/node-id annotation because the external attacher still uses it.
See kubernetes-csi/external-attacher#83 and https://github.com/kubernetes-csi/external-attacher/blob/master/pkg/controller/csi_handler.go#L755-L784

/cc @jsafrane
for double check.

carlory · 2026-01-19T04:12:59Z

The text should briefly explain the situation to readers though; they might wonder what persistent storage to use if non-CSI is deprecated and CSI depends on using a deprecated annotation.

updated.

lmktfy · 2026-02-23T20:42:02Z

It's actually OK to mark both of these deprecated right away

@lmktfy we can not deprecated the csi.alpha.kubernetes.io/node-id annotation because the external attacher still uses it. See kubernetes-csi/external-attacher#83 and https://github.com/kubernetes-csi/external-attacher/blob/master/pkg/controller/csi_handler.go#L755-L784

You really can; you can deprecate ("ask people not to do") a thing even when it still works.

carlory · 2026-02-24T02:48:02Z

You really can; you can deprecate ("ask people not to do") a thing even when it still works.

Added.

jsafrane · 2026-02-25T13:37:55Z

/lgtm
from sig-storage perspective. csi.volume.kubernetes.io/nodeid is not used anywhere, I think, but as @lmktfy wrote elsewhere, we should document even the unused ones.

k8s-ci-robot · 2026-02-25T13:38:05Z

LGTM label has been added.

Details

Git tree hash: 251ee83316a18e4e48e23ee547f07fdbf1a7cc3d

Adds documentation for csi.alpha.kubernetes.io/node-id annotation used on VolumeAttachments for finding node identifiers when CSINode object is unavailable, and csi.volume.kubernetes.io/nodeid deprecated annotation previously used on Nodes. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> Signed-off-by: carlory <baofa.fan@daocloud.io>

k8s-ci-robot · 2026-02-27T02:41:35Z

New changes are detected. LGTM label has been removed.

carlory · 2026-02-27T02:43:06Z

updated: v1.1.0 --> v2.2. See https://github.com/kubernetes-csi/external-attacher/blob/cc32e8cebcb4433b84c26aacc59e200aecd9f5be/CHANGELOG/CHANGELOG-2.2.md?plain=1#L11

/cc @jsafrane

lmktfy · 2026-04-04T13:23:42Z

content/en/docs/reference/labels-annotations-taints/_index.md

+This annotation is used internally to find the node identifier when it can not be obtained from
+the `CSINode` object. It is populated by the CSI external-attacher sidecar container before a volume is attached.
+
+It provides a fallback mechanism for detaching volumes when a `CSINode` object is not present.


Suggested change

This annotation is used internally to find the node identifier when it can not be obtained from

the `CSINode` object. It is populated by the CSI external-attacher sidecar container before a volume is attached.

It provides a fallback mechanism for detaching volumes when a `CSINode` object is not present.

the CSINode object. It is populated by the CSI external-attacher sidecar container before a volume is attached.

It provides a fallback mechanism for detaching volumes when an appropriate CSINode is not present.

(no backticks on API types, per style guide)

@carlory , are you able to address the above suggestion

lmktfy · 2026-04-04T13:24:43Z

content/en/docs/reference/labels-annotations-taints/_index.md

+
+This annotation was used internally to specify the identifier for a node as understood by the Container Storage Interface (CSI) driver. kubelet populated this annotation by calling the `NodeGetInfo` gRPC method of the CSI driver to retrieve the node ID during the driver registration. And the external-attacher sidecar container read this annotation to get the node ID when attaching or detaching volumes.
+
+But it has been deprecated in favor of the `CSINode` object, which provides the same functionality via the `spec.drivers[].nodeID` field. And it needs the csi driver to bump the external-attacher sidecar to v2.2 or later.


Suggested change

But it has been deprecated in favor of the `CSINode` object, which provides the same functionality via the `spec.drivers[].nodeID` field. And it needs the csi driver to bump the external-attacher sidecar to v2.2 or later.

The annotation has been deprecated in favor of using the CSINode object, which provides the same functionality via the `spec.drivers[].nodeID` field.

Instead of explaining the deprecation, hyperlink to some relevant CSI docs about it.

lmktfy · 2026-04-04T13:26:01Z

content/en/docs/reference/labels-annotations-taints/_index.md

+the `CSINode` object. It is populated by the CSI external-attacher sidecar container before a volume is attached.
+
+It provides a fallback mechanism for detaching volumes when a `CSINode` object is not present.
+


Suggested change

Because this annotation is deprecated, the Kubernetes project recommends that you do

**not** set this on a VolumeAttachment, nor on any other object.

lmktfy

Should this PR target main? I think the deprecation may already have happened.

k8s-ci-robot added this to the 1.36 milestone Jan 16, 2026

k8s-ci-robot added the cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. label Jan 16, 2026

k8s-ci-robot requested review from SayakMukhopadhyay and shannonxtreme January 16, 2026 03:37

k8s-ci-robot added language/en Issues or PRs related to English language size/S Denotes a PR that changes 10-29 lines, ignoring generated files. labels Jan 16, 2026

k8s-ci-robot requested review from jsafrane and lmktfy January 16, 2026 03:40

k8s-ci-robot added the do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. label Jan 16, 2026

carlory force-pushed the follow-up-kk-135676 branch 2 times, most recently from 01dc368 to 4ad3801 Compare January 19, 2026 04:12

k8s-ci-robot added needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. and removed needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. labels Jan 30, 2026

carlory force-pushed the follow-up-kk-135676 branch from 1544bd7 to e427b89 Compare February 2, 2026 02:29

carlory force-pushed the follow-up-kk-135676 branch from e427b89 to e08a839 Compare February 24, 2026 02:42

k8s-ci-robot assigned jsafrane Feb 25, 2026

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Feb 25, 2026

carlory force-pushed the follow-up-kk-135676 branch from e08a839 to da7a70a Compare February 27, 2026 02:41

k8s-ci-robot removed the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Feb 27, 2026

carlory mentioned this pull request Feb 27, 2026

Remove / deprecate the csi.volume.kubernetes.io/nodeid annotation of the Node object? kubernetes/kubernetes#137276

Open

lmktfy reviewed Apr 4, 2026

View reviewed changes


		This annotation was used internally to specify the identifier for a node as understood by the Container Storage Interface (CSI) driver. kubelet populated this annotation by calling the `NodeGetInfo` gRPC method of the CSI driver to retrieve the node ID during the driver registration. And the external-attacher sidecar container read this annotation to get the node ID when attaching or detaching volumes.

		But it has been deprecated in favor of the `CSINode` object, which provides the same functionality via the `spec.drivers[].nodeID` field. And it needs the csi driver to bump the external-attacher sidecar to v2.2 or later.

	But it has been deprecated in favor of the `CSINode` object, which provides the same functionality via the `spec.drivers[].nodeID` field. And it needs the csi driver to bump the external-attacher sidecar to v2.2 or later.
	The annotation has been deprecated in favor of using the CSINode object, which provides the same functionality via the `spec.drivers[].nodeID` field.

		the `CSINode` object. It is populated by the CSI external-attacher sidecar container before a volume is attached.

		It provides a fallback mechanism for detaching volumes when a `CSINode` object is not present.



	Because this annotation is deprecated, the Kubernetes project recommends that you do
	not set this on a VolumeAttachment, nor on any other object.

Conversation

carlory commented Jan 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Uh oh!

k8s-ci-robot commented Jan 16, 2026

Uh oh!

carlory commented Jan 16, 2026

Uh oh!

carlory commented Jan 16, 2026

Uh oh!

netlify bot commented Jan 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Pull request preview available for checking

Uh oh!

lmktfy commented Jan 16, 2026

Uh oh!

carlory commented Jan 16, 2026

Uh oh!

carlory commented Jan 19, 2026

Uh oh!

lmktfy commented Feb 23, 2026

Uh oh!

carlory commented Feb 24, 2026

Uh oh!

jsafrane commented Feb 25, 2026

Uh oh!

k8s-ci-robot commented Feb 25, 2026

Uh oh!

k8s-ci-robot commented Feb 27, 2026

Uh oh!

carlory commented Feb 27, 2026

Uh oh!

lmktfy Apr 4, 2026

Choose a reason for hiding this comment

Uh oh!

reylejano Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

lmktfy Apr 4, 2026

Choose a reason for hiding this comment

Uh oh!

lmktfy Apr 4, 2026

Choose a reason for hiding this comment

Uh oh!

lmktfy left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

carlory commented Jan 16, 2026 •

edited

Loading

netlify bot commented Jan 16, 2026 •

edited

Loading