It is often very useful to share diagrams when describing a software architecture to others. It applies the old adage that a “picture is worth a thousand words”. What’s more, it also helps you – as a builder – understand what you built and to learn areas to improve as you develop your software. While we seek to define “everything as code”, diagrams are often overlooked as an opportunity to treat everything as source code.
In this post, you will learn how to define your software architecture diagrams on AWS as code. What’s more, you will see how to create a deployment pipeline – using AWS CloudFormation, AWS CodePipeline, and AWS CodeBuild – that provides a “architecture diagram generation factory” for all of your diagrams. You can also run the solution in your own AWS account with a single command.
Earlier in 2020, I learned of a tool based on Graphviz called Diagrams. As the tagline of the article indicated, you can “build cloud architecture diagrams without leaving your IDE”. I was intrigued. I began using Graphviz over a decade ago to produce diagrams but – for whatever reason – hadn’t thought of it recently nor considered it for the diagrams I create the most: AWS architectures.
Over the years, I have used different tools for diagramming AWS architectures including Visio, Cloudcraft, LucidChart, and – over the past year or so – draw.io/diagrams.net. Diagrams.net is great because I am able to store and share documents in G Suite for Business. While many of these diagramming tools offer rich features, you have to leave your IDE when creating and maintaining these diagrams.
Launch Diagrams as Code Solution
The steps below describe how to launch a deployment pipeline that automatically generates diagrams from source code. If you would like to see a video that walks through the steps, click on the video below.
To reduce variation, you can run the commands from an AWS Cloud9 IDE. Regardless, you will need to ensure your environment has access credentials for running the AWS CLI.
Before running the commands to launch the stack, you should create a secret in AWS Secrets Manager by running the command below – replacing GITHUBTOKEN with your GitHub token you created at https://github.com/settings/tokens.
aws secretsmanager create-secret --name github/personal-access-token --description "GitHub Token" --secret-string "GITHUBTOKEN"
To launch the solution, run the commands from Listing 1. The bash script uses the AWS CLI to create a CloudFormation stack that provisions S3, IAM, CodeBuild, and CodePipeline resources.
It takes about 3 minutes to launch the stack and run through the pipeline.
Listing 1 – Commands to Launch the Diagrams as Code Solution Stack
- Go to the CloudFormation console, and find the diagrams* stack.
- Click on the Outputs pane.
- Click on the PipelineUrl value to launch the deployment pipeline in AWS CodePipeline. It should look similar to Figure 1.
Figure 1 – Deployment Pipeline that Generates Diagrams from Code
Once the pipeline is complete, go back to the CloudFormation Outputs pane and click on a few of the example diagrams – as shown in Figure 2.
Figure 2 – CloudFormation Output pane with Resource Links
This will display a diagram that looks similar to Figure 3.
Figure 3 – AWS Architecture Diagram Generated by Diagrams as Code
This diagram was generated from Python code, stored in a GitHub repository, and generated every time there’s a new commit to the repository. For example, the code to generate the diagram in Figure 3 is shown in Listing 2.
Listing 2 – Diagrams Code that Generates Architecture Diagram
In order to group components, I use with Cluster and give it a name. To define a component, I create an object of that type. For example, you see in the code snippet above that I am defining the CodePipeline component using codepipeline = Codepipeline("Pipeline"). You can provide relationships between components using >> and <<. Since this is all based on the Graphviz framework, you can learn more by going to the Graphviz Node, Edge and Graph Attributes documentation. mingrammer is posting examples here and I am also posting examples – that include a deployment pipeline – at examples.
Deployment Pipeline
While, for me, everything eventually leads to defining a deployment pipeline, another reason I created a pipeline for generating diagrams was because I am able to abstract all of the setup and configuration into the pipeline. This provides the benefit of reducing the many annoying configuration failures that can occur when running on a local machine. Furthermore, when working with a team, you ensure it runs the same way every time. Finally, it also forces me to put the code in a source code repository which provides all the benefits of versioning.
All of the resources are defined in an AWS CloudFormation template. This template defines the provisioning for S3 buckets to store and host files, IAM permissions for access to resources, an AWS CodeBuild project that install and configures the Diagrams tool and commands to generate the architecture diagrams, and an AWS CodePipeline resource that connects to GitHub and runs a build using CodeBuild.
Listing 3 shows a CloudFormation snippet that provisions the CodeBuild project that runs the commands to generate diagrams from code.
Listing 3 – CodeBuild Project Definition in CloudFormation Template
In Listing 4, you see a CloudFormation snippet that defines a CodePipeline resource for orchestrating the diagrams as code solution. It defines an AWS::CodePipeline::Pipeline resource followed by properties including the Stages and Actions of the pipeline. The Source stage defines a Source action that performs a clone of the GitHub repository and stores all source files in an encrypted S3 bucket provisioned by the CloudFormation stack. The Build Stage defines the GenerateDiagrams action which runs the CodeBuildCommands CodeBuild project that is defined in Listing 3.
Listing 4 – CloudFormation snippet that defines CodePipeline resource for orchestrating diagrams solution
Listing 5 shows the CodeBuild buildspec.yml file run from the pipeline defined in CodePipeline – as defined in Listing 4. In the install phase, it gets the latest versions of the Python package manager (i.e. pip), installs Graphviz, and installs the diagrams tool. During the build phase, it runs the commands to generate the architecture diagrams and then pushes them to a public-read S3 bucket so that anyone can access the generated diagrams.
Listing 5 – CodeBuild buildspec file that runs the commands to generate AWS architecture diagrams from code
Conclusion
In this post, you were able to launch a fully automated stack that deployed all of the resources to generate software architecture diagrams as code using AWS CloudFormation, AWS CodePipeline, and AWS CodeBuild. You also learned some examples of using the Diagrams tool to create AWS diagrams.
All of the source code for this solution is located at https://github.com/PaulDuvall/diagrams-as-code.
|
Stelligent Amazon Pollycast
 |
