An architectural decision record (ADR) is a document that describes a choice the team makes about a significant aspect of the software architecture they’re building. Each ADR describes the architectural decision, its context, and its consequences. Many ADRs represent cross cutting concerns which will impact the project as a whole.
The ADR process outputs a collection of architectural decision records. This collection creates the decision log. The decision log provides the project context as well as detailed implementation and design information. Project members skim the headlines of each ADR to get an overview of the project context. They read the ADRs to dive deep into project implementations and design choices.
When the team accepts an ADR, it becomes immutable. If new insights require a different decision, the team proposes a new ADR. When the team accepts the new ADR, it supersedes the previous ADR.
- The ADR "process" should be lightweight, many sources online recommended a whole lifecycle and approval process for an ADR. For a well functioning, automomous team these processes are deemed overkill
- As ADRs will be managed as code with git, they will be subject to the usual PR and PR review stages.
- With this in mind, there's no need for a Proposed status, ADRs are either Accepted or Superseded. Creating an ADR PR is the means to propose one, and the approval of the PR is the means to accept or approve them.
- Writing an ADR should be quick and simple (around 20 mins), otherwise they become an overhead and key decisions will get missed.
- The need to create an ADR should arise naturally in the course of discussions, e.g. standups, refinement, planning etc. e.g. Don't create a weekly ADR review or governance meeting.
- ADRs are not owned by one member of the team or the author, they represent an agreement and consensus, and should be written to reflect that.
- Store ADRs as markdown, under source control in the main code repo alongside your docs, resist the urge to put them in a special separate place, they will get forgotten.
- ADRs are numbered sequentially.
- Tools exist to automate this process, but in many cases can be overkill, and a simple template & manually numbering will suffice.
# Title of the ADR
## Status
Accepted or Superseded
## Context
## Decision
## Consequences
This is an example ADR from a real project
# Kubernetes Traffic & Network Ingress
## Status
Accepted
## Context
We will be running HTTP based services inside Kubernetes that we will want access to outside the cluster.
There are a number of approaches to do this but use of a [Kubernetes Ingress](link) is a strong recommendation.
The use of ingress comes with additional decisions, such as which [Ingress controller to use](link)
and should the IP of the ingress controller be exposed to the public internet or internally to an Azure VNet.
## Decision
- The project will use a Kubernetes Ingress controller.
- NGINX standard ingress controller will be used, as advanced features are not required.
- The ingress controller will have a private IP within Azure and not be exposed to the internet.
- Private DNS will be used in Azure to address hosts through the ingress.
## Consequences
Running ingress controller in cluster has some downsides vs Azure provided services such as Application Gateway.
Care will be taken to ensure the ingress control has dedicated resources (nodes) such a dedicated node pool.
Not giving the ingress a public IP means we will be required to access it via a jumpbox
or VPN into the Azure VNET. See ADR xxxx