TopGit
GitHub Repo Review

Rancher Local Path Provisioner: Dynamic K8s Storage

rancher/local-path-provisioner
RTopGit review image for rancher/local-path-provisioner
Review by Topgit.dev for rancher/local-path-provisioner, with GitHub repository stats and README context.
Quick verdict

Rancher Local Path Provisioner turns a directory on your Kubernetes nodes into a dynamically provisioned hostPath or local persistent volume, instead of making an admin pre-create a PV per path. Reach for it on a small cluster or dev/test setup where node-local storage is fine; skip it if you need enforced capacity limits or volumes that survive losing a node, since the README says limits aren't enforced and the data lives on just that node.

Stars
★ 3.0k
Forks
⑂ 532
Language
Go
License
Apache-2.0
Topic
—
Updated
Nov 2026
Homepage
—
GitHub

What is Rancher Local Path Provisioner?

Rancher Local Path Provisioner is a Kubernetes controller that dynamically creates hostPath or local persistent volumes from directories on your nodes, rather than requiring someone to provision storage ahead of time. It reads a ConfigMap to decide which node and path a given volume should use, building on Kubernetes' own Local Persistent Volume feature while cutting out most of the manual setup that feature normally needs.

Addressing Kubernetes local storage challenges

Kubernetes ships a Local Volume feature for using node disks as persistent storage, but the sig-storage-local-static-provisioner project that manages it can only hand out volumes an administrator already staged on each node ahead of time — it can't create them on demand. Local Path Provisioner closes that specific gap for smaller clusters: it watches for PersistentVolumeClaims and creates the hostPath or local directory on the right node itself, so nobody has to pre-carve storage on every machine before a workload can claim it.

Key capabilities of Local Path Provisioner

  • ✓Dynamic provisioning of hostPath or local volumes, unlike the static local volume provisioner, which can only expose paths an admin already staged.
  • ✓Config lives in the local-path-config ConfigMap: a nodePathMap lists which directories are eligible per node, with a DEFAULT_PATH_FOR_NON_LISTED_NODES fallback for nodes not listed.
  • ✓A sharedFileSystemPath option points the provisioner at one filesystem mounted on every node at once, the only mode that supports ReadWriteMany and ReadOnlyMany alongside ReadWriteOnce.
  • ✓Per-PVC or per-StorageClass volumeType (or defaultVolumeType) annotation picks hostPath vs. local, defaulting to hostPath when neither is set.
  • ✓nodePath and pathPattern StorageClass parameters control which node and subdirectory a class writes to, with userPattern/groupPattern/permPattern setting ownership and permissions on that directory.
  • ✓nodeAffinityKey lets a StorageClass pin PV node affinity to a stable label instead of kubernetes.io/hostname, for nodes whose hostnames change when they're recreated.
  • ✓Automatic ConfigMap reloading — edits to local-path-config apply without restarting the provisioner, and an invalid config is rejected while the last valid one keeps running.
  • ✓Custom setup/teardown scripts or setupCommand/teardownCommand binaries, plus a helperPod.yaml template useful for distroless images, with pod-spec fields validated unless --allow-unsafe-helper-pod-template is set.
How this repository's GitHub stars have grown over time. Source: star-history.com.View the star history ↗

Strengths

  • ✓Dynamic provisioning where Kubernetes' own local volume provisioner can't — no pre-created PV needed before a PVC can claim one.
  • ✓One ConfigMap for configuration: nodePathMap, sharedFileSystemPath, path templates, and user/group/permission patterns are all editable there and reload automatically.
  • ✓Fine-grained placement control via nodePath, pathPattern, and nodeAffinityKey — you decide which node, which subdirectory, and how PV node affinity is set.
  • ✓Apache-2.0 licensed and maintained under the Rancher org.
  • ✓A bad config doesn't take the provisioner down — a failed reload gets logged, and it keeps running on the last valid configuration.

Current limitations of the provisioner

  • △No enforced volume capacity limit — the README states the capacity limit is ignored today, so a claim's requested size isn't a hard ceiling.
  • △Volumes are tied to whichever node created them; if that node is lost, the data on it is lost too, since this isn't a replicated storage backend.
  • △Requires Kubernetes v1.12 or newer.
  • △Uninstalling requires deleting every PV on the local-path StorageClass first, per the README, with no built-in migration path off it.
  • △Helper pod safety checks block several pod-spec fields by default; opting out with --allow-unsafe-helper-pod-template is flagged in the README as something to use only for trusted, administrator-managed setups.

