fix(pihole): make the split-horizon answer cacheable, or one blip latches the WAN IP for 5 minutes

Operator reported DNS flapping between the cluster ingress and the router's public IP. PiHole is not at fault -- both replicas answer 192.168.2.20 consistently (6/6 via the VIP, 8/8 from a client). The bug is an asymmetry in CACHEABILITY that we created. Measured: pihole 192.168.2.23 -> 192.168.2.20 TTL=0 public 1.1.1.1 -> wan.home.keithjackson.dev TTL=300 router 192.168.2.1 -> wan.... TTL=153 -> 148 -> 143 (decrementing = caching) dnsmasq answers `address=` entries with TTL 0 unless told otherwise. The router forwards LAN queries to PiHole and caches the result, so the CORRECT answer is uncacheable -- re-queried on every lookup, maximum exposure to any gap -- while the WRONG answer caches for 300s. The instant the router falls back to upstream (standard forwarder behaviour when the target does not answer) it latches the WAN address for the whole LAN for five minutes, then expires, re-queries PiHole, gets TTL 0, and is immediately re-exposed. So ONE sub-second PiHole gap -- pod restart, L2 lease move, ARP flap, kured reboot -- becomes FIVE MINUTES of the house resolving to the WAN IP. That asymmetry, not the gap, is why it reads as "flapping". Fix: local-ttl=60 prepended to FTLCONF_misc_dnsmasq_lines. dnsmasq applies local-ttl to replies made from configuration, so one directive covers all five address= names. 60s rides out a pod restart and a lease re-election while a real VIP change still propagates inside a minute; these VIPs are pinned and static. apps/wave-0/pihole.yaml regenerated with the canonical render command (--all catalog -o apps --wave-layout --no-image-automation, NOT --emit-waves); exactly two files changed and the rendered diff is the single local-ttl prefix. UNAPPLIED. Does NOT remove the trigger: .23 still has two independently-elected L2 leases (as do crafty .22 and unifi .21), which the operator has parked. If the TTL is still 0 after merge, suspect FTL silently rejecting the passthrough line -- see the handoff. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Merge pull request 'fix(conformance): one regex made the merge gate take 28 minutes instead of 2' (#76 ) from fix/ha-check-catastrophic-regex into main
2026-10-18 02:56:49 -05:00 · 2026-10-18 07:51:51 +00:00 · 2026-10-18 07:40:20 +00:00 · 2026-10-18 02:38:23 -05:00 · 2026-10-18 01:43:43 -05:00 · 2026-10-18 06:28:30 +00:00
18 changed files with 1724 additions and 12 deletions
@@ -73,7 +73,7 @@ spec:
        - name: FTLCONF_dns_rateLimit_count
          value: '0'
        - name: FTLCONF_misc_dnsmasq_lines
-          value: address=/${BASE_DOMAIN}/${GATEWAY_VIP};address=/unifi.${BASE_DOMAIN}/${UNIFI_L4_VIP};address=/crafty-mc.${BASE_DOMAIN}/${CRAFTY_L4_VIP};address=/pihole-dns.${BASE_DOMAIN}/${PIHOLE_DNS_VIP};address=/plex-vip.${BASE_DOMAIN}/${PLEX_L4_VIP}
+          value: local-ttl=60;address=/${BASE_DOMAIN}/${GATEWAY_VIP};address=/unifi.${BASE_DOMAIN}/${UNIFI_L4_VIP};address=/crafty-mc.${BASE_DOMAIN}/${CRAFTY_L4_VIP};address=/pihole-dns.${BASE_DOMAIN}/${PIHOLE_DNS_VIP};address=/plex-vip.${BASE_DOMAIN}/${PLEX_L4_VIP}
        - name: FTLCONF_webserver_api_password
          valueFrom:
            secretKeyRef:
@@ -143,8 +143,39 @@ env:
  # resolved to the Gateway VIP and a connect to :32400 there returned http=000. That is a silent
  # failure: the Plex web UI on plex.${BASE_DOMAIN} keeps working through the Gateway on 443 while
  # every client that takes the ADVERTISED connection cannot reach the server at all.
+  #
+  # ── local-ttl=60 — THE SPLIT-HORIZON ANSWER MUST BE CACHEABLE ────────────────────────────────
+  # MEASURED 2026-10-18, diagnosing "DNS flapping between the cluster ingress and the public IP":
+  #
+  #   dig home.keithjackson.dev @192.168.2.23 (pihole)  -> 192.168.2.20                TTL=0
+  #   dig home.keithjackson.dev @1.1.1.1      (public)  -> wan.home.keithjackson.dev   TTL=300
+  #   dig home.keithjackson.dev @192.168.2.1  (router)  -> wan....  TTL=153 -> 148 -> 143
+  #
+  # dnsmasq answers `address=` entries with **TTL 0** unless told otherwise, and that is the whole
+  # bug. The SOHO router forwards LAN queries to PiHole and CACHES the result, so:
+  #   * the CORRECT answer is UNCACHEABLE (TTL 0) -- the router must re-query PiHole on every
+  #     single lookup, which is maximum exposure to any momentary gap; while
+  #   * the WRONG answer is CACHEABLE FOR 5 MINUTES -- the instant the router falls back to its
+  #     upstream (standard forwarder behaviour when the forward target does not answer) it latches
+  #     the public WAN address and serves it to EVERY LAN CLIENT for the public record's 300s TTL.
+  # The decrementing TTL on the router's reply above is the proof it caches rather than forwarding
+  # live. So ONE sub-second PiHole gap -- a pod restart, an L2 announcement lease moving, an ARP
+  # flap, a kured node reboot -- becomes FIVE MINUTES of the whole house resolving to the WAN IP.
+  # That asymmetry, not the gap, is why this is visible as "flapping" rather than a blip.
+  #
+  # 60s is a deliberate floor, not a tuning knob: long enough to ride out a pod restart and a lease
+  # re-election (both seconds), short enough that a genuine VIP change still propagates inside a
+  # minute. These VIPs are pinned by name (`lbipam.cilium.io/ips`) and effectively static, so the
+  # propagation cost is theoretical while the flap it prevents is measured. If flaps persist across
+  # LONGER outages, raising this toward the public record's 300 would cover them -- at the cost of
+  # the same delay on a real change. It does NOT help when PiHole is down longer than the TTL: the
+  # cache expires, the router falls back, and the public answer latches again. That is a real
+  # outage, and the fix for it is PiHole availability, not DNS caching.
+  #
+  # Applies to every `address=` reply below (dnsmasq: local-ttl governs replies made from
+  # configuration, /etc/hosts and DHCP leases), so one directive covers all five names.
  - name: FTLCONF_misc_dnsmasq_lines
-    value: "address=/${BASE_DOMAIN}/${GATEWAY_VIP};address=/unifi.${BASE_DOMAIN}/${UNIFI_L4_VIP};address=/crafty-mc.${BASE_DOMAIN}/${CRAFTY_L4_VIP};address=/pihole-dns.${BASE_DOMAIN}/${PIHOLE_DNS_VIP};address=/plex-vip.${BASE_DOMAIN}/${PLEX_L4_VIP}"
+    value: "local-ttl=60;address=/${BASE_DOMAIN}/${GATEWAY_VIP};address=/unifi.${BASE_DOMAIN}/${UNIFI_L4_VIP};address=/crafty-mc.${BASE_DOMAIN}/${CRAFTY_L4_VIP};address=/pihole-dns.${BASE_DOMAIN}/${PIHOLE_DNS_VIP};address=/plex-vip.${BASE_DOMAIN}/${PLEX_L4_VIP}"
  # THE ADMIN PASSWORD, previously the ONE operator-set value declared nowhere. Sourced from
  # apps/wave-0/pihole-bootstrap-secret.sops.yaml (SOPS/age, same wave => same reconcile), which
  # carries the full rationale and the measurement that found it.
@@ -445,8 +445,21 @@ join = re.search(r"--server https://\{\{\s*k3s_api_host", K3S_TEXT)
 check(join is not None,
      "roles/k3s_server does not join secondaries with `--server https://{{ k3s_api_host }}` "
      "— without a join target the servers are separate single-node clusters")
-join_when = re.search(r"--server https://.*?\n(?:.*\n){0,10}?\s*when:\s*k3s_server_mode\s*==\s*'secondary'",
-                      K3S_TEXT, re.S)
+# LINE-BOUNDED ON PURPOSE -- DO NOT "SIMPLIFY" BACK TO `.*` + re.S.
+# This was `--server https://.*?\n(?:.*\n){0,10}?\s*when:...` with re.S, which made every `.`
+# match newlines too. That is nested unbounded repetition (a `{0,10}` of a quantifier that can each
+# swallow the whole document), so a FAILED or late match backtracks exponentially. It cost
+# **19m54s of CPU in CI** (measured 2026-10-18 via `docker top` on the live job container) and made
+# the whole merge gate take ~28 minutes instead of ~2 on any change touching `infra/**` -- because
+# `ci/touched-requirements.sh` maps `infra/*` to R-ENV-01, which pulls in this whole-repo check.
+# It was latent for as long as the regex existed and only crossed the threshold when
+# roles/k3s_server grew by ~100 lines (the kubelet graceful-shutdown config, PR #71): K3S_TEXT is
+# every *.yml in that role concatenated, so the role growing is the input growing.
+# `[^\n]*` cannot cross a line, so the `{0,10}` is a genuine ten-line window with nothing to
+# backtrack into. Measured on the same input: 0.2 ms, same verdict (match found).
+join_when = re.search(
+    r"--server https://[^\n]*\n(?:[^\n]*\n){0,10}?[ \t]*when:[ \t]*k3s_server_mode[ \t]*==[ \t]*'secondary'",
+    K3S_TEXT)
 check(join_when is not None,
      "the join install task is not gated on k3s_server_mode == 'secondary' — the founder "
      "would also try to join itself")
