Kubernetes storageclass using Rancher Local Path Provisioner: Complete Step-by-Step Kubernetes Tutorial

Goal: Automatically provision hostPath-backed PersistentVolumes (PVs) for a 3-replica StatefulSet on a self-managed Ubuntu Kubernetes cluster, without hand-writing a PV or a PVC manifest.

Scope: For the application, you maintain only two YAML manifests: sc.yaml and sfs.yaml. You still install a cluster-level provisioner once. The provisioner installation itself contains a controller, RBAC permissions, configuration, and helper resources; these cannot be replaced by a StorageClass alone. StatefulSet generates PVC objects, and the provisioner generates PV objects automatically.

Safety: This is ideal for labs, development, and certain node-local workloads. It is not replicated or portable storage, and hostPath warrants careful security controls. With reclaimPolicy: Delete, deleting a PVC can delete its data. Do not use the cleanup commands on important workloads.

1. Understand the architecture

                Self-managed Kubernetes cluster

  +------------------------------------------------------+
  | Local Path Provisioner controller (installed once)   |
  |               rancher.io/local-path                  |
  +---------------------------+--------------------------+
                              |
                     watches PVC requests
                              |
  +---------------------------v--------------------------+
  | StorageClass: local-storage                           |
  | provisioner: rancher.io/local-path                    |
  | defaultVolumeType: hostPath                           |
  | volumeBindingMode: WaitForFirstConsumer               |
  +---------------------------+--------------------------+
                              |
                StatefulSet: local-test (3)
                   /           |           \
               Pod-0         Pod-1         Pod-2
                 |             |             |
               PVC-0         PVC-1         PVC-2
                 |             |             |
           auto PV-0      auto PV-1      auto PV-2
                 |             |             |
          hostPath dir   hostPath dir   hostPath dir
          on its node    on its node    on its node

Important distinction:

WaitForFirstConsumer delays scheduling-aware binding/provisioning. It does not turn kubernetes.io/no-provisioner into a dynamic provisioner.

The StatefulSet automatically creates one PVC per replica. The Rancher controller then creates the corresponding PV and backing directory on the chosen node. A 1Gi storage request records capacity for Kubernetes scheduling/accounting, but Rancher Local Path Provisioner does not enforce a 1Gi filesystem quota.

2. Prerequisites

You need:

• A running Ubuntu-based Kubernetes cluster with kubectl configured and cluster-admin rights for installation.
• At least one Ready, schedulable worker node. Your earlier cluster has two nodes, and one was excluded by an untolerated taint; avoid using the control-plane node for this lab.
• Working cluster networking, DNS, and access to pull images from a container registry.
• Available disk space on the worker node under /opt (or a custom configured storage root).
• Your original local-test StatefulSet and local-storage StorageClass are disposable lab resources if you follow the replacement steps.

Check your cluster:

kubectl version
kubectl cluster-info
kubectl get nodes -o wide
kubectl get nodes -o custom-columns=NAME:.metadata.name,TAINTS:.spec.taints
kubectl get sc
kubectl get pv
kubectl get pvc -A
Code language: JavaScript (javascript)

Check available disk space on each worker node that may store volumes:

df -h /opt

A storage request of 1Gi is not a disk usage limit with this provisioner. Plan actual disk capacity for all three replicas, logs, images, and node operations.

3. Remove the previous failed lab resources (only if disposable)

Your old StorageClass used kubernetes.io/no-provisioner, and the PVC local-vol-local-test-0 stayed Pending. The StorageClass provisioner field cannot be changed in place; recreate that particular class.

Read before running: these commands remove only your local-test example and its specifically named claims. Do not delete unrelated PVs/PVCs such as deehostpath, hostpath, or hostpath2.

<em># Inspect first</em>
kubectl get statefulset local-test --ignore-not-found
kubectl get pvc local-vol-local-test-0 local-vol-local-test-1 local-vol-local-test-2 --ignore-not-found
kubectl get sc local-storage --ignore-not-found

<em># Delete the old StatefulSet, then its example PVCs</em>
kubectl delete statefulset local-test --ignore-not-found
kubectl delete pvc \
  local-vol-local-test-0 \
  local-vol-local-test-1 \
  local-vol-local-test-2 \
  --ignore-not-found

