A Picture is Worth A Thousand Words

Verison control as we traditionally know is the practice of tracking and managing source code and most importantly it is an effective collaboration means for working amongst and across teams. Most of us have used and relied on traditional software like Team Foundation Version Control, Subversion, GitHub to name a few. These are proven means to store, track, branch, merge software code written as text. But they fall short of the ability to track architecture diagram changes.

Software tools like Vision, LucidCharts, and Draw.io are popular in creating and editing diagrams, illustrations, and visual aids. But the only way to version the diagrams is by storing them under different filenames. They do not provide the ability to compare between versions or to track changes.

That is until Now !! Welcome, a new entrant – “Diagram as Code“.

In this blog post, I demonstrate using a toy example how to install, use, test, and version control using Diagrams.

Although I use Azure cloud services & PyCharm as IDE, you are welcome to try using other cloud services or IDEs.

Prerequisites

1. Python version 3.6 or above
2. Graphviz – Python library to parse and render as image
3. diagrams

Command  - pip install graphviz  installs graphviz

Command  - pip install diagrams installs diagrams

Creating a Diagram

Diagrams consist of Diagram, Nodes, Clusters, and Edges.

• Diagram – similar to a drawing board/canvas representing a Solution Architecture.
• Node – A node representes a cloud resource e.g., a Linux Virtual machine or SQL database.
• Cluster – consists of a collection of Nodes encapsulated within its functional area.
• Edge – an object connecting two nodes.

Example 1

Step 1 –

Add an Azure Virtual Machine for an application to the Diagram. To import a node, add the node library from the list here.

# Demo
# import required libs
import os

# Set Graphviz path
os.environ["PATH"] += os.pathsep + 'C:/Program Files/Graphviz/bin'

# import required diagram
from diagrams import Cluster, Diagram
## Add Azure VM
from diagrams.azure.compute import VM


with Diagram("Demo", show=False):
    VM("App")

A png file called demo.png, like shown below, is created.

Step 2

Connect the VM to an Azure SQL Database, Create an Edge between nodes by adding “>>” .

# Demo
# import required libs
import os

# Set Graphviz path
os.environ["PATH"] += os.pathsep + 'C:/Program Files/Graphviz/bin'

# import required diagram
from diagrams import Cluster, Diagram
## Add Azure VM
from diagrams.azure.compute import VM
## Add Azure SQL Server
from diagrams.azure.database import SQLServers

with Diagram("Demo", show=False):
    VM("App") >> SQLServers("SQL Server")

Output of the above code –

Step 3 –

Let’s group App VM and SQL Server as the Application Layer cluster. Then, connect this Application Cluster to another group representing Azure Storage. The following lines of code, is used to achieve this –

with Cluster("Applications"):

Here is the code snippet –

# Demo
# import required libs
import os

# Set Graphviz path
os.environ["PATH"] += os.pathsep + 'C:/Program Files/Graphviz/bin'

# import required diagram
from diagrams import Cluster, Diagram
## Add Azure VM
from diagrams.azure.compute import VM
## Add Azure SQL Server
from diagrams.azure.database import SQLServers
## Add Azure Data Lake Storage
from diagrams.azure.storage import DataLakeStorage

with Diagram("Demo", show=False):
    with Cluster("Applications"):
        app_cluster = VM("App") >> SQLServers("SQL Server")

    with Cluster("Data Lake"):
        app_cluster >> DataLakeStorage("Azure Storage")

Output of the above code –

Example 2

Here is an example from Microsoft Reference Architecture for Retail and e-commerce using Cosmos DB

Below is the representation generated using diagrams.

Stay tuned, more examples and tutorials are to come. If you are interested in the source code for the above examples, leave a comment below.