ic-builder
9e0cf6aa33
Component + sequence + rotation-flow diagrams; consumer pattern; KNELBMS secrets-flow table + provisioning sequence; README to prod standard. Ticket: https://projects.knownelement.com/issues/832
2.4 KiB
2.4 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 |
creds/pfv-bms-beta sibling — 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 TSGCOO vault
participant B as pfv-bms on-box secrets.yaml
participant H as Home Assistant
R->>V: new value (sm setfield creds/<item> <KEY>)
R->>B: CR-gated provisioning (ssh -p 22222, CR + ha core check)
R->>H: ha core restart (Kuma window; dead-man covers the gap)
H-->>R: post-deploy validation (entity/heartbeat checks)
R->>V: rotation evidence on #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.