PersistentVolumeClaims
A PVC requests storage; the local-path provisioner fulfills it on demand.
Syntax
kubectl apply -f pvc.yamlYou do not create PersistentVolumes by hand with k3s. Instead you write a PersistentVolumeClaim (PVC) describing how much space you need, and the default provisioner creates the volume for you. This is called dynamic provisioning.
The lifecycle
- You apply a PVC.
- local-path-provisioner sees it and creates a folder-backed volume.
- The PVC binds to that volume.
- Your Pod mounts the PVC and reads/writes files.
Example
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: data-pvc
spec:
accessModes:
- ReadWriteOnce
storageClassName: local-path
resources:
requests:
storage: 1GiWhen to use it
- A developer creates a PVC for a Redis Deployment so its data survives pod restarts without manually pre-creating a PersistentVolume.
- An operator uses PVCs with ReadWriteOnce access mode on k3s local-path storage to give each database replica its own dedicated volume.
- A CI job creates a PVC to cache build artifacts between pipeline steps without needing an external NFS or object-store integration.
More examples
Create a PVC
Defines a 2 GiB PVC; the local-path provisioner automatically creates a backing directory on the node.
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: app-data
spec:
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 2GiMount PVC in a Pod
Mounts the PVC into the container at the Postgres data directory so database files are persisted on the node disk.
volumes:
- name: data
persistentVolumeClaim:
claimName: app-data
containers:
- name: app
image: postgres:16
volumeMounts:
- name: data
mountPath: /var/lib/postgresql/dataInspect PVC and PV binding
Shows the PVC status (Bound/Pending) and which PV the local-path provisioner created to fulfill the request.
kubectl get pvc app-data
kubectl get pv
kubectl describe pvc app-data | grep -E 'Status|Volume|StorageClass'
Discussion