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
51 lines
2.4 KiB
Markdown
51 lines
2.4 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` | `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
|
|
|
|
```mermaid
|
|
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_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.
|