Persistent Volume Claims

apiVersion: v1
kind: PersistentVolumeClaim         # PVC: a request for storage — developer-facing object
metadata:
  name: postgres-payments-pvc       # PVC name — referenced by Pod spec volumeClaimTemplates or volumes
  namespace: payments               # PVCs ARE namespace-scoped — unlike PVs which are cluster-scoped
  labels:
    app: postgres
    team: payments
  annotations:
    description: "PostgreSQL data volume for payments service"
spec:
  storageClassName: aws-ebs-gp3     # Which StorageClass to use — must match an existing StorageClass
                                    # Omitting this uses the default StorageClass (if one is set)
                                    # Set to "" (empty string) to request a pre-existing PV with no class
  accessModes:
    - ReadWriteOnce                 # Must be a subset of the access modes the PV supports
                                    # Database: RWO is correct — one writer, on one node at a time
  resources:
    requests:
      storage: 50Gi                 # How much storage you need — provisioner creates EBS volume of this size
                                    # With dynamic provisioning: EBS volume is exactly 50Gi
                                    # With static provisioning: Kubernetes finds a PV >= 50Gi
  volumeMode: Filesystem            # Filesystem (default): volume is mounted as a directory
                                    # Block: raw block device — for databases managing their own I/O buffers

apiVersion: apps/v1
kind: Deployment
metadata:
  name: postgres-payments
  namespace: payments
spec:
  replicas: 1                         # Databases: always 1 replica with RWO storage
                                      # Multiple replicas + RWO = only the Pod on the first node
                                      # that mounts the volume actually works — others stay Pending
  selector:
    matchLabels:
      app: postgres-payments
  template:
    metadata:
      labels:
        app: postgres-payments
    spec:
      containers:
        - name: postgres
          image: postgres:15.4         # Pin the exact version — never use postgres:latest
          ports:
            - containerPort: 5432
          env:
            - name: POSTGRES_DB
              value: "payments"
            - name: POSTGRES_USER
              valueFrom:
                secretKeyRef:
                  name: postgres-credentials
                  key: POSTGRES_USER
            - name: POSTGRES_PASSWORD
              valueFrom:
                secretKeyRef:
                  name: postgres-credentials
                  key: POSTGRES_PASSWORD
            - name: PGDATA
              value: /var/lib/postgresql/data/pgdata
              # PGDATA: PostgreSQL data directory — must be a subdirectory of the mount
              # EBS volumes mounted at the root path sometimes have a lost+found directory
              # that causes postgres to refuse to initialise — the pgdata subdir avoids this
          volumeMounts:
            - name: postgres-data      # Must match the volume name declared below
              mountPath: /var/lib/postgresql/data   # Standard PostgreSQL data directory
          resources:
            requests:
              cpu: "250m"
              memory: "512Mi"
            limits:
              cpu: "1000m"
              memory: "1Gi"
          readinessProbe:
            exec:
              command: ["pg_isready", "-U", "postgres"]
            initialDelaySeconds: 10
            periodSeconds: 5

      volumes:
        - name: postgres-data          # Volume name — referenced by volumeMounts above
          persistentVolumeClaim:       # persistentVolumeClaim: use a PVC as a volume source
            claimName: postgres-payments-pvc  # The PVC name in the same namespace
            readOnly: false            # readOnly: false — database needs write access

kubectl get pvc postgres-payments-pvc -n payments
# Confirm current size and Bound status before attempting resize

kubectl patch pvc postgres-payments-pvc -n payments \
  -p '{"spec":{"resources":{"requests":{"storage":"100Gi"}}}}'
# patch: update the storage request from 50Gi to 100Gi
# The CSI driver detects the change and expands the underlying EBS volume
# EBS resize is online — no Pod restart required for the block device expansion
# However, the FILESYSTEM resize may require a Pod restart on some older CSI driver versions

kubectl get pvc postgres-payments-pvc -n payments -w
# Watch for the Conditions field to update:
# FileSystemResizePending → FileSystemResizeSuccessful
# This confirms both the block device and the filesystem have been expanded

kubectl exec -it postgres-payments-6f8b9d-2xkpj -n payments -- df -h /var/lib/postgresql/data
# Confirm the new size is visible inside the container

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: postgres-eu-pvc
  namespace: payments-eu
spec:
  storageClassName: manual          # manual storageClass = static provisioning only
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 100Gi
  selector:                         # selector: only bind to PVs matching these labels
    matchLabels:
      region: eu-west               # Only bind to PVs labelled region=eu-west
      environment: production       # AND environment=production
                                    # Both conditions must match — this is an AND not OR
    matchExpressions:               # matchExpressions: set-based selector for more flexibility
      - key: tier
        operator: In
        values: ["ssd", "nvme"]     # Only bind to PVs on ssd or nvme storage tiers

kubectl get pvc -n payments
# First look: STATUS column — Pending means no PV bound yet

kubectl describe pvc postgres-payments-pvc -n payments
# KEY: look at Events section — it tells you exactly why it's pending:
# "no persistent volumes available for this claim and no storage class is set" → missing storageClassName
# "waiting for a volume to be created" → dynamic provisioner working (or stuck)
# "storageclass.storage.k8s.io not found" → StorageClass name is wrong or doesn't exist

kubectl get storageclass
# Verify the StorageClass the PVC references actually exists
# Check if it has (default) marker — a PVC with no storageClassName needs a default SC

kubectl get pv
# For static provisioning: are there any Available PVs that could match?
# Check that access modes, capacity, and storageClassName all match the PVC request

kubectl get events -n payments --sort-by='.lastTimestamp' | grep -i pvc
# Events stream: provisioner errors, binding failures, quota exceeded
# The provisioner logs errors here when it fails to create the backing volume

kubectl logs -n kube-system -l app=ebs-csi-controller -c csi-provisioner
# CSI provisioner logs — when dynamic provisioning fails, the error is here
# Common errors: IAM permission denied, AZ capacity exhausted, quota exceeded