@@ -0,0 +1,106 @@
+---
+date: 2026-10-17
+branch: feat/graceful-cluster-shutdown
+title: "Graceful node shutdown was never configured, and scaling a StatefulSet deleted its PVC"
+---
+
+## What changed
+
+All three nodes had to be powered off to move them onto a UPS. There was **no procedure for it**:
+`infra/cluster.sh stop` is `virsh`-based and only ever applied to the decommissioned dev cluster, so
+the whole sequence was improvised live. Two defects came out of doing it.
+
+**1. Kubelet graceful node shutdown was unconfigured on every prod node.** No `shutdownGracePeriod`
+anywhere in `infra/ansible/`, so `shutdown -h` stopped k3s, containerd went with it, and every pod
+was SIGKILLed where it stood — 9 CloudNativePG instances mid-checkpoint, the UniFi VM, and 25
+attached Longhorn volumes. `roles/k3s_server` now writes `kubelet-arg` into
+`/etc/rancher/k3s/config.yaml` with `shutdown-grace-period=90s` and
+`shutdown-grace-period-critical-pods=20s`.
+
+The half that is easy to miss and silently defeats the other half: **graceful node shutdown is
+enforced by logind, not by the kubelet.** The kubelet holds an inhibitor *delay* lock and systemd
+waits at most `InhibitDelayMaxSec` — **default 5 seconds** — before proceeding regardless. A grace
+period above that cap is truncated with no error, so the feature looks configured and still
+hard-kills pods. The role now ships a `logind.conf.d` drop-in setting it to 120, and **asserts**
+`k3s_logind_inhibit_delay_max_sec >= k3s_kubelet_shutdown_grace_period` rather than documenting the
+relationship, because the failure is invisible.
+
+**2. Scaling a StatefulSet to 0 DELETED its PVC and Longhorn volume.** `monitoring/loki` carries
+`persistentVolumeClaimRetentionPolicy: {whenDeleted: Delete, whenScaled: Delete}`, so the quiesce's
+`scale --replicas=0` destroyed `storage-loki-0` outright. Loki stores with `type: filesystem`, so
+that PVC was the only copy of its log data. This is the defect in this change set that actually
+destroyed something, and it was mine.
+
+New `infra/maintenance/quiesce.sh` (`quiesce` | `resume` | `status`) encodes the sequence that
+worked, and **refuses to scale any StatefulSet whose `whenScaled` is `Delete`** — it leaves it
+running, accepts that its volume hard-detaches at poweroff, and prints which volumes to expect
+`degraded`. A rebuild is a vastly better outcome than a deletion. Workload discovery is computed
+from the live cluster (every Deployment/StatefulSet whose pods mount a PVC, Longhorn or TrueNAS NFS)
+rather than hardcoded, so a newly onboarded service is covered without anyone remembering to add it.
+
+`runbooks/cluster-maintenance-shutdown.md` (new, registered in `runbooks/kustomization.yaml`) is the
+operator page: shutdown order, the TrueNAS-after-nodes constraint, power-on order, the
+un-hibernate-Postgres step Flux will not do for you, and a "what looks broken but is fine" section
+separating the `4/19`-Kustomizations-Ready cascade, the degraded-and-rebuilding volume and the
+self-recovering `keycloak-operator` from the one thing that genuinely needs a human (a stuck
+`oauth2-proxy` replica).
+
+## What I verified
+
+* **Graceful shutdown was genuinely absent**, not merely undocumented: `grep -rn
+  'shutdownGracePeriod|graceful-node-shutdown'` over `infra/ansible/` returns nothing, and no
+  `logind` or `InhibitDelay` setting exists anywhere in the tree.
+* **The whole shutdown/restart cycle was executed end to end on prod 2026-10-17** and the cluster
+  came back: 3/3 nodes Ready with etcd `healthz` ok, 19/19 Flux Kustomizations Ready,
+  `platform-config`'s `lastAppliedRevision` equal to the GitRepository artifact revision, all 3
+  CNPG clusters `healthy` with primaries elected, the UniFi VM `Running`, PiHole resolving
+  (`home.keithjackson.dev` → `192.168.2.20` via `192.168.2.23`), and the Gateway serving
+  `200/200/401` for apex/gitea/plex.
+* **The PVC-deletion mechanism is confirmed, not inferred:** `kubectl get sts loki -o
+  jsonpath={.spec.persistentVolumeClaimRetentionPolicy}` returns
+  `{"whenDeleted":"Delete","whenScaled":"Delete"}`, the PVC was `NotFound` after the cycle, and the
+  Longhorn volume count had gone 25 → 24.
+* **The damage was repaired and verified:** `scale sts loki --replicas=1` (restoring the replica
+  count the chart declares) recreated `storage-loki-0` as a fresh 50Gi Bound PVC, `loki-0` reached
+  `2/2 Running`, and the volume count returned to 25.
+* **The guard works against the live cluster**, tested both ways: `sts_deletes_pvc_on_scale
+  monitoring loki` returns true (would be skipped) and `pihole pihole` returns false (safe to
+  scale).
+* **The script's read-only paths run clean on prod:** `status` reports correctly, and the discovery
+  function returns the 13 workloads currently holding a PVC.
+* `bash -n` clean; the two edited Ansible YAML files parse.
+
+## What I did NOT verify
+
+* **The kubelet change has NEVER BEEN APPLIED OR TESTED.** This is the significant gap. I did not
+  run the role, did not restart k3s, and have **not** observed a node actually drain on
+  `shutdown -h`. Everything about it is reasoning from kubelet/systemd semantics plus the measured
+  absence of the setting. Applying it needs a **rolling** k3s restart (`serial: 1` — kube-vip keeps
+  the API up, etcd holds at 2/3), which is an operator action (CLAUDE.md §5). **Verify by draining
+  one node for real:** apply, then `shutdown -h now` on a single node and watch whether pods
+  terminate gracefully instead of vanishing.
+* **Whether 90s/20s are the right numbers.** Chosen to comfortably cover a Postgres fast shutdown
+  and a Longhorn flush; not measured against either. The budget is spent on every reboot, so if a
+  node takes noticeably longer to go down, this is why.
+* **Whether k3s accepts `kubelet-arg` in `config.yaml` as written.** The file already carries
+  `kube-apiserver-arg` as a list and `kubelet-arg` is the documented sibling, but I did not render
+  or apply it, so a typo would surface only at k3s restart — and a bad `config.yaml` is exactly the
+  kind of thing that makes k3s fail to come up. **Review this one before applying.**
+* **The `assert` task's `regex_replace` on the grace period** assumes a plain `90s`-style value; a
+  value expressed as `1m30s` would parse to the nonsense integer `130`. Fine for the committed
+  defaults, wrong if someone writes a compound duration.
+* **`resume`'s Flux-reconcile wait has never run**, and neither has `quiesce` as a script — the
+  2026-10-17 cycle was done with the equivalent commands by hand, so the script encodes a sequence
+  that worked but has not itself been executed end to end. Only `status` and the discovery and guard
+  functions have run.
+* **Loki's lost log window is gone for good.** Up to 72h of logs (its `retention_period`), destroyed
+  by my scale-down. Nothing recovers it; Velero's schedules cover the namespace but the PVC was
+  deleted, not corrupted, and I did not attempt a restore because the data self-expires anyway.
+* **No other `whenScaled: Delete` StatefulSet was audited.** The guard now catches them generically,
+  but I did not enumerate which other workloads carry the policy, so I cannot say loki was the only
+  one at risk. The runbook gives the one-liner to list them.
+* **TrueNAS and the router are entirely outside this change.** TrueNAS is not in the Ansible
+  inventory and refuses SSH, so its shutdown stays a web-UI step with no automation and no check.
+* **No runtime conformance.** `vars.CLUSTER_AVAILABLE` is still unset, so CI proves the L0/L1
+  offline subset only.
+* I did not re-measure branch protection or runner state (CLAUDE.md §2b).
@@ -0,0 +1,311 @@
+---
+date: 2026-10-17
+branch: feat/keycloak-passkeys
+title: Passkeys declared for the homelab realm — and the realm import will not apply them
+---
+
+## What changed
+
+`platform/keycloak/keycloak-realm-import.yaml` now declares passkey (WebAuthn Passwordless)
+login for the `homelab` realm, in two parts:
+
+1. **The WebAuthn Passwordless policy.** Ten `webAuthnPolicyPasswordless*` fields on the realm:
+   RP ID `${BASE_DOMAIN}`, RP entity name `Homelab SSO`, signature algorithms `[ES256, RS256]`,
+   `requireResidentKey: "Yes"`, `userVerificationRequirement: required`,
+   `authenticatorAttachment: "not specified"`, `attestationConveyancePreference: none`,
+   `acceptableAaguids: []`, `createTimeout: 300`, `avoidSameAuthenticatorRegister: true`.
+   Deliberately the **passwordless** family only; the two-factor `webAuthnPolicy*` family is left
+   at Keycloak's defaults because nothing in this realm uses `webauthn-authenticator`.
+
+2. **The browser flow.** `browser-mfa` keeps its alias and stays bound as `browserFlow`; its
+   interior is restructured so a passkey is an **ALTERNATIVE** beside the password form:
+
+   ```
+   browser-mfa                            (top level, unchanged)
+     browser-mfa-forms                    ALTERNATIVE
+       auth-username-form                   REQUIRED      <- was auth-username-password-form
+       browser-mfa-passkey-or-password      REQUIRED      <- NEW sub-flow
+         webauthn-authenticator-passwordless  ALTERNATIVE <- NEW: the passkey
+         browser-mfa-password-and-otp         ALTERNATIVE <- NEW sub-flow
+           auth-password-form                   REQUIRED  <- was half of the combined form
+           browser-mfa-conditional-otp          CONDITIONAL (unchanged, relocated intact)
+   ```
+
+The design decisions, with their reasoning, are written into the manifest comments in this repo's
+usual density. The ones that matter:
+
+* **Additive, not replacing. Enrolment optional, not forced.** This IdP gates Grafana, Gitea,
+  Nextcloud, Headlamp, Semaphore, PiHole, Crafty, the \*arr stack *and* `kubectl` via the
+  `kubernetes` OIDC client. A mandatory passkey flow that misfires is a total lock-out from the
+  platform and the cluster API at once, leaving only the Keycloak bootstrap admin and the
+  break-glass cert kubeconfig. The gain from forcing it (one human stops typing a password) does
+  not price that risk.
+* **No `requiredActions` block was added, on purpose.** Declaring one would have been the obvious
+  way to add `webauthn-register-passwordless`, and it would have been actively dangerous — see
+  "What I verified".
+* **RP ID is `${BASE_DOMAIN}`, not `keycloak.${BASE_DOMAIN}`.** A passkey's RP ID is fixed at
+  enrolment and can never be re-keyed, so it must not be bound to a name that can move. This realm
+  already declares an `auth.${BASE_DOMAIN}` redirect URI, and this repo already owns a reconciler
+  built because a hostname move silently failed to reach the realm. Residual risk, unavoidable:
+  changing `BASE_DOMAIN` itself invalidates every enrolled passkey.
+* **A passkey login is not also asked for TOTP.** `browser-mfa-conditional-otp` hangs off the
+  password branch only. The justification is `userVerificationRequirement: required` — the
+  ceremony already proves possession plus a verified human, phishing-resistantly and origin-bound.
+  Stacking a replayable shared secret on top of that buys friction. The manifest names the exact
+  one-line edit to reverse this decision.
+* **Login becomes two screens** (username, then password) for every user, passkey or not, because
+  the server must know who is logging in before it can decide whether a passkey exists. Accepted
+  cost; it is the enabling change.
+* **Usernameless login deliberately not used**, although Keycloak 26.0.6 supports it — see "What I
+  verified" for the measured reason it would have made every login open on a passkey prompt.
+
+`platform/keycloak/README.md` gains a `## Passkeys` section: the decision table, the fact that
+this does not reach the live realm, the two operator paths that would apply it, and the four-step
+browser verification nobody has run.
+
+No secret, key, credential or AAGUID was minted or committed. No file under `clusters/**`,
+`conformance/**`, `ci/**`, `platform/kyverno/**`, `**/rbac.yaml` or `**/*.sops.yaml` was touched,
+so this should not trip `ci/approval-policy.sh`'s sensitive-path review requirement.
+
+## What I verified
+
+**The live realm import has already completed and will never re-run.** Measured on prod,
+2026-10-17:
+
+```
+$ kubectl --context k3s-prod -n keycloak get keycloakrealmimport homelab -o jsonpath='{.status}'
+{"conditions":[{"message":"","status":"True","type":"Done"},
+               {"message":"","status":"False","type":"Started"},
+               {"message":"","status":"False","type":"HasErrors"}]}
+```
+
+`Done=True` / `Started=False`, exactly the one-shot state `platform/keycloak/README.md` already
+documents for client secrets and client URLs. **So the change in this PR has zero effect on how
+anyone logs in today**, and the client-secret/client-URL reconciler does not and cannot close the
+gap: its hard endpoint allow-list makes `/authentication` unreachable by design, and realm-level
+policy fields are not client fields.
+
+**The CRD accepts every field I used.** Measured against the live CRD (not the upstream docs):
+`kubectl --context k3s-prod get crd keycloakrealmimports.k8s.keycloak.org` lists all twelve
+`webAuthnPolicyPasswordless*` properties with the types I wrote (`RequireResidentKey`,
+`RpEntityName`, `RpId`, `UserVerificationRequirement`, `AttestationConveyancePreference`,
+`AuthenticatorAttachment` as `string`; `SignatureAlgorithms`, `AcceptableAaguids`, `ExtraOrigins`
+as `array/string`; `CreateTimeout` as `integer`; `AvoidSameAuthenticatorRegister` as `boolean`),
+plus `authenticationFlows`, `authenticatorConfig` and `requiredActions`. The `spec.realm` schema
+has **no** `x-kubernetes-preserve-unknown-fields`, so a misspelled field would have been pruned
+silently rather than rejected — which is why this was checked rather than assumed.
+
+**Running Keycloak is 26.0.6.** `quay.io/keycloak/keycloak:26.0.6` on `keycloak-0`/`keycloak-1`,
+operator `quay.io/keycloak/keycloak-operator:26.0.6`. Every source claim below is read from the
+`26.0.6` tag, not from memory or from docs.
+
+**Every provider ID is quoted from upstream source, not guessed.**
+
+| String I used | Where it is defined at tag 26.0.6 |
+|---|---|
+| `webauthn-authenticator-passwordless` | `WebAuthnPasswordlessAuthenticatorFactory.PROVIDER_ID`, display "WebAuthn Passwordless Authenticator" |
+| `auth-username-form` | `UsernameFormFactory.PROVIDER_ID`, display "Username Form" |
+| `auth-password-form` | `PasswordFormFactory.PROVIDER_ID`, display "Password Form" |
+| `webauthn-register-passwordless` | `WebAuthnPasswordlessRegisterFactory.PROVIDER_ID` (referenced in comments only) |
+
+**`requiredActions` is REPLACE, not merge — measured, and it is why I did not declare one.**
+`model/storage-private/.../DefaultExportImportManager.java` lines 327-338:
+
+```java
+if (rep.getRequiredActions() != null) {
+    for (RequiredActionProviderRepresentation action : rep.getRequiredActions()) { ... }
+    DefaultRequiredActions.addDeleteAccountAction(newRealm);
+} else {
+    DefaultRequiredActions.addActions(newRealm);
+}
+```
+
+Declaring one required action therefore skips the entire default set. `RealmManager` is no
+backstop: `setupRequiredActions` is `if (realm.getRequiredActionProvidersStream().count() == 0)`,
+and the count is already non-zero by then (`RepresentationToModel.importRealm` runs at
+`RealmManager.java:585`, the backstop at `:612`). A realm built that way would have had the passkey
+action plus `delete_account` and nothing else — **no `CONFIGURE_TOTP`**, which would leave
+`auth-otp-form` demanding a TOTP that no platform-admin could ever enrol: a hard lock-out
+delivered by a change whose purpose was to *add* a login method.
+
+**And declaring it would have bought nothing.** `DefaultRequiredActions.addWebAuthnPasswordlessRegisterAction`
+registers `webauthn-register-passwordless` with `setEnabled(true)`, `setDefaultAction(false)`,
+priority 80, gated on `Profile.Feature.WEB_AUTHN` — which is `Type.DEFAULT` in
+`common/.../Profile.java:74`, i.e. on unless explicitly disabled. `enabled=true` /
+`defaultAction=false` *is* the additive-and-optional posture this change wants.
+
+**`authenticationFlows` has the opposite semantics, which is why declaring flows is safe.**
+`importAuthenticationFlows` adds the declared flows, then backfills each unbound binding
+(browser, registration, direct grant, reset credentials, client auth, first broker login, docker
+auth) from the built-in defaults individually (`DefaultExportImportManager.java` ~1320-1410).
+
+**The graceful degradation to password is measured from the flow engine, not assumed.** For a user
+with no passkey: `WebAuthnPasswordlessAuthenticator.requiresUser()` returns `false`, so
+`DefaultAuthenticationFlow.processSingleFlowExecutionModel` takes the `else` branch (`daf:456-462`),
+whose four conditions all hold — a user is set (from `auth-username-form`), `configuredFor` is
+false, `WebAuthnPasswordlessAuthenticatorFactory.isUserSetupAllowed()` is `false`, and
+`WebAuthnAuthenticator implements Authenticator, CredentialValidator<...>` — so it raises
+`CREDENTIAL_SETUP_REQUIRED`. The ALTERNATIVE loop (`daf:289-302`) catches exactly that, marks the
+execution `ATTEMPTED` and proceeds to the next alternative, with the upstream comment *"the user,
+since he has alternatives, should be able to go to another alternative and continue"*. Hence: no
+passkey, no passkey screen, straight to the password form.
+
+**Why usernameless was rejected, measured.** The `configuredFor` guard sits inside the
+`requiresUser()` branch. With `requiresUser()` false and no user yet in context, that guard is
+skipped and the engine just calls `authenticate(context)` — so a passkey execution placed before
+the username form is offered to *everyone*, including users who will never own one.
+
+**The policy sentinels are read from the shipped code, and one of my initial assumptions was
+wrong.** `Constants.DEFAULT_WEBAUTHN_POLICY_NOT_SPECIFIED = "not specified"` is the
+realm-representation sentinel — but `WebAuthnConstants.OPTION_NOT_SPECIFIED = ""` (empty string) is
+the WebAuthn-API-level one. I checked both because they disagree. The login theme's
+`webauthnRegister.js` at 26.0.6 settles the behaviour:
+
+```js
+if (input.requireResidentKey !== 'not specified') {
+    if (input.requireResidentKey === 'Yes') { authenticatorSelection.requireResidentKey = true; }
+    else { authenticatorSelection.requireResidentKey = false; }
+}
+...
+if (input.createTimeout !== 0) { publicKey.timeout = input.createTimeout * 1000; }
+rp: {id: input.rpId, name: input.rpEntityName}
+```
+
+So `"Yes"` is a literal string compare (any other non-sentinel value means *false*), `"not
+specified"` is compared literally for four fields, and `createTimeout` is **seconds** with `0`
+meaning "send no timeout". It also shows 26.0.6 emits only the legacy `requireResidentKey` member,
+never `residentKey: "required"` — the client maps that per WebAuthn L2, but the policy cannot
+express `residentKey: "preferred"` at all.
+
+`[ES256, RS256]` is exactly `WebAuthnPolicy.DEFAULT_POLICY` /
+`Constants.DEFAULT_WEBAUTHN_POLICY_SIGNATURE_ALGORITHMS` — declared explicitly, not changed.
+`getWebAuthnPolicyPasswordless` was read field by field to confirm `[]` for `acceptableAaguids`
+means "no restriction" and that `RpEntityName` must be non-empty or the **update** path
+(`DefaultExportImportManager.java:842`) drops the whole policy silently.
+
+**The manifest parses and renders.** `yaml.safe_load` round-trips the file and the flow graph reads
+back exactly as designed (five flows, the executions and priorities above, `browserFlow:
+browser-mfa`, `requiredActions` absent). `python3 ci/render-keycloak-client-urls.py --check` →
+`client-urls.yaml is in sync`, rc 0 (no client URL changed, so no regeneration was needed).
+`yamllint -c ci/yamllint.yaml platform/keycloak/keycloak-realm-import.yaml` → rc 0; no line exceeds
+the 160-column ceiling.
+
+**`browser-mfa` keeps its alias deliberately.** `conformance/tests/l2-behavioral/keycloak-config-as-code`
+asserts `kubectl get keycloakrealmimport homelab -o jsonpath={.spec.realm.browserFlow} | grep -q
+'browser-mfa'`. Renaming the top-level flow would have failed that test.
+
+**Envsubst safety.** `platform-config`'s Flux Kustomization declares
+`postBuild.substituteFrom: cluster-vars` (`clusters/base/platform-config.yaml:26-29`), so this file
+is substituted. The only brace token I added is `${BASE_DOMAIN}`, which is declared at
+`clusters/base/cluster-vars.yaml:42` (`home.keithjackson.dev`). Every comment I wrote avoids braces
+entirely — the RP-ID discussion says `keycloak.<BASE_DOMAIN>` with angle brackets precisely so an
+unparseable token cannot fail the whole Kustomization.
+
+**Gate result: rc 3, zero failures, `gitea-settings` the only stage the gate counts as not-run** —
+the documented honest best local outcome. Run in the pinned toolbox from this worktree with all
+three §3 workarounds (`DEV_KUBECONFIG=/dev/null`, plus an `ENGINE` shim bind-mounting the main
+checkout's `.git` and the sibling spec repo with `SPEC_REPO=/home-network-k3s`):
+
+```
+[ ok ] stage spec-immutability: pass      <- NOT skipped; both shim mounts worked, R-TEST-06 covered
+[ ok ] stage decisions-log: pass          <- archive frozen, 48 entries well-formed
+[ ok ] stage lint: pass
+[ ok ] stage l0: pass                     <- incl. flux-postbuild-substitution + keycloak-client-secret-reconciler
+[ ok ] stage render-golden: pass
+[ ok ] stage l1: pass
+[ ok ] stage approval-policy: pass        <- no sensitive path touched, so no non-author review needed
+[skip] stage gitea-settings: SKIPPED      <- needs SETTINGS_API_TOKEN, CI-only; expected
+[skip] stage conformance: SKIPPED         <- cluster-gated L2/L3; expected
+MERGE GATE: UNDETERMINED — Stages that did not run: gitea-settings
+```
+
+No lint finding and no check failure names either file I changed. Touched requirements resolved to
+`R-IDP-01 R-IDP-02 R-IDP-03 R-IDP-04 R-IDP-05 R-IDP-06`; coverage 51/51, 0 gaps.
+
+**A note on how that number was obtained, because the first attempt was worthless.** My first gate
+run returned the same rc 3 and the same seven passes — against a tree that did not contain this
+change at all. The gate's `tracked_files()` reads **git**, and my edits were still uncommitted, so
+every stage gated `origin/main`. The tell was in the log and I nearly missed it: the
+touched-requirement subset reported UNDETERMINED with *"check out the feature branch you mean to
+gate (not the base branch)"*, and `decisions-log` counted **47** entries rather than 48. **A green
+gate run on an uncommitted worktree is a gate run on the base branch.** The numbers above are from
+the second run, after committing and rebasing.
+
+**The base moved under me mid-run.** `origin/main` advanced from `9a41a8e` to `1a0b208` (PR #70,
+oauth2-proxy OIDC startup race) while I was working. This branch is rebased onto `1a0b208`, so the
+gate above ran on the base CI will actually merge into. The rebase was clean — PR #70 touched
+`platform/oauth2-proxy/helmrelease.yaml` and its own decisions entry, disjoint from these files.
+
+## What I did NOT verify
+
+**This change is unapplied. It changes nothing about the live realm, and I did not attempt to make
+it.** `Done=True` / `Started=False` was measured, not inferred, and I ran no mutating `kubectl`,
+no `flux reconcile`, no admin-API call and no `kcadm`. Whether the operator's eventual
+admin-console reconstruction of this flow matches what is declared here is, by construction,
+unverifiable from git.
+
+**I never enrolled a passkey and never pointed a browser at any of this.** Nothing here has been
+exercised by a real WebAuthn ceremony on any device. Specifically unverified:
+
+* **That the RP ID works.** `home.keithjackson.dev` is a registrable-domain suffix of
+  `keycloak.home.keithjackson.dev`, so it *should* satisfy the browser's check — but I verified
+  that by reading the WebAuthn rule, not by watching a browser accept it. A wrong RP ID fails
+  **silently, in the browser, before Keycloak is involved**, with no server-side log line. If
+  enrolment produces no OS prompt and no error, this is the first suspect.
+* **That `"not specified"` is the right literal for `authenticatorAttachment` in a realm import.**
+  I traced it to `Constants.DEFAULT_WEBAUTHN_POLICY_NOT_SPECIFIED` and to the theme's string
+  compare, but I have not seen a realm import accept it. Omitting the field would default to the
+  same value; if an import ever rejects the literal, drop the line.
+* **That `createTimeout: 300` behaves.** Seconds-vs-milliseconds is read from the theme JS. The
+  claim that 300 is long enough for the cross-device QR/hybrid flow, and that Chrome clamps rather
+  than rejects it, is reasoning about browser behaviour, not a measurement.
+* **Whether a passkey user can still reach the password form.** I argued it from
+  `createAuthenticationSelectionList` producing a "Try another way" option, and I noted that for a
+  user holding both credentials the *first* screen is chosen by the user's own credential ordering
+  rather than by my priorities. Neither was observed.
+* **The two-screen login regression for ordinary users.** `auth-username-form` +
+  `auth-password-form` replacing `auth-username-password-form` is a visible change for every user
+  including non-passkey family accounts, and nobody has logged in through it.
+* **That conditional OTP for platform-admins still fires on the password branch.** The sub-flow and
+  its `conditional-otp-platform-admin` config are byte-identical and merely relocated one level
+  deeper, but "identical YAML" is not "still enforced at runtime". This is the highest-value
+  regression check and it is untested. The previous breakage of this exact step
+  (`condUserRole` vs a non-existent property key) 403'd every platform-admin login.
+* **That a platform-admin authenticating by passkey is not challenged for TOTP.** That is the
+  intended behaviour of the shape I wrote; it is unobserved, and it is also a deliberate
+  relaxation of R-IDP-04 as previously implemented, which the operator may want to reverse.
+
+**Whether the realm import reconciles into an existing realm: measured as NO for the completed
+one-shot, but I did not test a re-import.** I did not delete and recreate the
+`KeycloakRealmImport`, so I cannot say what a re-run would do to the existing `homelab` realm —
+whether it would merge the new policy and flows, duplicate flow aliases, or fail. The 2026-09-06
+total SSO outage documented in `platform/keycloak/README.md` is the reason I did not experiment.
+**Treat the re-import path in the README as untested advice, not a runbook.**
+
+**Nothing was proved about the live realm's current state.** I did not read the realm's existing
+required actions, its existing WebAuthn policies, or its live flow executions — doing so needs the
+admin credential and I did not decrypt or use it. So I cannot confirm that the live realm's
+required-action set actually contains `webauthn-register-passwordless` today; I can only show that
+Keycloak 26.0.6's defaults register it and that this repo's import never declared any required
+actions to suppress them. **That inference has not been checked against the realm.**
+
+**L2/L3 conformance did not run** (no cluster from the gate container; `vars.CLUSTER_AVAILABLE` is
+unset in CI anyway), so the existing `keycloak-config-as-code` behavioural test did not re-execute
+against this change. I reasoned about its assertion by reading it.
+
+**No new conformance test was added.** Nothing in `conformance/` asserts the passkey policy or the
+new flow shape, so a future edit can silently remove either and no gate stage will notice. That is
+a real gap this PR leaves open; closing it would touch `conformance/**`, which is a sensitive path
+needing non-author review.
+
+**The quoted gate run predates this file's own gate-result paragraph.** It gated commit `207f5db`;
+the gate numbers and the rebase note above were then written into this entry, so the pushed tree
+differs from the gated one by this handoff's prose only — no manifest, no check, no generated file.
+`decisions-log` is the only stage that reads this file, and it validates structure (frontmatter,
+the three headings, non-stub bodies), which is unchanged. I did not re-run the full gate for a
+prose edit; CI will gate the pushed commit.
+
+**`gitea-settings` did not run locally** — it needs `SETTINGS_API_TOKEN`, which exists only in CI.
+I did not re-measure branch protection, the runner, or `required_approvals` against the Gitea API
+this session; the claims in `CLAUDE.md` §2 are taken on trust here and are explicitly flagged there
+as needing re-measurement.
@@ -0,0 +1,108 @@
+---
+date: 2026-10-18
+branch: fix/coredns-ha
+title: "coredns ran at one replica, so any node drain was a cluster-wide DNS outage"
+---
+
+## What changed
+
+**MEASURED on prod 2026-10-18: `kube-system/coredns` had `replicas: 1`.** In-cluster DNS was a
+single pod on a single node, so draining or rebooting that node was a **cluster-wide in-cluster DNS
+outage** until the pod rescheduled and became ready — every Service lookup, every CNPG replica
+finding its primary, every operator addressing the API by name. It was invisible because `1/1
+Ready` looks perfectly healthy.
+
+It also became urgent rather than latent: the scheduled reboot automation on
+`feat/automated-upgrades` drains and reboots one node at a time, unattended, overnight — turning a
+single point of failure into a recurring one.
+
+New `platform/coredns/hpa.yaml`: a `HorizontalPodAutoscaler` on the coredns Deployment with
+`minReplicas: 2`, `maxReplicas: 3`, registered in the existing `platform/coredns/kustomization.yaml`
+alongside the split-horizon ConfigMap already there.
+
+**Why an HPA and not `replicas: 2` — this is the whole decision.** k3s owns the coredns Deployment
+and we cannot durably edit it: it is applied by k3s's own deploy controller from a bundled manifest
+(`AddOn/coredns`, source `/data/k3s/server/manifests/coredns.yaml`, `managedFields` managers
+`deploy@k3s-prod-1` and `k3s`, plus an `objectset.rio.cattle.io/hash` label). k3s re-stages its
+bundled manifests on startup, so a `replicas: 2` written there — or a `kubectl scale` — is reverted
+on the next k3s restart or upgrade. Two alternatives were weighed and rejected:
+
+* **`coredns.yaml.skip` + our own templated copy** (the pattern `roles/kube_vip` already uses for a
+  file in `server/manifests`). Deterministic and never flaps, but it takes ownership of coredns away
+  from k3s permanently — k3s upgrades would stop updating it and the version would need refreshing
+  by hand forever. Too high a price for a replica count.
+* **A Flux-managed patch of the Deployment.** Rejected outright: Flux and k3s's deploy controller
+  would both own one object and fight continuously — the exact shape of the `default-deny`
+  NetworkPolicy drift loop this cluster already suffered (~2500 events/10min).
+
+An HPA avoids both: a separate object k3s does not own, driving the `/scale` subresource rather than
+the Deployment spec, so there is no shared-ownership fight. If k3s re-stages `replicas: 1`, the HPA
+sees it below `minReplicas` and scales back within one reconcile.
+
+It is a **floor-holder, not an autoscaler**: the CPU metric exists only because an `autoscaling/v2`
+HPA needs one to be valid. `scaleDown.stabilizationWindowSeconds: 600` because DNS is the worst
+thing in the cluster to flap; `scaleUp` is immediate, since that is the path that restores redundancy
+after a k3s restart.
+
+**Immediate action taken outside this PR:** `kubectl -n kube-system scale deploy coredns
+--replicas=2` was run at the operator's explicit request, so the cluster has two replicas **now**
+rather than after merge. That hand scale is what this PR makes durable.
+
+## What I verified
+
+* **The defect:** `kubectl -n kube-system get deploy coredns` → `replicas=1 available=1`.
+* **k3s ownership:** the `AddOn/coredns` object exists with source
+  `/data/k3s/server/manifests/coredns.yaml`; the Deployment has no `ownerReferences` but carries
+  `objectset.rio.cattle.io/hash` and `managedFields` managers `deploy@k3s-prod-1` / `k3s`. So it is
+  k3s-managed, not Flux-managed — independently corroborated by another agent, which confirmed
+  `platform/coredns/` contains **only** the `coredns-custom` ConfigMap and does not touch the
+  Deployment or its replica count.
+* **The hand scale works and holds:** coredns went to `2/2 Running` on two different nodes, and
+  in-cluster DNS kept answering throughout (`nslookup kubernetes.default.svc.cluster.local
+  10.43.0.10` → `10.43.0.1`). Still `spec.replicas=2 ready=2` after ~2 minutes, with the AddOn
+  checksum **unchanged** — so k3s's deploy controller does not revert on a drift timer; it
+  re-applies on manifest change and on restart.
+* **The HPA's preconditions hold:** coredns ships `requests: {cpu: 100m, memory: 70Mi}` (so a
+  Resource/Utilization metric is meaningful), and metrics-server is installed as a k3s addon and
+  verified serving — `kubectl top pod -l k8s-app=kube-dns` returns **5m and 4m** against that 100m
+  request, i.e. ~5% utilisation, confirming the 80% target will never be approached and the HPA will
+  sit at `minReplicas`.
+* **The kustomization edit is additive:** `git diff --stat` is `1 file changed, 4 insertions(+)`,
+  and `- coredns` was already registered in `platform/kustomization.yaml`, so no change was needed
+  there.
+* All three touched/added YAML files parse.
+
+## What I did NOT verify
+
+* **The HPA has never been applied.** I did not reconcile it, so I have **not** observed it create,
+  reach `ScalingActive=True`, resolve its metric against real coredns data, or hold `minReplicas`.
+  Applying is an operator action (CLAUDE.md §5). The failure mode to watch for is
+  `ScalingActive=False` with `FailedGetResourceMetric` — the HPA would then be present and inert,
+  which looks identical to working because the hand scale already left 2 replicas in place. **Check
+  `kubectl -n kube-system describe hpa coredns` after merge**, not just the replica count.
+* **The central claim that k3s reverts `replicas` on restart is REASONED, NOT OBSERVED.** It rests
+  on k3s re-staging bundled manifests at startup plus the measured ownership evidence above. I did
+  **not** restart k3s to watch the revert happen — doing so is a rolling control-plane restart, an
+  operator action. If k3s in fact preserves a modified replica count, this HPA is unnecessary
+  (though harmless).
+* **I did not confirm the HPA wins the race against k3s's deploy controller after a restart.** Both
+  write the scale; the expectation is the HPA re-asserts within a reconcile, leaving a brief window
+  at 1 replica. Neither the window's length nor the outcome has been measured.
+* **I nearly shipped a destructive change.** My first write of
+  `platform/coredns/kustomization.yaml` replaced the file wholesale, listing only `hpa.yaml` — which
+  would have pruned the existing `coredns-custom` ConfigMap and **broken in-cluster split-horizon
+  DNS (R-DNS-01/03)**. It was caught by a guard assertion before commit and restored from `HEAD`, and
+  the diff is now additive. Recorded because the near-miss is the useful part: `platform/coredns/`
+  already existed and I assumed it did not. **No conformance check would obviously have caught the
+  removal** — it is valid YAML and a legitimate-looking prune.
+* **Whether 2 is enough.** Three nodes, and coredns' anti-affinity only *prefers* spreading, so both
+  replicas could in principle land on one node and a single drain would still take DNS down. I did
+  not add a `topologySpreadConstraint` or a PodDisruptionBudget — both arguably belong here and
+  neither is in this change.
+* **No alert fires if coredns drops to 1 replica**, so a future silent regression (k3s upgrade
+  changing the manifest, the HPA going inert) would not be reported. That gap is not closed here.
+* **No conformance test asserts this**, so a future edit could remove the HPA with no gate stage
+  noticing.
+* **No runtime conformance.** `vars.CLUSTER_AVAILABLE` is unset, so CI proves the L0/L1 offline
+  subset only.
+* I did not re-measure branch protection or runner state (CLAUDE.md §2b).
@@ -0,0 +1,76 @@
+---
+date: 2026-10-18
+branch: fix/ha-check-catastrophic-regex
+title: "One regex made the merge gate take 28 minutes instead of 2"
+---
+
+## What changed
+
+The merge gate started taking **~28 minutes** instead of its usual **<2 minutes**, on every change
+touching `infra/**`. One regex was responsible for essentially all of it.
+
+`conformance/tests/l0-static/ha-control-plane-as-code/check.sh` contained:
+
+```python
+join_when = re.search(r"--server https://.*?\n(?:.*\n){0,10}?\s*when:\s*k3s_server_mode\s*==\s*'secondary'",
+                      K3S_TEXT, re.S)
+```
+
+With `re.S`, every `.` also matches newlines, so `.*?` and the nested `(?:.*\n){0,10}?` can each
+consume the entire document. That is **nested unbounded repetition** — ten levels of a quantifier
+that can each swallow everything — and a failed or late match backtracks exponentially.
+
+Replaced `.` with `[^\n]*` and dropped `re.S`, so the `{0,10}` is a genuine ten-line window with
+nothing to backtrack into. Same intent, same verdict, no DOTALL.
+
+**Why it surfaced now, and it was mine.** `K3S_TEXT` is every `*.yml` in `roles/k3s_server`
+concatenated. The regex was latent for as long as it existed; **PR #71 added ~100 lines to that role
+(the kubelet graceful-shutdown config), which grew the input past the point where exponential
+backtracking stopped being survivable.** Nothing about the check changed — my change grew its input.
+
+**Why only `infra/**` changes were slow.** `ci/touched-requirements.sh:268` maps `infra/*` to
+`R-ENV-01`, and the resulting L0 run is `--include-scope whole-repo --requirements R-ENV-01`, which
+pulls in this whole-repo check. Doc-only and `platform/**` changes never selected it, which is why
+#69 (1m55s) and #72 (1m53s) stayed fast while #71 (27m44s), the #73 merge (27m46s) and #75 all ran
+~28 minutes.
+
+## What I verified
+
+* **The hot spot, by measurement rather than reading.** `docker top` on the live CI job container for
+  run #299 showed `python3 -` with **19:54 of CPU time** under
+  `ha-control-plane-as-code/check.sh`, inside
+  `conformance/run.sh --layer l0 --include-scope whole-repo --requirements R-ENV-01`.
+* **Reproduced locally**: the check did not finish within a 100-second budget on an unmodified
+  checkout.
+* **Localised to the exact line** by extracting the inline Python and running it under
+  `faulthandler.dump_traceback_later(25)`, which named `re/__init__.py:177 in search` called from
+  the `join_when` line — not inferred from reading the patterns.
+* **The pattern is unique in the repo**: `grep -rlnE "\{0,[0-9]+\}\?" conformance/tests/l0-static/*/check.sh`
+  returns only this file, so there is no sibling with the same hazard.
+* **The fix is fast AND verdict-preserving**, tested against the real `K3S_TEXT` (22,179 chars, 403
+  lines): the new regex matches (`YES`) in **0.2 ms**. Sanity-checked that the thing it looks for
+  genuinely exists — one `--server https://` and three `k3s_server_mode == 'secondary'` occurrences.
+* **The whole check now runs in 0.199s, rc 0, 115 assertions**, with the same success message as
+  before.
+
+## What I did NOT verify
+
+* **I did not re-time the full gate in CI after the fix.** The expectation is that `infra/**` changes
+  return to the ~2-minute range, but that is arithmetic from the 19m54s figure, not a measured
+  post-fix run. The PR's own CI run is the first real datapoint — read it.
+* **I did not audit the other 23 L0 checks for different performance pathologies.** This one was
+  found because it was actively burning CPU in a live job; a check that is merely slow (not
+  exponential) would not have stood out, and `ci/gate.sh` has **no per-stage timing** at all
+  (`grep -nE "SECONDS|date \+|elapsed"` finds nothing), so there is no data on where the remaining
+  time goes.
+* **Nothing prevents this class of bug returning.** No check asserts gate stage runtime, and no lint
+  forbids nested quantifiers under `re.S`. A timing budget per stage, or a `re` lint, would close it;
+  neither is written here.
+* **I did not verify my claim about *why* only `infra/**` was affected beyond the path mapping and
+  the observed durations.** The correlation is strong (5 runs, two clear clusters) and the live
+  process list confirms the `--requirements R-ENV-01` scope, but I did not read
+  `conformance/run.sh`'s scope-selection logic end to end.
+* The regex rewrite assumes the `when:` clause is indented with spaces or tabs only (`[ \t]*`). A
+  file using some other whitespace before `when:` would now fail to match where the old DOTALL
+  version would have succeeded. Unlikely in YAML, and the current input matches, but it is a
+  narrowing.
@@ -0,0 +1,82 @@
+---
+date: 2026-10-18
+branch: fix/pihole-local-ttl
+title: "The split-horizon answer was uncacheable while the wrong answer cached for 5 minutes"
+---
+
+## What changed
+
+The operator reported DNS "flapping between the cluster ingress and the router (public IP)".
+PiHole was not at fault — both replicas answer correctly and consistently. The bug is an
+**asymmetry in cacheability** that we created.
+
+Measured on prod 2026-10-18:
+
+```
+dig home.keithjackson.dev @192.168.2.23 (pihole)  -> 192.168.2.20                TTL=0
+dig home.keithjackson.dev @1.1.1.1      (public)  -> wan.home.keithjackson.dev   TTL=300
+dig home.keithjackson.dev @192.168.2.1  (router)  -> wan....  TTL=153 -> 148 -> 143
+```
+
+dnsmasq answers `address=` entries with **TTL 0** unless told otherwise. The SOHO router forwards
+LAN queries to PiHole and **caches** the result — the decrementing TTL above is the proof it caches
+rather than forwarding live. So:
+
+* the **correct** answer is **uncacheable** (TTL 0): the router must re-query PiHole on *every*
+  lookup, which is maximum exposure to any momentary gap;
+* the **wrong** answer is **cacheable for 300s**: the instant the router falls back to its upstream
+  (standard forwarder behaviour when the forward target does not answer) it latches the public WAN
+  address and serves it to **every LAN client** for five minutes.
+
+So **one sub-second PiHole gap becomes five minutes of the whole house resolving to the WAN IP** —
+then it expires, the router re-queries PiHole, gets TTL 0 again, and is immediately re-exposed.
+That asymmetry, not the gap itself, is why this is visible as flapping rather than a blip.
+
+Fix: `local-ttl=60` prepended to `FTLCONF_misc_dnsmasq_lines` in `catalog/pihole.yaml`, so the
+private answer is cacheable and a short gap is invisible to clients. `apps/wave-0/pihole.yaml`
+regenerated with the canonical render command.
+
+## What I verified
+
+* **PiHole is NOT the fault.** Both replicas, queried directly by pod IP, answer `192.168.2.20`;
+  the VIP returned it 6/6; this workstation 8/8. DHCP hands out only `192.168.2.23`.
+* **The router caches rather than forwards live** — three successive queries returned TTL 153, 148,
+  143 (decrementing), which a pure forwarder could not do.
+* **The TTL asymmetry**, as quoted above: 0 from PiHole, 300 from public DNS.
+* **The router does answer DNS and returns the public chain** (`wan.home.keithjackson.dev` → the WAN
+  address), so a fallback always has a wrong answer available.
+* **`local-ttl` is the right directive**: dnsmasq applies it to replies made from configuration,
+  `/etc/hosts` and DHCP leases, which covers all five `address=` names with one directive. It is a
+  standalone option, not a sub-field of `address=`, so prepending it to the `;`-separated
+  `FTLCONF_misc_dnsmasq_lines` list is syntactically correct.
+* **The render is clean and scoped**: `catalog/render.py --all catalog -o apps --wave-layout
+  --no-image-automation` (the canonical command `ci/render-golden.sh` asserts against, and
+  deliberately **not** `--emit-waves`) changed exactly two files — `catalog/pihole.yaml` and
+  `apps/wave-0/pihole.yaml` — and the rendered diff is the single `local-ttl=60;` prefix.
+
+## What I did NOT verify
+
+* **UNAPPLIED.** Nothing has been reconciled, so I have not observed PiHole serving a non-zero TTL,
+  nor the router caching the private answer, nor the flap stopping. **Verify after merge with
+  `dig home.keithjackson.dev @192.168.2.23` (expect `TTL=60`, not 0) and then the same query at the
+  router (expect `192.168.2.20` with a decrementing TTL, not `wan.…`).**
+* **I did not confirm that PiHole/FTL accepts `local-ttl` via `FTLCONF_misc_dnsmasq_lines`.** The
+  directive is valid dnsmasq and the field is a passthrough, but `catalog/pihole.yaml`'s own header
+  records that FTL has previously written a bogus line into `dnsmasq.conf` and reported "0 invalid"
+  — so a malformed passthrough fails *silently*. If the TTL is still 0 after merge, that is the
+  cause, not this reasoning. Check the pod's `/etc/pihole/dnsmasq.conf`.
+* **60s is chosen, not derived.** Long enough for a pod restart and a lease re-election (both
+  seconds); it does **nothing** for an outage longer than the TTL, where the cache expires and the
+  public answer latches again. That is a real availability problem, not a caching one.
+* **This does not remove the trigger.** `192.168.2.23` is served by **two** LoadBalancer Services
+  (`pihole-dns-tcp`, `pihole-dns-udp`) with **two independently-elected L2 announcement leases**, so
+  two nodes can ARP for the same address at once — they sat on different nodes earlier the same day
+  (tcp on prod-2, udp on prod-1). The same pattern applies to crafty (`.22`) and unifi (`.21`).
+  Merging each pair into one mixed-protocol Service would remove the class; the operator has parked
+  that decision, and it is deliberately **not** in this change.
+* **Client-side bypasses are unexamined.** A device with its own resolver, or a browser with
+  DNS-over-HTTPS, bypasses PiHole entirely and always gets the public answer; this fix cannot help
+  there. Only this one workstation's resolver chain was inspected.
+* **No alert fires if the split-horizon answer regresses to the public address.** Nothing probes
+  `home.keithjackson.dev` from a LAN vantage point and compares it against `${GATEWAY_VIP}`, so the
+  next recurrence would again be found by a human noticing. That gap is not closed here.
@@ -107,3 +107,31 @@ k3s_base_domain: "home.keithjackson.dev"

 # Derived, so the realm path is stated once. Override k3s_base_domain, not this.
 k3s_oidc_issuer_url: "https://keycloak.{{ k3s_base_domain }}/realms/homelab"
