Persistent Volume Claim Explained¶

Introduction¶

This guide explains persistent volume claim explained with practical kubectl commands, realistic output, and production-focused checks. Configuration and storage problems often appear as pod startup failures, missing files, stale environment variables, or PVCs stuck in Pending.

When You Need This¶

Use this guide when an application needs configuration, credentials, mounted files, persistent data, or storage provisioning.

Example Manifest¶

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: data
spec:
  accessModes: ["ReadWriteOnce"]
  resources:
    requests:
      storage: 10Gi

Apply and Inspect¶

kubectl get configmap,secret -n app
kubectl describe pod web-0 -n app
kubectl get pvc,pv,storageclass -n app
kubectl describe pvc data -n app
kubectl get events -n app --sort-by=.lastTimestamp

Expected output:

NAME       STATUS   VOLUME     CAPACITY   ACCESS MODES   STORAGECLASS   AGE
pvc/data   Bound    pvc-1234   10Gi       RWO            fast           2d

Verification¶

kubectl describe pod web-0 -n app
kubectl exec -n app web-0 -- ls -l /etc/config || true
kubectl get events -n app --sort-by=.lastTimestamp

Troubleshooting¶

Check object names, namespace, volumeMount paths, subPath behavior, secret type, PVC access mode, StorageClass, and provisioner events.

Common Mistakes¶

• Updating a ConfigMap and expecting existing environment variables to change without restarting pods.
• Mounting a Secret or ConfigMap from the wrong namespace.
• Troubleshooting PVC Pending without checking StorageClass and provisioner events.

Quick Checklist¶

• Confirm object exists in the same namespace.
• Check pod volume and volumeMount names.
• Inspect events for mount or provisioning errors.
• Restart pods when environment-based config changes.
• Protect Secrets with RBAC and least privilege.

Related Guides¶

• PVC Pending Troubleshooting
• Secret Security Best Practices
• Mount PVC To Pod
• Storage Troubleshooting Kubernetes

Summary¶

Config, secret, and storage issues are usually visible in pod events. Confirm the object, namespace, mount path, and storage binding before changing the workload.