PersistentVolume (PV) definition in Kubernetes - Commands & Configuration

Introduction

Sometimes applications need storage that stays even if the app restarts or moves. PersistentVolume (PV) in Kubernetes provides a way to keep data safe and available independently of the app's life cycle.

When you want to store database files that must not be lost if the database pod restarts.

When you need to share files between multiple pods without losing data.

When you want to keep logs or backups safe even if the pod is deleted.

When you want to separate storage management from pod management for better control.

When you want to use cloud storage or network storage with your Kubernetes apps.

Config File - persistentvolume.yaml

persistentvolume.yaml

apiVersion: v1
kind: PersistentVolume
metadata:
  name: example-pv
spec:
  capacity:
    storage: 5Gi
  accessModes:
    - ReadWriteOnce
  persistentVolumeReclaimPolicy: Retain
  storageClassName: manual
  hostPath:
    path: /mnt/data

This file defines a PersistentVolume named example-pv.

capacity sets the storage size to 5 gigabytes.

accessModes means the volume can be mounted as read-write by a single node.

persistentVolumeReclaimPolicy set to Retain means the data stays after the volume is released.

storageClassName groups this volume for matching with PersistentVolumeClaims.

hostPath uses a directory on the node's filesystem for storage (good for learning, not production).

Commands

This command creates the PersistentVolume in the Kubernetes cluster using the definition file.

Terminal

kubectl apply -f persistentvolume.yaml

Expected Output

persistentvolume/example-pv created

This command checks the status and details of the PersistentVolume named example-pv to confirm it was created.

Terminal

kubectl get pv example-pv

Expected Output

NAME         CAPACITY   ACCESS MODES   RECLAIM POLICY   STATUS      CLAIM   STORAGECLASS   REASON   AGE

example-pv   5Gi        RWO            Retain           Available           manual                 10s

This command shows detailed information about the PersistentVolume, including capacity, access modes, and reclaim policy.

Terminal

kubectl describe pv example-pv

Expected Output

Name:            example-pv

Labels:          <none>

Annotations:     <none>

Finalizers:      [kubernetes.io/pv-protection]

StorageClass:    manual

Status:          Available

Claim:

Reclaim Policy:  Retain

Access Modes:    RWO

Capacity:        5Gi

Node Affinity:   <none>

Message:

Source:

    Type:       HostPath (bare host directory volume)

    Path:       /mnt/data

Events:          <none>

Key Concept

If you remember nothing else from this pattern, remember: PersistentVolumes provide stable storage that lives beyond pod lifetimes and must be defined before use.

Common Mistakes

Not setting the correct accessModes for the workload

The pod may fail to mount the volume if access modes do not match its requirements.

Choose accessModes like ReadWriteOnce, ReadOnlyMany, or ReadWriteMany based on how your app uses the storage.

Using hostPath volumes in production

hostPath ties storage to a single node and can cause data loss if pods move to other nodes.

Use networked storage solutions like NFS, cloud volumes, or storage classes designed for production.

Forgetting to match storageClassName with PersistentVolumeClaims

Claims may not bind to the PV if storage classes do not match, causing pod startup failures.

Ensure storageClassName in PV and PVC are the same or use default storage class.

Summary

Create a PersistentVolume YAML file defining storage size, access modes, and storage location.

Apply the PersistentVolume to the cluster with kubectl apply.

Verify the PersistentVolume status with kubectl get pv and kubectl describe pv.