update pv & pvc doc

2025-10-08 20:15:41 +03:30
parent e65d9f4380
commit 80dab9ae5f
1 changed files with 90 additions and 53 deletions
--- 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 <namespace> <pvc-name>
+# Describe a specific PV or PVC
+kubectl describe pv <pv-name>
+kubectl describe pvc <pvc-name> -n <namespace>
+
+# Delete a PV or PVC
+kubectl delete pv <pv-name>
+kubectl delete pvc <pvc-name> -n <namespace>
 ```

 ---

-## 🚀 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: <pv-name>` 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 <pvc-name> -n <namespace>
+   ```
+5. **Automate cleanup** with proper reclaim policies or storage lifecycle controllers.
+