feat(ha): the CNI dials the control-plane VIP — kube-vip becomes a CNI prerequisite

OPERATOR DECISION 2026-09-06: "use the VIP as intended — a virtual address to reach
the cluster and provide fault tolerant HA. Without a change it will not work in HA."

THE DEFECT. Cilium's kube-proxy replacement dialled a SINGLE NODE. Re-confirmed live
before changing anything: all three prod cilium-agent pods carried
KUBERNETES_SERVICE_HOST=192.168.2.10 — k3s-prod-1's own address — while the kube-vip
VIP 192.168.2.9 was Running on all three nodes with a held lease. Lose prod-1 and the
CNI's control-plane path is dead on an "HA" cluster. clusters/prod's own comment said
the value must be the VIP and NOT .10, then called it "Not yet decided" — I treated
that stale comment as an open question when the evidence already settled it.

SPLIT, NOT REPOINT, because k3s_api_host had two consumers with opposite needs:
  k3s_api_host            unchanged — the FOUNDER's IP: the cold-bootstrap join
                          target and a tls-san. infra/tofu/outputs.tf GENERATES this
                          name, so renaming would ripple into tofu and the runbooks.
  k3s_apiserver_endpoint  NEW = {{ kube_vip_address }} — the HA address; what Cilium
                          consumes. Derived, not restated, so an environment overrides
                          ONE line and the VIP, the SAN and the CNI endpoint move
                          together. Prod needed no new override.

THE SECOND HAZARD, WHICH MY BRIEF DID NOT NAME and the agent found: pointing Cilium at
the VIP breaks a COLD bootstrap for the same reason the join would — site.yml ran
node-baseline -> k3s -> cilium, so Cilium would install against an address nothing
announced yet. That is the 2026-09-01 deadlock shape. Fixed by SEQUENCE, not value:
site.yml now imports kube-vip.yml BETWEEN k3s and cilium. It cannot go earlier
(kube-vip is a k3s auto-deploy manifest, so it needs a cluster) and it works there
because the DaemonSet is hostNetwork with KUBERNETES_SERVICE_HOST=127.0.0.1 — needing
neither CNI nor kube-proxy. roles/kube_vip gained a read-only `wait_for` on the VIP so
a cold run stops THERE with a named cause instead of surfacing as unreachable agents.

Also fixed a pre-existing bug that only mattered once this play joined site.yml: the
role's read-only interface probe ran without `check_mode: false`, so under --check it
was skipped and the assert fired with a misleading "set kube_vip_interface explicitly".

VERIFIED BY ME, not just reported:
  renders    dev K3S_API_HOST=192.168.1.49   prod=192.168.2.9  (each environment's VIP)
  cilium     template consumes k3s_apiserver_endpoint, not k3s_api_host
  cold join  still `--server https://{{ k3s_api_host }}:6443` — the founder
  order      site.yml: node-baseline -> k3s -> kube-vip -> cilium -> verify -> flux
  gate       full CI gate PASS
Agent-side, additionally: in-memory render of cilium-values.yaml.j2 per host showing
k8sServiceHost=the VIP with the join still on the founder; k3s_tls_sans renders
['.10','.9','127.0.0.1','.11','.12'] so NO cert reissue and NO k3s restart is involved
— .9 already answers under full CA verification; and --check --diff of kube-vip.yml
against prod reported 6 ok / 0 changed, i.e. the role edits change nothing about the
kube-vip prod already runs.

ha-control-plane-as-code 92 -> 112 assertions, turning two escalations into machine
checks: the Cilium template must use the endpoint var; the endpoint must derive from
kube_vip_address and k3s_api_host must not; per environment K3S_API_HOST must equal
that environment's VIP and be none of its node IPs (the [parity] contract, now
machine-checked rather than a comment); site.yml must order k3s -> kube-vip -> cilium.
Every new assertion mutation-tested and bites. One honest negative recorded: reverting
only the BASE default is not caught, because both overlays patch the key — the check
reads effective per-environment values, so the base default is unguarded.

APPLY ORDER, and this is the operator's step — nothing was applied:
  PROD FIRST, and it is the low-risk direction (prod is the broken one). Push and let
  Flux reconcile platform/cilium: the value change rolls the cilium-agent DaemonSet
  ONE NODE AT A TIME (maxUnavailable: 1 — the knob that bounded the 2026-09-01
  incident), it will not proceed past an unready pod, existing datapath survives an
  agent restart, and .9 is already live before the change lands.
  DEV SEPARATELY, operator present. Same mechanics but live dev agents dial
  192.168.1.50, and dev is mid-DNS-migration on dev-live. Do not fold it into that.
  ANSIBLE: nothing to run for either live cluster; the Ansible half matters only for a
  cold build. Remove the now-redundant standalone kube-vip.yml step from any runbook.

