feat(shutdown): configure graceful node shutdown, and never scale a Delete-policy StatefulSet

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

infra/ansible/roles/k3s_server/tasks/main.yml

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