ADR Log — Rack Management Platform

A complete, filled decision log (no placeholders) — the durable record of the platform's significant decisions, as you'd keep in adr/ and link from the design doc. Format per ../DESIGN-REVIEWS-ADRS.md.

ADR-001: One inventory model + one reconcile loop as the spine

  • Status: Accepted (2026-05-21)
  • Context: We must provision, monitor, firmware-update, and decommission thousands of nodes across sites. The naive path is per-feature scripts.
  • Decision: A single inventory graph (components, relationships, state, declared baseline) plus a per-node reconcile loop that drives current→desired; provisioning and firmware are actions the loop takes, not separate orchestrators.
  • Alternatives: per-feature imperative scripts (rejected: no self-healing, no drift correction, unmaintainable at scale); a heavyweight COTS DCIM (rejected for the core path: loses integration depth + the ODM feedback loop).
  • Consequences: (+) idempotent, resumable, self-healing; one contract every part shares. (−) more upfront design than scripts; the loop must be carefully idempotent.

ADR-002: Redfish-first device-driver abstraction with IPMI/SNMP fallback

  • Status: Accepted (2026-05-23)
  • Context: Heterogeneous fleet — Redfish nodes, SNMP PDUs, IPMI-only peer BMCs.
  • Decision: One DeviceDriver interface (power/sensors/firmware) with Redfish/IPMI/SNMP backends
    • a capability-detecting factory; a unified Reading model; a FakeDriver for tests.
  • Alternatives: Redfish-only (rejected: strands today's IPMI/SNMP gear); per-protocol code in callers (rejected: quirks leak, every caller changes to migrate a device).
  • Consequences: (+) quirks contained, hermetic tests, protocol migration without caller changes, reused by the exporter + capstone. (−) abstraction tax; risk of a lowest-common-denominator API (mitigated by capability flags + OEM passthrough); requires a conformance suite (ADR-006).

ADR-003: A/B firmware banks + verify-before-and-after + anti-rollback

  • Status: Accepted (2026-05-28)
  • Context: A botched flash can brick a remote node; the BMC is the riskiest target (brick it → lose OOB).
  • Decision: Update the inactive A/B bank, verify signature before and health after activation, commit or roll back; enforce an anti-rollback floor.
  • Alternatives: in-place single-bank flash (rejected: a bad flash destroys the only firmware); no anti-rollback (rejected: downgrade-to-vulnerable attack).
  • Consequences: (+) a bad flash never destroys working firmware; recovery is a pointer switch. (−) needs hardware A/B support; where absent, extra caution + a recovery path are required.

ADR-004: Management VLAN is a hard, non-negotiable boundary

  • Status: Accepted (2026-05-30)
  • Context: BMC/PDU/CDU have total power/firmware control; an exposed BMC is a full compromise.
  • Decision: The management plane lives on an isolated VLAN reachable only by the control plane; tenant→management is denied in code and overrides any ACL.
  • Alternatives: shared management/data network (rejected: catastrophic blast radius + Shodan-style exposure).
  • Consequences: (+) contains the worst-case; (−) requires disciplined network config + smart proxies near hardware. No tradeoff worth taking on the boundary itself.

ADR-005: Attestation-gated trust before tenant scheduling

  • Status: Accepted (2026-06-02)
  • Context: Multi-tenant + sovereign sites; can't assume a node is trustworthy.
  • Decision: A node earns tenant workloads/keys only after a valid TPM PCR quote against published golden values (measured boot + remote attestation); secure boot enforces signed code.
  • Alternatives: trust-on-provision (rejected: a compromised firmware could exfiltrate tenant data); secure boot only (rejected: doesn't prove state to the control plane).
  • Consequences: (+) provable, gateable trust; sealing secrets to PCR state. (−) operational burden: golden measurements per (BIOS,BMC,OS) triple that change with firmware (ties to ADR-003).

ADR-006: Conformance suite as the executable interface spec

  • Status: Accepted (2026-06-05)
  • Context: "Redfish-compliant" ODM hardware varies; prose specs drift.
  • Decision: Every interface requirement maps to an automated conformance check run against the ODM's emulator/HIL in CI; a failing check is the unambiguous defect (e.g., finding RM-2026-014).
  • Alternatives: prose-only spec (rejected: ambiguous, drifts); manual integration testing (rejected: not repeatable).
  • Consequences: (+) unambiguous ODM contract, regressions caught pre-deploy. (−) the suite is a product to maintain across vendor/firmware combos.

ADR-007: Every fleet change is a gated, canaried, reversible, domain-aware rollout

  • Status: Accepted (2026-06-08)
  • Context: Agent, config, firmware, and k8s changes all risk fleet-wide incidents.
  • Decision: One rollout discipline for all of them: canary (1→1%) → health/SLO-gated waves → 100%, auto image-pinned rollback, failure-domain-aware waves, drain-first for reboots.
  • Alternatives: push-to-all (rejected: a bad change is an outage); ad-hoc per-change processes (rejected: inconsistent, error-prone).
  • Consequences: (+) bounded blast radius; reuse across firmware (ADR-003) + k8s + agents. (−) rollouts are slower by design — the deliberate cost of "no fleet-wide incidents."

Superseded / revisited

  • (none yet) — supersessions are recorded here with Superseded by ADR-NNN and a date.