<em># Recreate the class later with the correct provisioner</em>
kubectl delete storageclass local-storage --ignore-not-found
Code language: HTML, XML (xml)

If these objects are already absent, skip this step. If they contain valuable data, do not delete them; use different demo names instead.

4. Install Rancher Local Path Provisioner (once per cluster)

Use the versioned upstream manifest rather than the moving master branch for a repeatable lab:

kubectl apply -f \
  https://raw.githubusercontent.com/rancher/local-path-provisioner/v0.0.37/deploy/local-path-storage.yaml
Code language: JavaScript (javascript)

This upstream manifest installs the provisioner in namespace local-path-storage. It also creates its own example/default-named local-path StorageClass. We will separately create our local-storage StorageClass next.

Verify installation:

kubectl get namespace local-path-storage
kubectl get deploy -n local-path-storage
kubectl get pods -n local-path-storage -o wide
kubectl rollout status deploy/local-path-provisioner -n local-path-storage --timeout=180s
kubectl get sc
Code language: JavaScript (javascript)

Expected: the local-path-provisioner Deployment is available and its Pod is Running (the Pod suffix will differ).

Check controller logs:

kubectl logs -n local-path-storage \
  -l app=local-path-provisioner --tail=100

What did that installation create?

kubectl get all -n local-path-storage
kubectl get configmap local-path-config -n local-path-storage
kubectl get sc local-path -o yaml
Code language: JavaScript (javascript)

The default configuration stores data beneath /opt/local-path-provisioner on the worker node that receives the Pod. The provisioner creates the per-volume directory automatically; you normally do not need to create each directory manually.

5. Create the dynamic StorageClass — sc.yaml

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: local-storage
  annotations:
    defaultVolumeType: hostPath
provisioner: rancher.io/local-path
reclaimPolicy: Delete
volumeBindingMode: WaitForFirstConsumer

Save the YAML above as sc.yaml, then apply it:

kubectl apply -f sc.yaml
kubectl get sc
kubectl describe sc local-storage
Code language: JavaScript (javascript)

What the key fields do:

Rancher defaults to hostPath if the volume type isn’t specified, but the explicit annotation makes the lab unambiguous. A PVC-level volumeType annotation can override this StorageClass default.

Important: This does not set local-storage as the cluster’s default StorageClass. Your StatefulSet explicitly requests it, which is safer for a lab.

6. Create the StatefulSet — sfs.yaml

This matches your original StatefulSet design, but replaces the old BusyBox image location and uses the new dynamically provisioned class.

apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: local-test
spec:
  serviceName: local-service
  replicas: 3
  selector:
    matchLabels:
      app: local-test
  template:
    metadata:
      labels:
        app: local-test
    spec:
      containers:
        - name: test-container
          image: busybox:1.36
          command:
            - /bin/sh
            - -c
          args:
            - sleep 100000
          volumeMounts:
            - name: local-vol
              mountPath: /usr/test-pod
  volumeClaimTemplates:
    - metadata:
        name: local-vol
      spec:
        accessModes:
          - ReadWriteOnce
        storageClassName: local-storage
        resources:
          requests:
            storage: 1Gi
Code language: JavaScript (javascript)

Save as sfs.yaml, and apply:

kubectl apply -f sfs.yaml
kubectl get statefulset local-test
kubectl get pods -o wide -w
Code language: JavaScript (javascript)

Each Pod gets its own PVC automatically, named:

local-vol-local-test-0
local-vol-local-test-1
local-vol-local-test-2

Why you may see only Pod 0 at first: By default, StatefulSets use ordered creation (OrderedReady): local-test-1 is not created until local-test-0 becomes Ready, and similarly for Pod 2.

The StatefulSet references serviceName: local-service. For a complete StatefulSet network identity, Kubernetes recommends creating a matching headless Service. Its absence is not the cause of your PV/PVC provisioning error; an optional Service manifest is shown in Section 13. The two main application YAML files remain sc.yaml and sfs.yaml.

7. Confirm the three dynamic PVs and PVCs

kubectl get statefulset local-test
kubectl get pods -o wide
kubectl get pvc
kubectl get pv
kubectl describe pvc local-vol-local-test-0
kubectl describe pod local-test-0
Code language: JavaScript (javascript)

