# 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.