StatefulSets

apiVersion: v1
kind: Service
metadata:
  name: postgres                     # This name becomes part of every Pod's DNS record
  namespace: payments
  labels:
    app: postgres
spec:
  clusterIP: None                    # Headless: no virtual IP — CoreDNS returns Pod IPs directly
  selector:
    app: postgres
  ports:
    - port: 5432
      name: postgres
  # With clusterIP: None, DNS for this service works like this:
  # postgres.payments.svc.cluster.local        → returns all Pod IPs (for clients that do their own LB)
  # postgres-0.postgres.payments.svc           → returns postgres-0's IP only
  # postgres-1.postgres.payments.svc           → returns postgres-1's IP only
  # This is how the primary (postgres-0) gets a stable, routable DNS name

apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: postgres
  namespace: payments
spec:
  serviceName: postgres              # REQUIRED: name of the headless Service above
                                     # This is what enables per-Pod DNS records
  replicas: 3
  selector:
    matchLabels:
      app: postgres
  updateStrategy:
    type: RollingUpdate              # RollingUpdate: update Pods one at a time, highest ordinal first
    rollingUpdate:
      partition: 0                   # Update all Pods (partition=0). Set to 2 to update only pod-2,
                                     # leaving pod-0 and pod-1 at the old version (canary pattern)
  podManagementPolicy: OrderedReady  # OrderedReady: wait for each Pod to be Ready before starting next
                                     # Parallel: start all Pods simultaneously (for non-dependent replicas)
  template:
    metadata:
      labels:
        app: postgres
    spec:
      terminationGracePeriodSeconds: 60   # Give postgres time to finish transactions on shutdown
      containers:
        - name: postgres
          image: postgres:15
          ports:
            - containerPort: 5432
          env:
            - name: POSTGRES_DB
              value: payments
            - name: POSTGRES_PASSWORD
              valueFrom:
                secretKeyRef:
                  name: postgres-credentials
                  key: POSTGRES_PASSWORD
            - name: PGDATA
              value: /var/lib/postgresql/data/pgdata
              # IMPORTANT: pgdata subdir avoids the lost+found problem
              # PostgreSQL won't start if PGDATA contains unexpected files
              # lost+found is created when mounting an ext4 volume — put PGDATA in a subdirectory
          volumeMounts:
            - name: postgres-data
              mountPath: /var/lib/postgresql/data   # Mount the PVC here
          readinessProbe:
            exec:
              command: ["pg_isready", "-U", "postgres"]
            initialDelaySeconds: 10
            periodSeconds: 5
          livenessProbe:
            exec:
              command: ["pg_isready", "-U", "postgres"]
            initialDelaySeconds: 30
            periodSeconds: 10
            failureThreshold: 3

  volumeClaimTemplates:              # THE key StatefulSet feature: per-Pod PVC
    - metadata:
        name: postgres-data          # PVC name prefix — becomes postgres-data-postgres-0, etc.
      spec:
        accessModes: ["ReadWriteOnce"]
        storageClassName: gp3-encrypted
        resources:
          requests:
            storage: 50Gi
        # Helm creates: postgres-data-postgres-0, postgres-data-postgres-1, postgres-data-postgres-2
        # Each Pod mounts ONLY its own PVC — data isolation is guaranteed by Kubernetes

# Scale up: postgres-3 starts after postgres-2 is Ready
kubectl scale statefulset postgres --replicas=4 -n payments

# Scale down: postgres-3 deleted first, then postgres-2, etc.
# The primary (postgres-0) is always the last to be deleted
kubectl scale statefulset postgres --replicas=2 -n payments

# Rolling update: update image version
# With partition=0, updates all Pods: highest ordinal (postgres-2) first
kubectl set image statefulset/postgres postgres=postgres:16 -n payments

# Watch ordered update (highest ordinal first):
kubectl rollout status statefulset/postgres -n payments
# Waiting for 3 pods to be ready...
# Waiting for partitioned roll out to finish: 1 out of 3 new pods have been updated...
# Waiting for partitioned roll out to finish: 2 out of 3 new pods have been updated...
# statefulset rolling update complete 3 pods at Version controller revision postgres-6d9f4

# Canary pattern: update only postgres-2 first, test, then update the rest
kubectl patch statefulset postgres -n payments \
  -p '{"spec":{"updateStrategy":{"rollingUpdate":{"partition":2}}}}'
kubectl set image statefulset/postgres postgres=postgres:16 -n payments
# Only postgres-2 updates — postgres-0 and postgres-1 remain on postgres:15
# Test postgres-2. If healthy:
kubectl patch statefulset postgres -n payments \
  -p '{"spec":{"updateStrategy":{"rollingUpdate":{"partition":0}}}}'
# Now all Pods update to postgres:16