Define StorageClass, PersistentVolume, and data-protection conventions #6

New issue

Closed

opened 2026-08-29 00:22:49 -05:00 by portegumi · 1 comment

portegumi commented

2026-08-29 00:22:49 -05:00

Collaborator

Description

Define the storage, persistence, and data-protection conventions that application manifests and UDS packages must follow. These conventions are derived from the completed workload and dataset decisions in #4 rather than imposing one storage pattern on every application.

The application-specific placement decisions and migration order are documented in Mat Homelab Application Migration Plan.

Dependency

Blocked by #4. The workload inventory determines which data remains static on TrueNAS, moves into dynamically provisioned storage, remains node-local, or stays completely outside Kubernetes.

Dynamic provisioning was selected and validated under #5:

truenas-iscsi for block-backed RWO storage
truenas-nfs for shared-file RWX storage

Conventions to formalize

Dynamic iSCSI RWO

Use for ordinary single-replica application state, SQLite data, and database volumes that require single-writer block storage. Applications must request the class explicitly unless a separate default-class decision is documented.

Dynamic NFS RWX

Use when an application requires shared file access across pods or nodes. Do not select RWX merely because it is convenient; the workload must actually tolerate shared filesystem semantics.

Static NFS for existing TrueNAS data

Use static PVs for large or pre-existing datasets that remain owned by TrueNAS, including:

Shared media
ROM library
Existing Foundry data pending import into #19
Ebook and audiobook libraries
Other retained shared datasets approved during an application migration

Static PVs must not imply that Kubernetes owns or may delete the underlying dataset.

Node-local storage

Use local PVs plus node affinity for data that intentionally remains attached to a specific worker:

OptiPlex game-server data
Media-server ComfyUI data
Other GPU-adjacent local assets approved explicitly

The workload is unavailable when that node is unavailable. Manifests must make this constraint obvious and must not claim transparent failover.

External TrueNAS services

MinIO, NocoDB, the UDS Keycloak PostgreSQL service, and the retained media automation stack remain external network services. Kubernetes workloads consume their endpoints; Kubernetes does not claim their datasets through PVCs.

Retention and migration rules

Never delete or repurpose a source dataset during initial cutover.
Deploy migrations in parallel under a temporary route where practical.
Validate application behavior, persistence after pod recreation, ingress, authentication, backup, and restore before DNS cutover.
Retain the source dataset until the application has operated successfully for the agreed observation period.
Reclaim policy and backup ownership must be stated for every stateful application.
Local PV workloads require an application-specific backup destination because local disks are not protected by TrueNAS snapshots.
Velero protects Kubernetes objects and supported volume data; it does not automatically protect external TrueNAS services or arbitrary node-local paths.

Documentation deliverables

StorageClass selection matrix
Naming conventions for PVCs, static PVs, and local PVs
Reclaim and retention policy
Expansion policy
Snapshot, backup, and restore responsibilities
Static-NFS ownership rules
Node-local scheduling and failure behavior
Per-application storage decision recorded in each migration issue

Acceptance criteria

Storage types and naming conventions are documented.
Each storage class has a stated access mode and intended workload type.
Default and non-default StorageClass policy is explicit.
Static NFS and node-local PV ownership rules are explicit.
Reclaim and data-retention behavior is explicit.
Snapshot, backup, and restore responsibilities are documented without claiming unimplemented capabilities.
Disposable NFS and iSCSI PV/PVC lifecycle tests validated provisioning, persistence, expansion, and reclaim behavior under #5.
At least one migrated application validates the completed conventions end to end.

## Description Define the storage, persistence, and data-protection conventions that application manifests and UDS packages must follow. These conventions are derived from the completed workload and dataset decisions in #4 rather than imposing one storage pattern on every application. The application-specific placement decisions and migration order are documented in [Mat Homelab Application Migration Plan](/gitchegumi/homelab/wiki/Mat-Homelab-Application-Migration-Plan). ## Dependency **Blocked by #4.** The workload inventory determines which data remains static on TrueNAS, moves into dynamically provisioned storage, remains node-local, or stays completely outside Kubernetes. Dynamic provisioning was selected and validated under #5: - `truenas-iscsi` for block-backed RWO storage - `truenas-nfs` for shared-file RWX storage ## Conventions to formalize ### Dynamic iSCSI RWO Use for ordinary single-replica application state, SQLite data, and database volumes that require single-writer block storage. Applications must request the class explicitly unless a separate default-class decision is documented. ### Dynamic NFS RWX Use when an application requires shared file access across pods or nodes. Do not select RWX merely because it is convenient; the workload must actually tolerate shared filesystem semantics. ### Static NFS for existing TrueNAS data Use static PVs for large or pre-existing datasets that remain owned by TrueNAS, including: - Shared media - ROM library - Existing Foundry data pending import into #19 - Ebook and audiobook libraries - Other retained shared datasets approved during an application migration Static PVs must not imply that Kubernetes owns or may delete the underlying dataset. ### Node-local storage Use local PVs plus node affinity for data that intentionally remains attached to a specific worker: - OptiPlex game-server data - Media-server ComfyUI data - Other GPU-adjacent local assets approved explicitly The workload is unavailable when that node is unavailable. Manifests must make this constraint obvious and must not claim transparent failover. ### External TrueNAS services MinIO, NocoDB, the UDS Keycloak PostgreSQL service, and the retained media automation stack remain external network services. Kubernetes workloads consume their endpoints; Kubernetes does not claim their datasets through PVCs. ## Retention and migration rules - Never delete or repurpose a source dataset during initial cutover. - Deploy migrations in parallel under a temporary route where practical. - Validate application behavior, persistence after pod recreation, ingress, authentication, backup, and restore before DNS cutover. - Retain the source dataset until the application has operated successfully for the agreed observation period. - Reclaim policy and backup ownership must be stated for every stateful application. - Local PV workloads require an application-specific backup destination because local disks are not protected by TrueNAS snapshots. - Velero protects Kubernetes objects and supported volume data; it does not automatically protect external TrueNAS services or arbitrary node-local paths. ## Documentation deliverables - StorageClass selection matrix - Naming conventions for PVCs, static PVs, and local PVs - Reclaim and retention policy - Expansion policy - Snapshot, backup, and restore responsibilities - Static-NFS ownership rules - Node-local scheduling and failure behavior - Per-application storage decision recorded in each migration issue ## Acceptance criteria - [x] Storage types and naming conventions are documented. - [x] Each storage class has a stated access mode and intended workload type. - [x] Default and non-default StorageClass policy is explicit. - [x] Static NFS and node-local PV ownership rules are explicit. - [x] Reclaim and data-retention behavior is explicit. - [x] Snapshot, backup, and restore responsibilities are documented without claiming unimplemented capabilities. - [x] Disposable NFS and iSCSI PV/PVC lifecycle tests validated provisioning, persistence, expansion, and reclaim behavior under #5. - [ ] At least one migrated application validates the completed conventions end to end.

portegumi added the

storage

documentation

labels

2026-08-29 00:22:49 -05:00