Skip to content
Switch branches/tags
Go to file
Latest commit 5d81bdf Mar 30, 2022 History
Update stable version to v0.0.22

Signed-off-by: Derek Su <>
10 contributors

Users who have contributed to this file

@yasker @derekbit @nicktming @webwurst @wahlstedtw @mmeinzer @mgoltzsche @jamct @gbonnefille @innobead

Local Path Provisioner

Build StatusGo Report Card


Local Path Provisioner provides a way for the Kubernetes users to utilize the local storage in each node. Based on the user configuration, the Local Path Provisioner will create hostPath based persistent volume on the node automatically. It utilizes the features introduced by Kubernetes Local Persistent Volume feature, but make it a simpler solution than the built-in local volume feature in Kubernetes.

Compare to built-in Local Persistent Volume feature in Kubernetes


Dynamic provisioning the volume using hostPath.


  1. No support for the volume capacity limit currently.
    1. The capacity limit will be ignored for now.


Kubernetes v1.12+.



In this setup, the directory /opt/local-path-provisioner will be used across all the nodes as the path for provisioning (a.k.a, store the persistent volume data). The provisioner will be installed in local-path-storage namespace by default.

  • Stable
kubectl apply -f
  • Development
kubectl apply -f

Or, use kustomize to deploy.

  • Stable
kustomize build "" | kubectl apply -f -
  • Development
kustomize build "" | kubectl apply -f -

After installation, you should see something like the following:

$ kubectl -n local-path-storage get pod
NAME                                     READY     STATUS    RESTARTS   AGE
local-path-provisioner-d744ccf98-xfcbk   1/1       Running   0          7m

Check and follow the provisioner log using:

kubectl -n local-path-storage logs -f -l app=local-path-provisioner


Create a hostPath backend Persistent Volume and a pod uses it:

kubectl create -f
kubectl create -f

Or, use kustomize to deploy them.

kustomize build "" | kubectl apply -f -

You should see the PV has been created:

$ kubectl get pv
NAME                                       CAPACITY   ACCESS MODES   RECLAIM POLICY   STATUS    CLAIM                    STORAGECLASS   REASON    AGE
pvc-bc3117d9-c6d3-11e8-b36d-7a42907dda78   2Gi        RWO            Delete           Bound     default/local-path-pvc   local-path               4s

The PVC has been bound:

$ kubectl get pvc
NAME             STATUS    VOLUME                                     CAPACITY   ACCESS MODES   STORAGECLASS   AGE
local-path-pvc   Bound     pvc-bc3117d9-c6d3-11e8-b36d-7a42907dda78   2Gi        RWO            local-path     16s

And the Pod started running:

$ kubectl get pod
volume-test   1/1       Running   0          3s

Write something into the pod

kubectl exec volume-test -- sh -c "echo local-path-test > /data/test"

Now delete the pod using

kubectl delete -f

After confirm that the pod is gone, recreated the pod using

kubectl create -f

Check the volume content:

$ kubectl exec volume-test cat /data/test

Delete the pod and pvc

kubectl delete -f
kubectl delete -f

Or, use kustomize to delete them.

kustomize build "" | kubectl delete -f -

The volume content stored on the node will be automatically cleaned up. You can check the log of local-path-provisioner-xxx for details.

Now you've verified that the provisioner works as expected.


Customize the ConfigMap

The configuration of the provisioner is a json file config.json, a Pod template helperPod.yaml and two bash scripts setup and teardown, stored in a config map, e.g.:

kind: ConfigMap
apiVersion: v1
  name: local-path-config
  namespace: local-path-storage
  config.json: |-
                        "paths":["/opt/local-path-provisioner", "/data1"]
  setup: |-
        set -eu
        mkdir -m 0777 -p "$VOL_DIR"
  teardown: |-
        set -eu
        rm -rf "$VOL_DIR"
  helperPod.yaml: |-
        apiVersion: v1
        kind: Pod
          name: helper-pod
          - name: helper-pod
            image: busybox



nodePathMap is the place user can customize where to store the data on each node.

  1. If one node is not listed on the nodePathMap, and Kubernetes wants to create volume on it, the paths specified in DEFAULT_PATH_FOR_NON_LISTED_NODES will be used for provisioning.
  2. If one node is listed on the nodePathMap, the specified paths in paths will be used for provisioning.
    1. If one node is listed but with paths set to [], the provisioner will refuse to provision on this node.
    2. If more than one path was specified, the path would be chosen randomly when provisioning.

The configuration must obey following rules:

  1. config.json must be a valid json file.
  2. A path must start with /, a.k.a an absolute path.
  3. Root directory(/) is prohibited.
  4. No duplicate paths allowed for one node.
  5. No duplicate node allowed.

Scripts setup and teardown and the helperPod.yaml template

  • The setup script is run before the volume is created, to prepare the volume directory on the node.
  • The teardown script is run after the volume is deleted, to cleanup the volume directory on the node.
  • The helperPod.yaml template is used to create a helper Pod that runs the setup or teardown script.

The scripts receive their input as environment variables:

Environment variable Description
VOL_DIR Volume directory that should be created or removed.
VOL_MODE The PersistentVolume mode (Block or Filesystem).
VOL_SIZE_BYTES Requested volume size in bytes.


The provisioner supports automatic configuration reloading. Users can change the configuration using kubectl apply or kubectl edit with config map local-path-config. There is a delay between when the user updates the config map and the provisioner picking it up.

When the provisioner detects the configuration changes, it will try to load the new configuration. Users can observe it in the log

time="2018-10-03T05:56:13Z" level=debug msg="Applied config: {"nodePathMap":[{"node":"DEFAULT_PATH_FOR_NON_LISTED_NODES","paths":["/opt/local-path-provisioner"]},{"node":"yasker-lp-dev1","paths":["/opt","/data1"]},{"node":"yasker-lp-dev3"}]}"

If the reload fails, the provisioner will log the error and continue using the last valid configuration for provisioning in the meantime.

time="2018-10-03T05:19:25Z" level=error msg="failed to load the new config file: fail to load config file /etc/config/config.json: invalid character '#' looking for beginning of object key string"

time="2018-10-03T05:20:10Z" level=error msg="failed to load the new config file: config canonicalization failed: path must start with / for path opt on node yasker-lp-dev1"

time="2018-10-03T05:23:35Z" level=error msg="failed to load the new config file: config canonicalization failed: duplicate path /data1 on node yasker-lp-dev1

time="2018-10-03T06:39:28Z" level=error msg="failed to load the new config file: config canonicalization failed: duplicate node yasker-lp-dev3"


Before uninstallation, make sure the PVs created by the provisioner have already been deleted. Use kubectl get pv and make sure no PV with StorageClass local-path.

To uninstall, execute:

  • Stable
kubectl delete -f
  • Development
kubectl delete -f


it providers a out-of-cluster debug env for deverlopers


git clone
cd local-path-provisioner
go build
kubectl apply -f debug/config.yaml
./local-path-provisioner --debug start --service-account-name=default




kubectl delete -f debug/config.yaml


Copyright (c) 2014-2020 Rancher Labs, Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.