Architecture Decision Records voor Azure-infrastructuur: waarom teams ze overslaan en wat ze missen
ADRs zijn ingeburgerd in applicatieontwikkeling, maar zelden toegepast op Azure-infrastructuurbeslissingen. Welke infrastructuurbeslissingen er een verdienen, plus een template dat je vandaag kunt gebruiken.
Architecture Decision Records voor Azure-infrastructuur: waarom teams ze overslaan en wat ze missen
“Waarom is het netwerk zo opgezet?”
Die vraag valt altijd op het slechtste moment. Halverwege een incident review. Drie dagen voor een audit.
En je weet het antwoord niet.
Niet omdat je slecht bent in je werk. Omdat die beslissing twee jaar geleden is genomen door iemand die er niet meer werkt, in een context die nergens is vastgelegd.
Dus je zoekt in Confluence. Je vindt een pagina: “Hub-spoke netwerktopologie gekozen.” Geen reden. Geen alternatieven. Geen aannames. Alleen de uitkomst.
En nu mag jij het verdedigen.
Dat is precies wat een Architecture Decision Record voorkomt. Een ADR legt vast waarom een infrastructuurbeslissing is genomen: met welke alternatieven, welke beperkingen en welke aannames. Voor applicatiecode doen teams dat trouw. Voor Azure-infrastructuur slaan ze het over. Wat overblijft is een berg beslissingen over netwerktopologie, identity en subscription-structuur die niemand later nog kan verdedigen.
Precies de beslissingen waar een auditor naar vraagt.
Waarom, niet hoe
Het probleem is niet dat er te weinig documentatie ligt. Het probleem is dat er geen redenering in staat. Een design document beschrijft hoe iets werkt. Een ADR legt vast waarom een keuze op een specifiek moment is gemaakt, met de beperkingen en aannames die op dat moment golden.
Dat onderscheid is niet filosofisch. Het is operationeel.
Neem een platform engineer bij een Nederlandse fintech, in 2025 verantwoordelijk gehouden voor een reeks productie-incidenten. De oorzaak lag in een netwerksegmentatiekeuze uit 2022. De engineer die die keuze maakte, was twee jaar eerder vertrokken. Geen vastlegging van de overwogen alternatieven. Geen spoor van de aanname waarop alles rustte: dat de applicatieteams nooit cross-subscription verkeer zouden genereren. Inmiddels deden ze dat wel.
Drie weken kostte het het platform team om de redenering te reconstrueren voordat ze de architectuur konden herzien. Drie weken, voor een beslissing die in een uur gedocumenteerd had kunnen worden.
Infrastructuurbeslissingen hebben minstens evenveel langetermijngevolgen als beslissingen over softwarearchitectuur. Meestal zijn ze een stuk moeilijker terug te draaien. En toch leggen we ze zelden vast met de redenering die je nodig hebt om ze later te begrijpen.
In applicatieontwikkeling zijn ADRs gangbaar. Voor Azure-infrastructuur niet. Voor dat verschil bestaat geen goede reden.
Nu denk je misschien: “Ja, maar bij ons staat alles in Terraform, dus onze infrastructuur documenteert zichzelf.”
Nee.
Je Terraform vertelt me dat er een hub-spoke staat met een Azure Firewall in het midden. Hij vertelt me niet dat jullie ExpressRoute hebben overwogen en hebben laten vallen omdat de kosten niet uit te leggen waren aan de business. Dat stond in een Teams-gesprek dat allang is opgeruimd. Code legt de uitkomst vast, nooit de afweging. (Ik heb dat argument zelf jarenlang gebruikt om geen ADRs te schrijven voor infrastructuur. Het was precies zo slim als het klinkt.)
Welke beslissingen een ADR nodig hebben (en welke niet)
Niet elke configuratiekeuze vraagt om formele vastlegging. De SKU van een App Service Plan, de retention-instelling op een Log Analytics Workspace: dat zijn configuratiedetails, geen architectuurbeslissingen.
De test is kort. Heeft deze beslissing structurele gevolgen die moeilijk terug te draaien zijn? Raakt ze meerdere workloads of teams? Kan een auditor er compliance-vragen over stellen?
Eén keer ja is genoeg.
Drie categorieën springen er consistent uit.
Netwerktopologie
Hub-spoke versus flat network versus Virtual WAN. ExpressRoute versus VPN Gateway versus helemaal geen private connectivity. Subnet-segmentatie en de logica achter je peering-configuraties. Dit zijn de beslissingen die de beveiligingsperimeter definiëren voor alles wat er daarna overheen wordt uitgerold. In een NIS2- of ISO 27001-context zijn dit precies de keuzes waarover een auditor doorvraagt.
“We vonden het destijds een goed idee” telt niet als antwoord.
Identity-architectuur
Managed identities versus service principals met secrets. Federated identity credentials versus certificaat-gebaseerde authenticatie voor workload identity. De structuur van Entra ID-groepen voor je RBAC-toewijzingen. Of en hoe Privileged Identity Management is ingericht. Deze keuzes zitten diep verankerd in CI/CD-pipelines, applicatiecode en operationele procedures. Herzie je ze zonder de oorspronkelijke redenering, dan herzie je ze ook zonder de beperkingen die die redenering stuurden.
Multi-subscription en management group structuur
De indeling in subscriptions: per omgeving, per businessunit, per criticality. De management group-hiërarchie en de logica achter de policy-toewijzingen op elk niveau. Wanneer een workload een eigen subscription rechtvaardigt in plaats van een resource group in een bestaande. Dit bepaalt wat je qua governance later überhaupt nog kúnt. En het is bijzonder pijnlijk om terug te draaien zodra het in productie staat.
Het template
Hieronder een template dat de structuur van Michael Nygards originele ADR-format volgt, uitgebreid met velden die specifiek relevant zijn voor infrastructuurbeslissingen. Kopieer het, gooi eruit wat je niet gebruikt.
# ADR-[nummer]: [Titel van de beslissing]
**Datum:** YYYY-MM-DD
**Status:** [Voorgesteld | Geaccepteerd | Verouderd | Superseded door ADR-[nummer]]
**Auteur(s):** [Namen of rollen]
---
## Context
[Beschrijf de situatie die de beslissing noodzakelijk maakte. Welke eisen golden er?
Welke beperkingen waren van kracht: technisch, organisatorisch, regulatoir?
Welke aannames zijn gemaakt die op dit moment als waar worden beschouwd?]
**Relevante frameworks en vereisten:**
- [ ] NIS2 / DORA / GDPR: specificeer welk artikel of vereiste van toepassing is
- [ ] ISO 27001:2022 Annex A: specificeer het controlenummer
- [ ] Interne beveiligingsbaseline
- [ ] Azure Well-Architected Framework pijler: [Security / Reliability / etc.]
---
## Beslissing
[Beschrijf de keuze in één of twee zinnen. Wees precies over de Azure-services,
configuratie-instellingen en scope.]
Voorbeeld: "Alle productie-workloads worden uitgerold in een hub-spoke topologie.
De hub-subscription bevat Azure Firewall Premium (Standard-policy), een VPN Gateway
(Generation 2, VpnGw2 SKU), en Azure Bastion (Standard-tier). Spoke-subscriptions
bevatten uitsluitend workload-resources. Alle egress-verkeer wordt gerouteerd via
de Azure Firewall in de hub."
---
## Gevolgen
**Positieve gevolgen:**
- [Concreet voordeel 1. Wees specifiek, geen generieke opsomming]
- [Concreet voordeel 2]
**Negatieve gevolgen / beperkingen:**
- [Wat wordt moeilijker of duurder door deze keuze?]
- [Welke toekomstige beslissingen worden beperkt?]
**Operationele implicaties:**
- [Wat verandert er in dagelijkse operaties, monitoring, of incident response?]
**Kostenindicatie:**
- [Schatting van de maandelijkse Azure-kosten die direct voortvloeien uit deze beslissing]
---
## Overwogen alternatieven
### Alternatief 1: [Naam]
[Beschrijf het alternatief. Waarom is het niet gekozen?]
### Alternatief 2: [Naam]
[Beschrijf het alternatief. Waarom is het niet gekozen?]
---
## Gerelateerde beslissingen
- ADR-[nummer]: [Titel]. [Waarom gerelateerd]
---
## Revisiegeschiedenis
| Datum | Wijziging | Auteur |
|-------|-----------|--------|
| YYYY-MM-DD | Initieel aangemaakt | [naam] |
En zo ziet het eruit als je het invult voor een echte beslissing:
# ADR-004: Workload identity via Managed Identity in plaats van Service Principal met client secret
**Datum:** 2026-04-14
**Status:** Geaccepteerd
**Auteur(s):** Platform Engineering Team
## Context
Meerdere applicatieworkloads gebruiken momenteel service principals met client secrets
voor toegang tot Azure Key Vault, Storage Accounts en Azure Container Registry.
Secrets worden handmatig geroteerd en opgeslagen in GitHub Actions Secrets en
Azure DevOps variable groups. Twee incidenten in de afgelopen acht maanden betroffen
verlopen secrets die productie-deployments blokkeerden.
ISO 27001:2022 Annex A control 8.3 (Information access restriction) vereist beperking
van toegang tot informatie en systemen. NIS2 Article 21(2)(i) vereist adequate
authenticatiepraktijken voor systemen die kritische diensten ondersteunen.
## Beslissing
Alle nieuwe workloads gebruiken System-assigned Managed Identities voor authenticatie
naar Azure-services. Bestaande service principals worden gemigreerd naar Managed Identity
binnen Q3 2026. User-assigned Managed Identities worden gebruikt waar meerdere resources
dezelfde identiteit moeten delen (gedeelde Container Registry-toegang).
## Gevolgen
**Positief:**
- Eliminatie van secret rotation als operationele last
- Geen credentials in pipeline-configuraties of applicatiecode
- RBAC-toewijzingen zijn direct zichtbaar en auditeerbaar in Azure Portal
**Negatief:**
- Managed Identities zijn niet bruikbaar buiten Azure (externe integraties vereisen
nog service principals of workload identity federation)
- Lokale ontwikkelomgevingen vereisen een expliciete fallback-strategie
(Azure CLI credential chain via DefaultAzureCredential)
## Overwogen alternatieven
### Service Principal met certificaat (i.p.v. secret)
Certificaten zijn veiliger dan secrets maar vereisen nog steeds rotatie en distributie.
Het operationele voordeel ten opzichte van Managed Identity is beperkt.
### Workload Identity Federation (GitHub Actions naar Entra ID)
Valide voor CI/CD-context. Gekozen als aanvullende oplossing voor pipeline-authenticatie,
niet als vervanging van runtime workload identity.
ADRs en drift detectie
Een ADR legt de bedoelde toestand vast. Drift detectie meet de werkelijke. De combinatie werkt pas als je weet wat je meet.
ADR-004 hierboven zegt dat workload-authenticatie via Managed Identities verloopt. Draait er vervolgens een automatisch assessment dat service principals met actieve secrets terugmeldt, gekoppeld aan productie-subscriptions, dan heb je een bevinding. Die bevinding krijgt pas betekenis als er een ADR naast ligt die zegt: dit hadden we anders besloten.
Zonder ADR is het een observatie. Met ADR is het een afwijking van een vastgelegde intentie, traceerbaar naar een beslissing, een datum en iemand die er verantwoordelijk voor was.
Dat gat is de reden dat ik Platform Architecture Authority ben gaan bouwen. Ik leverde assessmentrapporten op waarin elke bevinding dezelfde vraag opriep, “was dit expres of niet?”, en niemand aan tafel kon dat beantwoorden. Ik ook niet. Een scanner ziet de toestand; alleen een besluitregister ziet de bedoeling.
Het werkt trouwens ook andersom. Stel, een ADR schrijft voor dat alle egress-verkeer via Azure Firewall loopt, maar een flink deel van je resources heeft consistent directe internet-toegang omdat applicatieteams buiten de hub-spoke structuur om deployen. Dan is de drift het probleem niet. Dan is de architectuurbeslissing aan herziening toe. Wat je oplevert is een nieuwe ADR, geen remediatielijst.
Dat is het verschil tussen een governance-programma dat leert en één dat alleen rapporteert.
Een ADR geeft je omgeving iets wat beleidsregels alleen nooit kunnen geven: intentie met een datum erop. Precies wat ontbreekt in de meeste Azure-omgevingen op het moment dat er een formeel assessment overheen gaat.
Doe me een plezier. Pak de eerstvolgende infrastructuurbeslissing die je team neemt, en schrijf er een half A4 over. Niet netjes. Gewoon: dit hebben we gekozen, dit hebben we niet gekozen, en dit namen we aan. Over twee jaar is het het enige stuk documentatie dat er nog toe doet.
De korte versie
Een ADR legt de redenering achter een beslissing vast, niet alleen de uitkomst. Dat is wat design documenten en Confluence-pagina’s structureel missen. Drie soorten Azure-beslissingen verdienen er vrijwel altijd een: netwerktopologie, identity-architectuur, en de multi-subscription- en management group-structuur. De vuistregel: een beslissing hoort een ADR te krijgen zodra ze structurele, moeilijk omkeerbare gevolgen heeft, meerdere teams raakt, of iets is wat een auditor kan bevragen. Zonder ADR is elke drift-bevinding alleen een observatie. Mét ADR is het een meetbare afwijking van een vastgelegde intentie. Het template hierboven kun je vandaag gebruiken.
Veelgestelde vragen
Wat is het verschil tussen een ADR en een design document?
Een design document beschrijft hóe een systeem werkt. Een ADR legt vast wáárom een beslissing op een specifiek moment is genomen, met de alternatieven, beperkingen en aannames die toen golden. Het design document veroudert met de architectuur. De ADR blijft het historische besluitrecord, met datum en verantwoordelijke.
Welke Azure-infrastructuurbeslissingen hebben een ADR nodig?
Beslissingen met structurele, moeilijk omkeerbare gevolgen: netwerktopologie (hub-spoke, ExpressRoute, subnet-segmentatie), identity-architectuur (managed identities versus service principals, PIM) en de subscription- en management group-structuur. Configuratiedetails zoals een App Service-SKU of een retention-instelling horen er niet bij.
Hoe werken ADRs samen met drift detectie?
Een ADR documenteert de bedoelde toestand, drift detectie meet de werkelijke. Zonder ADR is een afwijking slechts een observatie. Met ADR is het een meetbare afwijking van een gedocumenteerde intentie, met een datum, een redenering en een verantwoordelijke engineer die de bevinding context geven.
Welk ADR-template moet ik gebruiken voor Azure?
Het format van Michael Nygard (context, beslissing, gevolgen, overwogen alternatieven), uitgebreid met velden die specifiek zijn voor infrastructuur: relevante frameworks (NIS2, DORA, ISO 27001:2022 Annex A), een kostenindicatie en operationele implicaties. Dit artikel bevat een volledig, direct bruikbaar template.
Want a second pair of eyes on it?
Ask for a free second opinion