Volume management

How kubelet mounts and unmounts the volumes a pod requires. The kubelet's job here is small — it picks the right plugin and asks it to mount — but the surrounding lifecycle (waiting for attach, projecting tokens, surfacing failures in pod status) is intricate.

Players

• Volume Manager (pkg/kubelet/volumemanager/) — the per-kubelet reconciler. Maintains a desired-state-of-world (DSW) computed from pods and an actual-state-of-world (ASW) computed from local mount state.
• Volume Host (pkg/kubelet/volume_host.go) — the kubelet's implementation of pkg/volume.VolumeHost, the dependency-injection seam that volume plugins use to get a kubelet-flavored API client, mounter, recorder, and so on.
• Plugin registry (pkg/volume/plugins.go) — every registered VolumePlugin. The kubelet, kube-controller-manager, and e2e framework all build their own registries.
• CSI plugin (pkg/volume/csi/) — the bridge to out-of-tree CSI drivers via gRPC over Unix sockets.
• Plugin manager (pkg/kubelet/pluginmanager/) — listens to /var/lib/kubelet/plugins_registry/ for new CSI/device-plugin sockets, registers them with the appropriate manager.

Reconciliation

graph LR
    Pods[Pod cache] -->|expected mounts| DSW[Desired-state-of-world]
    Mount[/proc/mounts] -->|observed mounts| ASW[Actual-state-of-world]
    DSW --> Reconciler
    ASW --> Reconciler
    Reconciler -->|mount missing| AttachMount[Attach + Mount]
    Reconciler -->|mount extra| Unmount
    AttachMount --> ASW
    Unmount --> ASW

The reconciler runs once per second by default. For each pod-volume in DSW that isn't in ASW it issues mount; for each in ASW that isn't in DSW it issues unmount. State changes are also driven by pod-source events (the volume manager subscribes to the pod manager) and by VolumeAttachment events (for CSI volumes that the attach/detach controller handles).

In-tree vs CSI

Historically, every storage type was implemented in-tree under pkg/volume/<name>/. CSI migration moved most of these out-of-tree:

• pkg/volume/csi/ is the in-tree adaptor that talks gRPC to a CSI driver pod.
• pkg/volume/csimigration/ does the translation step so that an in-tree volume spec (e.g. awsElasticBlockStore) is silently rewritten to a CSI spec when the corresponding CSI driver is installed.
• staging/src/k8s.io/csi-translation-lib/ is the shared translation library used by kubelet and the attach/detach controller.

Remaining always-in-tree plugins (because they have no out-of-tree equivalent):

• configmap, secret, downwardapi, projected — synthetic in-process volumes.
• emptyDir — node-local scratch.
• hostPath — node host filesystem mount.
• local — node-local PV with topology.
• image — container image as read-only volume.
• git_repo — deprecated.
• nfs, iscsi, fc — protocol-level mounts that don't have a CSI driver in-tree but can be replaced by external CSI drivers.

Token and certificate projection

projected volumes synthesize their content at mount time from:

• serviceAccountToken — bound, audience-scoped tokens minted via pkg/kubelet/token/ and the apiserver's TokenRequest API.
• configMap, secret, downwardAPI — read from the kubelet's per-pod cache.
• clusterTrustBundle — projected via pkg/kubelet/clustertrustbundle/.
• podCertificate (newer feature) — kubelet-minted client certificates per pod, in pkg/kubelet/podcertificate/.

The volume manager re-renders projected volumes at refresh interval so tokens and trust bundles stay current.

Resize / expand

Volume expansion is split:

• Online expand of CSI volumes is handled by kubelet via pkg/volume/csi/csi_block.go and nodeExpand calls.
• Offline expand requires the controller-side expand controller (pkg/controller/volume/expand/).
• The resource itself is the PersistentVolumeClaim.Spec.Resources.Requests.Storage value.

Failure surface

Volume failures are surfaced via:

• Kubelet events (FailedAttachVolume, FailedMount, SuccessfulAttachVolume, SuccessfulMountVolume).
• Pod conditions: PodInitializing, Unschedulable.
• The pod's Status.Conditions may include Ready=false with the message coming from the volume manager.

Key source files

File	Purpose
pkg/kubelet/volumemanager/volume_manager.go	Reconciler entry point
pkg/kubelet/volumemanager/cache/desired_state_of_world.go	DSW
pkg/kubelet/volumemanager/cache/actual_state_of_world.go	ASW
pkg/kubelet/volumemanager/reconciler/reconciler.go	Reconcile loop
pkg/kubelet/volume_host.go	VolumeHost binding
pkg/volume/plugins.go	Plugin registry
pkg/volume/csi/	CSI client
pkg/volume/csimigration/	In-tree → CSI translation orchestration
pkg/kubelet/pluginmanager/pluginwatcher/plugin_watcher.go	Socket-discovery for CSI / device plugins