Typical outcome (names/ages may differ):

$ kubectl get pods
NAME           READY   STATUS    RESTARTS
local-test-0   1/1     Running   0
local-test-1   1/1     Running   0
local-test-2   1/1     Running   0

$ kubectl get pvc
NAME                     STATUS   VOLUME       CAPACITY   ACCESS MODES   STORAGECLASS
local-vol-local-test-0   Bound    pvc-<uid0>   1Gi        RWO            local-storage
local-vol-local-test-1   Bound    pvc-<uid1>   1Gi        RWO            local-storage
local-vol-local-test-2   Bound    pvc-<uid2>   1Gi        RWO            local-storage
Code language: HTML, XML (xml)

The PVs’ .spec.storageClassName should be local-storage; their claim references should point to the three local-vol-local-test-* PVCs.

Verify the PV backend is really hostPath

<em># Find the PV name for replica 0</em>
PV=$(kubectl get pvc local-vol-local-test-0 -o jsonpath='{.spec.volumeName}')
echo "$PV"

<em># Read its hostPath (must be nonempty)</em>
kubectl get pv "$PV" -o jsonpath='{.spec.hostPath.path}{"\n"}'

<em># Inspect the full PV object (hostPath and node affinity)</em>
kubectl get pv "$PV" -o yaml

<em># Display PV backend paths for all PVs (old PVs may have different storage classes)</em>
kubectl get pv -o custom-columns=NAME:.metadata.name,STORAGECLASS:.spec.storageClassName,HOSTPATH:.spec.hostPath.path
Code language: PHP (php)

The PV will contain a spec.hostPath entry resembling:

spec:
  hostPath:
    path: /opt/local-path-provisioner/pvc-<uid>_default_local-vol-local-test-0
    type: DirectoryOrCreate
Code language: JavaScript (javascript)

The actual generated directory name will differ. Inspect the live PV to determine the exact path; do not assume the example path is literal.

Verify PV affinity and the selected node

kubectl get pod local-test-0 -o wide
kubectl get pv "$PV" -o yaml
Code language: JavaScript (javascript)

The PV is associated with the node where its data lives, commonly through nodeAffinity using kubernetes.io/hostname. A Pod using this PVC cannot automatically move its data to another node.

8. Test persistence inside a replica

Write a file into the PVC-backed mount:

kubectl exec local-test-0 -- sh -c \
  'echo "Hello from Rancher dynamic hostPath" > /usr/test-pod/hello.txt'

kubectl exec local-test-0 -- cat /usr/test-pod/hello.txt
Code language: JavaScript (javascript)

Expected:

Hello from Rancher dynamic hostPath
Code language: JavaScript (javascript)

Delete only the Pod (not the PVC):

kubectl delete pod local-test-0
kubectl get pod local-test-0 -w
Code language: JavaScript (javascript)

Once it is Running and Ready again:

kubectl exec local-test-0 -- cat /usr/test-pod/hello.txt

Expected: the same text. This demonstrates persistence across Pod recreation on its original storage node. It does not demonstrate survival of worker-node disk failure or data movement between nodes.

9. Verify separate data for separate replicas

for i in 0 1 2; do
  kubectl exec "local-test-$i" -- sh -c \
    "echo Replica-$i > /usr/test-pod/replica.txt"
done

for i in 0 1 2; do
  printf 'Pod %s: ' "$i"
  kubectl exec "local-test-$i" -- cat /usr/test-pod/replica.txt
done
Code language: JavaScript (javascript)

Expected:

Pod 0: Replica-0
Pod 1: Replica-1
Pod 2: Replica-2

Each StatefulSet replica gets its own PVC and PV. Even when the PVs reside on the same worker, they use different directories.

10. Locate the data on the Ubuntu worker node

First identify the node hosting replica 0, and read its PV’s path:

NODE=$(kubectl get pod local-test-0 -o jsonpath='{.spec.nodeName}')
PV=$(kubectl get pvc local-vol-local-test-0 -o jsonpath='{.spec.volumeName}')
HOST_PATH=$(kubectl get pv "$PV" -o jsonpath='{.spec.hostPath.path}')

printf 'Pod node: %s\nPV name: %s\nHost path: %s\n' "$NODE" "$PV" "$HOST_PATH"
Code language: PHP (php)

