Skip to content

Architecture Decision Records

ADRs (Architecture Decision Records) capture significant design choices made for the platform — what was decided, what alternatives were considered, and why. They serve as the source of truth for why the platform looks the way it does, even after the code itself has moved on.

Format

Each ADR follows a lightweight structure:

  • Status — Proposed / Accepted / Superseded / Deprecated
  • Context — What forced a decision
  • Decision — What was chosen
  • Consequences — What this enables, what it costs, and what to watch out for

Index

# Title Status
001 TLS Termination Pattern Accepted
002 Authentication & Authorization Architecture Accepted
003 ApplicationSet Migration Strategy Accepted (see Addendum)
004 Network Policy Design Partially superseded by 009
005 Istio Native OAuth2 Superseded by 010
006 Namespace Naming Partially superseded by 014
007 No Vault PKI Accepted (see Addendum)
008 Keycloak DB Credentials Superseded by 013
009 Shared allow-istio NetworkPolicy Accepted
010 Istio Native OAuth2 (Absent) Accepted
011 Vault Image Tag Explicit Pin Accepted
012 Policy Enforcement with Kyverno Accepted
013 Keycloak DB Credentials → Vault Dynamic Superseded by 019
014 Namespace Naming & Label Contract v2 Accepted
015 VCO + Setup-Script Hybrid Accepted
016 LAN-Frictionless Sessions + External-Gate Model Accepted in part (gate deferred)
017 Remove kensan-legacy (tag archive) Accepted
018 Backstage manifests placement Accepted
019 Keycloak DB Credentials → Revert to Vault Static Accepted
020 Namespace lifecycle app cleanup + backstage/app flatten Accepted
021 gateway-prod default-protected (opt-out) authorization Accepted
022 Backstage native OIDC Accepted