Geekahmed
Kubernetes Volumes: A Comprehensive Guide to Persistent Storage

Kubernetes Volumes: A Comprehensive Guide to Persistent Storage

Ahmed Moustafa's photo
Ahmed Moustafa
·

4 min read

Introduction

In Kubernetes, pods are ephemeral—they can be created, destroyed, or restarted anytime. However, many applications require persistent storage to retain data across pod restarts or share files between containers. This is where Kubernetes volumes come into play. Volumes allow containers to store data outside their isolated filesystems, ensuring data survives container crashes or pod rescheduling. This guide explains how volumes work, their types, and best practices for managing persistent storage in Kubernetes.

Key Concepts and Volume Types

1. emptyDir: Temporary Storage

  • Purpose: Share files between containers in the same pod.

  • Example: A pod with two containers—one generating HTML files and another serving them via Nginx.

      volumes:
    - name: html
      emptyDir: {}

    • emptyDir is created when the pod starts and deleted when the pod is removed.

    • Use medium: Memory for faster, in-memory storage (e.g., temporary cache).

2. gitRepo: Clone a Git Repository

  • Purpose: Populate a directory with files from a Git repo at pod startup.

  • Example: A pod serving a static website from a GitHub repository.

      volumes:
    - name: html
      gitRepo:
        repository: https://github.com/user/website.git
        revision: main
    • Limitation: The volume does not sync with the repo after creation. Use a sidecar container (e.g., git-sync) for live updates.

3. hostPath: Access Node Filesystem

  • Purpose: Mount directories from the worker node’s filesystem into a pod.

  • Example: A logging pod accessing /var/log on the node.

      volumes:
    - name: node-logs
      hostPath:
        path: /var/log
    • Caution: Ties pods to specific nodes; not suitable for persistent data.

4. Persistent Volumes (PVs) and Claims (PVCs)

  • PV: Cluster-wide storage resource (e.g., GCE Persistent Disk, NFS).

  • PVC: User’s request for storage (size, access mode).

  • Example: Using a GCE Persistent Disk for MongoDB:

      # PV Definition
  apiVersion: v1
  kind: PersistentVolume
  metadata:
    name: mongodb-pv
  spec:
    capacity:
      storage: 1Gi
    accessModes:
      - ReadWriteOnce
    gcePersistentDisk:
      pdName: mongodb
      fsType: ext4

  # PVC Definition
  apiVersion: v1
  kind: PersistentVolumeClaim
  metadata:
    name: mongodb-pvc
  spec:
    resources:
      requests:
        storage: 1Gi
    accessModes:
      - ReadWriteOnce

5. Dynamic Provisioning with StorageClasses

  • Purpose: Automatically create PVs when a PVC is requested.

  • Example: Using a fast StorageClass for SSD storage:

      # StorageClass Definition
  apiVersion: storage.k8s.io/v1
  kind: StorageClass
  metadata:
    name: fast
  provisioner: kubernetes.io/gce-pd
  parameters:
    type: pd-ssd

  # PVC Using the StorageClass
  apiVersion: v1
  kind: PersistentVolumeClaim
  metadata:
    name: mongodb-pvc
  spec:
    storageClassName: fast
    resources:
      requests:
        storage: 100Gi

Real-World Use Cases

  1. Multi-Container Pod:

    • A pod with a content-generator writing files to an emptyDir volume and a web-server serving those files.

  2. Database Persistence:

    • MongoDB using a PV (GCE Persistent Disk) to retain data across pod restarts.

  3. CI/CD Pipelines:

    • Cloning a Git repo into a gitRepo volume to deploy the latest code.

Troubleshooting Checklist

Here are common issues and solutions when working with volumes:

1. PVC Stuck in Pending State

  • Cause: No PV matches the PVC’s requirements (size, access mode).

  • Fix:

    • Check available PVs: kubectl get pv.

    • Ensure the PVC’s storageClassName matches an existing StorageClass.

2. Data Not Persisting

  • Cause: Using emptyDir or hostPath instead of a persistent volume.

  • Fix:

    • Use PV/PVC or cloud storage (e.g., GCE Persistent Disk).

3. Access Mode Conflicts

  • Cause: PVC requests ReadWriteMany, but the PV only supports ReadWriteOnce.

  • Fix:

    • Update the PVC’s access mode or create a compatible PV.

4. StorageClass Misconfiguration

  • Cause: Dynamic provisioning fails due to incorrect provisioner.

  • Fix:

    • Verify the StorageClass’s provisioner (e.g., kubernetes.io/gce-pd for GKE).

5. PV in Released State

  • Cause: PV’s reclaim policy is Retain after PVC deletion.

  • Fix:

    • Manually delete and recreate the PV.

Conclusion

Kubernetes volumes are essential for managing stateful applications and sharing data between containers. By understanding volume types like emptyDir, gitRepo, and hostPath, and leveraging PVs/PVCs for persistent storage, you can ensure data survives pod failures and rescheduling. Dynamic provisioning with StorageClasses simplifies storage management, making your applications portable across clusters. Always test your volume configurations and refer to the troubleshooting checklist to resolve common issues efficiently.

Kubernetes