NEW NAMED GAP, unwritten: the L2 test cannot assert the running agents' live
KUBERNETES_SERVICE_HOST, which is the drift the L0 check cannot see. Recorded in that
test's gap list.

Refs R-PLAT-01, R-NET-01, R-ENV-02.

Co-Authored-By: Claude Opus 5 <[email protected]>

infra/ansible/roles/kube_vip/defaults/main.yml

@@ -24,6 +24,16 @@ kube_vip_port: 6443
 # only if detection is wrong.
 kube_vip_interface: ""
 
+# How long to wait for the VIP to actually ANSWER on kube_vip_port after the manifest is
+# written (seconds). This is a real gate, not cosmetics: since 2026-09-06 Cilium's
+# k8sServiceHost is this VIP (k3s_apiserver_endpoint), and playbooks/site.yml runs this role
+# immediately before cilium.yml — so if the VIP never comes up, the run must stop HERE with
+# a clear message rather than proceed to install a CNI pointed at an address nothing
+# answers. On a cold cluster the budget covers k3s's deploy controller applying the
+# manifest, the ghcr.io image pull and leader election; on an already-running cluster the
+# check returns immediately.
+kube_vip_wait_timeout: 300
+
 # Leader-election tuning (seconds) — a snappy failover without thrashing.
 kube_vip_lease_duration: 15
 kube_vip_renew_deadline: 10

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

@@ -21,6 +21,14 @@
     executable: /bin/bash
   register: kube_vip_iface_detect
   changed_when: false
+  # RUN THIS EVEN UNDER --check. It is `ip -o -4 addr show`: it reads and changes nothing.
+  # Without check_mode: false the shell module is SKIPPED in check mode, kube_vip_iface_detect
+  # has no stdout, and the assert two tasks down aborts the play with "Could not detect the
+  # interface ... set kube_vip_interface explicitly" — a misleading failure that says nothing
+  # about the node. That mattered less while this play was an out-of-band operator step; it
+  # matters now that playbooks/site.yml imports it, because `--check` on the bring-up before a
+  # cold prod build is exactly the rehearsal an operator should be able to run.
+  check_mode: false
 
 - name: Resolve the kube-vip VIP interface (override wins, else detected)
   ansible.builtin.set_fact:
@@ -52,3 +60,34 @@
     owner: root
     group: root
     mode: "0600"
+
+# PROVE THE VIP IS ACTUALLY UP BEFORE THIS PLAY RETURNS (added 2026-09-06).
+#
+# Templating the manifest is not the same as having a floating endpoint: k3s's deploy
+# controller still has to apply it, the image still has to pull, and leader election still
+# has to pick an owner. Nothing used to check, which was tolerable while the VIP was only an
+# operator convenience. It is not tolerable now — Cilium's k8sServiceHost IS this VIP
+# (k3s_apiserver_endpoint) and playbooks/site.yml runs cilium.yml straight after this play,
+# so an unannounced VIP would mean installing a CNI that cannot reach the API server. That
+# failure is the 2026-09-01 shape and it is very expensive to diagnose from the far side;
+# failing here instead names the actual cause.
+#
+# run_once: the VIP is ONE address for the whole environment, so one probe answers for the
+# environment. Probing from a server host (not the controller) is deliberate: the servers
+# are on the VIP's own LAN in both environments, whereas the dev controller reaches dev's
+# API only through a pfSense NAT — a controller-side probe would have been a property of
+# where the play was launched from. READ-ONLY: it opens a TCP connection and changes nothing.
+- name: Wait for the control-plane VIP to answer (the CNI's endpoint depends on it)
+  ansible.builtin.wait_for:
+    host: "{{ kube_vip_address }}"
+    port: "{{ kube_vip_port }}"
+    timeout: "{{ kube_vip_wait_timeout }}"
+  run_once: true
+  changed_when: false
+  vars:
+    ansible_become: false
+  # DELIBERATELY NOT check_mode: false, unlike the interface probe above — so a `--check`
+  # rehearsal SKIPS this and does not sit on a socket for kube_vip_wait_timeout. wait_for
+  # declares no check-mode support, so the skip is the module's own behaviour and this comment
+  # is here only so the skip does not read as an oversight. CONSEQUENCE, stated plainly: a
+  # `--check` run does NOT verify the VIP is up. Only a real run gates the CNI on it.