feat(env): tokenize hardcoded dev LAN addresses into cluster-vars (R-ENV-02)

R-ENV-02 promises dev and prod differ ONLY by scoped cluster-vars overrides. In fact
dev LAN addresses were hardcoded into base manifests, so clusters/prod would have come
up ANNOUNCING DEV ADDRESSES (192.168.1.x) on the prod LAN (192.168.2.x).

New cluster-vars knobs (base default = dev literal, per the file's existing convention):
  K3S_API_HOST          platform/cilium/helmrelease.yaml (+ the values.yaml mirror)
  CILIUM_LB_POOL_START  platform-config/cilium/l2-ip-pool.yaml
  CILIUM_LB_POOL_STOP   "
  UNIFI_L4_VIP          apps/vms/unifi/50-service-l4.yaml
  CRAFTY_L4_VIP         platform/crafty/service-l4.yaml
  S3_BACKUP_ENDPOINT    platform/keycloak/postgres-cluster.yaml, apps/wave-0/{nextcloud,
                        semaphore}-db.yaml, and platform/velero/helmrelease.yaml

Also fixes GATEWAY_VIP's base default, which was still the RETIRED libvirt address
10.73.0.240, and adds the GATEWAY_VIP patch that clusters/prod was missing entirely.

clusters/base/apps-vms.yaml gains postBuild.substituteFrom (it was the one consuming
Kustomization without it, so a ${TOKEN} there would have shipped as a literal string).
The envsubst contract is documented there: ${VAR} substitutes and escapes as $${VAR};
$VAR and $(cmd) are left alone; ${ARR[0]} hard-errors. The three UOS_URL expansions in
the unifi cloud-init are escaped accordingly.

PROD ADDRESS PLAN (operator, 2026-08-31):
  nodes .10/.11/.12 · control-plane VIP .9 (Ansible-side) · GATEWAY_VIP .20
  Cilium LB pool .20-.30

CONTAINMENT INVARIANT, now documented at the pool and in the prod overlay: GATEWAY_VIP
MUST equal CILIUM_LB_POOL_START. The shared Gateway pins no address, so Cilium LB-IPAM
gives it the first free address of a matching pool block. An initial prod proposal put
.20 outside a .21-.30 pool; the Gateway would have come up on .21 while split-horizon
coredns-custom kept answering *.home.keithjackson.dev with .20 — an address nothing
announces — blackholing in-cluster OIDC hairpin traffic while reporting healthy. The
pool was widened to .20-.30. The control-plane VIP (.9) stays outside the pool so
kube-vip and LB-IPAM can never contend.

Values prod still cannot know stay INVALID `TBD-PROD-*` placeholders on purpose: base
defaults are dev values, so an omitted patch means prod silently inherits a dev address
— far worse than a loud failed apply.

DEV IS BYTE-IDENTICAL. Verified by kustomize build over 13 paths before/after, then
flux envsubst with the dev cluster-vars values applied to both sides: zero drift. The
only deltas are the intended additive keys in the overlay ConfigMap itself. No
unresolved ${TOKEN} survives. render-golden green (10 goldens); yamllint clean.

Serves: R-ENV-02. Task: T-7.1 (prerequisite). Gate: MERGE GATE: PASS.

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>

platform-config/cilium/l2-announcement-policy.yaml

@@ -1,6 +1,8 @@
 ---
-# CiliumL2AnnouncementPolicy — ARP-announce LoadBalancer VIPs on the node LAN so hosts on
-# 192.168.1.0/24 can reach Gateway listeners at the pool IP (l2announcements.enabled=true in the
+# CiliumL2AnnouncementPolicy — ARP-announce LoadBalancer VIPs on the node LAN so LAN hosts (dev
+# 192.168.1.0/24, prod 192.168.2.0/24) can reach Gateway listeners at the pool IP. The RANGE itself
+# is env-scoped in l2-ip-pool.yaml via CILIUM_LB_POOL_START/STOP; this policy is env-agnostic and
+# needs no cluster-vars knob (l2announcements.enabled=true in the
 # Cilium HelmRelease turns on the controller; this policy scopes WHAT/WHERE it announces).
 # Announces on the primary ethernet interface. On Proxmox VMs the NIC is typically ens18/eth0;
 # `^e(n|th)` matches ens*/enp*/eth* so the exact name need not be pinned. VERIFY-AT-BRINGUP: if

platform-config/cilium/l2-ip-pool.yaml

@@ -1,16 +1,33 @@
 ---
 # CiliumLoadBalancerIPPool — reserved VIP range for LoadBalancer Services. Gateway API listeners
-# (gatewayClassName: cilium) get their address from here. Range matches the tofu reservation
-# (cilium_l2_vip_range 192.168.1.53-.60) on the Proxmox LAN 192.168.1.0/24. These addresses sit
-# OUTSIDE the node IPs (.50/.51/.52) and any DHCP scope, so nothing else claims them.
+# (gatewayClassName: cilium) get their address from here. The range must match the environment's tofu
+# reservation (cilium_l2_vip_range) and sit OUTSIDE the node IPs and any DHCP scope, so nothing else
+# claims them.
 #
-# NOTE (dev): the range is hardcoded to the dev LAN reservation. A prod overlay must supply the
-# prod LAN range (parameterize via cluster-vars when prod hardware is built). See DECISIONS-LOG.
+# R-ENV-02: the range was HARDCODED to the dev LAN (192.168.1.53-.60 on the Proxmox LAN 192.168.1.0/24,
+# nodes .50/.51/.52) until 2026-08-31; it is now ${CILIUM_LB_POOL_START}..${CILIUM_LB_POOL_STOP} from
+# cluster-vars, substituted by the `platform-config` Flux Kustomization.
+#
+# CONTAINMENT INVARIANT — ${GATEWAY_VIP} MUST be inside this block, and in practice EQUAL to
+# ${CILIUM_LB_POOL_START}. The `shared` Gateway (platform/gateway/gateway.yaml) pins NOTHING: it has
+# no `lbipam.cilium.io/ips` annotation and no spec.addresses (unlike platform/crafty/service-l4.yaml
+# and apps/vms/unifi/50-service-l4.yaml, which DO pin). Cilium's Gateway controller creates a
+# `cilium-gateway-shared` LoadBalancer Service and LB-IPAM assigns it the FIRST FREE address of a
+# matching pool block — so the Gateway lands on POOL_START, and dev's GATEWAY_VIP (.53) IS dev's
+# POOL_START (.53-.60). A GATEWAY_VIP outside every pool is NOT allocatable: the Gateway would come
+# up on POOL_START anyway while split-horizon coredns-custom keeps answering *.home.keithjackson.dev
+# with the unannounced GATEWAY_VIP, blackholing in-cluster hairpin traffic while looking healthy.
+#
+# RESOLVED (operator, 2026-08-31): the invariant holds in BOTH environments. An earlier prod
+# proposal put GATEWAY_VIP .20 outside a .21-.30 pool; the operator widened the prod pool to
+# 192.168.2.20-.30 so GATEWAY_VIP (.20) IS prod's POOL_START, exactly as dev's .53 is dev's.
+# Prod's kube-vip CONTROL-PLANE VIP (192.168.2.9) sits deliberately BELOW the pool so kube-vip
+# and LB-IPAM can never contend for an address.
 apiVersion: cilium.io/v2alpha1
 kind: CiliumLoadBalancerIPPool
 metadata:
   name: default-pool
 spec:
   blocks:
-    - start: "192.168.1.53"
-      stop: "192.168.1.60"
+    - start: "${CILIUM_LB_POOL_START}"
+      stop: "${CILIUM_LB_POOL_STOP}"