+
+# --- Graceful node shutdown (kubelet) ----------------------------------------------------------
+# MEASURED 2026-10-17, during the UPS move: graceful node shutdown was NOT configured on any prod
+# node, so `shutdown -h` did NOT drain pods. systemd stops k3s, containerd goes with it, and every
+# pod is SIGKILLed where it stands -- including 9 CloudNativePG instances mid-checkpoint, the UniFi
+# VM, and 25 attached Longhorn volumes. The whole-cluster shutdown that day had to quiesce
+# everything BY HAND first (runbooks/cluster-maintenance-shutdown.md), and the one volume that did
+# not finish detaching came back `degraded` and had to rebuild.
+#
+# With these set, the kubelet takes a systemd inhibitor lock and, on shutdown, evicts ordinary pods
+# first and critical ones last, so a plain `shutdown -h`/reboot drains the node. That makes the
+# manual scale-down in the runbook a belt-and-braces step for a PLANNED whole-cluster shutdown
+# rather than the only thing standing between a reboot and a hard kill.
+#
+# 90s/20s, not larger: the budget is spent on every reboot and node upgrade, and the kubelet waits
+# the FULL ordinary period before it starts on critical pods. Postgres does a fast shutdown in
+# well under 90s here, and Longhorn needs only enough time to flush and detach.
+k3s_kubelet_shutdown_grace_period: "90s"
+k3s_kubelet_shutdown_grace_period_critical_pods: "20s"
+
+# *** THE HALF THAT IS EASY TO MISS, AND SILENTLY BREAKS THE OTHER HALF. ***
+# Graceful node shutdown works by the kubelet holding a logind INHIBITOR DELAY lock. systemd caps
+# how long any inhibitor may delay shutdown at `InhibitDelayMaxSec`, which DEFAULTS TO 5 SECONDS.
+# If that cap is below the grace period above, systemd proceeds anyway and the drain is truncated
+# to ~5s -- i.e. the feature appears configured, reports no error, and still hard-kills pods. So
+# this MUST be >= k3s_kubelet_shutdown_grace_period; the role asserts it rather than trusting it.
+# Set a little above the kubelet's total (90s + 20s) to leave headroom.
+k3s_logind_inhibit_delay_max_sec: 120
@@ -15,3 +15,12 @@
    port: "{{ k3s_api_port }}"
    timeout: 180
  listen: Restart k3s
