Storage Strategy

The storage design is workload-specific. Kubernetes consumes storage from TrueNAS and local disks, but it does not automatically own or relocate every persistent dataset.

Storage classes of service

Storage type	Intended use	Placement behavior
Static NFS PV/PVC	Existing or shared datasets, including media	Kubernetes objects bind a known TrueNAS NFS export and reuse its dataset in place
Dynamic shared-file storage	Kubernetes-managed workloads requiring shared filesystem access	Provisioned through the selected TrueNAS CSI/NFS integration
Dynamic block storage	Databases and single-writer state that fit block semantics	Provisioned through the selected TrueNAS CSI/iSCSI integration
Local PV	Hardware- or node-bound datasets	Bound to the node that physically owns the data
Ephemeral local storage	Cache, scratch space, and transcode data	Re-creatable and local to the scheduled worker

Responsibility boundary

Inside Kubernetes

• Static PV and PVC objects bind existing TrueNAS NFS exports.
• The TrueNAS CSI driver dynamically provisions NFS or iSCSI storage and communicates with the TrueNAS API.
• Local PV objects represent data physically stored on a worker.

On TrueNAS

• Existing datasets remain the underlying data source.
• NFS exports expose existing datasets for static PV consumption.
• CSI-backed dynamic storage supplies shared-file NFS and block iSCSI storage.

Static PV/PVC objects belong to Kubernetes, not TrueNAS. TrueNAS provides the exports, datasets, and block devices they consume.

TrueNAS datasets

Known dataset roots:

• Application data: /mnt/homelab/apps/
• Shared media: /mnt/homelab/media

Before Kubernetes mounts an existing dataset, the inventory records:

• Current application and owner
• Size and expected growth
• UID/GID and permission model
• Existing mount/container path
• Access mode and concurrent writers
• Backup and restore expectations
• Whether Kubernetes may manage lifecycle or only consume the data

Existing and shared data

Static NFS PVs are appropriate when a dataset already exists and should not be recreated or moved. Jellyfin media remains on the existing TrueNAS media dataset regardless of which worker runs Jellyfin.

Game-server persistent data may move from OptiPlex-local storage to TrueNAS where the workload and performance profile permit it. Shared storage would allow those game servers to schedule across the Sager and OptiPlex. Existing local PVs remain valid during the initial migration and for workloads that should stay node-bound.

Kubernetes-managed state

Dynamic storage exposes separate conventions for shared-file and block/database workloads. The exact CSI, NFS, and iSCSI implementation remains unresolved. Selection must include lifecycle, expansion, reclaim, snapshot, backup, and credential-handling behavior.

The Keycloak PostgreSQL database is expected to require persistent block storage, likely TrueNAS-backed, but its final placement remains TBD.

TrueNAS does not need kubectl. Storage integration components run in Kubernetes and communicate with TrueNAS through NFS, iSCSI, and the TrueNAS API where selected.

Node-local data

• ComfyUI: existing models remain at /mnt/assets/ComfyUI/models on the media GPU worker; node-affined local PV deployment is prepared but not yet applied. The earlier 786 GB figure is historical; the owner reported 841G used across the whole 4.6T assets filesystem on 2026-09-16, not a measured model-directory size.
• Game servers: existing OptiPlex local PVs may be used initially; suitable persistent data may move to shared TrueNAS storage.
• Jellyfin cache/transcode: uses local ephemeral or local persistent storage on its eventual worker rather than the TrueNAS media dataset.

Kubernetes local PVs are preferred over arbitrary hostPath mounts.

Data protection

Each persistent workload documents:

1. Source of truth
2. Backup owner and schedule
3. Restore procedure
4. Reclaim behavior
5. Node-loss implications
6. Cutover and rollback data handling

A successful PVC mount is not a backup or recovery strategy.

ComfyUI migration decisions — 2026-09-18

The owner approved separate dev/prod writable data under /mnt/assets/comfyui-cluster/, read-only model mounts, and comfyui.dev.gitchegumi.com / comfyui.gitchegumi.com. Following the owner review on platform PR #50, both environments use the existing /mnt/assets/ComfyUI/models library read-only, through separate reserved PVs and namespaced PVCs. No model copy or new model directory is required. Writable data remains separate at dev/state and prod/state; models remain unchanged during dev testing.

Platform PR #50 owns four Retain PVs and the nonprovisioning comfyui-local StorageClass. Comfy-UI PR #3 owns PVCs and the application in comfy-ui-dev / comfy-ui. The container uses UID/GID 1000 without recursive ownership changes to the existing library. PV capacities are binding metadata, not ext4 quotas. These changes are under review, not deployed; Comfy-UI #1 tracks acceptance.

GPU scheduling and CUDA computation are verified under platform #3. There is one GPU, so dev and production run sequentially. The terminal installation and its modified custom nodes remain the rollback source until migration is accepted. The owner has no backup destination yet: choose an off-node destination and test restoration before production cutover. Retain does not cover disk or node loss.

The prepared storage runbook and application runbook describe preparation, validation, cutover and rollback; their execution has not been verified.