DOCSEARCHbyAlgolia
Submit Docs

Rancher Local Path Provisioner

repository·master·Indexed 23 days ago

https://github.com/rancher/local-path-provisioner

A Kubernetes provisioner that enables dynamic provisioning of hostPath or local based persistent volumes, allowing users to utilize local storage on each node. It includes support for Helm installation, RBAC, XFS quota management, and customizable path mapping via ConfigMaps.

Tokens
6.5K
Snippets
13
Records
28
Agent score
84%

What's inside local-path-provisioner

  1. Install Local Path Provisioner

    master

    Install the Local Path Provisioner to enable dynamic provisioning of hostPath or local based persistent volumes. By default, the provisioner is installed in the local-path-storage namespace. In the default setup, the directory /opt/local-path-provisioner is used across all nodes for storing persistent volume data.

    Requirements:

    • Kubernetes v1.12+

    Installation via kubectl (Stable):

    kubectl apply -f https://raw.githubusercontent.com/rancher/local-path-provisioner/v0.0.36/deploy/local-path-storage.yaml

    Installation via kustomize (Stable):

    kustomize build "github.com/rancher/local-path-provisioner/deploy?ref=v0.0.36" | kubectl apply -f -
    kubectl apply -f https://raw.githubusercontent.com/rancher/local-path-provisioner/v0.0.36/deploy/local-path-storage.yaml

  3. Install Local Path Provisioner using Helm

    master

    Install the Local Path Provisioner on a Kubernetes cluster using the Helm package manager. This deploys the provisioner with default configurations. Ensure you have cloned the repository locally before running the install command.

    Prerequisites:

    • Kubernetes 1.12+ with Beta APIs enabled
    • Helm installed
    $ git clone https://github.com/rancher/local-path-provisioner.git
$ cd local-path-provisioner
$ helm install local-path-storage --create-namespace --namespace local-path-storage ./deploy/chart/local-path-provisioner/

  4. Enable XFS quota in Local Path Provisioner

    master

    To enable quota management for XFS filesystems using the local-path-provisioner, you must follow these steps:

    1. Build a custom helper image: Use the provided sample Dockerfile to build a helper image. This image replaces the default xxx/storage-xfs-quota:v0.1 specified in the helperPod.yaml within the debug.yaml configuration.
    2. Configure the Provisioner: You must set the environment variable ALLOW_UNSAFE_HELPER_POD_TEMPLATE=true on the provisioner. This is required because the helper pod uses privileged mounts to perform quota management.
    3. Verify Mountpoints: Ensure that the path defined in nodePathMap is the actual mountpoint of the XFS filesystem where pquota is enabled.
    4. Deployment: Use the sample setup and teardown scripts included in the kustomization directory to manage the lifecycle of this configuration.

  5. Install the Local Path Provisioner chart with RBAC enabled

    master

    To install the Local Path Provisioner using Helm and ensure that the recommended RBAC roles and rolebindings are created, use the --set rbac.create=true flag. This requires your cluster to have --authorization-mode=RBAC enabled on the API server.

    $ helm install ./deploy/chart/local-path-provisioner --name local-path-storage --namespace local-path-storage --set rbac.create=true

  6. Configure the Local Path Provisioner via ConfigMap

    master

    The provisioner is configured using a ConfigMap (typically named local-path-config in the local-path-storage namespace). This ConfigMap contains a config.json file for path mapping, setup and teardown bash scripts for volume lifecycle management, and a helperPod.yaml template for the helper Pod.

    To enable automatic reloading of the helperPod.yaml manifest when the ConfigMap is updated, you must set the CONFIG_MOUNT_PATH environment variable in the provisioner container to the directory where the ConfigMap is mounted (e.g., /etc/config/).

    kind: ConfigMap
apiVersion: v1
metadata:
  name: local-path-config
  namespace: local-path-storage
data:
  config.json: |- 
        {
                "nodePathMap":[
                {
                        "node":"DEFAULT_PATH_FOR_NON_LISTED_NODES",
                        "paths":["/opt/local-path-provisioner"]
                },
                {
                        "node":"yasker-lp-dev1",
                        "paths":["/opt/local-path-provisioner", "/data1"]
                }
                ]
        }
  setup: |- 
        #!/bin/sh
        set -eu
        mkdir -m 0777 -p "$VOL_DIR"
  teardown: |- 
        #!/bin/sh
        set -eu
        rm -rf "$VOL_DIR"
  helperPod.yaml: |- 
        apiVersion: v1
        kind: Pod
        metadata:
          name: helper-pod
        spec:
          containers:
          - name: helper-pod
            image: busybox

  8. Verify RBAC support in your Kubernetes cluster

    master

    Before installing the Local Path Provisioner with RBAC enabled, ensure your Kubernetes API server supports RBAC. You can check this by running the kubectl api-versions command and searching for rbac in the output. If the output contains beta, you can proceed with installing the chart with RBAC resources enabled.

    $ kubectl api-versions | grep rbac

  9. Uninstall the Local Path Provisioner

    master

    Before uninstalling, ensure all PersistentVolumes (PVs) created by the provisioner are deleted. Verify this by running kubectl get pv and ensuring no PVs with the local-path StorageClass remain.

    To uninstall, run the appropriate command based on your version:

    Stable:

    kubectl delete -f https://raw.githubusercontent.com/rancher/local-path-provisioner/v0.0.36/deploy/local-path-storage.yaml

    Development:

    kubectl delete -f https://raw.githubusercontent.com/rancher/local-path-provisioner/master/deploy/local-path-storage.yaml

  10. Verify Local Path Provisioner installation and logs

    master

    After installation, verify that the provisioner pod is running in the local-path-storage namespace:

    kubectl -n local-path-storage get pod

    You can monitor the provisioner's activity by following its logs:

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

  11. Set up an out-of-cluster debug environment

    master

    Developers can set up an out-of-cluster debug environment by cloning the repository, building the binary, applying the debug configuration to a Kubernetes cluster, and running the provisioner locally with the --debug start flag.

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

  12. Configure StorageClass parameters: `pathPattern` and `nodePath`

    master

    Customize how volumes are provisioned using parameters in your StorageClass:

    • nodePath: Forces the provisioner to use a specific path (which must be defined in the nodePathMap).
    • pathPattern: A Go template used to name the volume subdirectory. The default is {{ .PVName }}_{{ .PVC.Namespace }}_{{ .PVC.Name }}.
      • Requirement: Rendered paths must start with {{ .PVC.Namespace }}/{{ .PVC.Name }}/ and must not contain directory traversal (e.g., ../).
      • Bypass: Set allowUnsafePathPattern: "true" in parameters or metadata.annotations to skip these validations.
    • nodeAffinityKey: Specifies a custom node label key for node affinity instead of the default kubernetes.io/hostname. This is useful for environments with unstable hostnames.
    apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: ssd-local-path
provisioner: rancher.io/local-path
parameters:
  nodePath: /data/ssd
  pathPattern: "{{ .PVC.Namespace }}/{{ .PVC.Name }}/"
volumeBindingMode: WaitForFirstConsumer
reclaimPolicy: Delete