+
+# logind re-reads InhibitDelayMaxSec only on restart. Restarting logind does NOT log users out or
+# disturb k3s -- it manages login sessions and inhibitor locks, not workloads. The kubelet picks up
+# the new cap when it next takes its lock, so no k3s restart is needed for THIS half.
+- name: Restart logind
+  ansible.builtin.systemd_service:
+    name: systemd-logind
+    state: restarted
+  listen: Restart logind
@@ -86,6 +86,16 @@
      # k3s_base_domain (defaults/main.yml), whose [parity] contract with the cluster's
      # BASE_DOMAIN is documented there. Dev's default renders the value it already runs, so
      # config.yaml is unchanged and the Restart handler does not fire.
+      # ── Graceful node shutdown ──────────────────────────────────────────────────────────────
+      # Without these the kubelet takes no systemd inhibitor lock, so `shutdown -h` stops
+      # containerd and SIGKILLs every pod where it stands -- MEASURED on all three prod nodes
+      # 2026-10-17 (defaults/main.yml has the detail). The companion logind drop-in below raises
+      # InhibitDelayMaxSec, WITHOUT WHICH systemd caps the drain at ~5s and these values are
+      # quietly ignored.
+      kubelet-arg:
+        - "shutdown-grace-period={{ k3s_kubelet_shutdown_grace_period }}"
+        - "shutdown-grace-period-critical-pods={{ k3s_kubelet_shutdown_grace_period_critical_pods }}"
+
      kube-apiserver-arg:
        - "oidc-issuer-url={{ k3s_oidc_issuer_url }}"
        - "oidc-client-id=kubernetes"
@@ -183,3 +193,46 @@
    host: "127.0.0.1"
    port: "{{ k3s_api_port }}"
    timeout: 180
