LocalVolume volumes let you mount local storage devices—such as disks, partitions, or directories—to pods. Unlike HostPath volumes, LocalVolume volumes support node affinity scheduling, which ensures that pods are always scheduled to the node where the local storage exists.
Limitations
Before using LocalVolume volumes, be aware of the following constraints:
-
Supported nodes: ECS nodes only. GPU nodes, Lingjun nodes, ECI, and ACS are not supported.
-
No dynamic provisioning: LocalVolume volumes do not support dynamic provisioning. All PersistentVolumes (PVs) must be created statically.
-
Node availability: If a node becomes unavailable, the local volume on that node is also unavailable, and any pod using it cannot run. Applications must tolerate this reduced availability and potential data loss, depending on the durability of the underlying disk.
LocalVolume vs. HostPath
| Feature | LocalVolume | HostPath |
|---|---|---|
| Node affinity scheduling | Supported | Not supported |
| Supported mount types | Directories and raw devices | Directories, files, and other formats |
| Automatic directory creation | Not supported | Supported |
Create a PersistentVolume
The following YAML defines a LocalVolume-type PV. Apply it to statically provision local storage on a specific node.
apiVersion: v1
kind: PersistentVolume
metadata:
name: example-pv
spec:
capacity:
storage: 100Gi
volumeMode: Filesystem
accessModes:
- ReadWriteOnce
persistentVolumeReclaimPolicy: Delete
storageClassName: local-storage
local:
path: /mnt/disks/ssd1
nodeAffinity:
required:
nodeSelectorTerms:
- matchExpressions:
- key: kubernetes.io/hostname
operator: In
values:
- example-node`nodeAffinity` is required. The Kubernetes scheduler uses this field to schedule pods to the correct node—the one where the local storage physically exists. Without it, pods may be scheduled to nodes that do not have access to the volume.
Automate PV lifecycle with the static provisioner
LocalVolume does not support dynamic provisioning. If you manage PV creation manually, you are also responsible for manually deleting and cleaning up PVs when they are no longer needed.
To automate PV discovery and lifecycle management, deploy the community sig-storage-local-static-provisioner. The provisioner watches a configured directory on each node and automatically creates and deletes PVs as local disks appear and are removed.
What's next
-
For the Kubernetes upstream specification for local volumes, see local.
-
For automated PV management, see the sig-storage-local-static-provisioner documentation.