Now SSH or use your normal admin access to that specific worker node, then inspect the path printed above:

sudo ls -lah /opt/local-path-provisioner

Optionally inspect the exact HOST_PATH you printed, after verifying it, on the node where the PV lives:

sudo ls -lah /opt/local-path-provisioner/<generated-volume-directory>/
Code language: HTML, XML (xml)

If the command runner is a control-plane host rather than the Pod’s worker, the directory may not exist there. Local storage is located on the selected worker, not wherever you execute kubectl.

11. Understand the storage lifecycle

You can explore safe scaling behavior:

kubectl scale statefulset local-test --replicas=1
kubectl get pods
kubectl get pvc  <em># Claims for replicas 1 and 2 normally remain.</em>

kubectl scale statefulset local-test --replicas=3
kubectl get pods -w
Code language: JavaScript (javascript)

Do not mistake ReadWriteOnce for automatic cross-node shared storage. These are separate local volumes, each with node affinity.

12. Troubleshooting your exact Pending problem

Your previous scheduler messages included:

WaitForFirstConsumer
WaitForPodScheduled
0/2 nodes are available:
  1 node(s) didn't find available persistent volumes to bind,
  1 node(s) had untolerated taint(s).

Those messages were consistent with the old kubernetes.io/no-provisioner class and missing matching static PVs. After switching to the Rancher class, use the checks below.

A. PVC still Pending

kubectl get sc local-storage -o yaml
kubectl describe pvc local-vol-local-test-0
kubectl describe pod local-test-0
kubectl get events -A --sort-by=.lastTimestamp | tail -n 40
Code language: JavaScript (javascript)

Confirm all of the following:

• StorageClass provisioner is rancher.io/local-path, not kubernetes.io/no-provisioner.
• The controller Deployment is available in local-path-storage.
• local-test-0 is eligible for a Ready worker node.
• The PVC references storageClassName: local-storage.
• There are no admission-policy failures or permission errors preventing helper Pods from creating directories.

B. Provisioner is not Running / images fail to pull

kubectl get pods -n local-path-storage -o wide
kubectl describe deploy local-path-provisioner -n local-path-storage
kubectl describe pods -n local-path-storage
kubectl logs -n local-path-storage -l app=local-path-provisioner --tail=200
Code language: JavaScript (javascript)

Check node internet/registry access, DNS, proxy settings, and image pull errors. The provisioner uses a helper Pod to set up and remove directories; blocked helper Pods can prevent PVC binding.

C. Pod cannot schedule because of a node taint

kubectl get nodes -o wide
kubectl get nodes -o custom-columns=NAME:.metadata.name,TAINTS:.spec.taints
kubectl describe pod local-test-0
Code language: JavaScript (javascript)

Recommendation: Keep your control-plane taint in place and run this lab on the worker. Do not remove production control-plane taints merely to make the demo succeed. If the only worker is NotReady, cordoned, or resource-starved, fix that first.

D. Pod says ImagePullBackOff

Use the current image from the tutorial:

image: busybox:1.36
Code language: CSS (css)

The original k8s.gcr.io/busybox reference is outdated. Check kubectl describe pod local-test-0 for exact registry/network failures.

E. Volume created on the wrong node / directory cannot be found

kubectl get pod local-test-0 -o wide
PV=$(kubectl get pvc local-vol-local-test-0 -o jsonpath='{.spec.volumeName}')
kubectl get pv "$PV" -o yaml
Code language: PHP (php)

Examine the PV’s node affinity and spec.hostPath.path. Inspect that path on the selected worker.

F. Disk full or permission errors

On the selected worker:

df -h /opt
sudo ls -ld /opt/local-path-provisioner

Check provisioner/helper-Pod logs, node security rules, and your Pod’s UID/GID. The default upstream setup script creates the volume directory with permissive permissions; don’t assume that is suitable for multi-tenant production.

G. sc.yaml fails because the old provisioner is immutable

A StorageClass’s provisioner field cannot be edited in place. For this disposable lab, remove the old local-test StatefulSet and its old PVCs, delete only StorageClass local-storage, then recreate it with rancher.io/local-path (Sections 3–5).

H. Three replicas, only one Pod visible

kubectl get sts local-test
kubectl describe pod local-test-0
Code language: JavaScript (javascript)