+
+# ── Graceful node shutdown: the systemd half — tag `shutdown` ──────────────────────────────────
+# The kubelet's shutdown-grace-period is ENFORCED BY logind, not by the kubelet: the kubelet holds
+# an inhibitor DELAY lock, and systemd will wait at most `InhibitDelayMaxSec` for it (default 5s)
+# before proceeding regardless. A grace period above that cap is therefore silently truncated --
+# the feature looks configured, logs no error, and still hard-kills pods. Assert the relationship
+# instead of documenting it, because the failure is invisible.
+- name: Assert the logind inhibitor cap can actually cover the kubelet grace period
+  ansible.builtin.assert:
+    that:
+      - (k3s_logind_inhibit_delay_max_sec | int) >= (k3s_kubelet_shutdown_grace_period | regex_replace('[^0-9]', '') | int)
+    fail_msg: >-
+      k3s_logind_inhibit_delay_max_sec ({{ k3s_logind_inhibit_delay_max_sec }}s) is below
+      k3s_kubelet_shutdown_grace_period ({{ k3s_kubelet_shutdown_grace_period }}). systemd would
+      stop waiting for the kubelet's inhibitor lock before the drain finished, so pods would be
+      SIGKILLed anyway and graceful node shutdown would be configured but ineffective.
+    quiet: true
+  tags: [shutdown]
+
+- name: Ensure /etc/systemd/logind.conf.d exists
+  ansible.builtin.file:
+    path: /etc/systemd/logind.conf.d
+    state: directory
+    owner: root
+    group: root
+    mode: "0755"
+  tags: [shutdown]
+
+# A drop-in, not an edit of logind.conf: the distro file stays pristine and `state: absent` here
+# would fully revert the change.
+- name: Raise the logind inhibitor delay cap so the kubelet can finish draining
+  ansible.builtin.copy:
+    dest: /etc/systemd/logind.conf.d/10-k3s-graceful-shutdown.conf
+    owner: root
+    group: root
+    mode: "0644"
+    content: |
+      # Managed by Ansible (roles/k3s_server). See defaults/main.yml.
+      # MUST stay >= kubelet shutdown-grace-period, or the drain is truncated to this value.
+      [Login]
+      InhibitDelayMaxSec={{ k3s_logind_inhibit_delay_max_sec }}
+  notify: Restart logind
+  tags: [shutdown]
@@ -0,0 +1,265 @@
+#!/usr/bin/env bash
+# =================================================================================================
+# quiesce.sh — bring the prod cluster to a safe standstill before powering nodes off, and bring it
+#              back afterwards. Companion to runbooks/cluster-maintenance-shutdown.md.
+# =================================================================================================
+# WHY THIS EXISTS. On 2026-10-17 all three nodes had to be powered off to move them onto a UPS, and
+# there was NO procedure for it: `infra/cluster.sh stop` is `virsh`-based and only ever applied to
+# the decommissioned dev cluster. The whole sequence was improvised live. This script is that
+# sequence, so the next person does not improvise it.
+#
+# WHY IT IS NOT JUST `shutdown -h`. Graceful node shutdown was unconfigured on every prod node that
+# day, so systemd stopped containerd and SIGKILLed every pod where it stood. roles/k3s_server now
+# sets shutdown-grace-period (+ the logind InhibitDelayMaxSec cap that actually enforces it), which
+# makes a bare reboot safe. This script is still the right tool for a PLANNED whole-cluster
+# shutdown, for three reasons the kubelet's drain does not cover:
+#   1. The UniFi VM needs an ACPI guest shutdown, not an eviction.
+#   2. CloudNativePG wants hibernation, not pod deletion -- and hibernation is IMPERATIVE state
+#      that Flux will not set or clear for you.
+#   3. Draining three nodes one at a time makes pods RESCHEDULE onto the survivors, churning
+#      Longhorn replicas for no reason when the whole cluster is going down anyway. Scaling in
+#      place avoids all of it.
+#
+# SAFE TO RE-RUN. Every step is idempotent and `resume` is the exact inverse of `quiesce`.
+#
+# WHAT IT DELIBERATELY DOES NOT DO: power anything off. Node poweroff is an operator action
+# (CLAUDE.md §5) and needs the become password; the runbook gives the ansible one-liner. It also
+# does not touch TrueNAS (not in the inventory, SSH refused -- web UI only) or the router.
+set -euo pipefail
+
+CONTEXT="${CONTEXT:-k3s-prod}"
+KUBECTL=(kubectl --context "$CONTEXT" --request-timeout=30s)
+TIMEOUT="${TIMEOUT:-600}"
+
+# The three CloudNativePG clusters, as namespace/name. Hibernation is per-Cluster.
+CNPG=(keycloak/keycloak-db nextcloud-db/nextcloud-db semaphore-db/semaphore-db)
+
+log()  { printf '\033[34m[quiesce]\033[0m %s\n' "$*"; }
+ok()   { printf '\033[32m[ ok ]\033[0m %s\n' "$*"; }
+warn() { printf '\033[33m[warn]\033[0m %s\n' "$*"; }
+die()  { printf '\033[31m[fail]\033[0m %s\n' "$*" >&2; exit 1; }
+
+need() { command -v "$1" >/dev/null || die "$1 not on PATH — run this inside ./infra/devcontainer/dev.sh"; }
+
+# ---------------------------------------------------------------- discovery
+# Every Deployment/StatefulSet whose pods mount a PVC — Longhorn OR the TrueNAS NFS bulk tier.
+# Computed from the LIVE cluster rather than hardcoded, so a newly onboarded service is covered
+# without anyone remembering to add it here. PROTECTED namespaces are excluded because scaling
+# them down would remove the very machinery that performs the detach (longhorn-system), keep the
+# API reachable (kube-system), or finish the hibernation and the VM shutdown (cnpg-system,
+# kubevirt).
+pvc_workloads() {
+  "${KUBECTL[@]}" get pods -A -o json | python3 -c '
+import json,sys
+PROTECT={"longhorn-system","kube-system","cilium-secrets","cnpg-system","kubevirt","flux-system","cdi"}
+out={}
+for p in json.load(sys.stdin)["items"]:
+    ns=p["metadata"]["namespace"]
+    if ns in PROTECT: continue
+    if not any(v.get("persistentVolumeClaim") for v in (p["spec"].get("volumes") or [])): continue
+    ow=(p["metadata"].get("ownerReferences") or [])
+    if not ow: continue
+    k,n=ow[0]["kind"],ow[0]["name"]
+    if k=="ReplicaSet": k,n="deployment",n.rsplit("-",1)[0]
+    elif k=="StatefulSet": k="statefulset"
+    else: continue          # Jobs, and CNPG Clusters, are handled separately
+    out[(ns,k,n)]=1
+for ns,k,n in sorted(out): print(ns,k,n)
+'
+}
+
+# ---------------------------------------------------------------- the PVC-deletion guard
+# *** DO NOT REMOVE THIS CHECK. IT EXISTS BECAUSE SCALING A StatefulSet DESTROYED DATA. ***
+# A StatefulSet may carry `persistentVolumeClaimRetentionPolicy.whenScaled: Delete`, and then
+# scaling it to 0 DELETES ITS PVCs -- and with them the Longhorn volumes. MEASURED 2026-10-17: the
+# quiesce for the UPS move scaled `monitoring/loki` (whenScaled: Delete) to 0 and its
+# `storage-loki-0` PVC and volume were deleted outright. Loki stores with `type: filesystem`, so
+# that PVC was the only copy; 72h retention bounded the loss to a rolling window, but nothing about
+# the mechanism is bounded -- the same action on a Delete-policy StatefulSet holding real state
+# would be unrecoverable. The volume count going 25 -> 24 was the only visible symptom, and it was
+# first misread as a miscount.
+#
+# So: such a StatefulSet is NEVER scaled. It is left RUNNING and its volume hard-detaches at
+# poweroff, which costs a replica rebuild on restart (degraded -> healthy, automatic). A rebuild is
+# an enormously better outcome than a deletion, and that is the whole trade being made here.
+sts_deletes_pvc_on_scale() { # ns name -> 0 if scaling it would delete its PVCs
+  local policy
+  policy=$("${KUBECTL[@]}" -n "$1" get statefulset "$2" \
+            -o jsonpath='{.spec.persistentVolumeClaimRetentionPolicy.whenScaled}' 2>/dev/null || true)
+  [ "$policy" = "Delete" ]
+}
+
+wait_for() { # wait_for <description> <shell-condition>
+  local desc="$1" cond="$2" waited=0
+  log "waiting: $desc (up to ${TIMEOUT}s)"
+  until eval "$cond"; do
+    (( waited += 10 )); (( waited >= TIMEOUT )) && { warn "TIMED OUT waiting: $desc"; return 1; }
+    sleep 10
+  done
+  ok "$desc"
+}
+
+# ---------------------------------------------------------------- quiesce
+do_quiesce() {
+  need kubectl; need python3
+
+  # Refuse to start if Longhorn is already unhealthy. Powering off on top of a degraded volume is
+  # how one replica becomes zero; better to stop here and let it rebuild first.
+  local unhealthy
+  unhealthy=$("${KUBECTL[@]}" -n longhorn-system get volumes.longhorn.io \
+    -o jsonpath='{range .items[*]}{.status.robustness}{"\n"}{end}' | grep -cvE '^(healthy|unknown)$' || true)
+  [ "$unhealthy" = "0" ] || die "$unhealthy Longhorn volume(s) are not healthy — fix or wait for rebuild BEFORE powering off"
+  ok "Longhorn: all volumes healthy"
+
+  # 1. Flux first, or it reverts every scale-down below within its reconcile interval.
+  log "suspending Flux Kustomizations"
+  local k
+  for k in $("${KUBECTL[@]}" -n flux-system get kustomizations -o name); do
+    "${KUBECTL[@]}" -n flux-system patch "${k}" --type=merge -p '{"spec":{"suspend":true}}' >/dev/null
+  done
+  ok "all Kustomizations suspended"
+
+  # 2. The VM needs an ACPI shutdown of the GUEST. KubeVirt does that on running:false; a plain
+  #    pod eviction would be a power cut to the VM.
+  if "${KUBECTL[@]}" -n unifi get vm unifi >/dev/null 2>&1; then
+    log "ACPI-stopping the UniFi VM"
+    "${KUBECTL[@]}" -n unifi patch vm unifi --type=merge -p '{"spec":{"running":false}}' >/dev/null
+  fi
+
+  # 3. Postgres: hibernation is a clean smart shutdown that KEEPS the PVCs. CNPG does one instance
+  #    at a time, primary last-ish, so this is not instant.
+  log "hibernating CloudNativePG clusters"
+  local c ns name
+  for c in "${CNPG[@]}"; do
+    ns="${c%%/*}"; name="${c##*/}"
+    "${KUBECTL[@]}" -n "$ns" annotate cluster.postgresql.cnpg.io "$name" \
+      cnpg.io/hibernation=on --overwrite >/dev/null 2>&1 || warn "could not hibernate $c"
+  done
+
+  # 4. Everything holding a PVC, scaled in place. NFS consumers first so nothing holds a hard
+  #    TrueNAS mount; PiHole last because it is the LAN resolver.
+  log "scaling down PVC-holding workloads"
+  local line ns2 kind nm deferred=() skipped_delete_policy=()
+  while read -r ns2 kind nm; do
+    [ -z "${ns2:-}" ] && continue
+    if [ "$kind" = "statefulset" ] && sts_deletes_pvc_on_scale "$ns2" "$nm"; then
+      warn "SKIPPING $ns2/$nm — whenScaled: Delete would DELETE its PVC (see the guard above)."
+      warn "  Left running; its volume hard-detaches at poweroff and rebuilds on restart."
+      skipped_delete_policy+=("$ns2/$nm")
+      continue
+    fi
+    if [ "$ns2" = "pihole" ]; then deferred+=("$ns2 $kind $nm"); continue; fi
+    "${KUBECTL[@]}" -n "$ns2" scale "$kind" "$nm" --replicas=0 >/dev/null 2>&1 \
+      && printf '    scaled 0  %s/%s %s\n' "$ns2" "$kind" "$nm" \
+      || warn "could not scale $ns2/$kind/$nm"
+  done < <(pvc_workloads)
+  for line in "${deferred[@]:-}"; do
+    [ -z "${line:-}" ] && continue
+    # shellcheck disable=SC2086
+    set -- $line
+    "${KUBECTL[@]}" -n "$1" scale "$2" "$3" --replicas=0 >/dev/null 2>&1 \
+      && printf '    scaled 0  %s/%s %s  (LAN DNS — expect name resolution to stop)\n' "$1" "$2" "$3"
+  done
+
+  # 5. The only assertion that matters. An attached volume at poweroff comes back degraded and
+  #    rebuilds; this is what we are buying with all of the above.
+  wait_for "UniFi VMI gone" \
+    '[ "$('"${KUBECTL[*]}"' -n unifi get vmi --no-headers 2>/dev/null | wc -l)" = "0" ]' || true
+  wait_for "all Postgres instances stopped" \
+    '[ "$('"${KUBECTL[*]}"' get pods -A --no-headers 2>/dev/null | grep -cE "(keycloak|nextcloud|semaphore)-db-[0-9]")" = "0" ]' || true
+  wait_for "all Longhorn volumes detached" \
+    '[ "$('"${KUBECTL[*]}"' -n longhorn-system get volumes.longhorn.io -o jsonpath="{range .items[*]}{.status.state}{\"\n\"}{end}" 2>/dev/null | grep -c attached)" = "0" ]' || \
+      warn "some volumes are STILL ATTACHED — they will come back degraded and rebuild; acceptable, but note which"
+
+  if [ "${#skipped_delete_policy[@]}" -gt 0 ]; then
+    echo
+    warn "NOT scaled down (whenScaled: Delete — scaling them would delete their PVCs):"
+    printf '      %s\n' "${skipped_delete_policy[@]}"
+    warn "Expect these volumes to come back 'degraded' and rebuild. That is correct and automatic."
+  fi
+  echo
+  ok "QUIESCED. Safe to power off."
+  cat <<'NEXT'
+
+  Next, from inside the devcontainer (it holds the become password):
+    cd /work/infra/ansible && ansible -i inventory/hosts.ini k3s_prod -b \
+      -m shell -a 'shutdown -h +1 "maintenance"'
+
+  THEN, in this order and not before:
+    1. TrueNAS (192.168.2.30) — web UI only; not in the ansible inventory and SSH is refused.
+    2. Router / switch last.
+NEXT
+}
+
+# ---------------------------------------------------------------- resume
+do_resume() {
+  need kubectl
+
+  # THE STEP THAT IS ALWAYS FORGOTTEN. Hibernation is imperative state: Flux neither sets nor
+  # clears it, so resuming Flux alone leaves all three databases down and every app that needs
+  # one looking broken for reasons that point nowhere near Postgres.
+  log "un-hibernating CloudNativePG clusters"
+  local c ns name
+  for c in "${CNPG[@]}"; do
+    ns="${c%%/*}"; name="${c##*/}"
+    "${KUBECTL[@]}" -n "$ns" annotate cluster.postgresql.cnpg.io "$name" \
+      cnpg.io/hibernation=off --overwrite >/dev/null 2>&1 || warn "could not un-hibernate $c"
+  done
+
+  # Flux restores every replica count AND the VM's running:true from git, so nothing here needs to
+  # undo the scale-downs by hand.
+  log "resuming Flux Kustomizations"
+  local k
+  for k in $("${KUBECTL[@]}" -n flux-system get kustomizations -o name); do
+    "${KUBECTL[@]}" -n flux-system patch "${k}" --type=merge -p '{"spec":{"suspend":false}}' >/dev/null
+  done
+  ok "all Kustomizations resumed"
+
+  wait_for "Flux fully reconciled" \
+    '[ "$('"${KUBECTL[*]}"' -n flux-system get kustomizations --no-headers 2>/dev/null | grep -vc True)" = "0" ]' || \
+      warn "some Kustomizations are not Ready — the graph serialises behind platform-config, so give it a few minutes before worrying"
+
+  echo
+  ok "RESUMED."
+  cat <<'NEXT'
+
+  Known cold-start race, not a fault in this script: oauth2-proxy performs OIDC discovery at
+  startup and exits 1 on the 503 it gets while Keycloak is still coming up, then sits in
+  exponential CrashLoopBackOff. If a replica is stuck, delete the pod once:
+    kubectl --context k3s-prod -n oauth2-proxy delete pod <name>
+NEXT
+}
+
+do_status() {
+  need kubectl
+  printf 'nodes:      %s Ready\n' "$("${KUBECTL[@]}" get nodes --no-headers | grep -c ' Ready')"
+  printf 'flux:       %s/%s Ready\n' \
+    "$("${KUBECTL[@]}" -n flux-system get kustomizations --no-headers | grep -c True)" \
+    "$("${KUBECTL[@]}" -n flux-system get kustomizations --no-headers | wc -l)"
+  printf 'longhorn:   %s attached, %s detached, %s not healthy\n' \
+    "$("${KUBECTL[@]}" -n longhorn-system get volumes.longhorn.io -o jsonpath='{range .items[*]}{.status.state}{"\n"}{end}' | grep -c attached)" \
+    "$("${KUBECTL[@]}" -n longhorn-system get volumes.longhorn.io -o jsonpath='{range .items[*]}{.status.state}{"\n"}{end}' | grep -c detached)" \
+    "$("${KUBECTL[@]}" -n longhorn-system get volumes.longhorn.io -o jsonpath='{range .items[*]}{.status.robustness}{"\n"}{end}' | grep -cvE '^(healthy|unknown)$' || true)"
+  printf 'postgres:   %s instance pod(s)\n' \
+    "$("${KUBECTL[@]}" get pods -A --no-headers | grep -cE '(keycloak|nextcloud|semaphore)-db-[0-9]' || true)"
+  printf 'unifi VM:   %s VMI\n' "$("${KUBECTL[@]}" -n unifi get vmi --no-headers 2>/dev/null | wc -l)"
+}
+
+case "${1:-}" in
+  quiesce) do_quiesce ;;
+  resume)  do_resume ;;
+  status)  do_status ;;
+  *) cat >&2 <<USAGE
+usage: $0 {quiesce|resume|status}
+
+  quiesce  suspend Flux, ACPI-stop the UniFi VM, hibernate Postgres, scale down every
+           PVC-holding workload, and wait for all Longhorn volumes to detach.
+           Does NOT power anything off — see runbooks/cluster-maintenance-shutdown.md.
+  resume   the exact inverse: un-hibernate Postgres, resume Flux, wait for reconcile.
+  status   one-screen readout of nodes / Flux / Longhorn / Postgres / VM.
+
+Run it inside the pinned toolbox, which supplies kubectl and the context:
+  ./infra/devcontainer/dev.sh run bash -c './infra/maintenance/quiesce.sh status'
+USAGE
+     exit 2 ;;
+esac
@@ -0,0 +1,112 @@
+---
+# =================================================================================================
+# coredns HA floor — hold in-cluster DNS at >= 2 replicas, which k3s does not.
+# =================================================================================================
+# MEASURED on prod 2026-10-18: `kube-system/coredns` ran with **replicas: 1**. In-cluster DNS is a
+# single pod on a single node, so **draining or rebooting that one node is a cluster-wide
+# in-cluster DNS outage** for as long as the pod takes to reschedule and become ready — every pod
+# that looks up a Service, every CNPG replica finding its primary, every operator talking to the
+# API by name. It is the single cheapest availability defect in the cluster, and it was invisible
+# because `1/1 Ready` looks perfectly healthy.
+#
+# This matters more now than it did: the reboot automation (kured + unattended-upgrades) drains and
+# reboots one node at a time on a schedule, which turns a latent single point of failure into a
+# recurring one, unattended, in the middle of the night.
+#
+# -------------------------------------------------------------------------------------------------
+# WHY AN HPA, AND NOT JUST `replicas: 2` — this is the whole decision
+# -------------------------------------------------------------------------------------------------
+# **k3s owns the coredns Deployment and we cannot durably edit it.** It is applied by k3s's own
+# deploy controller from a bundled manifest, not by Flux:
+#
+#   $ kubectl -n kube-system get addon coredns
+#   NAME      SOURCE                                        CHECKSUM
+#   coredns   /data/k3s/server/manifests/coredns.yaml        8cd91595...
+#   $ kubectl -n kube-system get deploy coredns -o jsonpath='{.metadata.managedFields[*].manager}'
+#   deploy@k3s-prod-1 k3s
+#
+# and the Deployment carries an `objectset.rio.cattle.io/hash` label — a wrangler objectset. k3s
+# RE-STAGES its bundled manifests on startup, so a `replicas: 2` written into that file (or a
+# `kubectl scale`) is reverted the next time k3s restarts or is upgraded. MEASURED the same day: a
+# hand `kubectl scale` to 2 was NOT actively reverted (it held, and the AddOn checksum did not
+# change) — the deploy controller re-applies on manifest change and on restart, not on a drift
+# timer. So the hand fix survives until exactly the event we are protecting against: a reboot.
+#
+# The two durable alternatives were weighed and rejected:
+#   * **`coredns.yaml.skip` + our own templated copy** (the pattern roles/kube_vip already uses for
+#     a manifest in server/manifests). Fully deterministic and never flaps — but it takes OWNERSHIP
+#     of coredns away from k3s permanently, so k3s upgrades would stop updating it and the version
+#     would have to be refreshed by hand forever. Too high a price for a replica count.
+#   * **A Flux-managed patch of the Deployment itself.** Rejected outright: Flux and k3s's deploy
+#     controller would both own one object and fight continuously. That is the shape of the
+#     `default-deny` NetworkPolicy drift loop this cluster already suffered (Kyverno generate + Flux
+#     both owning one resource, ~2500 events per 10 minutes).
+#
+# An HPA avoids both. It is a SEPARATE object that k3s does not own and will never reconcile away,
+# and it drives the Deployment's `/scale` subresource rather than its spec — so there is no
+# shared-ownership fight. If k3s re-stages `replicas: 1`, the HPA observes it under `minReplicas`
+# and scales back to 2 within one reconcile (~15s by default).
+#
+# THE COST, STATED PLAINLY: there is a brief window — seconds, after a k3s restart — where coredns
+# is back at 1 replica until the HPA notices. That is strictly better than the status quo, where it
+# is at 1 replica permanently, but it is not zero. Accepting that window is the trade being made
+# here; the `.skip` option above is what to reach for if it ever proves unacceptable.
+#
+# -------------------------------------------------------------------------------------------------
+# THIS IS A FLOOR-HOLDER, NOT A REAL AUTOSCALER
+# -------------------------------------------------------------------------------------------------
+# `minReplicas: 2` is the entire point. The CPU metric exists because an autoscaling/v2 HPA needs a
+# metric to be a valid object, not because coredns is expected to scale on load: measured via
+# metrics-server, the two pods use **5m and 4m** against a **100m** request — ~5% utilisation, so
+# the 80% target will never be approached and the HPA will sit at `minReplicas` indefinitely.
+#
+# The CPU request is what makes this legal: coredns ships `requests: {cpu: 100m, memory: 70Mi}`
+# (measured), and a Resource/Utilization metric is meaningless without a request. metrics-server is
+# installed as a k3s addon and verified serving (`kubectl top pod -l k8s-app=kube-dns` returns
+# figures), so the metric resolves rather than leaving the HPA with `ScalingActive=False`.
+#
+# `maxReplicas: 3` = the node count. coredns' pod anti-affinity prefers one pod per node, so a
+# fourth replica would add no failure-domain coverage; the ceiling exists so a metrics glitch can
+# never balloon DNS pods across the cluster.
+apiVersion: autoscaling/v2
+kind: HorizontalPodAutoscaler
+metadata:
+  name: coredns
+  # kube-system, because that is where k3s puts coredns. This is the only object this component
+  # places outside a namespace it owns, and it is additive: it creates nothing in kube-system and
+  # mutates only the coredns Deployment's scale subresource.
+  namespace: kube-system
+  labels:
+    app.kubernetes.io/name: coredns
+spec:
+  scaleTargetRef:
+    apiVersion: apps/v1
+    kind: Deployment
+    name: coredns
+  minReplicas: 2
+  maxReplicas: 3
+  metrics:
+    - type: Resource
+      resource:
+        name: cpu
+        target:
+          type: Utilization
+          # Deliberately high. See "floor-holder" above: this must not scale on normal DNS load.
+          averageUtilization: 80
+  behavior:
+    scaleDown:
+      # 10 minutes. DNS is the worst thing in the cluster to flap: a scale-down races in-flight
+      # queries and every client's negative cache. The HPA should be reluctant in this direction.
+      stabilizationWindowSeconds: 600
+      policies:
+        - type: Pods
+          value: 1
+          periodSeconds: 600
+    scaleUp:
+      # Prompt in the direction that restores redundancy — this is the path taken after a k3s
+      # restart has re-staged `replicas: 1`.
+      stabilizationWindowSeconds: 0
+      policies:
+        - type: Pods
+          value: 2
+          periodSeconds: 60
@@ -7,3 +7,7 @@ apiVersion: kustomize.config.k8s.io/v1beta1
 kind: Kustomization
 resources:
  - coredns-custom.yaml
+  # HA floor for the coredns Deployment itself — a separate concern from the split-horizon server
+  # block above, and deliberately an HPA rather than a replica edit: k3s owns that Deployment via
+  # its own deploy controller and re-stages `replicas: 1` on restart. hpa.yaml has the reasoning.
+  - hpa.yaml
@@ -154,6 +154,74 @@ NEW client, a new protocol mapper or a changed scope still needs the realm impor
 (it will not on its own) or a deliberate admin-API/`kcadm` change. `Done=True` is never evidence that
 a realm edit landed.