Installing Local Path Provisioner

Installing Rancher Local Path Provisioner means applying one manifest: `kubectl apply -f https://raw.githubusercontent.com/rancher/local-path-provisioner/v0.0.37/deploy/local-path-storage.yaml` for the stable v0.0.37 release, or swap in `master` for the development branch. A kustomize build of the same `deploy` directory works too. By default it installs into the `local-path-storage` namespace and uses `/opt/local-path-provisioner` on every node as the storage directory, and it needs Kubernetes v1.12 or newer. Confirm it's running with `kubectl -n local-path-storage get pod`, and tail its behavior with `kubectl -n local-path-storage logs -f -l app=local-path-provisioner`.

Using Local Path Provisioner for persistent volumes

The example workflow applies a PVC and a pod that mounts it: `kubectl create -f .../examples/pvc/pvc.yaml` then `kubectl create -f .../examples/pod/pod.yaml` (a kustomize build of the examples/pod directory does the same thing). `kubectl get pv` and `kubectl get pvc` then show a bound volume on the `local-path` StorageClass. Write a file into the pod's mounted path, delete the pod, recreate it, and the file is still there, because the data lives in a directory on the node, not in the pod. Delete both the pod and the PVC and that directory is cleaned up automatically — you can watch it happen in the provisioner's own log.

Local Path Provisioner vs. built-in Kubernetes local volumes

sig-storage-local-static-provisioner — Kubernetes' own local volume provisioner; it exposes pre-staged local disks as PVs but can't create them dynamically the way Local Path Provisioner does.Manual hostPath volumes — mounting a host directory directly with no provisioner involved; works, but every PV is created by hand with none of the path templating or reload behavior here.Longhorn — Rancher's own distributed block storage for Kubernetes, replicating data across nodes; worth it once node-local storage stops being durable enough.OpenEBS — another Kubernetes-native storage layer with multiple engines, including replicated ones, for workloads that need a volume to survive losing a node.

Frequently asked questions

What is the license for Rancher Local Path Provisioner?

Rancher Local Path Provisioner is released under the Apache License 2.0 (Apache-2.0), copyrighted by Rancher Labs, Inc.

What Kubernetes versions are required for Local Path Provisioner?

Local Path Provisioner requires Kubernetes v1.12 or later, per its README.

Does Local Path Provisioner support volume capacity limits?

Local Path Provisioner does not currently enforce volume capacity limits; the README says any capacity limit set on a claim is ignored for now.

Can Local Path Provisioner use a shared filesystem for volumes?

Local Path Provisioner can use a shared filesystem through the sharedFileSystemPath configuration option, which points to storage mounted identically on every node and supports ReadWriteOnce, ReadOnlyMany, and ReadWriteMany access.

How can I customize storage paths for specific nodes?

Local Path Provisioner reads a nodePathMap in its local-path-config ConfigMap, where each node name lists the directories it should use; unlisted nodes fall back to DEFAULT_PATH_FOR_NON_LISTED_NODES, and a node with an empty paths list is refused for provisioning.

What is the default volume type provisioned by Local Path Provisioner?

Local Path Provisioner defaults to hostPath-backed volumes unless a volumeType or defaultVolumeType annotation on the PVC or StorageClass requests local instead.

Best use cases

  • •Giving a small or single-node Kubernetes cluster persistent storage without standing up a separate distributed storage system.
  • •Local development and CI clusters where pods just need a node directory that survives a pod restart, not a node failure.
  • •Pinning a StorageClass to a specific fast local disk on specific nodes with the nodePath parameter.
  • •Clusters with VM-backed nodes whose hostnames change on recreation, using nodeAffinityKey to keep existing PVs schedulable.

Who should try it — and who should skip

Try Rancher Local Path Provisioner if you run Kubernetes on a small cluster, in dev/test, or anywhere pods just need a node directory that outlives a pod restart, and you'd rather not operate a distributed storage system for that. Skip it if you need capacity limits enforced or volumes that survive a node being replaced — that's a job for a replicated storage layer, not this provisioner.

Source & attribution

Facts and quotes sourced from the rancher/local-path-provisioner GitHub repository and its README.

GitHub data · last synced Aug 12, 2026Reviewed by Henry
← Back to TopGit

Want a second opinion on local-path-provisioner?

Ask an AI that can read this page — one click and you get its take on local-path-provisioner.

GitHub