This is often due to the StatefulSet’s default OrderedReady creation behavior. Fix Pod 0; later replicas should follow.

13. Optional: add the StatefulSet’s headless Service

Not required for proving dynamic PV creation, but recommended if you want correct per-Pod DNS and normal StatefulSet network identity.

apiVersion: v1
kind: Service
metadata:
  name: local-service
spec:
  clusterIP: None
  selector:
    app: local-test
  ports:
    - name: http
      port: 80
      targetPort: 80

Save as headless-service.yaml, then:

kubectl apply -f headless-service.yaml
kubectl get svc local-service
Code language: JavaScript (javascript)

The BusyBox lab container does not listen on port 80; the example Service exists for StatefulSet identity, not application HTTP traffic. If you require strictly two YAML resources, you may omit this optional Service for the storage-only exercise.

14. Optional: customize the host data directory

The installer default is /opt/local-path-provisioner. To see the live setting:

kubectl get configmap local-path-config -n local-path-storage \
  -o jsonpath='{.data.config\.json}{"\n"}'
Code language: PHP (php)

The config contains nodePathMap, for example:

{
  "nodePathMap": [
    {
      "node": "DEFAULT_PATH_FOR_NON_LISTED_NODES",
      "paths": ["/opt/local-path-provisioner"]
    }
  ]
}
Code language: JSON / JSON with Comments (json)

If you want a different host directory, such as /mnt/k8s-local-data, first ensure that path is available on all eligible workers, and edit the provisioner’s ConfigMap:

kubectl edit configmap local-path-config -n local-path-storage

Change only the paths entry inside its config.json to your desired existing/accessible parent path. The provisioner supports configuration reload, but existing PVs remain on their original paths. For a simple first lab, keep the default location.

Do not choose / as a provisioning root. Ensure your worker disks, mount points, permissions, backup plan, and node selection are appropriate before using any custom path.

15. Cleanup the lab safely

Destructive warning: Because local-storage uses reclaimPolicy: Delete, deleting your PVCs can remove their PVs and stored files.

<em># 1. Stop the application</em>
kubectl delete statefulset local-test --ignore-not-found

<em># 2. Remove only this lab's claims — THIS DELETES THE DATA</em>
kubectl delete pvc \
  local-vol-local-test-0 \
  local-vol-local-test-1 \
  local-vol-local-test-2 \
  --ignore-not-found

<em># 3. Verify the associated PVs disappear</em>
kubectl get pv

<em># 4. Remove our additional StorageClass</em>
kubectl delete sc local-storage --ignore-not-found

<em># 5. Only if you created the optional headless Service</em>
kubectl delete svc local-service --ignore-not-found
Code language: HTML, XML (xml)

If you also want to uninstall the provisioner itself, first verify no other PVC/PV/StorageClass depends on rancher.io/local-path. Then remove the same versioned upstream manifest used to install it:

kubectl delete -f \
  https://raw.githubusercontent.com/rancher/local-path-provisioner/v0.0.37/deploy/local-path-storage.yaml
Code language: JavaScript (javascript)

This removes cluster-level installed resources (including the upstream local-path class). Do not uninstall it if other workloads still depend on it.

16. Complete command sequence (quick reference)

For a fresh, disposable lab, after checking cluster access and preparing sc.yaml and sfs.yaml as in Sections 5–6:

<em># Check nodes / taints</em>
kubectl get nodes -o wide
kubectl get nodes -o custom-columns=NAME:.metadata.name,TAINTS:.spec.taints

<em># Install the dynamic provisioner (once)</em>
kubectl apply -f \
  https://raw.githubusercontent.com/rancher/local-path-provisioner/v0.0.37/deploy/local-path-storage.yaml
kubectl rollout status deploy/local-path-provisioner -n local-path-storage --timeout=180s

<em># If replacing the old, disposable objects from your original failed lab:</em>
kubectl delete sts local-test --ignore-not-found
kubectl delete pvc local-vol-local-test-0 local-vol-local-test-1 local-vol-local-test-2 --ignore-not-found
kubectl delete sc local-storage --ignore-not-found

<em># Apply your TWO application YAML files</em>
kubectl apply -f sc.yaml
kubectl apply -f sfs.yaml

