Ultimate PV

PersistentVolume

apiVersion: v1
kind: PersistentVolume
metadata:
  name: my-pv                                # Unique name for the PV
  # namespace: default                       # Typically, PVs are cluster-scoped resources (no namespace)
  labels:                                    # Optional: Labels help identify or group PVs
    environment: production
    region: us-east-1
  annotations:                               # Optional: Provide additional metadata
    pv.kubernetes.io/provisioned-by: "csi.driver.name"  # Typically set by external-provisioner if dynamically created
    volume.beta.kubernetes.io/storage-class: "standard" # Legacy annotation-based approach
    # custom annotations here...

  finalizers:                                # Optional: Prevents deletion under certain conditions
    - kubernetes.io/pv-protection
  # other metadata fields could include:
  #   ownerReferences:
  #   managedFields:
  #   clusterName:
  #   generateName:
  # etc.

spec:
  capacity:
    storage: 10Gi                            # The storage capacity of the volume

  accessModes:                               # How the volume can be accessed
    - ReadWriteOnce
    # - ReadOnlyMany
    # - ReadWriteMany
    # Typically depends on the storage backend

  persistentVolumeReclaimPolicy: Retain | Recycle | Delete  # Behavior when the claim is released
  # - Retain: Manual reclamation after PVC is deleted
  # - Recycle: (Deprecated) Basic scrub (rm -rf /thevolume)
  # - Delete: Automatic deletion of the storage resource

  storageClassName: "standard"               # Associates the PV with a StorageClass

  volumeMode: "Filesystem" | "Block"         # Filesystem is default; some CSI backends support raw block

  mountOptions:                              # Optional: Additional mount options
    - debug
    - noexec

  claimRef:                                  # Optional: Binds the PV to a specific PVC
    kind: PersistentVolumeClaim
    namespace: default
    name: myclaim
    uid: f7c6d3a5-3a62-11eb-b378-0242ac130004
    apiVersion: v1
    resourceVersion: "12345"
    # The above is typically set automatically when the PV is bound to a PVC.

  # nodeAffinity: Used to constrain which nodes this PV can be accessed from
  nodeAffinity:
    required:
      nodeSelectorTerms:
        - matchExpressions:
            - key: kubernetes.io/hostname
              operator: In | NotIn | Exists | DoesNotExist | Gt | Lt
              values:
                - node1
                - node2
    preferredDuringSchedulingIgnoredDuringExecution:
      - weight: 1
        preference:
          matchExpressions:
            - key: topology.kubernetes.io/zone
              operator: In
              values:
                - us-east-1a
      - weight: 5
        preference:
          matchExpressions:
            - key: kubernetes.io/instance-type
              operator: In
              values:
                - m5.large

  #-------------------------
  # Below are various volume source types; only ONE can be used per PV.
  #-------------------------

  # 1) NFS Volume Source
  nfs:
    path: /var/nfs/general
    server: nfs-server.example.com
    readOnly: false

  # 2) HostPath Volume Source
  # hostPath:
  #   path: /data
  #   type: Directory | DirectoryOrCreate | File | FileOrCreate | Socket | CharDevice | BlockDevice | ...

  # 3) GCE Persistent Disk Volume Source
  # gcePersistentDisk:
  #   pdName: my-gce-disk
  #   fsType: ext4
  #   partition: 1
  #   readOnly: false

  # 4) AWS Elastic Block Store Volume Source
  # awsElasticBlockStore:
  #   volumeID: aws://us-east-1a/vol-abc123
  #   fsType: ext4
  #   partition: 1
  #   readOnly: false

  # 5) Azure File Volume Source
  # azureFile:
  #   secretName: azure-secret
  #   shareName: my-azure-share
  #   readOnly: false

  # 6) Azure Disk Volume Source
  # azureDisk:
  #   diskName: my-managed-disk
  #   diskURI: /subscriptions/abc/resourceGroups/xyz/providers/Microsoft.Compute/disks/my-managed-disk
  #   cachingMode: None | ReadOnly | ReadWrite
  #   fsType: ext4
  #   kind: Managed | Shared | Dedicated
  #   readOnly: false

  # 7) iSCSI Volume Source
  # iscsi:
  #   targetPortal: 10.0.0.2:3260
  #   iqn: iqn.2001-04.com.example:storage.kube.sys1.xyz
  #   lun: 0
  #   fsType: ext4
  #   readOnly: false
  #   portals:
  #     - 10.0.0.3:3260
  #   chapAuthDiscovery: false
  #   chapAuthSession: false
  #   secretRef:
  #     name: my-iscsi-secret
  #   initiatorName: customInitiator

  # 8) GlusterFS Volume Source
  # glusterfs:
  #   endpoints: gluster-cluster
  #   path: my-vol
  #   readOnly: false

  # 9) Ceph RBD Volume Source
  # rbd:
  #   monitors:
  #     - 10.0.0.1:6789
  #   image: foo
  #   fsType: ext4
  #   pool: rbd
  #   user: admin
  #   keyring: /etc/ceph/keyring
  #   secretRef:
  #     name: ceph-secret
  #   readOnly: false

  # 10) CSI Volume Source
  # csi:
  #   driver: csi.example.com                     # Name of the CSI driver
  #   volumeHandle: "unique-volume-id"            # Unique ID for the volume
  #   fsType: ext4
  #   volumeAttributes:                           # Additional key-value attributes for the driver
  #     storage.kubernetes.io/csiProvisionerIdentity: "1234567890"
  #     foo: bar
  #   controllerPublishSecretRef:
  #     name: csi-controller-publish-secret
  #     namespace: default
  #   nodeStageSecretRef:
  #     name: csi-node-stage-secret
  #     namespace: default
  #   nodePublishSecretRef:
  #     name: csi-node-publish-secret
  #     namespace: default
  #   controllerExpandSecretRef:
  #     name: csi-controller-expand-secret
  #     namespace: default

  # 11) Flex Volume Source
  # flexVolume:
  #   driver: example.com/foo
  #   fsType: ext4
  #   secretRef:
  #     name: flex-secret
  #   options:
  #     key: value

  # Additional volume sources exist, but these are among the most common.

PersistentVolumeStatus

status:
  phase: Available | Bound | Released | Failed   # Current state of the PV
  # - Available: Free for use
  # - Bound: Claimed by a PVC
  # - Released: PVC is deleted, but PV not reclaimed
  # - Failed: Volume can no longer be used

  # The fields below are typically managed by the system automatically.

  message: "Volume bound to myclaim"       # Human-readable message
  reason: "BoundByController"              # Brief reason for current phase
  capacity:
    storage: 10Gi
  accessModes:
    - ReadWriteOnce
  claimRef:                                # Duplicate from spec if bound
    kind: PersistentVolumeClaim
    namespace: default
    name: myclaim
  conditions:                              # Conditions for the volume
    - type: "Resizing"
      status: "True"
      reason: "ControllerExpansionInProgress"
      message: "Volume is expanding from 10Gi to 20Gi"
      lastProbeTime: "2021-03-10T09:14:00Z"
      lastTransitionTime: "2021-03-10T09:14:00Z"