Persistent Volume Claim (PVC)

A PVC can automatically trigger the creation of a new PersistentVolume (PV) on-demand. When a PVC specifies a StorageClass, the cluster's provisioner creates the underlying storage resource (e.g., an AWS EBS volume or Azure Disk) and a corresponding PV object, which is then bound to the PVC. This eliminates the need for administrators to pre-provision PVs manually.

• Example: A PVC with storageClassName: fast-ssd causes the cloud provider's CSI driver to create a new SSD-based volume.
• Key Benefit: Enables self-service storage for developers and automated scaling.

A PVC specifies how the mounted storage can be accessed by pods. Kubernetes supports three primary modes:

• ReadWriteOnce (RWO): The volume can be mounted as read-write by a single node. This is common for block storage.
• ReadOnlyMany (ROX): The volume can be mounted as read-only by many nodes simultaneously.
• ReadWriteMany (RWX): The volume can be mounted as read-write by many nodes. This is typically provided by file or object storage (e.g., NFS, CephFS).

The PVC's request is matched against PVs that support the required mode, ensuring compatibility with the application's data sharing needs.

The StorageClass resource defines a class of storage (e.g., performance tier, availability zone, backup policy). A PVC references a StorageClass by name to request storage with those specific qualities.

• Parameters: A StorageClass contains parameters passed to the provisioner, like type: gp3 or replication: "3".
• Default Class: A cluster can have a default StorageClass; PVCs without a specified class will use it.
• Binding Mode: Determines when volume binding occurs (Immediate vs. WaitForFirstConsumer), which is critical for topology-aware scheduling (e.g., ensuring a pod's volume is created in the same cloud availability zone as the pod).

A PVC defines the quantity of storage required using standard Kubernetes resource syntax.

• Request (spec.resources.requests.storage): The minimum amount of storage the PVC needs (e.g., 10Gi). This is the primary matching criterion for PV binding.
• Expansion: Many storage drivers support volume expansion. A PVC's request can be increased post-creation if its StorageClass has allowVolumeExpansion: true. The underlying volume is resized, and the file system typically needs expansion within the pod.
• Limits: While not directly specified in the PVC, ResourceQuotas at the namespace level can limit the total amount of storage a team can claim via PVCs.

The lifecycle of a PVC and its bound PV is governed by reclaim policies set on the PV.

• Retain: When the PVC is deleted, the PV is not deleted. It enters a Released state, preserving its data. An administrator must manually clean it up before it can be reused.
• Delete: The default for dynamically provisioned volumes. Deleting the PVC triggers the deletion of the associated PV and the underlying storage asset in the cloud or infrastructure.
• Recycle (Deprecated): A basic data scrubbing policy, now replaced by dynamic provisioning. This policy is crucial for data safety, preventing accidental loss of persistent data when claims are removed.

The interaction between a PVC and a PV involves specific binding rules and data presentation formats.

• Static Binding: A pre-existing PV is matched to a PVC based on storage size, access modes, StorageClass, and other labels. The closest match is selected.
• Dynamic Binding: As described in Dynamic Provisioning.
• Volume Mode: Specifies whether the volume is presented as a filesystem (Filesystem) or a raw block device (Block) to the pod. Block mode is used for performance-sensitive applications like databases that manage their own file systems.
• Selector: A PVC can use selector to request a PV with specific labels, enabling fine-grained control over which pre-provisioned volume it binds to.

PVCs provide the durable storage backend for databases like PostgreSQL, MySQL, and MongoDB running in Kubernetes. The PVC ensures that critical data persists independently of the pod's lifecycle, preventing data loss during pod rescheduling, node failures, or rolling updates. This is a fundamental requirement for any production database deployment.

• Example: A StatefulSet for PostgreSQL creates a unique PVC for each pod replica, guaranteeing stable network identity and persistent storage.

Message brokers (e.g., Apache Kafka, RabbitMQ) and streaming platforms require persistent storage for message durability and log retention. PVCs are bound to these pods to store message queues, topic partitions, and consumer offsets. This ensures that in-flight messages and stream history are not lost if a broker pod is restarted or moved.

• Critical for: Guaranteeing at-least-once or exactly-once delivery semantics in event-driven architectures.

Observability stacks like the Elasticsearch, Logstash, and Kibana (ELK) or Grafana Loki rely on PVCs for long-term metric and log storage. The central log aggregator (e.g., Elasticsearch) uses PVCs to maintain its indices, allowing historical data analysis and trend visualization. Without PVCs, this data would be ephemeral and lost on pod eviction.

• Typical setup: A dedicated storage class with high IOPS for fast log ingestion and query performance.

Applications that serve user-generated content—such as document management systems, media libraries, or web content managers—use PVCs as mounted file systems. The PVC acts as a network-attached directory where uploaded files, images, and assets are stored. This allows multiple application pod replicas to share access to the same set of files.

• Access Modes: Typically use ReadWriteMany (RWX) access mode if supported by the storage provider to allow concurrent writes from multiple pods.

In ML pipelines, PVCs are used to store large training datasets, pre-trained model weights, and experiment artifacts. Training jobs can mount the same PVC to access shared data, and upon completion, persist the trained model to the PVC for serving. This decouples the expensive compute (training pods) from the storage layer.

• Workflow: 1. Data preparation pod writes processed dataset to PVC. 2. Training pod mounts PVC, reads data, writes model. 3. Inference service pod mounts the same PVC to load the model.

Continuous Integration/Continuous Deployment systems (e.g., Jenkins, Tekton, GitLab Runner) use PVCs to provide workspace persistence across pipeline stages. This allows build artifacts, dependency caches (like Maven or npm), and test results to be shared between sequential steps (e.g., build, test, package) without re-downloading or rebuilding.

• Performance Benefit: Caching dependencies in a PVC can dramatically reduce pipeline execution time and network egress costs.

A Persistent Volume (PV) is the actual storage resource in a Kubernetes cluster, provisioned by an administrator or dynamically by a storage class. It is a cluster-level resource with a specific capacity, access mode (e.g., ReadWriteOnce, ReadOnlyMany), and a defined storage class. A PVC binds to an available PV to fulfill its request. Think of the PV as the physical disk and the PVC as the request to use it.

• Static Provisioning: An admin manually creates a pool of PVs in advance.
• Dynamic Provisioning: A PV is automatically created on-demand when a PVC references a StorageClass.

A StorageClass is a Kubernetes resource that defines a 'class' of storage, abstracting the underlying storage provider (e.g., AWS EBS, Google Persistent Disk, Azure Disk, Ceph). It allows for dynamic volume provisioning. When a PVC references a StorageClass, the cluster automatically creates a suitable PV. Key parameters include:

• provisioner: Determines which volume plugin is used.
• parameters: Provider-specific settings like disk type (e.g., gp3, pd-ssd) or IOPS.
• reclaimPolicy: Defines what happens to the PV when its bound PVC is deleted (Delete or Retain).

A StatefulSet is the primary Kubernetes workload controller for managing stateful applications like databases (MySQL, Cassandra, etc.). It provides guarantees about the ordering and uniqueness of pods. Crucially, when a StatefulSet's pod is rescheduled, its associated PVC (and thus its PV) is reattached, providing stable, persistent storage identity. This is essential for agent deployment observability, where an agent's memory or context must persist across pod restarts during updates or failures.

• Each pod gets a stable hostname and a unique ordinal index (e.g., app-0, app-1).
• Each pod template can define a volumeClaimTemplate, which automatically creates a unique PVC for each pod instance.

A Volume in Kubernetes is a broader concept that enables a container to access and store data. Unlike a local container filesystem, volumes persist beyond the lifecycle of an individual container. There are many volume types:

• ephemeral: emptyDir (tied to pod lifecycle).
• projected: configMap, secret, downwardAPI (inject configuration).
• persistent: persistentVolumeClaim (the subject of this glossary).

A PVC is mounted into a pod as a volume by referencing the PVC's name in the pod spec under spec.volumes. This decouples the pod definition from the specific storage implementation details.

The Container Storage Interface (CSI) is a standard that enables storage vendors to develop plugins once and have them work across multiple container orchestration systems, including Kubernetes. It decouples the Kubernetes core code from storage provider logic. When a PVC requests storage from a StorageClass backed by a CSI driver (e.g., ebs.csi.aws.com), the CSI driver handles the communication with the cloud provider's API to create, attach, and mount the actual storage device. This is the modern, extensible mechanism for most persistent storage in Kubernetes.

Access Modes define how a Persistent Volume can be mounted by pods. A PVC must request an access mode compatible with the PV it binds to. The three modes are:

• ReadWriteOnce (RWO): The volume can be mounted as read-write by a single node. This is the most common mode for databases or single-pod agents.
• ReadOnlyMany (ROX): The volume can be mounted as read-only by many nodes simultaneously.
• ReadWriteMany (RWX): The volume can be mounted as read-write by many nodes. This is required for shared storage scenarios but is less commonly supported by cloud block storage (often requires a file-based system like NFS or CephFS).

Choosing the correct access mode is critical for the data consistency and availability of your deployed agents.