Architecting and designing systems is not easy and much of it is dependent on platform and technology choice, along with business requirements, backup criteria, disaster recovery, end user expectations and operational management. Some key areas of building an architecture include:
Artefacts
All of the above considerations feed into the actual artefacts and deliverables that we create throughout the project. Before writing a design document, I confirm who the target audiences and stakeholders are. These can include –
- Client architects — key stakeholder and likely responsible for document sign-offs
- Microsoft or AWS architects — provide cloud related technical feedback
- Project engineers — build the solution based upon the design
- 3rd party vendors — are interested in any integrations
- Operations team — are interested in support implications
Some common design artefacts and their purpose –
Architecture Overview document
This document provides an overarching view or blueprint for the solution. It’s here that key design decisions around Azure subscriptions, management groups, regions, operations etc. This document is the ideal place to tie design decisions back to individual NFR’s.
The Architecture Overview is also ideal for including design principles and statements of intent. For example, native Azure AD groups will be used for managing RBAC across Azure subscriptions. Or that Terraform and Azure DevOps is the preferred choice for infrastructure as code in Azure, Cloud Formation and related tools in AWS.
Think of this document as putting in place the big building blocks that are difficult or time consuming to change later.
High-Level Design document
The High-Level Design document expands upon the Architecture Overview and provides the next level of detail. It covers areas such as resource groups, VPCs, VNET’s, environments, configuration of each cloud service. It also covers performance, regional resiliency, availability zones, disaster recovery and backups.
Low-Level Design / Wiki
Unfortunately Low-Level Design documents are being created less often. This is a mistake, even assuming that the HLD has sufficient detail, which can often be used as the starting point for implementing the infrastructure as code and CI/CD pipelines.
Depending on an organization’s maturity and experience with IaC, they may be comfortable with not creating an LLD but this is NOT recommended. A well-commented and structured IaC is largely self-documenting but needs formalisation anyway in a repository. Supporting documentation can be added to a wiki such as those available in most CI/CD platforms such as Azure DevOps, AWS Code Pipeline, Code Commit and GitLab.
The advantage of wikis is that they are more easily maintained and accessible. They are useful to include the following types of information –
- Pipeline guides and how to’s
- Azure resource naming conventions
- IP address schemas
- etc.
Reusability and Best Practice
Whether they’re design document templates or snippets of Cloud Formation, JSON, YAML, ARM templates, or Terraform modules. For example, an environment hosting design can often be templatized to allow it to be easily re-used and called a ‘landing zone’ into which you deploy the infrastructure.
Templatizing and creating a library of commonly used artefacts is the best way to accelerate designing for and deploying to cloud consistently. For this reason, we can use AWS or Azure’s Architecture Centers and Cloud Adoption Frameworks as good starting points for best practice recommendations and blueprints.