predictable-path-provisioner

README

P3 (Predictable Path Provisioner)

A Kubernetes external dynamic provisioner that creates local PersistentVolumes under human-readable folder paths.

Table of Contents

• P3 (Predictable Path Provisioner)
  • Table of Contents
  • Important considerations
  • Installation
    • Using helm
    • Using kubectl
  • Usage
    • Example storage classes
      • With defaults:
      • With custom basePath and pathTemplate:
  • Container Images
    • Image location
    • Tags

Important considerations

• There is no mechanism to prevent path collisions. Use custom name templates at your own risk.
• This is mostly a hobby project, intended for my own use. Use at your own risk.
• Only AccessModes ReadWriteOnce and ReadWriteOncePod are supported.
• When using VolumeBindingMode Immediate, volumes are scheduled on a random node. It is recommended to use WaitForFirstConsumer to ensure the k8s scheduler decides the placement.

Installation

Using helm

P3 helm charts are released via oci repos and can be installed with:

helm install p3 oci://ghcr.io/heathcliff26/manifests/predictable-path-provisioner --version <version>

Please use the latest version from the releases page.

Using kubectl

An example deployment can be found here.

To deploy it to your cluster, run:

kubectl apply -f https://raw.githubusercontent.com/heathcliff26/predictable-path-provisioner/main/examples/p3.yaml

This will deploy the app to your cluster into the namespace p3.

Usage

By default P3 uses the provisioner name heathcliff.eu/predictable-path-provisioner.

It's behaviour can be configured via the StorageClass parameters. The following parameters are supported:

Parameter	Default	Description
basePath	/var/lib/predictable-path-provisioner	The base directory on the host under which the volumes will be created. Needs to be an absolute path.
pathTemplate	{{pvc.namespace}}/{{pvc.name}}	The template for the volume folder. It accepts the following templates (case sensitive): pvc.name, pvc.namespace, pvc.uid

Example storage classes

With defaults:

---
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: "p3"
  annotations:
    storageclass.kubernetes.io/is-default-class: "true"
provisioner: heathcliff.eu/predictable-path-provisioner
reclaimPolicy: Delete
volumeBindingMode: WaitForFirstConsumer

This would result in the Persistent Volume for the Claim default/test being created under /var/lib/predictable-path-provisioner/default/test.

With custom basePath and pathTemplate:

---
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: "p3"
  annotations:
    storageclass.kubernetes.io/is-default-class: "true"
provisioner: heathcliff.eu/predictable-path-provisioner
parameters:
    basePath: /data/p3
    pathTemplate: pvc-{{pvc.uid}}
reclaimPolicy: Delete
volumeBindingMode: WaitForFirstConsumer

This would result in the Persistent Volume being created under /data/p3/pvc-<some-uid>

Container Images

Image location

Container Registry	Image
Github Container	ghcr.io/heathcliff26/p3
Docker Hub	docker.io/heathcliff26/p3
Quay.io	quay.io/heathcliff26/p3

Tags

There are different flavors of the image:

Tag(s)	Description
latest	Last released version of the image
rolling	Rolling update of the image, always build from main branch.
vX.Y.Z	Released version of the image