Claude Code Kubernetes Persistent Volumes Guide

Persistent volumes in Kubernetes solve a fundamental challenge: containers are ephemeral by design, but many applications need durable storage that survives pod restarts and rescheduling. This guide demonstrates how to work with PersistentVolumes (PVs) and PersistentVolumeClaims (PVCs) using Claude Code and complementary skills.

Understanding Persistent Volumes in Kubernetes

A PersistentVolume represents a piece of storage in the cluster that exists independently of any individual pod. When a pod needs persistent storage, it requests storage through a PersistentVolumeClaim. This separation allows storage to be managed separately from pod lifecycle.

There are two main approaches to provisioning persistent storage: static and dynamic. Static provisioning involves creating PVs manually, while dynamic provisioning uses StorageClasses to create storage on-demand. Most modern deployments rely on dynamic provisioning through the cloud-provider’s native storage solutions.

Creating a PersistentVolumeClaim

A PersistentVolumeClaim requests a specific amount of storage with optional access modes. Here’s a basic PVC definition:

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: app-data-pvc
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 10Gi
  storageClassName: standard

The accessModes field defines how the volume can be mounted. ReadWriteOnce allows mounting by a single node. For multi-node access, use ReadWriteMany with compatible storage backends like NFS or CephFS.

When you apply this PVC, Kubernetes binds it to an available PersistentVolume that satisfies the requirements. You can then reference this PVC in your pod specification:

apiVersion: v1
kind: Pod
metadata:
  name: app-with-storage
spec:
  containers:
  - name: app
    image: my-app:latest
    volumeMounts:
    - name: data-volume
      mountPath: /app/data
  volumes:
  - name: data-volume
    persistentVolumeClaim:
      claimName: app-data-pvc

Using StorageClasses for Dynamic Provisioning

StorageClasses enable dynamic volume provisioning, eliminating the need to pre-create PersistentVolumes. Each StorageClass defines a provisioner and parameters for the underlying storage system.

Common provisioners include:

kubernetes.io/gce-pd for Google Cloud Engine
kubernetes.io/aws-ebs for Amazon Elastic Block Store
kubernetes.io/azure-disk for Azure Disk Storage
nginx-ingress for NFS-backed storage

Here’s a PVC that uses a specific StorageClass:

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: fast-storage-pvc
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 50Gi
  storageClassName: fast-ssd

To create a StorageClass for fast SSD-backed storage:

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: fast-ssd
provisioner: kubernetes.io/gce-pd
parameters:
  type: pd-ssd
  replication-type: regional-pd
volumeBindingMode: WaitForFirstConsumer

The WaitForFirstConsumer binding mode delays volume binding until a pod using the PVC is scheduled, allowing the scheduler to choose an optimal node based on the pod’s requirements.

Managing Persistent Volumes with Claude Code

Claude Code can generate Kubernetes manifests efficiently. When working on storage-heavy applications, combine Claude Code with the pdf skill to document your storage architecture, or use the tdd skill to write tests that verify data persistence across pod restarts.

For example, ask Claude Code: “Create a StatefulSet with persistent storage for a PostgreSQL database, including appropriate resource limits and storage class configuration.” Claude will generate the manifest with proper volume templates:

apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: postgres-statefulset
spec:
  serviceName: postgres
  replicas: 3
  selector:
    matchLabels:
      app: postgres
  template:
    metadata:
      labels:
        app: postgres
    spec:
      containers:
      - name: postgres
        image: postgres:15
        volumeMounts:
        - name: postgres-data
          mountPath: /var/lib/postgresql/data
  volumeClaimTemplates:
  - metadata:
      name: postgres-data
    spec:
      accessModes: ["ReadWriteOnce"]
      storageClassName: fast-ssd
      resources:
        requests:
          storage: 20Gi

Resizing Persistent Volumes

Kubernetes supports volume expansion for most cloud-provider storage types. To enable resizing, the StorageClass must have allowVolumeExpansion set to true:

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: standard
provisioner: kubernetes.io/gce-pd
allowVolumeExpansion: true

Once enabled, you can resize a PVC by modifying the storage request:

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: app-data-pvc
spec:
  resources:
    requests:
      storage: 20Gi  # Increased from 10Gi

The expansion happens automatically for CSI-based provisioners. For older provisioners, you may need to delete and recreate the pod after the resize.

Data Backup Strategies

Persistent volumes contain your application state, making backup critical. Common approaches include:

Volume snapshots capture the volume state at a specific point in time:

apiVersion: snapshot.storage.k8s.io/v1
kind: VolumeSnapshot
metadata:
  name: data-backup
spec:
  volumeSnapshotClassName: standard
  source:
    persistentVolumeClaimName: app-data-pvc

For application-level backups, consider scheduling jobs that export data to object storage. Tools like Velero provide cluster-level disaster recovery, including persistent volume snapshots.

Common Pitfalls and Solutions

One frequent issue is PVCs stuck in Pending state. This typically occurs when no available PV matches the claim requirements or the StorageClass provisioner is misconfigured. Check events on the PVC to identify the root cause:

kubectl describe pvc <pvc-name>

Another common problem is pod startup failures due to volume mount issues. Verify the PVC is bound (kubectl get pvc) and check pod events for mount errors.

For production workloads, always set appropriate resource requests and limits on your storage. Use the supermemory skill to maintain documentation of your storage architecture decisions and the reasoning behind storage class selections.

Summary

Persistent volumes provide essential durability for stateful applications in Kubernetes. Master the PVC workflow: request storage through claims, select appropriate StorageClasses for your performance needs, and implement backup strategies before deploying to production. Claude Code accelerates this process by generating correct manifests and identifying potential issues in your configuration.

Built by theluckystrike — More at zovo.one