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

clusters/base/apps.yaml

@@ -0,0 +1,26 @@
+---
+# Flux Kustomization: APPLICATION workloads. Reconciles ./apps AFTER platform is healthy.
+# Phase 0 STUB. apps/ is owned by WS-APPS; this entrypoint is the GitOps contract that renders it.
+apiVersion: kustomize.toolkit.fluxcd.io/v1
+kind: Kustomization
+metadata:
+  name: apps
+  namespace: flux-system
+spec:
+  interval: 10m
+  retryInterval: 2m
+  timeout: 5m
+  prune: true
+  wait: true
+  # Ordering: platform (CNI, storage, TLS, DNS, gateway, identity) must be healthy first.
+  dependsOn:
+    - name: platform
+  sourceRef:
+    kind: GitRepository
+    name: flux-system
+  path: ./apps
+  postBuild:
+    substituteFrom:
+      - kind: ConfigMap
+        name: cluster-vars
+  # TODO(WS-SEC, Phase 1): enable SOPS decryption (ADR-0007) — reference age secret by name only.

clusters/base/cluster-vars.yaml

@@ -0,0 +1,41 @@
+---
+# cluster-vars — the overlay knob surface (R-ENV-02).
+#
+# This ConfigMap holds BASE DEFAULTS. Flux `postBuild.substituteFrom` injects these into every
+# `${TOKEN}` in platform/ and apps/ manifests at reconcile time. dev/ and prod/ overlays STRATEGIC-
+# MERGE PATCH this single ConfigMap — that patch is the *entire* difference between environments.
+#
+# Add a knob here (with a base default) before referencing `${KNOB}` in a component manifest, then
+# give each overlay its env-scoped value. Never fork a base manifest to differ per environment.
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: cluster-vars
+  namespace: flux-system
+data:
+  # --- identity of the environment ---
+  cluster_env: "base"                       # dev | prod  (overlays set this)
+
+  # --- DNS / TLS ---
+  base_domain: "home.keithjackson.dev"      # same in both envs (split-horizon per docs/09)
+  acme_cluster_issuer: "letsencrypt-staging" # dev: staging | prod: letsencrypt-prod (ADR-0006)
+
+  # --- storage (ADR-0003) ---
+  longhorn_default_replica_count: "3"       # default StorageClass replica count (3 on 3 nodes)
+
+  # --- observability sizing (docs/10) ---
+  monitoring_prometheus_retention: "7d"     # dev short | prod long
+  monitoring_prometheus_pvc_size: "10Gi"
+  monitoring_loki_pvc_size: "10Gi"
+
+  # --- identity / auth (ADR-0014) ---
+  keycloak_replicas: "1"                     # dev 1 | prod 2 (HA)
+  oauth2_proxy_replicas: "1"                 # dev 1 | prod 2 (HA)
+
+  # --- backup / DR (ADR-0003, R-STATE-03) ---
+  velero_backup_schedule: "0 3 * * *"        # cron; overlays may differ
+  velero_retention: "168h"                   # dev short | prod long
+
+  # --- placement ---
+  platform_node_selector_key: "kubernetes.io/os"   # base no-op selector; prod may pin roles
+  platform_node_selector_value: "linux"

clusters/base/flux-system.yaml

@@ -0,0 +1,25 @@
+---
+# GitRepository — the single source of truth Flux reconciles from (R-GITOPS-01).
+# Phase 0 STUB: not applied until Flux is bootstrapped in Phase 1 (WS-INFRA).
+#
+# Bootstrapping sequence (spec docs/05 "Source-of-truth", CONTRIBUTING.md):
+#   1. Initially points at the BOOTSTRAP SOURCE (this local repo / out-of-band).
+#   2. Gitea is onboarded early (roadmap Phase 6).
+#   3. TODO(WS-GITOPS, Phase 6): repoint spec.url -> https://gitea.home.keithjackson.dev/<org>/home-network-k3s-impl
+#      and keep an off-cluster mirror so a source-of-truth outlives the cluster.
+apiVersion: source.toolkit.fluxcd.io/v1
+kind: GitRepository
+metadata:
+  name: flux-system
+  namespace: flux-system
+spec:
+  interval: 1m
+  # TODO(WS-INFRA/WS-GITOPS): set to the bootstrap source URL at Phase-1 bootstrap.
+  url: https://REPLACE-ME.invalid/home-network-k3s-impl.git
+  ref:
+    # Reconcile the tracked branch. Overlay may patch this if dev/prod track different branches;
+    # the default model tracks a single branch and differentiates by clusters/<env> path.
+    branch: main
+  # TODO(WS-SEC, Phase 1): reference the SOPS/age or deploy-key secret BY NAME only (no plaintext).
+  # secretRef:
+  #   name: flux-system   # created by `flux bootstrap`

clusters/base/kustomization.yaml

@@ -0,0 +1,10 @@
+---
+# Base Flux entrypoint set. Shared by BOTH environment overlays (clusters/dev, clusters/prod).
+# Overlays reference this base and patch ONLY the cluster-vars ConfigMap (R-ENV-02).
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+resources:
+  - flux-system.yaml     # GitRepository (reconciliation source)
+  - platform.yaml        # Flux Kustomization -> ./platform
+  - apps.yaml            # Flux Kustomization -> ./apps (dependsOn platform)
+  - cluster-vars.yaml    # overlay knob surface (base defaults)

clusters/base/platform.yaml

@@ -0,0 +1,32 @@
+---
+# Flux Kustomization: PLATFORM services (cluster-wide). Reconciles ./platform.
+# Phase 0 STUB. Realizes R-GITOPS-01/03 (pull-based reconcile + drift correction) and
+# R-ENV-02 (env differences supplied ONLY via substituteFrom cluster-vars).
+apiVersion: kustomize.toolkit.fluxcd.io/v1
+kind: Kustomization
+metadata:
+  name: platform
+  namespace: flux-system
+spec:
+  interval: 10m
+  retryInterval: 2m
+  timeout: 5m
+  prune: true          # drift correction: delete resources removed from git (R-GITOPS-03)
+  wait: true           # block `apps` until platform is healthy
+  sourceRef:
+    kind: GitRepository
+    name: flux-system
+  path: ./platform
+  # R-ENV-02: the ONLY place environment differences enter platform manifests.
+  # dev/prod overlays patch the cluster-vars ConfigMap; the base manifests are never forked.
+  postBuild:
+    substituteFrom:
+      - kind: ConfigMap
+        name: cluster-vars
+  # TODO(WS-SEC, Phase 1): enable SOPS decryption once the age key exists (ADR-0007).
+  #   decryption:
+  #     provider: sops
+  #     secretRef:
+  #       name: sops-age
+  # TODO(PM): the top-level ./platform/kustomization.yaml must include platform/kyverno/
+  #           (owned by the policy engineer, WS-TEST). See platform/README.md integration TODO.