+## Passkeys (WebAuthn Passwordless) — DECLARED IN GIT, NOT YET IN THE REALM (2026-10-17)
+
+`keycloak-realm-import.yaml` now declares passkey login: the realm's **WebAuthn Passwordless**
+policy (`webAuthnPolicyPasswordless*`), and a `browser-mfa` flow that offers a passkey as an
+**ALTERNATIVE** beside the password form. Design decisions and their reasoning are in the manifest
+comments, not repeated here. The headline choices:
+
+| Decision | Value | One-line reason |
+|---|---|---|
+| Additive or replacing? | **Additive** — passkey *or* password | A misfiring mandatory flow locks the single operator out of every SSO app *and* kubectl |
+| Enrolment | **Optional**, never a default action | Same reason; `webauthn-register-passwordless` is already enabled-not-forced by default |
+| Relying-party ID | `${BASE_DOMAIN}` (not `keycloak.${BASE_DOMAIN}`) | An unre-keyable credential must not be bound to a hostname that can move |
+| User verification | `required` | Without it, mere possession of an unlocked device is a complete login |
+| Resident key | `Yes` | A non-discoverable credential is a second factor, not a passkey |
+| OTP after a passkey? | **No** — conditional OTP stays on the password branch | A UV-required passkey is already two factors, and a phishing-resistant pair at that |
+
+### This change does NOT reach the live realm. At all.
+
+Same one-shot failure this file already documents twice above, third field over. Measured on prod
+2026-10-17:
+
+```
+$ kubectl --context k3s-prod -n keycloak get keycloakrealmimport homelab -o jsonpath='{.status}'
+{"conditions":[{"status":"True","type":"Done"},{"status":"False","type":"Started"},
+               {"status":"False","type":"HasErrors"}]}
+```
+
+`Done=True` / `Started=False` — the import has completed and **will not re-run**, so a policy block
+and three new sub-flows added to this file change nothing about how anyone logs in. The
+client-secret/client-URL reconciler does **not** close this gap and was never meant to: its hard
+endpoint allow-list makes `/authentication` unreachable **by design** (see the table above), and
+realm-level policy fields are not client fields. This is exactly the "a NEW client, a new protocol
+mapper or a changed scope still needs the realm import to actually re-run" case named above.
+
+**So the manifest is the declared source of truth and a DR-rebuild input, and nothing more, until
+an operator applies it by hand.** Two paths, both operator actions:
+
+1. **Admin console (expected path).** *Authentication → Policies → WebAuthn Passwordless Policy*
+   for the policy block, then *Authentication → Flows → browser-mfa* to rebuild the executions to
+   match the manifest. The flow edit is the fiddly half: split the existing Username Password Form
+   into Username Form + Password Form and add the two sub-flows exactly as declared.
+2. **A deliberate re-import.** Deleting and recreating the `KeycloakRealmImport` re-runs it against
+   the **existing** realm. Do not reach for this casually — it is the operation whose failure mode
+   is the 2026-09-06 total SSO outage documented above, and it has not been rehearsed here.
+
+Either way the realm is then configured by hand and git is only the record of intent, which is a
+live exception to R-IDP-03 (config as code) — not a new one, but one more instance of it.
+
+### Verifying it actually works (nobody has, as of 2026-10-17)
+
+No passkey has been enrolled and no browser has been pointed at this. The checks that would prove
+it, in order:
+
+```sh
+# 1. the policy is live (RP ID must read as the base domain, NOT the keycloak host, NOT a URL)
+#    Authentication -> Policies -> WebAuthn Passwordless Policy, in the admin console.
+# 2. enrol: account console (https://keycloak.${BASE_DOMAIN}/realms/homelab/account) -> Signing in
+#    -> Passwordless -> set up. A browser/OS passkey prompt must appear; if it does not, the RP ID
+#    is wrong for the origin and NOTHING will say so.
+# 3. log in: a fresh private window to any SSO-gated app. Expect username screen, then a passkey
+#    prompt. A platform-admin must NOT be asked for TOTP on this path.
+# 4. regression (the important one): a user with NO passkey must still get the password screen,
+#    and a platform-admin must still be asked for TOTP there.
+```
+
+A failed passkey ceremony is usually silent in the server log — the browser refuses before Keycloak
+is involved — so step 2 failing with no log entry is the expected signature of a wrong RP ID.
+
 ## Exceptions that keep native auth (do not force SSO) — ADR-0014

 Plex/Seerr (Plex auth), Minecraft (Mojang/Microsoft), UniFi (native).
@@ -74,6 +74,142 @@ spec:
    bruteForceProtected: true
    permanentLockout: false
    sslRequired: external
+    # ===========================================================================================
+    # PASSKEYS — the WebAuthn PASSWORDLESS policy (R-IDP-04). 2026-10-17.
+    # ===========================================================================================
+    # Read this together with the browser-mfa flow at the bottom of the file: THIS block decides
+    # what a passkey must BE, the FLOW decides when one is OFFERED. Keycloak keeps TWO independent
+    # WebAuthn policies per realm and they are not interchangeable:
+    #
+    #   webAuthnPolicy*             -> the TWO-FACTOR policy, consumed by the `webauthn-authenticator`
+    #                                  authenticator (a security key presented AFTER a password).
+    #   webAuthnPolicyPasswordless* -> the PASSWORDLESS policy, consumed by
+    #                                  `webauthn-authenticator-passwordless` (a passkey presented
+    #                                  INSTEAD of a password). This is the one passkeys use.
+    #
+    # Setting the wrong family is a silent no-op: the passwordless authenticator reads
+    # getWebAuthnPolicyPasswordless() only (WebAuthnPasswordlessAuthenticator.getWebAuthnPolicy),
+    # so a policy written into the two-factor fields is simply never consulted by a passkey login.
+    # Only the passwordless family is declared here; the two-factor family is deliberately left at
+    # Keycloak's defaults because nothing in this realm uses `webauthn-authenticator` — TOTP
+    # (auth-otp-form) is the second factor for platform-admins, see the flow section.
+    #
+    # ADDITIVE AND OPTIONAL — THE DECISION THIS BLOCK EXISTS TO MAKE
+    # -------------------------------------------------------------
+    # Passkeys are offered ALONGSIDE the password, never instead of it, and enrolment is NOT forced.
+    # This is a single-operator homelab whose IdP gates Grafana, Gitea, Nextcloud, Headlamp,
+    # Semaphore, PiHole, Crafty, the *arr stack AND kubectl itself (the `kubernetes` client below).
+    # A mandatory passkey flow that misfires is therefore not an inconvenience, it is a total
+    # lock-out from the whole platform AND from the cluster API in one step — and the only repair
+    # paths left would be the Keycloak bootstrap admin and the break-glass cert kubeconfig. The
+    # expected gain from forcing enrolment (one human stops typing a password) is small; the
+    # expected loss is the platform. So: additive, optional, and password login keeps working for
+    # every user who never enrols.
+    #
+    # Concretely that means: no `requiredActions` block is declared anywhere in this file (see the
+    # long note in the flow section for why declaring one would be actively DANGEROUS), and the
+    # passkey step sits as an ALTERNATIVE beside the password form rather than ahead of it.
+    #
+    # RELYING-PARTY ID — THE FIELD THAT SILENTLY BREAKS EVERY PASSKEY IF IT IS WRONG
+    # ------------------------------------------------------------------------------
+    # The RP ID is baked into every credential at enrolment and can never be changed afterwards:
+    # a passkey created under one RP ID is unusable under another, with no error the user can act
+    # on — the browser simply reports that no credential is available. It is also browser-enforced,
+    # so it cannot be "fixed" server-side: per WebAuthn, the RP ID must be equal to, or a
+    # registrable-domain suffix of, the origin's effective domain. Keycloak is served at
+    # keycloak.<BASE_DOMAIN> (httproute.yaml, and the Keycloak CR's hostname), so the legal choices
+    # are keycloak.<BASE_DOMAIN>, <BASE_DOMAIN>, or the registrable domain one level up. It is NOT
+    # the full URL and NOT a scheme — "https://..." here would fail every ceremony.
+    #
+    # We choose BASE_DOMAIN, the shared platform suffix, NOT the keycloak host, for one concrete
+    # reason drawn from this repo's own history: a credential that cannot be re-keyed must not be
+    # bound to a name that can move. The oauth2-proxy client below ALREADY declares a redirect URI
+    # on auth.<BASE_DOMAIN>, i.e. this platform already contemplates serving auth on a second
+    # hostname; and the client-URL reconciler exists precisely because moving a hostname in git
+    # silently fails to reach the realm (see README, "Client URLs: the same one-shot failure").
+    # Binding passkeys to the keycloak subdomain would mean that relocating Keycloak invalidates
+    # every enrolled passkey; binding them to BASE_DOMAIN survives it. The cost is scope: any
+    # future WebAuthn relying party under this base domain could assert the same RP ID. In a
+    # homelab where every such party is already behind THIS IdP that is not a trust boundary worth
+    # buying. Note the residual, unavoidable risk: changing BASE_DOMAIN itself invalidates every
+    # passkey, which is a re-enrolment, not a repair.
+    #
+    # Written as the cluster-var so it is substituted by the same Flux postBuild pass, with the same
+    # value, as every hostname in this file — there is no second place the domain is decided.
+    webAuthnPolicyPasswordlessRpId: ${BASE_DOMAIN}
+    # The human-readable name the browser/OS shows in the passkey prompt and stores beside the
+    # credential ("Save a passkey for Homelab SSO?"). Matches the realm displayName above so the
+    # OS keychain entry is recognisable. It is also load-bearing on the UPDATE path: Keycloak's
+    # updateRealm applies the passwordless policy ONLY when this field is non-empty
+    # (DefaultExportImportManager line ~842), so an admin-API realm update that omits it drops the
+    # whole policy silently.
+    webAuthnPolicyPasswordlessRpEntityName: "Homelab SSO"
+    # ES256 then RS256 — exactly Keycloak's own DEFAULT_POLICY, declared explicitly rather than
+    # inherited so the realm's crypto is auditable from git. ES256 is what every platform
+    # authenticator (Touch ID/Face ID, Windows Hello, Android) and every FIDO2 key produces;
+    # RS256 is the fallback for older Windows Hello TPM-backed credentials. EdDSA/Ed25519 is
+    # deliberately NOT offered: authenticator and browser support is uneven, and an authenticator
+    # that picks an algorithm the verifier handles badly fails at enrolment, which is the worst
+    # moment to discover it. Order is a preference list, not an allow-list ordering requirement.
+    webAuthnPolicyPasswordlessSignatureAlgorithms:
+      - ES256
+      - RS256
+    # DISCOVERABLE CREDENTIAL REQUIRED. "Yes" is a Keycloak sentinel, not a boolean, and the login
+    # theme compares it as the literal string: webauthnRegister.js maps 'Yes' to
+    # authenticatorSelection.requireResidentKey=true and ANY other non-sentinel value to false.
+    # This is not optional for passkeys — a non-discoverable credential cannot be found by the
+    # browser without the server first naming it, so it is a second factor, not a passkey.
+    # (Keycloak 26.0.6 emits only the LEGACY requireResidentKey member, not the newer
+    # residentKey:"required"; per WebAuthn L2 the client maps requireResidentKey=true onto
+    # residentKey="required", so discoverable credentials are genuinely requested — but it also
+    # means this policy cannot express residentKey:"preferred" at all.)
+    webAuthnPolicyPasswordlessRequireResidentKey: "Yes"
+    # USER VERIFICATION REQUIRED. The authenticator must verify the human (biometric or PIN) and
+    # say so in the assertion. This is the field that makes a passkey login at least as strong as
+    # the password it replaces: with verification merely "preferred", possession of an unlocked
+    # phone or an unattended security key would be a COMPLETE login to every SSO-gated app — a
+    # single-factor possession check, strictly weaker than the password+TOTP path beside it.
+    # Required makes the passkey branch inherently two-factor (something you have + something you
+    # are/know), which is the premise the flow section relies on when it does NOT ask a
+    # passkey-authenticated platform-admin for TOTP as well.
+    webAuthnPolicyPasswordlessUserVerificationRequirement: required
+    # "not specified" is Keycloak's sentinel for "either kind of authenticator"
+    # (Constants.DEFAULT_WEBAUTHN_POLICY_NOT_SPECIFIED; the theme JS omits the WebAuthn member
+    # entirely when it sees this exact string). Deliberately NOT narrowed: "platform" would reject
+    # every YubiKey and every phone used as a cross-device passkey, and "cross-platform" would
+    # reject Touch ID and Windows Hello — i.e. either choice silently halves the usable hardware.
+    # The operator should be able to enrol a laptop AND a phone AND a hardware key.
+    webAuthnPolicyPasswordlessAuthenticatorAttachment: "not specified"
+    # ATTESTATION: none. Requesting "direct" would hand Keycloak an attestation statement it has
+    # no trust anchors to validate here (no metadata service is configured) and nothing to compare
+    # it against, since the AAGUID allow-list below is deliberately empty — so the statement would
+    # be collected, unverifiable, and would add an extra "share model information?" consent prompt
+    # on Safari/iOS for no security gain. Attestation is how you ENFORCE an approved-hardware list;
+    # we do not have one, so asking for it is cost without benefit.
+    webAuthnPolicyPasswordlessAttestationConveyancePreference: none
+    # Empty = accept any authenticator model. An AAGUID allow-list is a hardware whitelist: it
+    # would have to be maintained by hand, and every new phone, laptop or key the operator buys
+    # would be rejected at enrolment with a message that does not explain itself. It is also moot
+    # while attestation is "none" (above) — with no attestation statement there is no trustworthy
+    # AAGUID to match against in the first place.
+    webAuthnPolicyPasswordlessAcceptableAaguids: []
+    # Ceremony timeout in SECONDS (the login theme multiplies by 1000; 0 means "send no timeout and
+    # let the browser decide"). 300s is chosen over a tighter value because the slowest LEGITIMATE
+    # path is the cross-device hybrid flow — Keycloak renders a QR code, the operator unlocks a
+    # phone, scans it, and completes a biometric check — which routinely takes over a minute. A
+    # 60-120s timeout looks tidy and converts that flow into an unexplained failure. Browsers clamp
+    # this value (Chrome to at most 10 minutes), so 300 is honoured rather than reinterpreted.
+    webAuthnPolicyPasswordlessCreateTimeout: 300
+    # Send the user's existing passkeys as excludeCredentials at enrolment, so re-enrolling an
+    # authenticator the user already registered is refused by the authenticator itself instead of
+    # producing a second, indistinguishable credential in the account console. Cheap, and it keeps
+    # "which passkey is which" answerable — which matters when the recovery story is "delete the
+    # lost one".
+    webAuthnPolicyPasswordlessAvoidSameAuthenticatorRegister: true
+    # webAuthnPolicyPasswordlessExtraOrigins is intentionally NOT set. It exists to admit non-web
+    # origins (native app facet IDs, e.g. android:apk-key-hash:...). Every ceremony here happens in
+    # a browser on Keycloak's own origin, which is already covered by the RP ID above; adding
+    # origins is only ever a widening of who may ask for these credentials.
    # --- Authorization model (R-IDP-06): groups drive access; platform-admins carry a realm role. ---
    roles:
      realm:
@@ -528,14 +664,105 @@ spec:
              "access.token.claim": "true"
              "userinfo.token.claim": "true"
              "claim.name": groups
