Architecture Decision Records (ADRs)

  • Wed, Jul 10, 2024
  • 4-minute read

Architecture Decision Records (ADRs) are a way to capture important architectural decisions made along with their context and consequences. They are essential for maintaining a clear historical record of why certain architectural paths were chosen over others by the team. This helps in understanding the evolution of the system, facilitating knowledge transfer, and ensuring that future decisions are informed by past experiences.

Structure of an ADR

A typical ADR includes the following sections:

  1. Title: A descriptive title.
  2. Context: Background information explaining why the decision is needed.
  3. Decision: The decision itself.
  4. Status: The current status (e.g., proposed, accepted, deprecated).
  5. Consequences: The expected outcomes, both positive and negative, of the decision.

Architecture Decision Records (ADRs) are typically maintained as markdown documents within code repositories. This practice ensures that the rationale behind key architectural decisions is easily accessible to the entire development team, directly within the context of the project’s codebase. By keeping ADRs in the same repository as the source code, teams can benefit from version control, collaborative editing, and the ability to link decisions directly to the code they affect. This seamless integration helps in maintaining a clear historical record of why certain decisions were made, facilitating better communication, and supporting informed decision-making throughout the project’s lifecycle.

Let’s dive into an example to understand this better.

Example of an ADR:

GitHub Self-Hosted Runner Security Architecture.

Secure Deployment of GitHub Self-Hosted Runners

Context

Our organization is increasingly relying on continuous integration and continuous deployment (CI/CD) pipelines to automate software development processes. GitHub Actions is the chosen CI/CD platform due to its seamless integration with our existing GitHub repositories. However, using GitHub-hosted runners poses certain limitations and security risks, particularly in handling sensitive data and running workflows with elevated permissions.

To mitigate these risks and gain more control over the environment, we have decided to use self-hosted runners. This ADR outlines the security architecture for deploying self-hosted runners to ensure they operate securely within our infrastructure.

Decision

We will implement the following security measures for our GitHub self-hosted runners:

  1. Isolated Environment: Self-hosted runners will be deployed in isolated virtual machines (VMs) within a dedicated Virtual Private Cloud (VPC) to prevent any unauthorized access.
  2. Access Control: Use of role-based access control (RBAC) to ensure that only authorized personnel can manage and access the self-hosted runners.
  3. Network Security: Implementation of strict network security groups and firewall rules to control inbound and outbound traffic to and from the runners.
  4. Secrets Management: Utilization of a centralized secrets management system to handle sensitive data, ensuring that secrets are never exposed in the runner’s environment.
  5. Auto-Scaling and Rotation: Automatic scaling of runners based on workload demands and periodic rotation of VMs to minimize the risk of long-term exposure.
  6. Monitoring and Logging: Continuous monitoring and logging of runner activities to detect and respond to any suspicious behavior or security incidents promptly.
  7. Patch Management: Regular updates and patches to the runner operating systems and software to address any known vulnerabilities.

Status

Accepted

Consequences

Positive

  • Enhanced Security: The isolated environment and strict access controls significantly reduce the risk of unauthorized access and data breaches.
  • Controlled Environment: Centralized management of secrets and network rules ensure a consistent and secure runner configuration.
  • Scalability: Auto-scaling and rotation of runners enhance reliability and reduce the risk of long-term security exposures.
  • Visibility: Continuous monitoring and logging provide visibility into runner operations, aiding in quick detection and response to security incidents.

Negative

  • Increased Complexity: The setup and maintenance of the isolated environment, access controls, and network security require additional effort and resources.
  • Cost: Deploying and managing self-hosted runners in isolated VMs within a dedicated VPC may incur higher costs compared to using GitHub-hosted runners.
  • Maintenance Overhead: Regular updates, patch management, and monitoring add to the operational overhead.

Example of Architecture Decision Record Repository

  • Lullabot: Here is an example of how Lullabot manages their ADRs, which you can explore by visiting their architecture site: Lullabot Architecture.
  • UK Government Agencies: This is another notable example from a UK Government agency capturing key architecture decisions.

Ending

Documenting architectural decisions through ADRs provides a structured way to capture the rationale behind critical decisions, ensuring clarity and consistency in the development process. The example of securing GitHub self-hosted runners illustrates how a well-thought-out ADR can guide the implementation of robust security measures, balancing the benefits against the associated costs and complexities.

By maintaining a comprehensive record of such decisions, development teams can facilitate better communication, improve decision-making processes, and ensure that future developments build upon a solid foundation of informed choices.

post architecture-decision-recordadrsoftware-architecture