Files

Jean-Gabriel Gill-Couture 397f266d31 docs(adr-025): groups are the security boundary — rewrite, trail, guide

Rewrite ADR-025 around the group-based design: groups gate (admin-
managed identity), labels place, OpenBao enforces via external groups;
batch tokens with 1h TTL make expiry re-login the membership sync.
Iteration trail preserved under 025-device-secret-access/ (025-1 JWT
claim scoping, 025-2 entity-by-policy as built, 025-3 the scale and
security analysis with verified sources). Add the user-facing guide
and the implementation + branch-consolidation rollout plan.

2026-06-12 00:26:24 -04:00

4.0 KiB

Raw Permalink Blame History

Architecture Decision Records

An Architecture Decision Record (ADR) documents a significant architectural decision made during the development of Harmony — along with its context, rationale, and consequences.

Why We Use ADRs

As a platform engineering framework used by a team, Harmony accumulates technical decisions over time. ADRs help us:

Track rationale — understand why a decision was made, not just what was decided
** onboard new contributors** — the "why" is preserved even when team membership changes
Avoid repeating past mistakes — previous decisions and their context are searchable
Manage technical debt — ADRs make it easier to revisit and revise past choices

An ADR captures a decision at a point in time. It is not a specification — it is a record of reasoning.

ADR Format

Every ADR follows this structure:

Section	Purpose
Status	Proposed / Pending / Accepted / Implemented / Deprecated
Context	The problem or background — the "why" behind this decision
Decision	The chosen solution or direction
Rationale	Reasoning behind the decision
Consequences	Both positive and negative outcomes
Alternatives considered	Other options that were evaluated
Additional Notes	Supplementary context, links, or open questions

ADR Index

Number	Title	Status
000	ADR Template	Reference
001	Why Rust	Accepted
002	Hexagonal Architecture	Accepted
003	Infrastructure Abstractions	Accepted
004	iPXE	Accepted
005	Interactive Project	Proposed
006	Secret Management	Accepted
007	Default Runtime	Accepted
008	Score Display Formatting	Proposed
009	Helm and Kustomize Handling	Accepted
010	Monitoring and Alerting	Accepted
011	Multi-Tenant Cluster	Accepted
012	Project Delivery Automation	Proposed
013	Monitoring Notifications	Accepted
015	Higher Order Topologies	Proposed
016	Harmony Agent and Global Mesh	Proposed
017-1	NATS Clusters Interconnection Topology	Proposed
018	Template Hydration for Workload Deployment	Proposed
019	Network Bond Setup	Proposed
020-1	Zitadel + OpenBao Secure Config Store	Accepted
020	Interactive Configuration Crate	Proposed
022	Fleet Agent Upgrade Procedure	Accepted
023	Deploy Architecture	Accepted
024	Fleet Platform Capability Decomposition	Accepted
025	Fleet Device Secret Access	Accepted
025-3	Groups as the Security Boundary — Scale & Security Analysis	Accepted

Contributing

When making a significant technical change:

Check existing ADRs — the decision may already be documented
Create a new ADR using the template if the change warrants architectural discussion
Set status to Proposed and open it for team review
Once accepted and implemented, update the status accordingly

4.0 KiB Raw Permalink Blame History