-    # --- MFA for platform-admins (R-IDP-04): a browser flow whose OTP step is CONDITIONAL on the
-    #     platform-admin role. Non-admins log in without OTP; platform-admins must enroll/present TOTP.
-    #     Set as the realm browserFlow below. VERIFY at bring-up (see runbook): a malformed flow fails
-    #     the whole import — if so, the fallback is to comment this block + browserFlow and configure
-    #     the conditional-OTP-by-role flow via the admin console. ---
+    # ===========================================================================================
+    # MFA for platform-admins (R-IDP-04) + PASSKEY login (2026-10-17). The realm browserFlow is
+    # bound to browser-mfa at the bottom of this file.
+    # ===========================================================================================
+    # Non-admins log in without OTP; platform-admins must enroll/present TOTP. VERIFY at bring-up
+    # (see runbook): a malformed flow fails the whole import — if so, the fallback is to comment
+    # this block + browserFlow and configure the flow via the admin console.
+    #
+    # THE SHAPE, AND WHY IT IS THIS SHAPE
+    # -----------------------------------
+    #   browser-mfa                           (top level, bound as browserFlow)
+    #     auth-cookie                     ALTERNATIVE   already-authenticated SSO cookie
+    #     identity-provider-redirector    ALTERNATIVE   (no IdPs configured; kept for parity)
+    #     browser-mfa-forms               ALTERNATIVE   the interactive path:
+    #       auth-username-form              REQUIRED      WHO are you (no password yet)
+    #       browser-mfa-passkey-or-password REQUIRED      ...and PROVE it, one of two ways:
+    #         webauthn-authenticator-passwordless  ALTERNATIVE   a passkey, or
+    #         browser-mfa-password-and-otp         ALTERNATIVE   the password path:
+    #           auth-password-form                   REQUIRED      password, then
+    #           browser-mfa-conditional-otp          CONDITIONAL   TOTP iff platform-admin
+    #
+    # WHY THE USERNAME/PASSWORD SCREEN HAD TO BE SPLIT IN TWO. The previous flow used the combined
+    # `auth-username-password-form`, which collects both on one page. A passkey branch cannot live
+    # behind that: the server must know WHICH user is logging in before it can decide whether a
+    # passkey is even available, and the combined form has already taken the password by the time
+    # it knows. So it is replaced by the `auth-username-form` / `auth-password-form` pair — the
+    # same decomposition Keycloak's own passwordless recipe uses. THIS IS A VISIBLE UX CHANGE FOR
+    # EVERY USER, passkey or not: login becomes two screens (username, then password) instead of
+    # one. That cost is accepted deliberately — it is the enabling change, it is what Google and
+    # Microsoft logins already do, and the alternative (below) is worse.
+    #
+    # WHY NOT USERNAMELESS ("just tap your passkey", no username screen at all). Keycloak 26.0.6
+    # does support it: WebAuthnPasswordlessAuthenticator.requiresUser() returns FALSE, so the
+    # authenticator can legally run as a first step with no user in context. We deliberately do not
+    # do that, because of how the flow engine then behaves. In DefaultAuthenticationFlow the
+    # "does this user actually have this credential?" guard sits INSIDE the requiresUser() branch;
+    # with requiresUser() false and no user yet set, the engine skips that guard and simply invokes
+    # the authenticator. A passkey execution placed before the username form is therefore offered
+    # to EVERYONE, so every login — including every password-only user and every family member who
+    # will never own a passkey — would open on a passkey prompt they must dismiss. That is the
+    # opposite of additive. Keeping the passkey step AFTER auth-username-form means a user is in
+    # context, which is what makes the graceful degradation below actually work.
+    #
+    # WHY THE PASSKEY BRANCH DEGRADES CLEANLY TO A PASSWORD (the property the whole "additive"
+    # claim rests on). With a user in context, the engine takes the non-requiresUser branch and
+    # raises CREDENTIAL_SETUP_REQUIRED when the user has no credential of this type and the
+    # authenticator's factory does not allow self-setup — and WebAuthnPasswordlessAuthenticatorFactory
+    # .isUserSetupAllowed() is false, and the authenticator is a CredentialValidator, so both
+    # conditions hold. That exception is raised INSIDE the ALTERNATIVE loop, which catches it,
+    # marks the execution ATTEMPTED and proceeds to the next alternative. Net effect: a user with
+    # no passkey never sees a passkey screen and lands on the password form; a user WITH one gets
+    # the passkey screen and keeps the password as a "Try another way" option. Note that for a
+    # user holding BOTH, which screen appears FIRST is decided by Keycloak's authentication
+    # selection list (the user's own credential ordering), not by the priorities below.
+    #
+    # WHY A PASSKEY LOGIN IS NOT ALSO ASKED FOR TOTP. browser-mfa-conditional-otp hangs off the
+    # PASSWORD branch only, so a platform-admin who authenticates with a passkey is not challenged
+    # for TOTP. That is intentional, and it rests on the policy above: userVerification is
+    # `required`, so the authenticator has already proved possession of hardware AND verified the
+    # human (biometric or PIN) in one phishing-resistant, origin-bound ceremony. Stacking TOTP on
+    # top would add a replayable, phishable shared secret to a credential that is neither, for
+    # friction on every login. If a future operator disagrees, the change is small and local: move
+    # the browser-mfa-conditional-otp reference out of browser-mfa-password-and-otp and into
+    # browser-mfa-passkey-or-password's parent as a REQUIRED step, so it applies to both branches.
+    #
+    # WHY THERE IS NO `requiredActions` BLOCK IN THIS FILE — DO NOT ADD ONE
+    # --------------------------------------------------------------------
+    # Enrolment uses Keycloak's `webauthn-register-passwordless` required action, and the obvious
+    # move is to declare it here. DO NOT. In Keycloak 26.0.6 the realm import treats
+    # requiredActions as REPLACE, NOT MERGE: DefaultExportImportManager.importRealm branches on
+    # `if (rep.getRequiredActions() != null)` and, when the representation declares ANY, imports
+    # exactly those plus delete_account — the `else` branch that installs the full default set
+    # (DefaultRequiredActions.addActions) never runs. RealmManager.setupRequiredActions is no
+    # backstop either: it fires only when the realm has ZERO required-action providers.
+    #
+    # So declaring one action would create this realm with that action and delete_account and
+    # NOTHING ELSE — no CONFIGURE_TOTP, no UPDATE_PASSWORD, no VERIFY_EMAIL, no delete_credential,
+    # no UPDATE_PROFILE. The first casualty would be the MFA requirement this very flow enforces:
+    # with CONFIGURE_TOTP unregistered, a platform-admin who does not yet have TOTP could never
+    # enrol one, while auth-otp-form below still demands it — a hard lock-out of every
+    # platform-admin from every SSO-gated app, including Headlamp and kubectl, delivered by a
+    # change whose stated purpose was to ADD a login method.
+    #
+    # And the declaration buys nothing, because the default set ALREADY CONTAINS IT.
+    # DefaultRequiredActions registers `webauthn-register-passwordless` with enabled=true,
+    # defaultAction=false, priority 80, gated on Profile.Feature.WEB_AUTHN — which is Type.DEFAULT
+    # in 26.0.6, i.e. on unless explicitly disabled. enabled=true / defaultAction=false IS the
+    # additive-and-optional posture this change wants: the action exists and can be triggered for
+    # a user on demand, but it is not forced on anyone at next login. Declaring it would restate
+    # the default while deleting ten siblings.
+    #
+    # (The symmetric question for authenticationFlows has the opposite answer, which is why THIS
+    # block is safe: importAuthenticationFlows adds the declared flows and then backfills each
+    # unbound binding — browser, registration, direct grant, reset credentials, client auth, first
+    # broker login, docker auth — from the built-in defaults individually. Declaring flows does not
+    # suppress the built-ins; declaring required actions does suppress them.)
    authenticationFlows:
      - alias: browser-mfa
-        description: "Browser flow with conditional OTP required for platform-admins."
+        description: "Browser flow: passkey or password, with conditional OTP for platform-admins."
        providerId: basic-flow
        topLevel: true
        builtIn: false
@@ -555,13 +782,63 @@ spec:
            priority: 30
            flowAlias: browser-mfa-forms
            userSetupAllowed: false
+      # Identify the user FIRST (username only), then prove it. Both steps are REQUIRED: the
+      # username is never optional, and neither is proving possession of the account.
      - alias: browser-mfa-forms
-        description: "Username/password then conditional OTP."
+        description: "Username, then passkey or password (+ conditional OTP)."
        providerId: basic-flow
        topLevel: false
        builtIn: false
        authenticationExecutions:
-          - authenticator: auth-username-password-form
+          # auth-username-form = Keycloak's "Username Form" (UsernameFormFactory) — resolves the
+          # user WITHOUT taking a password, which is the prerequisite for offering a passkey.
+          # Replaces the previous auth-username-password-form; see the header for the UX cost.
+          - authenticator: auth-username-form
+            authenticatorFlow: false
+            requirement: REQUIRED
+            priority: 10
+            userSetupAllowed: false
+          - authenticatorFlow: true
+            requirement: REQUIRED
+            priority: 20
+            flowAlias: browser-mfa-passkey-or-password
+            userSetupAllowed: false
+      # THE FORK. Two ALTERNATIVEs, so satisfying either one completes the flow. Priority puts the
+      # passkey first for users who have one; users who do not fall through to the password branch
+      # automatically (CREDENTIAL_SETUP_REQUIRED is caught by the ALTERNATIVE loop — see header).
+      - alias: browser-mfa-passkey-or-password
+        description: "A passkey (WebAuthn passwordless), or password with conditional OTP."
+        providerId: basic-flow
+        topLevel: false
+        builtIn: false
+        authenticationExecutions:
+          # webauthn-authenticator-passwordless = "WebAuthn Passwordless Authenticator"
+          # (WebAuthnPasswordlessAuthenticatorFactory). It reads the realm's PASSWORDLESS policy
+          # declared above — NOT the two-factor webAuthnPolicy* family. Keep it ALTERNATIVE: as
+          # REQUIRED it would force a passkey on every user, which is the lock-out this change is
+          # explicitly designed not to create.
+          - authenticator: webauthn-authenticator-passwordless
+            authenticatorFlow: false
+            requirement: ALTERNATIVE
+            priority: 10
+            userSetupAllowed: false
+          - authenticatorFlow: true
+            requirement: ALTERNATIVE
+            priority: 20
+            flowAlias: browser-mfa-password-and-otp
+            userSetupAllowed: false
+      # The unchanged pre-passkey behaviour, relocated intact into the password branch: password,
+      # then TOTP iff the user holds the platform-admin role. Nothing about the OTP condition
+      # changed; it simply no longer sits on the path a passkey login takes.
+      - alias: browser-mfa-password-and-otp
+        description: "Password, then conditional OTP for platform-admins."
+        providerId: basic-flow
+        topLevel: false
+        builtIn: false
+        authenticationExecutions:
+          # auth-password-form = Keycloak's "Password Form" (PasswordFormFactory) — the password
+          # half of the old combined form, now that the username has already been collected.
+          - authenticator: auth-password-form
            authenticatorFlow: false
            requirement: REQUIRED
            priority: 10
@@ -0,0 +1,162 @@
+# cluster-maintenance-shutdown — powering the whole cluster off, and back on
+
+**Operator procedure, not an alert page.** Nothing links here from an alert.
+**Script:** `infra/maintenance/quiesce.sh` (`quiesce` | `resume` | `status`)
+**Related:** `/runbooks/update-rollback` is for rolling node work where the cluster stays up. This
+page is for taking **all three nodes down at once**.
+
+First written after the 2026-10-17 UPS move, which was improvised live because no procedure
+existed — `infra/cluster.sh stop` is `virsh`-based and only ever applied to the decommissioned dev
+cluster, so it does nothing for these three baremetal nodes.
+
+## Why you cannot just run `shutdown -h`
+
+You mostly can now, and could not before.
+
+Until 2026-10-17 **kubelet graceful node shutdown was unconfigured on every prod node**, so systemd
+stopped k3s, containerd went with it, and every pod was SIGKILLed where it stood — 9 Postgres
+instances mid-checkpoint, the UniFi VM, and 25 attached Longhorn volumes.
+`roles/k3s_server` now sets `shutdown-grace-period` (and, critically, the
+`InhibitDelayMaxSec` logind cap that actually enforces it — without that systemd stops waiting
+after 5s and the drain is silently truncated). A plain reboot of one node is therefore safe.
+
+**A planned whole-cluster shutdown still wants `quiesce`**, for three things the kubelet's drain
+does not do:
+
+1. **The UniFi VM needs an ACPI guest shutdown**, not an eviction. KubeVirt does that on
+   `running: false`; an eviction is a power cut to the guest.
+2. **CloudNativePG wants hibernation**, not pod deletion — and hibernation is **imperative** state
+   that Flux will neither set nor clear.
+3. **Draining three nodes one at a time makes pods reschedule onto the survivors**, churning
+   Longhorn replicas for no reason when everything is going down anyway. Scaling in place avoids it.
+
+## The hazard that bit us — read this before scaling anything by hand
+
+**A StatefulSet can carry `persistentVolumeClaimRetentionPolicy.whenScaled: Delete`, and scaling it
+to 0 then DELETES its PVCs and their Longhorn volumes.**
+
+On 2026-10-17 the hand-rolled quiesce scaled `monitoring/loki` (which has that policy) to 0, and
+`storage-loki-0` was deleted outright. Loki stores with `type: filesystem`, so that PVC was the only
+copy. Its 72h retention bounded the loss to a rolling window — nothing about the *mechanism* is
+bounded. The only visible symptom was the Longhorn volume count going 25 → 24, which was first
+misread as a miscount.
+
+`quiesce.sh` now refuses to scale any such StatefulSet, leaves it running, and tells you which
+volumes to expect `degraded` on restart. **If you quiesce by hand, check the policy first:**
+
+```bash
+kubectl --context k3s-prod get statefulset -A \
+  -o custom-columns='NS:.metadata.namespace,NAME:.metadata.name,WHEN_SCALED:.spec.persistentVolumeClaimRetentionPolicy.whenScaled'
+```
+
+A hard-detached volume comes back `degraded` and rebuilds itself automatically. That is a vastly
+better outcome than a deleted one — take the rebuild.
+
+## Shutting down
+
+Run everything through the pinned toolbox; it supplies `kubectl` and the context.
+
+```bash
+# 0. Look before you leap. Refuses to proceed if any Longhorn volume is unhealthy —
+#    powering off on top of a degraded volume is how one replica becomes zero.
+./infra/devcontainer/dev.sh run bash -c './infra/maintenance/quiesce.sh status'
+
+# 1. Quiesce: suspend Flux, ACPI-stop the VM, hibernate Postgres, scale down every
+#    PVC-holding workload (NFS consumers first, PiHole last), wait for detach.
+./infra/devcontainer/dev.sh run bash -c './infra/maintenance/quiesce.sh quiesce'
+```
+
+**Expect DNS to stop** when PiHole scales down — it is the LAN resolver. `kubectl` is unaffected
+because the kubeconfig points at the kube-vip IP `192.168.2.9`, not a name.
+
+```bash
+# 2. Power the nodes off. Inside the devcontainer, which holds the become password.
+./infra/devcontainer/dev.sh run bash -c \
+  'cd /work/infra/ansible && ansible -i inventory/hosts.ini k3s_prod -b \
+     -m shell -a "shutdown -h +1 \"maintenance\""'
+```
+
+`+1` gives Ansible time to disconnect cleanly. The group resolves to all three nodes; confirm with
+`--list-hosts` if you want to see them first.
+
+```bash
+# 3. Confirm they are actually down before touching anything else.
+for h in 192.168.2.10 192.168.2.11 192.168.2.12; do ping -c1 -W2 $h >/dev/null && echo "$h UP" || echo "$h down"; done
+```
+
+**Then, in this order and not before:**
+
+| # | Machine | How |
+|---|---|---|
+| 4 | **TrueNAS** `192.168.2.30` | **Web UI only.** Not in the ansible inventory, and SSH is **refused** (service disabled). `https://192.168.2.30` → power icon → Shut Down. Safe once the nodes are down, because every NFS consumer (`plex-media`, `*-media`, `qbittorrent-downloads`, `nextcloud-legacy-archive`) is already scaled to zero and nothing holds a hard mount. |
+| 5 | **Router / switch** | Last. |
+
+TrueNAS must go **after** the k3s nodes: a hard NFS mount on a live node wedges kubelet in
+D-state (`/runbooks/nfs-export-latency`, and the load-average symptom in the 2026-10-?? note).
+
+## Bringing it back
+
+**Power on in the reverse order: router/switch → TrueNAS → all three nodes together.** etcd needs
+2 of 3 for quorum, so start the nodes as a group rather than one at a time.
+
+```bash
+# 1. Nodes Ready, etcd quorum, storage reachable.
+./infra/devcontainer/dev.sh run bash -c 'kubectl --context k3s-prod get nodes'
+./infra/devcontainer/dev.sh run bash -c 'kubectl --context k3s-prod get --raw=/healthz/etcd'
+
+# 2. Resume: un-hibernate Postgres, then resume Flux.
+./infra/devcontainer/dev.sh run bash -c './infra/maintenance/quiesce.sh resume'
+```
+
+**Un-hibernating Postgres is the step everyone forgets.** The annotation is imperative and survives
+a Flux resume, so resuming Flux alone leaves all three databases down and Keycloak, Nextcloud and
+Semaphore looking broken for reasons that point nowhere near Postgres. `resume` does it first, for
+exactly that reason.
+
+Flux restores every scaled-down replica count **and** the VM's `running: true` from git, so nothing
+needs undoing by hand.
+
+### What "still broken" looks like when it is actually fine
+
+* **`4/19` Kustomizations Ready for several minutes.** The dependency graph serialises behind
+  `platform-config`; 15 of them report `dependency ... is not ready` until it finishes. Check
+  `platform-config` itself is `Ready=True` and its `lastAppliedRevision` matches the GitRepository
+  artifact — if it is, wait.
+* **One or more Longhorn volumes `degraded`.** Any volume that was still attached at poweroff
+  rebuilds its lagging replica automatically. On 2026-10-17 it was Prometheus's 50Gi TSDB; it went
+  healthy on its own. Worry only if it is still degraded after ~30 minutes.
+* **`keycloak-operator` crashlooping, then recovering.** It is the CRD reconciler, not in the
+  request path; Keycloak's StatefulSet stays 2/2 and auth never goes down. See
+  `/runbooks/keycloak-*` and the known OOM-at-450Mi behaviour.
+
+### What is actually broken and needs you
+
+* **An `oauth2-proxy` replica stuck in CrashLoopBackOff.** It performs OIDC discovery at startup and
+  **exits 1** on the `503 no healthy upstream` it gets while Keycloak is still coming up, then sits
+  in exponential backoff long after Keycloak is fine. It has no startup dependency on Keycloak.
+  Delete the pod once and it comes up clean:
+
+  ```bash
+  ./infra/devcontainer/dev.sh run bash -c \
+    'kubectl --context k3s-prod -n oauth2-proxy delete pod <name>'
+  ```
+
+* **Orphaned `Unknown`/`Error` Job pods** from CronJobs that were mid-run at poweroff. They never
+  recover; delete them.
+
+## Verifying you are actually back
+
+```bash
+./infra/devcontainer/dev.sh run bash -c './infra/maintenance/quiesce.sh status'
+# nodes 3 Ready | flux 19/19 | longhorn 0 not healthy | postgres 9 pods | unifi 1 VMI
+
+# DNS, through PiHole's VIP
+./infra/devcontainer/dev.sh run bash -c 'nslookup home.keithjackson.dev 192.168.2.23'
+
+# The Gateway actually serving (401 on an auth-gated host is CORRECT)
+for h in home.keithjackson.dev gitea.home.keithjackson.dev plex.home.keithjackson.dev; do
+  curl -s -o /dev/null -w "$h %{http_code}\n" -k --resolve $h:443:192.168.2.20 https://$h/
+done
+```
+
+Expect `200`, `200`, `401`.
@@ -52,6 +52,13 @@ configMapGenerator:
      - backup-failure=backup-failure.md
      - backup-missed=backup-missed.md
      - backup-partial=backup-partial.md
