ic-builder
e3c8e43ffb
The first architecture set did not render (backslash-n escapes, semicolons in sequence messages, braces in text). All diagrams rewritten to conservative syntax and QA-verified with mermaid-cli (3/3 PARSE-OK). qa-diagrams.sh added; CI enforces it on docs changes. Ticket: https://projects.knownelement.com/issues/832
2.3 KiB
2.3 KiB
KNELBMS integration — secrets flow
Repo: https://git.knownelement.com/KNEL/KNELBMS (PhysicalPlant lane; Home Assistant BMS on VM 100 @ pfv-tsys1, dev -> release deploy by git).
What the BMS consumes
On-box secret (HA secrets.yaml) |
Vault item + field | Provenance |
|---|---|---|
gitea_auth_header |
creds/pfv-bms-deploy -> GITEA_DEPLOY_WATCH_TOKEN |
release-branch sha-watch REST sensor |
deploy_webhook_id / pfv_relay_webhook_id |
creds/pfv-bms-deploy |
fast-path deploy webhook |
kuma_push_url |
dead-man monitor pfv-bms-ha-heartbeat-2026-09 push token |
rotated 2026-09-06 under CR 21 |
pve_tsys{1,3,4,5,6,7}_api_token |
creds/pve-upsagent (per-node fields) |
upsagent@pam!ups, PVEAdmin-on-/vms, privsep=0 |
doorman_*, pfvbms_smb_*, beta HA creds |
respective creds/* items |
as rotated |
Provisioning + rotation flow
sequenceDiagram
participant R as Rotation run - 829 wave
participant V as Vault
participant B as pfv-bms secrets.yaml
participant H as Home Assistant
R->>V: setfield new value
R->>B: CR-gated provisioning - ssh port 22222
R->>H: ha core restart - Kuma window
H-->>R: post-deploy validation
R->>V: rotation evidence on ticket 829
Rules that bind this flow (house rules + #811):
- pfv-bms prod changes need a GLPI CR and a Kuma maintenance window when a restart is involved; the deploy path itself stays dev -> CI -> release PR (founder merges).
- HA runtime template contexts cannot read secrets — the on-box
shell_commandentries reference!secretnames only (see KNELBMS PR #6 / CR 21 for the dead-man fix that taught us this). - The dead-man heartbeat (
pfv-bms-ha-heartbeat-2026-09, Kuma id 291) is the canary for provisioning mistakes: if the on-box secret and the vault disagree, the push fails and the monitor pages.
Current integration state (2026-09-06)
- On-box
secrets.yamlprovisioned manually under CR 21 (PVE tokens + rotated Kuma push URL); git-side KNELBMS matches for the!secretkeys it owns (PR #6 on dev, awaiting founder release merge). - Automated push-from-vault (rotation waves writing the box directly via the AWX ssh path) is planned, not built — wave 4. Until then the table above is the manual runbook, executed under CR.