coreci/atelier
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 28 Wiki Activity
Files
4e433158cd80a34dde592be3306aeb4dcc42c191
atelier/domains/kubernetes/storage.md
T
Jon Chery d1aa5daf2b docs(milestone): complete v0.2 — infrastructure-as-code + kubernetes 
---ci---
project: atelier
phase: 5
milestone: v0.2
status: complete
requirements:
  covered: [ATELIER-36, ATELIER-37, ATELIER-38, ATELIER-39, ATELIER-40, ATELIER-41, ATELIER-42, ATELIER-43, ATELIER-44, ATELIER-45, ATELIER-46, ATELIER-47, ATELIER-48, ATELIER-49, ATELIER-50, ATELIER-51, ATELIER-52, ATELIER-53, ATELIER-54, ATELIER-55, ATELIER-56, ATELIER-57, ATELIER-58, ATELIER-59]
  partial: []
---/ci---
2026-08-05 02:20:17 +00:00

4.3 KiB
Raw Blame History

Storage — Derived Rules

Derives from domains/kubernetes/first-principles.md. P8 (Storage is Explicit) lives here. Covers Volumes, PV/PVC, StorageClass, CSI, snapshots, and reclaim policies. Cross-link domains/data/ for the data-model angle.

Ephemeral by Default (P8 Storage is Explicit)

  • A container's filesystem is ephemeral. When the pod dies, the filesystem dies with it. This is the design, not a flaw.
  • emptyDir is an ephemeral volume scoped to the pod's lifetime (survives container restarts within the pod, dies with the pod). It is scratch space, never durable storage.
  • Any data that must survive a pod restart requires a PersistentVolumeClaim (PVC). The choice of "must survive" is the data-safety decision at the heart of P8.

PersistentVolume and PersistentVolumeClaim (P8 Storage is Explicit)

  • A PersistentVolume (PV) is a piece of storage in the cluster. A PersistentVolumeClaim (PVC) is a request for that storage by a workload.
  • The PV is the resource; the PVC is the consumer. A workload mounts the PVC, not the PV directly.
  • For StatefulSets, use volumeClaimTemplates so each replica gets its own PVC with a stable name (data-<statefulset>-0). Do not share one PVC across replicas of a stateful workload.

StorageClass and Dynamic Provisioning (P8 Storage is Explicit, P5 Version Everything)

  • A StorageClass describes the "flavour" of storage (e.g., fast-ssd, cold-hdd, encrypted). A PVC names a StorageClass or gets the cluster default.
  • Dynamic provisioning creates the PV on demand when the PVC is created, via the CSI driver. Manual PV creation is for specific cases (a pre-existing disk, a static NFS export).
  • Mark a default StorageClass only if the default is safe for all workloads. A fast-but-expensive default can cause cost surprises; a slow default can cause performance surprises.

CSI (P5 Version Everything)

  • The Container Storage Interface (CSI) is the standard driver interface. Each storage backend ships a CSI driver. Pin the CSI driver version in the cluster; treat it as infrastructure.
  • CSI enables features beyond mount/unmount: snapshots, cloning, volume expansion, and topology-aware provisioning. Not all drivers implement all features; verify before relying.

Volume Snapshots (P5 Reversibility, P8 Storage is Explicit)

  • A VolumeSnapshot is a point-in-time copy of a PVC, taken by the CSI driver. Restore creates a new PVC from the snapshot.
  • Snapshots are not backups. They are local to the storage backend and may share blocks with the source. An off-cluster backup is still required for disaster recovery.
  • Snapshot scheduling is a workload concern (use a CronJob or a tool like Velero), not a k8s-native feature.

Reclaim Policies (P8 Storage is Explicit, P5 Reversibility)

Policy On PVC delete When
Retain PV and its data persist; PV must be manually reclaimed Production, data-safety default
Delete PV and the underlying storage are deleted Ephemeral, dev, scratch
Recycle (deprecated) PV scrubbed and made available again Do not use — use dynamic provisioning
  • The reclaim policy is a data-safety decision. Delete on a production PVC is a footgun: deleting the PVC destroys the data. Default to Retain for prod, Delete for dev.
  • For StatefulSet PVCs, the reclaim policy on the StorageClass governs what happens when the PVC is deleted (which happens when the StatefulSet is scaled down or deleted, depending on the policy).

Ephemeral Volumes (P8 Storage is Explicit)

  • configMap, secret, downwardAPI volumes are read-only (by default) projections injected at pod start. They are configuration, not storage.
  • emptyDir with medium: Memory is a tmpfs — fast, ephemeral, memory-charged. Use for scratch that must be fast and never persist.

What Violates Storage Discipline

Violation Principle
emptyDir for data that must survive pod restart P8 Storage is Explicit
Shared PVC across StatefulSet replicas P8 Storage is Explicit (use volumeClaimTemplates)
Delete reclaim policy on production storage P8 Storage is Explicit, P5 Reversibility
Snapshot treated as a backup P5 Reversibility (snapshots are local, not DR)
No default StorageClass decision (accidental default) P8 Storage is Explicit
Manual PV creation when dynamic provisioning exists C3 Simplicity
Reference in New Issue View Git Blame Copy Permalink