Architecture decision records overview

To help explain why your infrastructure or application teams make certain design choices, you can use architecture decision records (ADRs). This document explains when and how to use ADRs as you build and run applications on Google Cloud.

An ADR captures the key options available, the main requirements that drive a decision, and the design decisions themselves. You often store ADRs in a Markdown file close to the code base relevant to that decision. If someone needs to understand the background of a specific architectural decision, such as why you use a regional Google Kubernetes Engine (GKE) cluster, they can review the ADR and then the associated code.

ADRs can also help you run more reliable applications and services. The ADR helps you understand your current state and troubleshoot when there's a problem. ADRs also build a collection of engineering decisions to help future decision choices and deployments.

When to use ADRs

You use ADRs to track the key areas that you think are important to your deployment. The following categories might be in your ADRs:

  • Specific product choices, such as the choice between Pub/Sub and Pub/Sub Lite.
  • Specific product options and configurations, such as the use of regional GKE clusters with Multi Cluster Ingress for highly available applications.
  • General architectural guidance, such as best practices for Dockerfile manifests.

Some specific examples that might prompt you to create an ADR could be for the following choices:

  • How and why do you set up high availability (HA) for your Cloud SQL instances?
  • How do you approach uptime of GKE clusters? Do you use regional clusters? Do you use canary releases? Why or why not?

As you evaluate the products to use, the ADR helps to explain each of your decisions. In the example of choosing between Pub/Sub and Pub/Sub Lite, your ADR might discuss how your requirements help guide the decision on which product to use. The following table outlines some of the differences between Pub/Sub and Pub/Sub Lite:

Feature Pub/Sub Pub/Sub Lite
Message replication Multi-zone in single region Single zone
Capacity Automatically provisioned Provision before you use
Pricing Pay for the capacity that you use Pay for the capacity that you provision
Storage Unlimited 30 GiB, 10 TiB per Lite topic
Retention period Up to 7 days Unlimited
Service endpoints Global and regional Regional
Resource namespace Global Zonal
Message routing Global Zonal

Your requirements might include global message routing or message replication across multiple zones in a single region. In this example, your ADR explains that you use Pub/Sub because it provides these features, but Pub/Sub Lite only provides zonal message routing and single-zone message replication.

You can revisit the ADR as the team evolves and learns more about the stack and additional decisions are made or adjusted. If you make adjustments, include the previous decision and why a change is made. This history keeps a record of how the architecture has changed as business needs evolve, or where there are new technical requirements or available solutions.

The following prompts help you to know when to create ADRs:

  • When you have a technical challenge or question and there's no existing basis for a decision, such as a recommended solution, standard operation procedure, blueprint, or code base.
  • When you or your team offers a solution that's not documented somewhere accessible to the team.
  • When there are two or more engineering options and you want to document your thoughts and reasons behind the selection.

When you write an ADR, it helps to have potential readers in mind. The primary readers are members of the team that work on the technology covered by the ADR. Broader groups of potential readers of the ADR might include adjacent teams who want to understand your decisions, such as architecture and security teams.

You should also consider that the application might change owners or include new team members. An ADR helps new contributors understand the background of the engineering choices that were made. An ADR also makes it easier to plan future changes.

Format of an ADR

A typical ADR includes a set of chapters. Your ADRs should help capture what you feel is important to the application and your organization. Some ADRs might be one page long, whereas others require a longer explanation.

The following example ADR outline shows how you might a format an ADR to include the information that's important for your environment:

  • Authors and the team
  • Context and problem you want to solve
  • Functional and non-functional requirements you want to address
  • Potential critical user journey (CUJ) the decision impacts
  • Overview of the key options
  • Your decision and reasons behind the accepted choice

To help keep a record of decisions, you might include a timestamp for each decision to show when the choice was made.

How ADRs work

ADRs work best when engineers, developers, or application owners can easily access information they contain. When they have a question about the why something is done a certain way, they can look at the ADR to find the answer.

To make the ADR accessible, some teams host it in a central wiki that's also accessible to business owners, instead of in their source control repository. When someone has a question about a specific engineering decision, the ADR is there to provide answers.

ADRs work well in the following scenarios:

  • Onboarding: New team members can easily learn about the project, and they can review the ADR when they have questions as they look at the application code or other implentations.
  • Ownership handover: If there's a transfer of technology stack between teams, the new owners can review past decisions to understand the current state. The ADR can also help avoid a repeat of the same discussion points, or to revisit topics in the future with knowledge of the historical context.
  • Alignment: Teams can align on best practices across the organization when ADRs detail why certain decisions were made and alternatives were decided against.

An ADR is often written in Markdown to keep it lightweight and text-based. Markdown files can be included in the source control repository with your application code.

Store your ADRs close to your application code, ideally in the same version control system. As you make changes to your ADR, you can review previous versions from source control as needed.

You could also use another medium like a shared Google Doc or an internal wiki. These alternate locations might be more accessible to users not part of the ADR's team. Another option is to create your ADR in a source control repository, but mirror key decisions into a more accessible wiki.

What's next