Architecture Decision Records
Lightweight, numbered, immutable records of architectural decisions that govern the shared foundation plus the Azure Local and Hyper-V platform tracks.
These are project-scoped ADRs. Org-wide platform standards live in AzureLocal/platform/decisions/.
Design lane scope map
The early accepted ADRs were written for the Azure Local baseline. They do not automatically govern Hyper-V simply because both products use SCOM or share health terminology.
| Design lane | Governing decisions |
|---|---|
| Shared portfolio architecture | ADRs 0020, 0021, 0024, 0030, and integration boundary ADR 0038 |
| Shared SCOM product boundaries | ADR 0022 requires independent runtime products; ADR 0026 requires platform-owned DAs |
| Azure Local platform baseline | ADRs 0001–0003, 0007–0009, and 0014–0018 |
| Azure Local SCOM | ADRs 0022, 0026, and 0032–0035 supersede or refine the earlier Azure Local SCOM baseline |
| Azure Local Azure Monitor | ADRs 0006, 0010, 0012, 0013, 0019, and current preview refinement ADR 0036 |
| Hyper-V platform and SCOM | Accepted ADRs 0022, 0025–0029, 0031, and 0040–0048 for product boundary, network authority, DA, object/discovery, health/DA, authoring toolchain, external ownership, Pure Storage, SOFS/networking, v2 packaging, Network ATC, SDN, VMM, explicit PowerShell 7 execution, and governed release sealing; ADR 0040 supersedes 0039 and ADR 0043 supersedes 0027 for v2 |
| Hyper-V Azure Monitor | ADR 0023 constrained go and ADR 0037 development architecture |
Cross-cutting lifecycle ADRs can provide reusable patterns, but each platform and delivery lane must still validate its applicable topology, dependencies, artifacts, tests, and release contract.
Index
| # | Title | Status |
|---|---|---|
| 0001 | Scope & topology — Azure Local infrastructure (3 layers, ~27 entities) | Accepted |
| 0002 | Primary signal source — Azure Local PowerShell APIs + ARM/Resource Graph | Accepted |
| 0003 | Health rollup policy — worst-state default with documented exceptions | Accepted |
| 0004 | SCOM discovery strategy — PowerShell Discovery (not WMI) | Accepted |
| 0005 | SCOM class hierarchy + hosting relationships (3-layer model) | Accepted |
| 0006 | Azure Monitor entity model alignment (mirrors SCOM 1:1) | Accepted |
| 0007 | Naming convention — cross-track parity | Accepted |
| 0008 | Customization strategy — sealed MP + override pack tiers; Bicep params + tiers | Accepted |
| 0009 | Alert vs health-state separation policy | Accepted |
| 0010 | Cloud-side prerequisites contract (HCI Insights, AMA, DCMA, Service Group, RBAC, networking) | Accepted |
| 0011 | L3 Azure-side scope: agent-local Arc health checks (Tier A) vs. management server ARM probes (Tier B) | Accepted |
| 0012 | Azure Monitor Workspace vs Log Analytics Workspace: metrics routing for the health model (dual-topology support) | Accepted |
| 0013 | Azure Monitor Health Model deployment strategy — Bicep-first, portal-bootstrap | Accepted |
| 0014 | CI/CD pipeline strategy — GitHub Actions, OIDC, release-please | Accepted |
| 0015 | Testing strategy — 5-layer pyramid, cross-track parity gate | Accepted |
| 0016 | Signing & secrets management — two-key MP signing, OIDC SPNs | Accepted |
| 0017 | Versioning & release policy — single repo SemVer, Conventional Commits, mike docs | Accepted |
| 0018 | Self-observability — monitor the monitoring pipeline as a parallel root branch | Accepted |
| 0019 | Cost, scale, and data retention — per-tier ingestion envelopes, sharding, retention policy | Accepted |
| 0020 | Documentation platform — VitePress with Mermaid and GitHub Pages | Accepted |
| 0021 | Platform-first architecture — Azure Local and Hyper-V, split by SCOM and Azure Monitor delivery surfaces | Accepted |
| 0022 | Independent SCOM packaging — no shared runtime MP dependencies | Accepted |
| 0023 | Hyper-V Azure Monitor through Arc-enabled SCVMM — constrained go | Accepted |
| 0024 | Repository and publishing identity — Hybrid Solutions Cloud and labs.hybridsolutions.cloud | Accepted |
| 0025 | Hyper-V network-management authority — prefer Network ATC when eligible; distinguish SCVMM/SDN and manual paths | Accepted |
| 0026 | Platform-owned SCOM Distributed Applications — separate Azure Local and Hyper-V service roots | Accepted |
| 0027 | Hyper-V SCOM Management Pack decomposition — modular sealed product suite and customer override boundary | Accepted |
| 0028 | Hyper-V object and discovery architecture — stable mobility identity, staged discovery, and cookdown | Accepted |
| 0029 | Hyper-V health, alert, and DA rollup — evidence-driven state, actionable alerts, and topology-aware service health | Accepted |
| 0030 | Platform-first source tree — Azure Local and Hyper-V, each split into SCOM and Azure Monitor solution roots | Accepted |
| 0031 | Hyper-V Management Pack authoring toolchain — canonical XML/fragments, deterministic build, Microsoft verification/sealing, and SCOM lab authority | Accepted |
| 0032 | Azure Local SCOM local runtime boundary — no Azure dependency in the core product | Accepted |
| 0033 | Azure Local Management Pack decomposition — five independent artifacts and customer-owned overrides | Accepted |
| 0034 | Azure Local object, discovery, and Distributed Application architecture | Accepted |
| 0035 | Azure Local health, alert, and rollup architecture | Accepted |
| 0036 | Azure Local Azure Monitor Health Model v1 — preview resource graph, identity, entities, and initial signals | Accepted |
| 0037 | Hyper-V Azure Monitor Health Model — SCVMM inventory plus Arc-enabled host telemetry | Accepted |
| 0038 | SCOM-to-ServiceNow connector boundary — optional MID Server connector with product allow-lists | Accepted |
| 0039 | Hyper-V v2 external object ownership — initial adapter decision before S2D/SDN inspection | Superseded by 0040 |
| 0040 | Hyper-V v2 Microsoft S2D and SDN ownership — authoritative Microsoft objects through optional adapters | Accepted |
| 0041 | Hyper-V v2 Pure Storage integration — vendor-owned topology with HCS SAN-to-VM correlation | Accepted |
| 0042 | Hyper-V v2 file services and physical network ownership — Microsoft objects with HCS service correlations | Accepted |
| 0043 | Hyper-V v2 package and deployment profiles — four required core MPs plus optional capability adapters | Accepted |
| 0044 | Hyper-V v2 Network ATC monitoring — stable intent/node identity, explicit authority, read-only convergence and adapter health | Accepted |
| 0045 | Hyper-V v2 Windows Server SDN integration — Microsoft-owned topology with read-only HCS binding and service impact | Accepted |
| 0046 | Hyper-V v2 Virtual Machine Manager integration — build-matched Microsoft fabric with read-only HCS gap coverage and service impact | Accepted |
| 0047 | Hyper-V v2 execution host — public SCOM command executors launch the machine-wide PowerShell 7 MSI path explicitly | Accepted |
| 0048 | Hyper-V v2 governed sealing — permanent product identity, fail-closed packaging, checksums, and stable release assets | Accepted |
When to write an ADR
- Any architectural choice that affects how the SCOM MP or Azure Monitor health model is built
- Any decision that creates a constraint on Phases 3–6
- Any cross-track parity decision
- Any decision the next maintainer would otherwise have to re-litigate
Format
See template.md. Numbered sequentially, ZERO-padded to four digits. Filename is NNNN-kebab-case-title.md. Once an ADR is Accepted it is immutable — supersede it with a new ADR rather than editing it in place.
Workflow
- Open a PR adding the ADR with status
Proposed - Discuss and refine in PR review
- Merge with status
Acceptedonce consensus reached - If later overturned, write a successor ADR and mark this one
Superseded by ADR XXXX