T-0.1 Flux GitOps layout + dev/prod overlays + platform component skeletons (R-GITOPS-01/03, R-ENV-02, R-PLAT-01)

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
2026-08-16 00:08:31 -05:00
1 parent bd8de96456
commit af4f6c07ae
@@ -0,0 +1,31 @@
+# platform/longhorn
+
+**Longhorn** — distributed replicated block storage across the 3 nodes.
+
+- **Governing ADR:** [ADR-0003 — Distributed storage: Longhorn (+ bulk tier + Velero)](../../../home-network-k3s/decisions/adr-0003-storage-longhorn.md)
+- **Spec:** [docs/04 — Storage & State](../../../home-network-k3s/docs/04-storage-and-state.md)
+- **Serves:** R-STATE-01..04
+- **Owner:** WS-STORAGE
+
+## What this stub is
+
+Flux `HelmRelease` + two `StorageClass`es:
+- **`longhorn`** — the **default**, **3-replica** replicated class (replica count is the
+  `${LONGHORN_DEFAULT_REPLICA_COUNT}` overlay knob). Durable home for app/config state and KubeVirt
+  VM disks (via CDI).
+- **`bulk`** — non-replicated tier for large media (Plex library, download staging). **STUB**: its
+  backing store is **OQ-2 (unresolved)** — escalate before finalizing. Plex's metadata DB stays on
+  the 3-replica class regardless (ADR-0003).
+
+## Contract (consumed by everyone with state)
+
+Per `roadmap/workstreams.md`, WS-STORAGE exposes the `longhorn` (replicated) and `bulk` (media)
+StorageClasses; WS-APPS/WS-VM/WS-OBS reference them from ServiceDefinitions. Do not place bulk media
+on the replicated tier or app DBs on the bulk tier.
+
+## TODO (later phases)
+
+- **OQ-2 (human):** decide the bulk-tier backing (NAS/NFS vs dedicated disk). Blocks `bulk` finalize.
+- **Phase 2 (WS-STORAGE):** dedicated Longhorn data disk path (docs/02); prove a PVC survives
+  pod destroy/rebuild (R-STATE-01, Phase-2 exit gate).
+- **Phase 4 (WS-STORAGE):** wire off-cluster backup target with Velero (R-STATE-03).
@@ -0,0 +1,36 @@
+---
+# Longhorn — distributed replicated block storage (ADR-0003). Phase 0 STUB.
+apiVersion: helm.toolkit.fluxcd.io/v2
+kind: HelmRelease
+metadata:
+  name: longhorn
+  namespace: longhorn-system
+spec:
+  interval: 30m
+  chart:
+    spec:
+      chart: longhorn
+      version: ">=1.7.0 <1.8.0"   # TODO(WS-STORAGE): pin at bring-up; Renovate maintains
+      sourceRef:
+        kind: HelmRepository
+        name: longhorn
+        namespace: longhorn-system
+  install:
+    createNamespace: false
+    remediation:
+      retries: 3
+  upgrade:
+    remediation:
+      retries: 3
+  values:
+    # We define StorageClasses ourselves (storageclasses.yaml) so the default 3-replica SC and the
+    # bulk tier are explicit and GitOps-managed. Disable the chart's built-in default SC.
+    persistence:
+      defaultClass: false
+      # ${LONGHORN_DEFAULT_REPLICA_COUNT} resolved from cluster-vars (R-ENV-02).
+      defaultClassReplicaCount: ${LONGHORN_DEFAULT_REPLICA_COUNT}
+    defaultSettings:
+      # TODO(WS-STORAGE, Phase 2): set defaultDataPath to the dedicated Longhorn data disk
+      #   (docs/02 — a dedicated data disk is presented to Longhorn on each node).
+      defaultDataPath: "/var/lib/longhorn"
+    # TODO(WS-STORAGE, Phase 4): configure off-cluster backup target here (see velero/ + ADR-0003).
@@ -0,0 +1,9 @@
+---
+apiVersion: source.toolkit.fluxcd.io/v1
+kind: HelmRepository
+metadata:
+  name: longhorn
+  namespace: longhorn-system
+spec:
+  interval: 1h
+  url: https://charts.longhorn.io
@@ -0,0 +1,8 @@
+---
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+resources:
+  - namespace.yaml
+  - helmrepository.yaml
+  - helmrelease.yaml
+  - storageclasses.yaml
@@ -0,0 +1,5 @@
+---
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: longhorn-system
@@ -0,0 +1,34 @@
+---
+# Default replicated StorageClass — 3 replicas (ADR-0003). The durable home for app/config state
+# and KubeVirt VM disks. Replica count is an overlay knob (R-ENV-02).
+apiVersion: storage.k8s.io/v1
+kind: StorageClass
+metadata:
+  name: longhorn
+  annotations:
+    storageclass.kubernetes.io/is-default-class: "true"
+provisioner: driver.longhorn.io
+allowVolumeExpansion: true
+reclaimPolicy: Delete
+volumeBindingMode: Immediate
+parameters:
+  numberOfReplicas: "${LONGHORN_DEFAULT_REPLICA_COUNT}"   # from cluster-vars (default 3)
+  staleReplicaTimeout: "30"
+  fsType: "ext4"
+---
+# Bulk media tier — large, NON-replicated data (Plex library, download staging). ADR-0003 / docs/04.
+# NOTE: backing store (NAS/NFS vs dedicated large disk) is OQ-2, unresolved — this is a STUB.
+# Plex's metadata DB stays on the 3-replica `longhorn` class regardless (ADR-0003).
+apiVersion: storage.k8s.io/v1
+kind: StorageClass
+metadata:
+  name: bulk
+provisioner: driver.longhorn.io      # TODO(WS-STORAGE): may become an NFS provisioner per OQ-2
+allowVolumeExpansion: true
+reclaimPolicy: Retain
+volumeBindingMode: Immediate
+parameters:
+  numberOfReplicas: "1"              # non-replicated bulk tier (capacity, not durability)
+  staleReplicaTimeout: "30"
+  fsType: "ext4"
+# TODO(WS-STORAGE): finalize once OQ-2 (bulk backing) is answered by the human operator.
@@ -0,0 +1,7 @@
+# Longhorn Helm values — PLACEHOLDER (Phase 0). Authoritative values inline in helmrelease.yaml.
+#
+# persistence.defaultClass: false                 # we own StorageClasses (storageclasses.yaml)
+# persistence.defaultClassReplicaCount: ${LONGHORN_DEFAULT_REPLICA_COUNT}   # overlay knob
+# defaultSettings.defaultDataPath: <data disk>    # TODO(WS-STORAGE): dedicated Longhorn disk (docs/02)
+# defaultSettings.backupTarget: <off-cluster>     # TODO(WS-STORAGE, Phase 4): DR target (ADR-0003)
+# Longhorn UI exposure gated behind oauth2-proxy forward-auth (ADR-0014).