{"id":79848,"date":"2026-11-12T05:55:12","date_gmt":"2026-11-12T05:55:12","guid":{"rendered":"https:\/\/www.devopsschool.com\/blog\/?p=79848"},"modified":"2026-11-12T05:56:32","modified_gmt":"2026-11-12T05:56:32","slug":"kubernetes-storageclass-using-rancher-local-path-provisioner-complete-step-by-step-kubernetes-tutorial","status":"publish","type":"post","link":"https:\/\/www.devopsschool.com\/blog\/kubernetes-storageclass-using-rancher-local-path-provisioner-complete-step-by-step-kubernetes-tutorial\/","title":{"rendered":"Kubernetes storageclass using Rancher Local Path Provisioner: Complete Step-by-Step Kubernetes Tutorial"},"content":{"rendered":"\n

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

Lab setting<\/th>Value<\/th><\/tr><\/thead>
Kubernetes<\/td>v1.35.10 (self-managed \/ kubeadm-style installation)<\/td><\/tr>
Nodes<\/td>2 in the original example; one node may be control-plane tainted<\/td><\/tr>
Operating system<\/td>Ubuntu Linux<\/td><\/tr>
Provisioner<\/td>Rancher Local Path Provisioner (rancher.io\/local-path<\/code>)<\/td><\/tr>
Example installer version<\/td>v0.0.37<\/code> (upstream documented stable version when checked)<\/td><\/tr>
Volume backend<\/td>Kubernetes hostPath<\/code> (not NFS, EBS, or a local:<\/code> PV)<\/td><\/tr>
StorageClass<\/td>local-storage<\/code><\/td><\/tr>
StatefulSet<\/td>local-test<\/code>, 3 replicas<\/td><\/tr>
PVC per replica<\/td>1Gi requested; not a hard disk quota<\/strong><\/td><\/tr>
Default host data root<\/td>\/opt\/local-path-provisioner<\/code> on the selected node<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
\n

Scope:<\/strong> For the application, you maintain only two YAML manifests: sc.yaml<\/code> and sfs.yaml<\/code><\/strong>. 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.<\/p>\n<\/blockquote>\n\n\n\n

\n

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

\n\n\n\n

1. Understand the architecture<\/h2>\n\n\n\n
                Self-managed Kubernetes cluster\n\n  +------------------------------------------------------+\n  | Local Path Provisioner controller (installed once)   |\n  |               rancher.io\/local-path                  |\n  +---------------------------+--------------------------+\n                              |\n                     watches PVC requests\n                              |\n  +---------------------------v--------------------------+\n  | StorageClass: local-storage                           |\n  | provisioner: rancher.io\/local-path                    |\n  | defaultVolumeType: hostPath                           |\n  | volumeBindingMode: WaitForFirstConsumer               |\n  +---------------------------+--------------------------+\n                              |\n                StatefulSet: local-test (3)\n                   \/           |           \\\n               Pod-0         Pod-1         Pod-2\n                 |             |             |\n               PVC-0         PVC-1         PVC-2\n                 |             |             |\n           auto PV-0      auto PV-1      auto PV-2\n                 |             |             |\n          hostPath dir   hostPath dir   hostPath dir\n          on its node    on its node    on its node\n<\/code><\/pre>\n\n\n\n
Important distinction:<\/strong><\/p>\n\n\n\n
Provisioner<\/th>Dynamic PV creation?<\/th>PV backend<\/th>Needs an installed controller?<\/th><\/tr><\/thead>
kubernetes.io\/no-provisioner<\/code><\/td>No<\/strong><\/td>Existing manually-created PVs<\/td>No (but you create PVs yourself)<\/td><\/tr>
rancher.io\/local-path<\/code><\/td>Yes<\/strong><\/td>hostPath<\/code> or local<\/code><\/td>Yes<\/strong><\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
WaitForFirstConsumer<\/code> delays scheduling-aware binding\/provisioning<\/strong>. It does not<\/strong> turn kubernetes.io\/no-provisioner<\/code> into a dynamic provisioner.<\/p>\n\n\n\n
The StatefulSet automatically creates one PVC per replica<\/strong>. The Rancher controller then creates the corresponding PV and backing directory on the chosen node. A 1Gi<\/code> storage request records capacity for Kubernetes scheduling\/accounting, but Rancher Local Path Provisioner does not<\/strong> enforce a 1Gi filesystem quota.<\/p>\n\n\n\n
\n\n\n\n
2. Prerequisites<\/h2>\n\n\n\n
You need:<\/p>\n\n\n\n
    \n
  • A running Ubuntu-based Kubernetes cluster with\u00a0kubectl<\/code>\u00a0configured and cluster-admin rights for installation.<\/li>\n\n\n\n
  • At least one\u00a0Ready, schedulable worker node<\/strong>. Your earlier cluster has two nodes, and one was excluded by an\u00a0untolerated taint<\/strong>; avoid using the control-plane node for this lab.<\/li>\n\n\n\n
  • Working cluster networking, DNS, and access to pull images from a container registry.<\/li>\n\n\n\n
  • Available disk space on the worker node under\u00a0\/opt<\/code>\u00a0(or a custom configured storage root).<\/li>\n\n\n\n
  • Your original\u00a0local-test<\/code>\u00a0StatefulSet and\u00a0local-storage<\/code>\u00a0StorageClass are disposable\u00a0lab resources<\/strong>\u00a0if you follow the replacement steps.<\/li>\n<\/ul>\n\n\n\n
    Check your cluster:<\/p>\n\n\n
    kubectl version\nkubectl cluster-info\nkubectl get<\/span> nodes -o wide\nkubectl get<\/span> nodes -o custom-columns=NAME:.metadata.name,TAINTS:.spec.taints\nkubectl get<\/span> sc\nkubectl get<\/span> pv\nkubectl get<\/span> pvc -A\n<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
    Check available disk space on each worker node that may store volumes<\/strong>:<\/p>\n\n\n
    df -h \/opt\n<\/code><\/span><\/pre>\n\n\n
    \n
    A storage request of 1Gi<\/code> is not<\/strong> a disk usage limit with this provisioner. Plan actual disk capacity for all three replicas, logs, images, and node operations.<\/p>\n<\/blockquote>\n\n\n\n
    \n\n\n\n
    3. Remove the previous failed lab resources (only if disposable)<\/h2>\n\n\n\n
    Your old StorageClass used kubernetes.io\/no-provisioner<\/code>, and the PVC local-vol-local-test-0<\/code> stayed Pending<\/code>. The StorageClass provisioner<\/code> field cannot be changed in place; recreate that particular class.<\/p>\n\n\n\n
    Read before running:<\/strong> these commands remove only your local-test<\/code> example and its specifically named claims. Do not<\/strong> delete unrelated PVs\/PVCs such as deehostpath<\/code>, hostpath<\/code>, or hostpath2<\/code>.<\/p>\n\n\n
    <em<\/span>><\/span># Inspect first<\/em<\/span>><\/span>\nkubectl get statefulset local-test --ignore-not-found\nkubectl get pvc local-vol-local-test-0 local-vol-local-test-1 local-vol-local-test-2 --ignore-not-found\nkubectl get sc local-storage --ignore-not-found\n\n<em<\/span>><\/span># Delete the old StatefulSet, then its example PVCs<\/em<\/span>><\/span>\nkubectl delete statefulset local-test --ignore-not-found\nkubectl delete pvc \\\n  local-vol-local-test-0 \\\n  local-vol-local-test-1 \\\n  local-vol-local-test-2 \\\n  --ignore-not-found\n\n<em<\/span>><\/span># Recreate the class later with the correct provisioner<\/em<\/span>><\/span>\nkubectl delete storageclass local-storage --ignore-not-found\n<\/code><\/span>Code language:<\/span> HTML, XML<\/span> (<\/span>xml<\/span>)<\/span><\/small><\/pre>\n\n\n
    If these objects are already absent, skip this step. If they contain valuable data, do not delete them<\/strong>; use different demo names instead.<\/p>\n\n\n\n
    \n\n\n\n
    4. Install Rancher Local Path Provisioner (once per cluster)<\/h2>\n\n\n\n
    Use the versioned upstream manifest rather than the moving master<\/code> branch for a repeatable lab:<\/p>\n\n\n
    kubectl apply -f \\\n  https<\/span>:\/\/raw.githubusercontent.com\/rancher\/local-path-provisioner\/v0.0.37\/deploy\/local-path-storage.yaml<\/span>\n<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
    This upstream manifest installs the provisioner in namespace local-path-storage<\/code><\/strong>. It also creates its own example\/default-named local-path<\/code><\/strong> StorageClass. We will separately create our<\/strong> local-storage<\/code> StorageClass next.<\/p>\n\n\n\n
    Verify installation:<\/p>\n\n\n
    kubectl get<\/span> namespace local-path-storage\nkubectl get<\/span> deploy -n local-path-storage\nkubectl get<\/span> pods -n local-path-storage -o wide\nkubectl rollout status deploy\/local-path-provisioner -n local-path-storage --timeout=180s\nkubectl get<\/span> sc\n<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
    Expected: the local-path-provisioner<\/code> Deployment is available and its Pod is Running<\/code> (the Pod suffix will differ).<\/p>\n\n\n\n
    Check controller logs:<\/p>\n\n\n
    kubectl logs -n local-path-storage \\\n  -l app=local-path-provisioner --tail=100\n<\/code><\/span><\/pre>\n\n\n
    What did that installation create?<\/h3>\n\n\n
    kubectl get<\/span> all -n local-path-storage\nkubectl get<\/span> configmap local-path-config -n local-path-storage\nkubectl get<\/span> sc local-path -o yaml\n<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
    The default configuration stores data beneath \/opt\/local-path-provisioner<\/code> on the worker node that receives the Pod<\/strong>. The provisioner creates the per-volume directory automatically; you normally do not<\/strong> need to create each directory manually.<\/p>\n\n\n\n
    \n\n\n\n
    5. Create the dynamic StorageClass \u2014 sc.yaml<\/code><\/h2>\n\n\n
    apiVersion: storage.k8s.io\/v1\nkind: StorageClass\nmetadata:\n  name: local-storage\n  annotations:\n    defaultVolumeType: hostPath\nprovisioner: rancher.io\/local-path\nreclaimPolicy: Delete\nvolumeBindingMode: WaitForFirstConsumer\n<\/code><\/span><\/pre>\n\n\n
    Save the YAML above as sc.yaml<\/code><\/strong>, then apply it:<\/p>\n\n\n
    kubectl apply -f sc.yaml\nkubectl get<\/span> sc\nkubectl describe sc local-storage\n<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
    What the key fields do:<\/p>\n\n\n\n
    Field<\/th>Meaning<\/th><\/tr><\/thead>
    name: local-storage<\/code><\/td>Name referenced in the StatefulSet’s volumeClaimTemplates<\/code>.<\/td><\/tr>
    defaultVolumeType: hostPath<\/code><\/td>Rancher-specific StorageClass annotation that requests a hostPath<\/strong>-backed PV.<\/td><\/tr>
    provisioner: rancher.io\/local-path<\/code><\/td>Delegates provisioning to the installed Rancher controller.<\/td><\/tr>
    reclaimPolicy: Delete<\/code><\/td>When a PVC is deleted, the dynamically provisioned PV and its backing directory are normally deleted.<\/td><\/tr>
    volumeBindingMode: WaitForFirstConsumer<\/code><\/td>Selects an appropriate node for the consuming Pod before creating\/binding node-local storage.<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
    \n
    Rancher defaults to hostPath<\/code> if the volume type isn’t specified, but the explicit annotation makes the lab unambiguous. A PVC-level volumeType<\/code> annotation can override this StorageClass default.<\/p>\n<\/blockquote>\n\n\n\n
    \n
    Important:<\/strong> This does not<\/strong> set local-storage<\/code> as the cluster’s default StorageClass. Your StatefulSet explicitly requests it, which is safer for a lab.<\/p>\n<\/blockquote>\n\n\n\n
    \n\n\n\n
    6. Create the StatefulSet \u2014 sfs.yaml<\/code><\/h2>\n\n\n\n
    This matches your original StatefulSet design, but replaces the old BusyBox image location and uses the new dynamically provisioned class.<\/p>\n\n\n
    apiVersion: apps\/v1\nkind<\/span>: StatefulSet\nmetadata<\/span>:\n  name: local-test\nspec<\/span>:\n  serviceName: local-service\n  replicas<\/span>: 3<\/span>\n  selector<\/span>:\n    matchLabels:\n      app: local-test\n  template<\/span>:\n    metadata:\n      labels:\n        app: local-test\n    spec<\/span>:\n      containers:\n        - name: test-container\n          image<\/span>: busybox:1.36<\/span>\n          command<\/span>:\n            - \/bin\/<\/span>sh\n            - -c\n          args<\/span>:\n            - sleep 100000<\/span>\n          volumeMounts<\/span>:\n            - name: local-vol\n              mountPath<\/span>: \/usr\/<\/span>test-pod\n  volumeClaimTemplates<\/span>:\n    - metadata:\n        name: local-vol\n      spec<\/span>:\n        accessModes:\n          - ReadWriteOnce\n        storageClassName<\/span>: local-storage\n        resources<\/span>:\n          requests:\n            storage: 1<\/span>Gi\n<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
    Save as sfs.yaml<\/code><\/strong>, and apply:<\/p>\n\n\n
    kubectl apply -f sfs.yaml\nkubectl get<\/span> statefulset local-test\nkubectl get<\/span> pods -o wide -w\n<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
    Each Pod gets its own PVC automatically, named:<\/p>\n\n\n
    local-vol-local-test-0\nlocal-vol-local-test-1\nlocal-vol-local-test-2\n<\/code><\/span><\/pre>\n\n\n
    Why you may see only Pod 0 at first:<\/strong> By default, StatefulSets use ordered creation (OrderedReady<\/code>): local-test-1<\/code> is not created until local-test-0<\/code> becomes Ready, and similarly for Pod 2.<\/p>\n\n\n\n
    \n
    The StatefulSet references serviceName: local-service<\/code>. For a complete StatefulSet network identity, Kubernetes recommends creating a matching headless Service<\/strong>. Its absence is not<\/strong> 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<\/code> and sfs.yaml<\/code>.<\/p>\n<\/blockquote>\n\n\n\n
    \n\n\n\n
    7. Confirm the three dynamic PVs and PVCs<\/h2>\n\n\n
    kubectl get<\/span> statefulset local-test\nkubectl get<\/span> pods -o wide\nkubectl get<\/span> pvc\nkubectl get<\/span> pv\nkubectl describe pvc local-vol-local-test-0\nkubectl describe pod local-test-0\n<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
    Typical outcome (names\/ages may differ):<\/p>\n\n\n
    $ kubectl get pods\nNAME           READY   STATUS    RESTARTS\nlocal-test-0   1\/1     Running   0\nlocal-test-1   1\/1     Running   0\nlocal-test-2   1\/1     Running   0\n\n$ kubectl get pvc\nNAME                     STATUS   VOLUME       CAPACITY   ACCESS MODES   STORAGECLASS\nlocal-vol-local-test-0   Bound    pvc-<uid0<\/span>><\/span>   1Gi        RWO            local-storage\nlocal-vol-local-test-1   Bound    pvc-<uid1<\/span>><\/span>   1Gi        RWO            local-storage\nlocal-vol-local-test-2   Bound    pvc-<uid2<\/span>><\/span>   1Gi        RWO            local-storage\n<\/code><\/span>Code language:<\/span> HTML, XML<\/span> (<\/span>xml<\/span>)<\/span><\/small><\/pre>\n\n\n
    The PVs’ .spec.storageClassName<\/code> should be local-storage<\/code>; their claim references should point to the three local-vol-local-test-*<\/code> PVCs.<\/p>\n\n\n\n
    Verify the PV backend is really hostPath<\/em><\/h3>\n\n\n
    <em># Find the PV name for replica 0<\/em><\/span>\nPV=$(kubectl get pvc local-vol-local-test-0<\/span> -o jsonpath='{.spec.volumeName}'<\/span>)\necho<\/span> \"$PV\"<\/span>\n\n<em># Read its hostPath (must be nonempty)<\/em><\/span>\nkubectl get pv \"$PV\"<\/span> -o jsonpath='{.spec.hostPath.path}{\"\\n\"}'<\/span>\n\n<em># Inspect the full PV object (hostPath and node affinity)<\/em><\/span>\nkubectl get pv \"$PV\"<\/span> -o yaml\n\n<em># Display PV backend paths for all PVs (old PVs may have different storage classes)<\/em><\/span>\nkubectl get pv -o custom-columns=NAME:.metadata.name,STORAGECLASS:.spec.storageClassName,HOSTPATH:.spec.hostPath.path\n<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
    The PV will contain a spec.hostPath<\/code> entry resembling:<\/p>\n\n\n
    spec:\n  hostPath:\n    path: \/opt\/<\/span>local-path-provisioner\/pvc-<uid<\/span>><\/span>_default_local-vol-local-test-0\n    type: DirectoryOrCreate\n<\/span><\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
    The actual generated directory name will differ. Inspect the live<\/em> PV to determine the exact path; do not assume the example path is literal.<\/p>\n\n\n\n
    Verify PV affinity and the selected node<\/h3>\n\n\n
    kubectl get<\/span> pod local-test-0 -o wide\nkubectl get<\/span> pv \"$PV\" -o yaml\n<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
    The PV is associated with the node where its data lives, commonly through nodeAffinity<\/code> using kubernetes.io\/hostname<\/code>. A Pod using this PVC cannot automatically move its data to another node.<\/strong><\/p>\n\n\n\n
    \n\n\n\n
    8. Test persistence inside a replica<\/h2>\n\n\n\n
    Write a file into the PVC-backed mount:<\/p>\n\n\n
    kubectl exec local-test-0<\/span> -- sh -c \\\n  'echo \"Hello from Rancher dynamic hostPath\" > \/usr\/test-pod\/hello.txt'<\/span>\n\nkubectl exec local-test-0<\/span> -- cat \/usr\/test-pod\/hello.txt\n<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
    Expected:<\/p>\n\n\n
    Hello from<\/span> Rancher dynamic hostPath\n<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
    Delete only the Pod<\/em> (not the PVC):<\/p>\n\n\n
    kubectl delete<\/span> pod local-test-0<\/span>\nkubectl get<\/span> pod local-test-0 -w\n<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
    Once it is Running<\/code> and Ready again:<\/p>\n\n\n
    kubectl exec local-test-0 -- cat \/usr\/test-pod\/hello.txt\n<\/code><\/span><\/pre>\n\n\n
    Expected: the same text. This demonstrates persistence across Pod recreation on its original storage node<\/strong>. It does not<\/strong> demonstrate survival of worker-node disk failure or data movement between nodes.<\/p>\n\n\n\n
    \n\n\n\n
    9. Verify separate data for separate replicas<\/h2>\n\n\n
    for<\/span> i in<\/span> 0<\/span> 1<\/span> 2<\/span>; do<\/span>\n  kubectl exec \"local-test-$i\"<\/span> -- sh -c \\\n    \"echo Replica-$i > \/usr\/test-pod\/replica.txt\"<\/span>\ndone\n\nfor<\/span> i in<\/span> 0<\/span> 1<\/span> 2<\/span>; do<\/span>\n  printf 'Pod %s: '<\/span> \"$i\"<\/span>\n  kubectl exec \"local-test-$i\"<\/span> -- cat \/usr\/test-pod\/replica.txt\ndone\n<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
    Expected:<\/p>\n\n\n
    Pod 0: Replica-0\nPod 1: Replica-1\nPod 2: Replica-2\n<\/code><\/span><\/pre>\n\n\n
    Each StatefulSet replica gets its own PVC and PV. Even when the PVs reside on the same worker<\/strong>, they use different directories.<\/p>\n\n\n\n
    \n\n\n\n
    10. Locate the data on the Ubuntu worker node<\/h2>\n\n\n\n
    First identify the node hosting replica 0, and read its PV’s path:<\/p>\n\n\n
    NODE=$(kubectl get pod local-test-0<\/span> -o jsonpath='{.spec.nodeName}'<\/span>)\nPV=$(kubectl get pvc local-vol-local-test-0<\/span> -o jsonpath='{.spec.volumeName}'<\/span>)\nHOST_PATH=$(kubectl get pv \"$PV\"<\/span> -o jsonpath='{.spec.hostPath.path}'<\/span>)\n\nprintf 'Pod node: %s\\nPV name: %s\\nHost path: %s\\n'<\/span> \"$NODE\"<\/span> \"$PV\"<\/span> \"$HOST_PATH\"<\/span>\n<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
    Now SSH or use your normal admin access to that specific worker node<\/strong>, then inspect the path printed above:<\/p>\n\n\n
    sudo ls -lah \/opt\/local-path-provisioner\n<\/code><\/span><\/pre>\n\n\n
    Optionally inspect the exact<\/strong> HOST_PATH<\/code> you printed, after verifying it, on the node where the PV lives:<\/p>\n\n\n
    sudo ls -lah \/opt\/local-path-provisioner\/<generated-volume-directory<\/span>><\/span>\/\n<\/code><\/span>Code language:<\/span> HTML, XML<\/span> (<\/span>xml<\/span>)<\/span><\/small><\/pre>\n\n\n
    If the command runner is a control-plane host rather than the Pod’s worker, the directory may not exist there<\/strong>. Local storage is located on the selected worker, not wherever you execute kubectl<\/code>.<\/p>\n\n\n\n
    \n\n\n\n
    11. Understand the storage lifecycle<\/h2>\n\n\n\n
    Operation<\/th>What happens to data?<\/th><\/tr><\/thead>
    Delete a StatefulSet Pod<\/td>StatefulSet recreates it and normally reuses its PVC and node-local data.<\/td><\/tr>
    Scale StatefulSet down<\/td>Pods are removed; PVCs are retained by default.<\/td><\/tr>
    Scale it back up<\/td>Existing retained PVCs are normally reused.<\/td><\/tr>
    Delete StatefulSet<\/td>Existing PVCs remain by default under the default PVC retention policy.<\/td><\/tr>
    Delete a PVC using this class<\/td>Delete<\/code> reclaim policy means backing PV\/directory are normally removed by the provisioner. Destructive.<\/strong><\/td><\/tr>
    Worker node\/disk fails<\/td>Data is not replicated<\/strong>; the bound PVC is not transparently portable to another node.<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
    You can explore safe scaling behavior:<\/p>\n\n\n
    kubectl scale statefulset local-test --replicas=1<\/span>\nkubectl get<\/span> pods\nkubectl get<\/span> pvc  <em># Claims for replicas 1 and 2 normally remain.<\/em>\n\nkubectl scale statefulset local-test --replicas=3\nkubectl get<\/span> pods -w\n<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
    \n
    Do not mistake ReadWriteOnce<\/code> for automatic cross-node shared storage. These are separate local volumes<\/strong>, each with node affinity.<\/p>\n<\/blockquote>\n\n\n\n
    \n\n\n\n
    12. Troubleshooting your exact Pending<\/code> problem<\/h2>\n\n\n\n
    Your previous scheduler messages included:<\/p>\n\n\n
    WaitForFirstConsumer\nWaitForPodScheduled\n0\/2 nodes are available:\n  1 node(s) didn't find available persistent volumes to bind,\n  1 node(s) had untolerated taint(s).\n<\/code><\/span><\/pre>\n\n\n
    Those messages were consistent with the old<\/strong> kubernetes.io\/no-provisioner<\/code> class and missing matching static PVs. After switching to the Rancher class, use the checks below.<\/p>\n\n\n\n
    A. PVC still Pending<\/h3>\n\n\n
    kubectl get<\/span> sc local-storage -o yaml\nkubectl describe pvc local-vol-local-test-0\nkubectl describe pod local-test-0\nkubectl get<\/span> events -A --sort-by=.lastTimestamp | tail -n 40\n<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
    Confirm all<\/strong> of the following:<\/p>\n\n\n\n
      \n
    • StorageClass provisioner is\u00a0rancher.io\/local-path<\/code><\/strong>,\u00a0not<\/em>\u00a0kubernetes.io\/no-provisioner<\/code>.<\/li>\n\n\n\n
    • The controller Deployment is available in\u00a0local-path-storage<\/code>.<\/li>\n\n\n\n
    • local-test-0<\/code>\u00a0is eligible for a Ready worker node.<\/li>\n\n\n\n
    • The PVC references\u00a0storageClassName: local-storage<\/code>.<\/li>\n\n\n\n
    • There are no admission-policy failures or permission errors preventing helper Pods from creating directories.<\/li>\n<\/ul>\n\n\n\n
      B. Provisioner is not Running \/ images fail to pull<\/h3>\n\n\n
      kubectl get<\/span> pods -n local-path-storage -o wide\nkubectl describe deploy local-path-provisioner -n local-path-storage\nkubectl describe pods -n local-path-storage\nkubectl logs -n local-path-storage -l app=local-path-provisioner --tail=200\n<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
      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.<\/p>\n\n\n\n
      C. Pod cannot schedule because of a node taint<\/h3>\n\n\n
      kubectl get<\/span> nodes -o wide\nkubectl get<\/span> nodes -o custom-columns=NAME:.metadata.name,TAINTS:.spec.taints\nkubectl describe pod local-test-0\n<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
      Recommendation:<\/strong> 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<\/code>, cordoned, or resource-starved, fix that first.<\/p>\n\n\n\n
      D. Pod says ImagePullBackOff<\/h3>\n\n\n\n
      Use the current image from the tutorial:<\/p>\n\n\n
      image<\/span>: busybox<\/span>:1.36<\/span>\n<\/code><\/span>Code language:<\/span> CSS<\/span> (<\/span>css<\/span>)<\/span><\/small><\/pre>\n\n\n
      The original k8s.gcr.io\/busybox<\/code> reference is outdated. Check kubectl describe pod local-test-0<\/code> for exact registry\/network failures.<\/p>\n\n\n\n
      E. Volume created on the wrong node \/ directory cannot be found<\/h3>\n\n\n
      kubectl get pod local-test-0<\/span> -o wide\nPV=$(kubectl get pvc local-vol-local-test-0<\/span> -o jsonpath='{.spec.volumeName}'<\/span>)\nkubectl get pv \"$PV\"<\/span> -o yaml\n<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
      Examine the PV’s node affinity and spec.hostPath.path<\/code>. Inspect that path on the selected worker<\/strong>.<\/p>\n\n\n\n
      F. Disk full or permission errors<\/h3>\n\n\n\n
      On the selected worker:<\/p>\n\n\n
      df -h \/opt\nsudo ls -ld \/opt\/local-path-provisioner\n<\/code><\/span><\/pre>\n\n\n
      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.<\/p>\n\n\n\n
      G. sc.yaml<\/code> fails because the old provisioner is immutable<\/h3>\n\n\n\n
      A StorageClass’s provisioner<\/code> field cannot be edited in place. For this disposable lab, remove the old local-test<\/code> StatefulSet and its old PVCs, delete only<\/strong> StorageClass local-storage<\/code>, then recreate it with rancher.io\/local-path<\/code> (Sections 3\u20135).<\/p>\n\n\n\n
      H. Three replicas, only one Pod visible<\/h3>\n\n\n
      kubectl get<\/span> sts local-test\nkubectl describe pod local-test-0\n<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
      This is often due to the StatefulSet’s default OrderedReady<\/code> creation behavior. Fix Pod 0; later replicas should follow.<\/p>\n\n\n\n
      \n\n\n\n
      13. Optional: add the StatefulSet’s headless Service<\/h2>\n\n\n\n
      Not required for proving dynamic PV creation<\/strong>, but recommended if you want correct per-Pod DNS and normal StatefulSet network identity.<\/p>\n\n\n
      apiVersion: v1\nkind: Service\nmetadata:\n  name: local-service\nspec:\n  clusterIP: None\n  selector:\n    app: local-test\n  ports:\n    - name: http\n      port: 80\n      targetPort: 80\n<\/code><\/span><\/pre>\n\n\n
      Save as headless-service.yaml<\/code>, then:<\/p>\n\n\n
      kubectl apply -f headless-service.yaml\nkubectl get<\/span> svc local-service\n<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
      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<\/strong>, you may omit this optional Service for the storage-only exercise<\/strong>.<\/p>\n\n\n\n
      \n\n\n\n
      14. Optional: customize the host data directory<\/h2>\n\n\n\n
      The installer default is \/opt\/local-path-provisioner<\/code>. To see the live setting:<\/p>\n\n\n
      kubectl get configmap local-path-config -n local-path-storage \\\n  -o jsonpath='{.data.config\\.json}{\"\\n\"}'<\/span>\n<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
      The config contains nodePathMap<\/code>, for example:<\/p>\n\n\n
      {\n  \"nodePathMap\"<\/span>: [\n    {\n      \"node\"<\/span>: \"DEFAULT_PATH_FOR_NON_LISTED_NODES\"<\/span>,\n      \"paths\"<\/span>: [\"\/opt\/local-path-provisioner\"<\/span>]\n    }\n  ]\n}\n<\/code><\/span>Code language:<\/span> JSON \/ JSON with Comments<\/span> (<\/span>json<\/span>)<\/span><\/small><\/pre>\n\n\n
      If you want a different host directory, such as \/mnt\/k8s-local-data<\/code>, first ensure that path is available on all eligible workers, and edit the provisioner’s ConfigMap:<\/p>\n\n\n
      kubectl edit configmap local-path-config -n local-path-storage\n<\/code><\/span><\/pre>\n\n\n
      Change only<\/strong> the paths<\/code> entry inside its config.json<\/code> 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<\/strong>.<\/p>\n\n\n\n
      \n
      Do not choose \/<\/code> as a provisioning root. Ensure your worker disks, mount points, permissions, backup plan, and node selection are appropriate before using any custom path.<\/p>\n<\/blockquote>\n\n\n\n
      \n\n\n\n
      15. Cleanup the lab safely<\/h2>\n\n\n\n
      Destructive warning:<\/strong> Because local-storage<\/code> uses reclaimPolicy: Delete<\/code>, deleting your PVCs can remove their PVs and stored files<\/strong>.<\/p>\n\n\n
      <em<\/span>><\/span># 1. Stop the application<\/em<\/span>><\/span>\nkubectl delete statefulset local-test --ignore-not-found\n\n<em<\/span>><\/span># 2. Remove only this lab's claims \u2014 THIS DELETES THE DATA<\/em<\/span>><\/span>\nkubectl delete pvc \\\n  local-vol-local-test-0 \\\n  local-vol-local-test-1 \\\n  local-vol-local-test-2 \\\n  --ignore-not-found\n\n<em<\/span>><\/span># 3. Verify the associated PVs disappear<\/em<\/span>><\/span>\nkubectl get pv\n\n<em<\/span>><\/span># 4. Remove our additional StorageClass<\/em<\/span>><\/span>\nkubectl delete sc local-storage --ignore-not-found\n\n<em<\/span>><\/span># 5. Only if you created the optional headless Service<\/em<\/span>><\/span>\nkubectl delete svc local-service --ignore-not-found\n<\/code><\/span>Code language:<\/span> HTML, XML<\/span> (<\/span>xml<\/span>)<\/span><\/small><\/pre>\n\n\n
      If you also want to uninstall the provisioner itself<\/strong>, first verify no other PVC\/PV\/StorageClass depends on rancher.io\/local-path<\/code>. Then remove the same versioned upstream manifest<\/strong> used to install it:<\/p>\n\n\n
      kubectl delete<\/span> -f \\\n  https<\/span>:\/\/raw.githubusercontent.com\/rancher\/local-path-provisioner\/v0.0.37\/deploy\/local-path-storage.yaml<\/span>\n<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
      This removes cluster-level installed resources (including the upstream local-path<\/code> class). Do not uninstall it if other workloads still depend on it.<\/p>\n\n\n\n
      \n\n\n\n
      16. Complete command sequence (quick reference)<\/h2>\n\n\n\n
      For a fresh, disposable<\/strong> lab, after checking cluster access and preparing sc.yaml<\/code> and sfs.yaml<\/code> as in Sections 5\u20136:<\/p>\n\n\n
      <em># Check nodes \/ taints<\/em><\/span>\nkubectl get nodes -o wide\nkubectl get nodes -o custom-columns=NAME:.metadata.name,TAINTS:.spec.taints\n\n<em># Install the dynamic provisioner (once)<\/em><\/span>\nkubectl apply -f \\\n  https:\/\/raw.githubusercontent.com\/rancher\/local-path-provisioner\/v0.0.37\/deploy\/local-path-storage.yaml<\/span>\nkubectl rollout status deploy\/local-path-provisioner -n local-path-storage --timeout=180<\/span>s\n\n<em># If replacing the old, disposable objects from your original failed lab:<\/em><\/span>\nkubectl delete sts local-test --ignore-not-found\nkubectl delete pvc local-vol-local-test-0<\/span> local-vol-local-test-1<\/span> local-vol-local-test-2<\/span> --ignore-not-found\nkubectl delete sc local-storage --ignore-not-found\n\n<em># Apply your TWO application YAML files<\/em><\/span>\nkubectl apply -f sc.yaml\nkubectl apply -f sfs.yaml\n\n<em># Verify automatic PV \/ PVC creation<\/em><\/span>\nkubectl get sc\nkubectl get sts\nkubectl get pods -o wide\nkubectl get pvc\nkubectl get pv\n\n<em># Confirm backend is hostPath<\/em><\/span>\nPV=$(kubectl get pvc local-vol-local-test-0<\/span> -o jsonpath='{.spec.volumeName}'<\/span>)\nkubectl get pv \"$PV\"<\/span> -o jsonpath='{.spec.hostPath.path}{\"\\n\"}'<\/span>\n\n<em># Verify persistence after Pod recreation<\/em><\/span>\nkubectl exec local-test-0<\/span> -- sh -c 'echo works > \/usr\/test-pod\/check.txt'<\/span>\nkubectl delete pod local-test-0<\/span>\nkubectl wait --for<\/span>=condition=Ready pod\/local-test-0<\/span> --timeout=180<\/span>s\nkubectl exec local-test-0<\/span> -- cat \/usr\/test-pod\/check.txt\n<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
      Success criteria:<\/strong><\/p>\n\n\n\n