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
51 lines
2.3 KiB
Markdown
51 lines
2.3 KiB
Markdown
# 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
|
|
|
|
```mermaid
|
|
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_command` entries reference `!secret` names 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.yaml` provisioned manually under CR 21 (PVE tokens +
|
|
rotated Kuma push URL); git-side KNELBMS matches for the `!secret`
|
|
keys 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.
|