From 80dab9ae5f129d951c7bcaeeb9ee009307bf61d3 Mon Sep 17 00:00:00 2001 From: RadinPirouz Date: Wed, 8 Oct 2025 20:15:41 +0330 Subject: [PATCH] update pv & pvc doc --- .../Kubernetes/Storage/Pv.md | 143 +++++++++++------- 1 file changed, 90 insertions(+), 53 deletions(-) diff --git a/Containerization-Orchestration/Kubernetes/Storage/Pv.md b/Containerization-Orchestration/Kubernetes/Storage/Pv.md index 9a8138a..935fe4f 100644 --- a/Containerization-Orchestration/Kubernetes/Storage/Pv.md +++ b/Containerization-Orchestration/Kubernetes/Storage/Pv.md @@ -1,77 +1,95 @@ -# 🌐 Kubernetes Persistent Volumes (PV) Cheat Sheet +# Kubernetes Persistent Volumes (PV) Cheat Sheet -## πŸ“¦ What is a Persistent Volume (PV)? +## What is a Persistent Volume (PV)? A **Persistent Volume (PV)** is a piece of storage in a Kubernetes cluster that can be: -- **Pre-provisioned** by an administrator, or -- **Dynamically provisioned** using a **StorageClass**. +* **Pre-provisioned** by an administrator, or +* **Dynamically provisioned** using a **StorageClass**. -> PVs allow data to **persist beyond the lifecycle of individual Pods**. +PVs allow data to **persist beyond the lifecycle of individual Pods**. --- -## πŸ“ PV Storage Options +## PV Storage Options -### 1. **HostPath** -- Mounts a file or directory from the host node’s filesystem into a Pod. -- Only suitable for **single-node testing or development** environments. +### 1. HostPath -### 2. **Persistent Volume (PV) & Persistent Volume Claim (PVC)** -- **PV**: Represents the actual physical or virtual storage resource. -- **PVC**: A user's request for specific storage resources and access modes. +* Mounts a file or directory from the host node’s filesystem into a Pod. +* Suitable **only for local development or single-node clusters** such as Minikube or Kind. +* Not recommended for production workloads. + +### 2. NFS + +* Network File System; allows multiple Pods and nodes to share storage. +* Recommended for shared or distributed environments. + +### 3. Cloud Volumes + +* **AWS:** `awsElasticBlockStore` +* **GCP:** `gcePersistentDisk` +* **Azure:** `azureDisk` or `azureFile` +* **CSI Drivers:** Preferred modern approach for all major clouds and on-prem solutions. --- -## 🧱 Kubernetes Storage Architecture +## Kubernetes Storage Architecture -1. **Persistent Volume (PV)** – The actual storage unit, managed by the admin or provisioned dynamically. -2. **Persistent Volume Claim (PVC)** – A user’s request for a certain amount and type of storage. +1. **Persistent Volume (PV)** – Represents the actual storage resource, managed by the cluster admin or a dynamic provisioner. +2. **Persistent Volume Claim (PVC)** – A user request for storage with specific size and access requirements. +3. **StorageClass** – Defines how dynamic provisioning should occur (provisioner, reclaim policy, parameters). --- -## πŸ”„ PV Lifecycle Phases +## PV Lifecycle Phases -| **State** | **Description** | -|---------------|---------------------------------------------| -| Provisioning | PV is being created or initialized. | -| Binding | PV is bound to a PVC. | -| Using | PV is in use by a Pod. | -| Releasing | PVC is deleted; PV becomes unbound. | -| Reclaiming | Based on reclaim policy: | -| | - `Delete`: Remove the storage. | -| | - `Recycle`: Basic scrub (deprecated). | -| | - `Retain`: Manual cleanup required. | +| State | Description | +| ------------- | -------------------------------------------------------- | +| **Available** | PV is ready to be bound. | +| **Bound** | PV is bound to a PVC. | +| **Released** | PVC was deleted; PV is unbound but data may still exist. | +| **Failed** | Automatic cleanup failed. | + +### Reclaim Policies: + +* **Delete:** Removes the underlying storage resource. +* **Retain:** Keeps data for manual recovery. +* **Recycle:** Deprecated (previously used to scrub the volume). --- -## πŸ”’ PV Access Modes +## PV Access Modes -| **Mode** | **Description** | -|------------|-------------------------------------------------| -| `RWO` | **ReadWriteOnce** – One node can read/write. | -| `ROX` | **ReadOnlyMany** – Multiple nodes can read. | -| `RWX` | **ReadWriteMany** – Multiple nodes can read/write. | -| `RWOP` | **ReadWriteOncePod** – Only one Pod can mount it with read/write access. | +| Mode | Description | +| ------------------------- | -------------------------------------------------------------------- | +| `ReadWriteOnce` (RWO) | One node can read/write. | +| `ReadOnlyMany` (ROX) | Many nodes can read. | +| `ReadWriteMany` (RWX) | Many nodes can read/write. | +| `ReadWriteOncePod` (RWOP) | Only one Pod can mount it with read/write access (Kubernetes β‰₯1.22). | --- -## πŸ› οΈ CLI Commands to Manage PVs & PVCs +## CLI Commands to Manage PVs & PVCs ```bash # List all Persistent Volumes kubectl get pv # List all Persistent Volume Claims -kubectl get pvc +kubectl get pvc -A -# Edit a PVC -kubectl edit pvc -n +# Describe a specific PV or PVC +kubectl describe pv +kubectl describe pvc -n + +# Delete a PV or PVC +kubectl delete pv +kubectl delete pvc -n ``` --- -## πŸš€ Example: Deployment with `hostPath` Volume +## Example: Deployment with `hostPath` Volume ```yaml apiVersion: apps/v1 @@ -83,11 +101,11 @@ spec: replicas: 3 selector: matchLabels: - name: nginx + app: nginx template: metadata: labels: - name: nginx + app: nginx spec: containers: - name: nginx @@ -104,18 +122,15 @@ spec: type: DirectoryOrCreate ``` -### Valid `hostPath` Types: -- `DirectoryOrCreate` -- `Directory` -- `FileOrCreate` -- `File` -- `Socket` -- `CharDevice` -- `BlockDevice` +**Valid `hostPath` Types:** +`DirectoryOrCreate`, `Directory`, `FileOrCreate`, `File`, `Socket`, `CharDevice`, `BlockDevice` --- -## πŸ“„ Example: Static Persistent Volume (PV) +## Example: Static Persistent Volume (PV) + +**Important:** A PV **must specify a volume source type** (this was the cause of your validation error). +For example, this corrected PV uses `hostPath`: ```yaml apiVersion: v1 @@ -128,11 +143,14 @@ spec: accessModes: - ReadWriteMany persistentVolumeReclaimPolicy: Retain + storageClassName: manual + hostPath: + path: /mnt/data/pv001 ``` --- -## πŸ“„ Example: Persistent Volume Claim (PVC) +## Example: Persistent Volume Claim (PVC) ```yaml apiVersion: v1 @@ -146,16 +164,18 @@ spec: resources: requests: storage: 64Mi + storageClassName: manual ``` -> βœ… To bind a PVC to a specific PV, add `volumeName: ` in the PVC spec: +To bind this PVC to a specific PV manually: + ```yaml volumeName: pv001 ``` --- -## 🌐 NFS-Based Persistent Volume +## NFS-Based Persistent Volume ### Persistent Volume (PV) @@ -199,7 +219,7 @@ spec: --- -## πŸ—οΈ Static StorageClass for Pre-Provisioned Volumes +## Static StorageClass for Pre-Provisioned Volumes ```yaml apiVersion: storage.k8s.io/v1 @@ -207,4 +227,21 @@ kind: StorageClass metadata: name: nginx-files provisioner: kubernetes.io/no-provisioner +volumeBindingMode: WaitForFirstConsumer +reclaimPolicy: Retain ``` + +--- + +## Recommended Additions + +1. **Always include `storageClassName`** to ensure predictable binding. +2. **Set `volumeBindingMode: WaitForFirstConsumer`** in StorageClasses for node-aware provisioning. +3. **Avoid using `hostPath` in multi-node clusters**; use NFS or CSI drivers. +4. **Check events** for troubleshooting PV/PVC binding: + + ```bash + kubectl describe pvc -n + ``` +5. **Automate cleanup** with proper reclaim policies or storage lifecycle controllers. +