+      # Operator procedure, not an alert page — nothing links here from an alert. Served because
+      # the whole-cluster shutdown had NO written procedure until 2026-10-17 (infra/cluster.sh is
+      # virsh-based and only ever applied to the decommissioned dev cluster), so the UPS move was
+      # improvised live, and the one hazard it exposed -- a StatefulSet with
+      # persistentVolumeClaimRetentionPolicy whenScaled: Delete loses its PVC when scaled to 0 --
+      # destroyed monitoring/loki's volume before anyone noticed.
+      - cluster-maintenance-shutdown=cluster-maintenance-shutdown.md
      - cdi-import-stuck=cdi-import-stuck.md
      - cert-expiry=cert-expiry.md
      - cert-issuance=cert-issuance.md
Author	SHA1	Message	Date
jakman85andClaude Opus 5	fda5c31a94	fix(pihole): make the split-horizon answer cacheable, or one blip latches the WAN IP for 5 minutes gate / gate (pull_request) Successful in 1m56s Details gate / conformance (pull_request) Has been skipped Details Operator reported DNS flapping between the cluster ingress and the router's public IP. PiHole is not at fault -- both replicas answer 192.168.2.20 consistently (6/6 via the VIP, 8/8 from a client). The bug is an asymmetry in CACHEABILITY that we created. Measured: pihole 192.168.2.23 -> 192.168.2.20 TTL=0 public 1.1.1.1 -> wan.home.keithjackson.dev TTL=300 router 192.168.2.1 -> wan.... TTL=153 -> 148 -> 143 (decrementing = caching) dnsmasq answers `address=` entries with TTL 0 unless told otherwise. The router forwards LAN queries to PiHole and caches the result, so the CORRECT answer is uncacheable -- re-queried on every lookup, maximum exposure to any gap -- while the WRONG answer caches for 300s. The instant the router falls back to upstream (standard forwarder behaviour when the target does not answer) it latches the WAN address for the whole LAN for five minutes, then expires, re-queries PiHole, gets TTL 0, and is immediately re-exposed. So ONE sub-second PiHole gap -- pod restart, L2 lease move, ARP flap, kured reboot -- becomes FIVE MINUTES of the house resolving to the WAN IP. That asymmetry, not the gap, is why it reads as "flapping". Fix: local-ttl=60 prepended to FTLCONF_misc_dnsmasq_lines. dnsmasq applies local-ttl to replies made from configuration, so one directive covers all five address= names. 60s rides out a pod restart and a lease re-election while a real VIP change still propagates inside a minute; these VIPs are pinned and static. apps/wave-0/pihole.yaml regenerated with the canonical render command (--all catalog -o apps --wave-layout --no-image-automation, NOT --emit-waves); exactly two files changed and the rendered diff is the single local-ttl prefix. UNAPPLIED. Does NOT remove the trigger: .23 still has two independently-elected L2 leases (as do crafty .22 and unifi .21), which the operator has parked. If the TTL is still 0 after merge, suspect FTL silently rejecting the passthrough line -- see the handoff. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>	2026-10-18 02:56:49 -05:00
jakman85	c340bbfc4b	Merge pull request 'fix(conformance): one regex made the merge gate take 28 minutes instead of 2' (#76 ) from fix/ha-check-catastrophic-regex into main gate / gate (push) Successful in 1m56s Details gate / conformance (push) Has been skipped Details Reviewed-on: #76 Reviewed-by: Keith Jackson <[email protected]>	2026-10-18 07:51:51 +00:00
jakman85	a9a529750d	Merge pull request 'fix(unattended-upgrades): Debian has no reboot-sentinel package, so ship the writer' (#75 ) from fix/unattended-upgrades-debian-sentinel into main gate / conformance (push) Has been cancelled Details gate / gate (push) Has been cancelled Details Reviewed-on: #75	2026-10-18 07:40:20 +00:00
jakman85andClaude Opus 5	793c3940a8	fix(conformance): one regex made the merge gate take 28 minutes instead of 2 gate / gate (pull_request) Successful in 1m55s Details gate / conformance (pull_request) Has been skipped Details ha-control-plane-as-code/check.sh had: re.search(r"--server https://.?\n(?:.\n){0,10}?\swhen:...'secondary'", K3S_TEXT, re.S) With re.S every `.` matches newlines, so `.?` and the nested `(?:.\n){0,10}?` can each consume the whole document -- nested unbounded repetition, which backtracks exponentially on a failed or late match. MEASURED in CI via `docker top` on the live job container: python3 at 19:54 of CPU time, which is essentially the entire ~28 minute gate. Localised to the exact line by extracting the inline python and running it under faulthandler.dump_traceback_later, which named re/__init__.py:177 in search from this call -- not inferred from reading. Replaced `.` with `[^\n]` and dropped re.S, so the {0,10} is a real ten-line window with nothing to backtrack into. On the real input (22,179 chars): 0.2 ms, match still found. Whole check: 0.199s, rc 0, 115 assertions, identical success message. WHY IT SURFACED NOW, AND IT WAS MINE: K3S_TEXT is every .yml in roles/k3s_server concatenated. The regex was latent for as long as it existed; PR #71 added ~100 lines to that role (kubelet graceful-shutdown config), growing the input past the point where exponential backtracking stopped being survivable. WHY ONLY infra/* WAS SLOW: touched-requirements.sh maps infra/* to R-ENV-01, so the L0 run becomes --include-scope whole-repo --requirements R-ENV-01, which selects this whole-repo check. Doc/platform changes never did -- #69 1m55s and #72 1m53s stayed fast while #71 27m44s, the #73 merge 27m46s and #75 all ran ~28m. The pattern is unique in the repo (grep over all l0-static check.sh files). Not re-timed in CI post-fix; this PR's own run is the first datapoint. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>	2026-10-18 02:38:23 -05:00
jakman85andClaude Opus 5	ef8ef5ac29	fix(unattended-upgrades): Debian has no reboot-sentinel package, so ship the writer gate / gate (pull_request) Successful in 27m51s Details gate / conformance (pull_request) Has been skipped Details The first real run failed on all three nodes: fatal: [k3s-prod-1]: "No package matching 'update-notifier-common' is available" update-notifier-common is an UBUNTU package and does not exist in Debian -- `apt-cache policy` returns Candidate: (none) on trixie. The role asserted it "owns the hook that creates /var/run/reboot-required", which is true on Ubuntu and false here, so the role could never have worked. Three further measurements settled the replacement: notify-reboot-required is absent; NO linux-image-* postinst references it (invoking it is an Ubuntu patch, so dropping a script at that path would never be called); and no hook under apt.conf.d or /etc/kernel mentions reboot-required. Debian trixie ships no mechanism at all. So the role now provides it: * /usr/local/sbin/k3s-notify-reboot-required -- touches the sentinel when the running kernel is not the newest installed, using `linux-version` (from linux-base, a dependency of every linux-image, measured present) because kernel version ordering is not string ordering. * /etc/apt/apt.conf.d/99-k3s-reboot-required -- DPkg::Post-Invoke, `\|\| true` so it can never abort an apt transaction. /run is tmpfs (measured), so the sentinel self-clears on boot; no cleanup task. The verify assert was ALSO weaker than it looked: a `find` glob for update-notifier / unattended-upgrades under apt.conf.d would have matched Debian's own unattended-upgrades conffile and reported "writer present" while none existed. It now stats the two exact paths this role owns and requires the script to be executable. Newly verified: the script ran on prod-1 as unprivileged k3s under sh -x -- running=newest=7.1.8+deb13-amd64, took the equal branch, exited 0, wrote nothing. Correct. sh -n and bash -n clean. Still unverified: the WRITING half never executes while running == newest, so the sentinel has not been seen created and kured has not been seen react. The honest test is the next kernel upgrade. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>	2026-10-18 01:43:43 -05:00
jakman85	ee196c7bcd	Merge pull request 'feat(upgrades): automate node reboots (kured) and wire Renovate, which had never run' (#73 ) from feat/automated-upgrades into main gate / gate (push) Successful in 27m46s Details gate / conformance (push) Has been skipped Details Reviewed-on: #73 Reviewed-by: Keith Jackson <[email protected]>	2026-10-18 06:28:30 +00:00
jakman85	83d3568150	Merge pull request 'feat(shutdown): configure graceful node shutdown, and never scale a Delete-policy StatefulSet' (#71 ) from feat/graceful-cluster-shutdown into main gate / gate (push) Successful in 27m39s Details gate / conformance (push) Has been skipped Details Reviewed-on: #71	2026-10-18 05:51:20 +00:00
jakman85	24bea918ab	Merge pull request 'fix(coredns): hold in-cluster DNS at 2 replicas via an HPA, because k3s owns the Deployment' (#74 ) from fix/coredns-ha into main gate / conformance (push) Has been cancelled Details gate / gate (push) Has been cancelled Details Reviewed-on: #74	2026-10-18 05:50:46 +00:00
jakman85andClaude Opus 5	5642881c4d	fix(coredns): hold in-cluster DNS at 2 replicas via an HPA, because k3s owns the Deployment gate / gate (pull_request) Successful in 1m52s Details gate / conformance (pull_request) Has been skipped Details MEASURED on prod 2026-10-18: kube-system/coredns had replicas: 1. In-cluster DNS was a single pod on a single node, so draining or rebooting that node was a CLUSTER-WIDE in-cluster DNS outage until the pod rescheduled -- every Service lookup, every CNPG replica finding its primary, every operator addressing the API by name. It was invisible because 1/1 Ready looks healthy. It is urgent rather than latent now: the scheduled reboot automation on feat/automated-upgrades drains and reboots one node at a time, unattended, overnight -- turning a single point of failure into a recurring one. WHY AN HPA AND NOT replicas: 2 -- the whole decision. k3s OWNS the coredns Deployment: AddOn/coredns, source /data/k3s/server/manifests/coredns.yaml, managedFields managers deploy@k3s-prod-1 + k3s, objectset.rio.cattle.io/hash label. k3s re-stages its bundled manifests on startup, so replicas: 2 written there -- or a kubectl scale -- is reverted on the next restart or upgrade. Rejected alternatives: * coredns.yaml.skip + our own templated copy (the roles/kube_vip pattern). Deterministic, but takes ownership of coredns from k3s permanently so k3s upgrades stop updating it. Too high a price for a replica count. * A Flux patch of the Deployment. Rejected outright: Flux and k3s's deploy controller would both own one object and fight -- the default-deny NetworkPolicy drift-loop shape (~2500 events/10min) this cluster already hit. An HPA is a separate object k3s does not own, driving /scale rather than the Deployment spec, so there is no shared-ownership fight; if k3s re-stages replicas: 1 it is re-asserted within a reconcile. Disclosed cost: a brief window at 1 replica after a k3s restart. It is a FLOOR-HOLDER, not an autoscaler -- the CPU metric exists only so the autoscaling/v2 object is valid. Measured: 5m/4m against a 100m request (~5%), so the 80% target is never approached. scaleDown stabilization 600s because DNS is the worst thing to flap; scaleUp immediate, since that restores redundancy. The kustomization edit is ADDITIVE: platform/coredns/ already existed and holds the coredns-custom split-horizon ConfigMap (R-DNS-01/03), which is untouched. UNAPPLIED. The HPA has never run, and the claim that k3s reverts replicas on restart is reasoned, not observed. After merge check `describe hpa coredns` for ScalingActive=True -- an inert HPA looks identical to a working one because the hand scale already left 2 replicas. See the handoff entry. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>	2026-10-18 00:44:09 -05:00
jakman85	4d489f2059	Merge pull request 'feat(keycloak): add passkey (WebAuthn passwordless) login, additive and optional' (#72 ) from feat/keycloak-passkeys into main gate / gate (push) Successful in 1m53s Details gate / conformance (push) Has been skipped Details Reviewed-on: #72	2026-10-18 05:44:03 +00:00
jakman85andClaude Opus 5	16894b7b73	feat(keycloak): declare passkey (WebAuthn passwordless) login for the homelab realm gate / gate (pull_request) Successful in 1m53s Details gate / conformance (pull_request) Has been skipped Details Adds the realm's WebAuthn Passwordless policy and restructures the browser-mfa flow so a passkey is an ALTERNATIVE beside the password form. Additive and optional by design: this IdP gates every SSO app plus kubectl, so a mandatory passkey flow that misfires is a total lock-out. Enrolment is not forced. Policy: RP ID is ${BASE_DOMAIN} (not the keycloak host) because a passkey's RP ID is fixed at enrolment and must not be bound to a name that can move; resident key required (a non-discoverable credential is a second factor, not a passkey); user verification required (without it, possession alone is a complete login). Flow: auth-username-password-form is split into auth-username-form + auth-password-form, because the server must know who is logging in before it can decide whether a passkey exists. Conditional OTP for platform-admins is relocated intact onto the password branch only — a UV-required passkey is already two phishing-resistant factors. No requiredActions block is declared, deliberately: Keycloak 26.0.6 treats requiredActions as REPLACE not merge, so declaring one would delete the default set including CONFIGURE_TOTP and lock every platform-admin out of the OTP step this flow still enforces. webauthn-register-passwordless is already registered enabled-but-not-default by Keycloak's own defaults. UNAPPLIED: the realm import is a one-shot resting at Done=True/Started=False, so this reaches the live realm never. See the handoff entry and the README section. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>	2026-10-17 23:23:36 -05:00
jakman85andClaude Opus 5	2f2e98aa19	feat(shutdown): configure graceful node shutdown, and never scale a Delete-policy StatefulSet gate / gate (pull_request) Successful in 27m44s Details gate / conformance (pull_request) Has been skipped Details All three nodes had to be powered off to move them onto a UPS, and there was NO procedure: infra/cluster.sh stop is virsh-based and only ever applied to the decommissioned dev cluster. The sequence was improvised live. Two defects came out of doing it. 1. GRACEFUL NODE SHUTDOWN WAS UNCONFIGURED ON EVERY PROD NODE. No shutdownGracePeriod anywhere in infra/ansible/, so `shutdown -h` stopped k3s, containerd went with it, and every pod was SIGKILLed where it stood -- 9 CNPG instances mid-checkpoint, the UniFi VM, 25 attached Longhorn volumes. roles/k3s_server now sets kubelet-arg shutdown-grace-period=90s and shutdown-grace-period-critical-pods=20s. The half that silently defeats the other half: this is enforced by LOGIND, not the kubelet. The kubelet holds an inhibitor DELAY lock and systemd waits at most InhibitDelayMaxSec -- DEFAULT 5 SECONDS -- then proceeds regardless, truncating the drain with no error. The role ships a logind.conf.d drop-in (120) and ASSERTS cap >= grace period, because the failure is invisible. 2. SCALING A StatefulSet TO 0 DELETED ITS PVC AND VOLUME. monitoring/loki carries persistentVolumeClaimRetentionPolicy whenScaled: Delete, so the quiesce destroyed storage-loki-0 outright. Loki stores type: filesystem, so that PVC was the only copy; 72h retention bounded the loss, the mechanism does not. Symptom was the volume count going 25 -> 24, first misread as a miscount. Repaired: scale back to the declared 1 recreated the PVC and loki-0 is 2/2 Running. New infra/maintenance/quiesce.sh (quiesce\|resume\|status) encodes the sequence that worked and REFUSES to scale any whenScaled: Delete StatefulSet -- it stays running, its volume hard-detaches, and it rebuilds on restart. A rebuild beats a deletion. Discovery is computed from the live cluster, so a newly onboarded service needs no edit here. runbooks/cluster-maintenance-shutdown.md is the operator page: order in both directions, TrueNAS-after-nodes (hard NFS mount wedges kubelet), the un-hibernate-Postgres step Flux will NOT do for you, and a "looks broken but is fine" section separating the 4/19 Flux cascade, the degraded-and-rebuilding volume and the self-recovering keycloak-operator from the one thing that needs a human (a stuck oauth2-proxy replica). THE KUBELET CHANGE HAS NEVER BEEN APPLIED OR TESTED -- it needs a rolling k3s restart, which is an operator action. Review config.yaml's kubelet-arg before applying: a bad config.yaml is how k3s fails to come up. See the handoff entry. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>	2026-10-17 22:26:47 -05:00