Diagrams as code

10 Jun, 2022
Xebia Background Header Wave

Most of you have heard of “infrastructure as code” by now. But building cloud infrastructures is more than coding infrastructure. In this blog I will show you how I make my own live easier by generating infrastructure diagrams from code. When you have read my previous blogs about Commit messages done the right way. You are not surprised that I like to make things easy for the reader. When you are new to a team, or you are not familiar with a specific repository that your team maintains. It helps when the of the repository helps you understand what the repository does.

A picture is worth a thousand words!

Nice diagrams will help you a lot! But often they are either created in a program that you don’t master. Or you don’t have a access or a license to it. This makes it harder to keep the images up to date. And easier not to update them at all. By managing the diagrams the same way as we manage our infrastructure. We also get the same benefits! Not only that when you make a change to your infrastructure you can update the image in the same commit. This makes it easier for the reviewer. Because, next to the code change he also will see a visual presentation of the change.

How does it work?

Enough about the theory, how do you do that? Within Python there is a package named diagrams. The website has a lot of examples I copied a few to this article. First we will configure a poetry environment. Afterwards we will install the dependency.

mkdir diagrams-as-code
cd diagrams-as-code
poetry init
poetry add diagrams

Once you have done that, we can create a file called

from diagrams import Diagram
from import EC2
from import RDS
from import ELB

with Diagram("Grouped Workers", show=False, direction="TB", filename="images/grouped_workers"):
    ELB("lb") >> [EC2("worker1"),
                  EC2("worker5")] >> RDS("events")

As you can see the syntax is pretty straight forward. We have 5 workers that are behind a load balancer. The workers can connect to an RDS database named events. When you then run the following command:

poetry run python

The output looks like this: Grouped Workers Pretty cool right? Let’s do another one, we will create a file called

from diagrams import Cluster, Diagram
from import ECS
from import ElastiCache, RDS
from import ELB
from import Route53

with Diagram("Clustered Web Services", show=False, filename="images/clustered_web_services"):
    dns = Route53("dns")
    lb = ELB("lb")

    with Cluster("Services"):
        svc_group = [ECS("web1"),

    with Cluster("DB Cluster"):
        db_primary = RDS("userdb")
        db_primary - [RDS("userdb ro")]

    memcached = ElastiCache("memcached")

    dns >> lb >> svc_group
    svc_group >> db_primary
    svc_group >> memcached

So this example is a bit more complex. We now introduced Route53, and we added a caching mechanism. To clarify the grouping we made use of the Cluster option. And when we run the following command:

poetry run python

We will get the following output:

Clustered Web Services


You will receive the same benefits from “infrastructure as code”. When you manage your “diagrams as code”. Version control comes out of the box. Because you combine the infrastructure code change. With the diagram code change you make the life of you and your teammates a lot easier. Photo by Luca Bravo on Unsplash.

Joris Conijn
Joris has been working with the AWS cloud since 2009 and focussing on building event driven architectures. While working with the cloud from (almost) the start he has seen most of the services being launched. Joris strongly believes in automation and infrastructure as code and is open to learn new things and experiment with them, because that is the way to learn and grow. In his spare time he enjoys running and runs a small micro brewery from his home.

Get in touch with us to learn more about the subject and related solutions

Explore related posts