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]>

platform/monitoring/README.md

@@ -0,0 +1,31 @@
+# platform/monitoring
+
+**Observability stack** — kube-prometheus-stack (Prometheus + Alertmanager + Grafana) + **Loki** +
+**Grafana Alloy**.
+
+- **Spec:** [docs/10 — Observability & Alerting](../../../home-network-k3s/docs/10-observability-and-alerting.md)
+  (named in [docs/01](../../../home-network-k3s/docs/01-architecture-overview.md); no dedicated ADR)
+- **Serves:** R-OBS-01..04
+- **Owner:** WS-OBS
+
+## What this stub is
+
+Three Flux `HelmRelease`s (kube-prometheus-stack, loki, alloy) with placeholder values. Retention and
+PVC sizes are overlay knobs (`${MONITORING_*}`, R-ENV-02): short/small in dev, long/large in prod.
+Persistent data uses the replicated `longhorn` StorageClass.
+
+## Contract (observability)
+
+The "observability contract" (`roadmap/workstreams.md`): how a service declares metrics/SLIs/alerts
+and gets dashboards. ServiceMonitors/dashboards are rendered from ServiceDefinitions by WS-APPS/WS-VM
+against this stack. Grafana is part of the C2 UI composition (docs/12), behind Keycloak SSO
+(ADR-0014).
+
+## TODO (later phases)
+
+- **Phase 4 (WS-OBS):** Alertmanager → Gmail SMTP receiver (creds SOPS-encrypted, name only);
+  Loki retention via compactor (`retention_enabled: true` — a period alone does nothing); Alloy log
+  scrape config → Loki; platform-health alerts. **Reconciliation errors + drift are alerting
+  conditions (R-OBS-04).**
+- **Exit gate (Phase 4):** an injected fault emails an alert; dashboards render (R-OBS-01/02/03/04).
+- **Grafana OIDC** client via Keycloak (WS-SEC/WS-C2).

platform/monitoring/alloy.yaml

@@ -0,0 +1,25 @@
+---
+# Grafana Alloy — telemetry collector / log shipping to Loki (docs/10). Phase 0 STUB.
+apiVersion: helm.toolkit.fluxcd.io/v2
+kind: HelmRelease
+metadata:
+  name: alloy
+  namespace: monitoring
+spec:
+  interval: 30m
+  chart:
+    spec:
+      chart: alloy
+      version: ">=0.10.0 <1.0.0"   # TODO(WS-OBS): pin at bring-up; Renovate maintains
+      sourceRef:
+        kind: HelmRepository
+        name: grafana
+        namespace: monitoring
+  install:
+    remediation:
+      retries: 3
+  upgrade:
+    remediation:
+      retries: 3
+  values: {}
+    # TODO(WS-OBS, Phase 4): Alloy config to scrape pod/node logs -> Loki; K8s events; metrics relay.

platform/monitoring/helmrepositories.yaml

@@ -0,0 +1,18 @@
+---
+apiVersion: source.toolkit.fluxcd.io/v1
+kind: HelmRepository
+metadata:
+  name: prometheus-community
+  namespace: monitoring
+spec:
+  interval: 1h
+  url: https://prometheus-community.github.io/helm-charts
+---
+apiVersion: source.toolkit.fluxcd.io/v1
+kind: HelmRepository
+metadata:
+  name: grafana
+  namespace: monitoring
+spec:
+  interval: 1h
+  url: https://grafana.github.io/helm-charts

platform/monitoring/kube-prometheus-stack.yaml

@@ -0,0 +1,44 @@
+---
+# kube-prometheus-stack — Prometheus + Alertmanager + Grafana (docs/10). Phase 0 STUB.
+# Retention/sizes are overlay knobs (R-ENV-02). Alertmanager emails via SMTP.
+apiVersion: helm.toolkit.fluxcd.io/v2
+kind: HelmRelease
+metadata:
+  name: kube-prometheus-stack
+  namespace: monitoring
+spec:
+  interval: 30m
+  chart:
+    spec:
+      chart: kube-prometheus-stack
+      version: ">=65.0.0 <66.0.0"   # TODO(WS-OBS): pin at bring-up; Renovate maintains
+      sourceRef:
+        kind: HelmRepository
+        name: prometheus-community
+        namespace: monitoring
+  install:
+    remediation:
+      retries: 3
+  upgrade:
+    remediation:
+      retries: 3
+  values:
+    prometheus:
+      prometheusSpec:
+        retention: ${MONITORING_PROMETHEUS_RETENTION}     # overlay knob (dev short / prod long)
+        storageSpec:
+          volumeClaimTemplate:
+            spec:
+              storageClassName: longhorn                  # replicated tier (ADR-0003)
+              resources:
+                requests:
+                  storage: ${MONITORING_PROMETHEUS_PVC_SIZE}
+    grafana:
+      # Grafana behind Keycloak SSO (native OIDC) — ADR-0014. C2 UI composition (docs/12).
+      # TODO(WS-SEC/WS-C2): OIDC client + admin password from SOPS secret (name only).
+      enabled: true
+    alertmanager:
+      alertmanagerSpec: {}
+      # TODO(WS-OBS, Phase 4): Alertmanager → Gmail SMTP receiver; SMTP creds SOPS-encrypted (name
+      #   only). Reconciliation errors + drift are alerting conditions (R-OBS-04). Prove: injected
+      #   fault emails an alert (Phase-4 exit gate).

platform/monitoring/kustomization.yaml

@@ -0,0 +1,9 @@
+---
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+resources:
+  - namespace.yaml
+  - helmrepositories.yaml
+  - kube-prometheus-stack.yaml
+  - loki.yaml
+  - alloy.yaml

platform/monitoring/loki.yaml

@@ -0,0 +1,33 @@
+---
+# Loki — log aggregation (docs/10). Phase 0 STUB. PVC size is an overlay knob (R-ENV-02).
+apiVersion: helm.toolkit.fluxcd.io/v2
+kind: HelmRelease
+metadata:
+  name: loki
+  namespace: monitoring
+spec:
+  interval: 30m
+  chart:
+    spec:
+      chart: loki
+      version: ">=6.0.0 <7.0.0"   # TODO(WS-OBS): pin at bring-up; Renovate maintains
+      sourceRef:
+        kind: HelmRepository
+        name: grafana
+        namespace: monitoring
+  install:
+    remediation:
+      retries: 3
+  upgrade:
+    remediation:
+      retries: 3
+  values:
+    # TODO(WS-OBS, Phase 4): single-binary vs scalable deployment mode; retention via compactor
+    #   (retention_enabled: true — a period alone does nothing); storage backing.
+    loki:
+      storage:
+        type: filesystem
+    singleBinary:
+      persistence:
+        storageClass: longhorn
+        size: ${MONITORING_LOKI_PVC_SIZE}

platform/monitoring/namespace.yaml

@@ -0,0 +1,5 @@
+---
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: monitoring