<em># Verify automatic PV / PVC creation</em>
kubectl get sc
kubectl get sts
kubectl get pods -o wide
kubectl get pvc
kubectl get pv

<em># Confirm backend is hostPath</em>
PV=$(kubectl get pvc local-vol-local-test-0 -o jsonpath='{.spec.volumeName}')
kubectl get pv "$PV" -o jsonpath='{.spec.hostPath.path}{"\n"}'

<em># Verify persistence after Pod recreation</em>
kubectl exec local-test-0 -- sh -c 'echo works > /usr/test-pod/check.txt'
kubectl delete pod local-test-0
kubectl wait --for=condition=Ready pod/local-test-0 --timeout=180s
kubectl exec local-test-0 -- cat /usr/test-pod/check.txt
Code language: PHP (php)

Success criteria:

• kubectl get pods shows local-test-0, local-test-1, and local-test-2 as Running and Ready.
• All three local-vol-local-test-* PVCs are Bound.
• Kubernetes has automatically created three PVs with StorageClass local-storage.
• Each PV has a nonempty spec.hostPath.path.
• A file written under /usr/test-pod remains after deleting/recreating its Pod.

17. Frequently asked questions

Q: Can kubernetes.io/no-provisioner create dynamic hostPath PVs?
No. Its name literally means it will not provision PVs. You must create matching PVs manually.

Q: Can WaitForFirstConsumer make it dynamic?
No. It only controls the timing of binding/provisioning where a provisioner exists.

Q: Is Rancher itself or a Rancher-managed Kubernetes cluster required?
No. The Local Path Provisioner can run as a component in a self-managed upstream Kubernetes cluster. You don’t need to install the Rancher management platform.

Q: Can I use a single StorageClass with multiple StatefulSet replicas?
Yes. Each replica’s PVC uses the same class, but gets its own separate PV/directory.

Q: Does 1Gi prevent the Pod from writing more than 1Gi?
No. The Rancher Local Path Provisioner currently doesn’t enforce the requested capacity as a hard quota.

Q: Can the storage follow a Pod to another node?
No. With a local hostPath volume, PV node affinity ties the volume to its node. Consider NFS CSI, Longhorn, or a replicated/distributed CSI solution if portability or redundancy is required.

Q: Why didn’t my original hostpath2 PV bind to the PVC?
Its storageClassName was manual, not local-storage; additionally, the old local-storage class had no dynamic provisioner. PV matching checks StorageClass as well as capacity, access modes, volume mode, and scheduling constraints.

Q: Is this suitable for production databases?
Only after evaluating node failure, disk health, backups, recovery, quotas, permission boundaries, monitoring, and availability requirements. For production-grade replicated storage, assess a storage system designed for that need.

18. Official references

1. Rancher Local Path Provisioner (README, installation, volume types, configuration, limitations): https://github.com/rancher/local-path-provisioner
2. Rancher Local Path Provisioner releases: https://github.com/rancher/local-path-provisioner/releases
3. Versioned install manifest (v0.0.37): https://raw.githubusercontent.com/rancher/local-path-provisioner/v0.0.37/deploy/local-path-storage.yaml
4. Kubernetes StatefulSet volume claim templates: https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/
5. Kubernetes StorageClasses and volume binding modes: https://kubernetes.io/docs/concepts/storage/storage-classes/
6. Kubernetes PersistentVolumes: https://kubernetes.io/docs/concepts/storage/persistent-volumes/
7. Kubernetes local and hostPath volumes: https://kubernetes.io/docs/concepts/storage/volumes/

Tutorial prepared for Kubernetes v1.35.10 on a self-managed Ubuntu cluster. Confirm the current stable Rancher release when repeating this installation later; pin the installer version for reproducibility.

Rajesh Kumar

I’m Rajesh Kumar, a DevOps, SRE, DevSecOps, Cloud, and Platform Engineering expert passionate about sharing practical knowledge, real-world experiences, and industry best practices. I have worked at Cotocus and regularly write about technology, travel, investing, health, product reviews, and digital marketing through my various platforms.

I publish technical articles at DevOps School, travel stories at Holiday Landmark, stock market insights at Stocks Mantra, health and fitness guidance at My Medic Plus, product reviews at TrueReviewNow, and SEO and digital marketing strategies at Wizbrand.