PersistentVolumeClaim (PVC) definition in Kubernetes - Commands & Configuration

Introduction

When you want to save data in Kubernetes so it stays safe even if your app restarts or moves, you use a PersistentVolumeClaim. It asks Kubernetes for storage space that your app can use like a hard drive.

When your app needs to save files or databases that must not disappear after a restart.

When you want to share storage between different parts of your app.

When you want to separate storage setup from your app code for easier management.

When you need to request a specific size and type of storage for your app.

When you want Kubernetes to handle storage allocation automatically.

Config File - pvc.yaml

pvc.yaml

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: example-pvc
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 1Gi
  storageClassName: standard

apiVersion: Specifies the Kubernetes API version used.

kind: Defines this resource as a PersistentVolumeClaim.

metadata.name: The name to identify this claim.

spec.accessModes: How the volume can be accessed; ReadWriteOnce means one node can mount it for reading and writing.

spec.resources.requests.storage: The amount of storage requested.

spec.storageClassName: The storage class that defines the type of storage to use.

Commands

This command creates the PersistentVolumeClaim in Kubernetes, asking for 1Gi of storage with ReadWriteOnce access.

Terminal

kubectl apply -f pvc.yaml

Expected Output

persistentvolumeclaim/example-pvc created

This command checks the status of the PersistentVolumeClaim to see if it has been bound to a PersistentVolume.

Terminal

kubectl get pvc example-pvc

Expected Output

NAME          STATUS   VOLUME                                     CAPACITY   ACCESS MODES   STORAGECLASS   AGE

example-pvc   Bound    pvc-12345678-90ab-cdef-1234-567890abcdef   1Gi        RWO            standard       10s

This command shows detailed information about the PersistentVolumeClaim, including events and which volume it is using.

Terminal

kubectl describe pvc example-pvc

Expected Output

Name:          example-pvc

Namespace:     default

StorageClass:  standard

Status:        Bound

Volume:        pvc-12345678-90ab-cdef-1234-567890abcdef

Labels:        <none>

Annotations:   <none>

Finalizers:    [kubernetes.io/pvc-protection]

Capacity:      1Gi

Access Modes:  RWO

VolumeMode:    Filesystem

Events:

  Type    Reason                 Age   From                         Message

  ----    ------                 ----  ----                         -------

  Normal  ProvisioningSucceeded  20s   persistentvolume-controller  Successfully provisioned volume pvc-12345678-90ab-cdef-1234-567890abcdef

Key Concept

If you remember nothing else from this pattern, remember: a PersistentVolumeClaim is how your app asks Kubernetes for storage space it can use safely and persistently.

Common Mistakes

Not specifying the storageClassName and expecting automatic binding.

Without a storage class, Kubernetes may not know which storage to allocate, causing the claim to stay pending.

Always specify a valid storageClassName or ensure a default storage class is set in the cluster.

Requesting more storage than available in the cluster.

The claim will remain unbound because no volume can satisfy the request.

Check available storage and request a size that can be fulfilled.

Using accessModes that do not match the volume capabilities.

The claim will fail to bind if the requested access mode is unsupported by the volume.

Use accessModes compatible with your storage class and volume type, commonly ReadWriteOnce.

Summary

Create a PersistentVolumeClaim YAML file to request storage with specific size and access mode.

Apply the YAML file with kubectl apply to create the claim in Kubernetes.

Check the claim status with kubectl get pvc and kubectl describe pvc to confirm it is bound and ready.