Docker - Diagrams as code

But what a joy it is to be able to draw diagrams by just writing text. Some tools are better known than others, e.g. Mermaid — which I've since automated in Documentation as Code - Transform Your Infrastructure into Beautiful Diagrams with Python and Mermaid, and whose Graphviz cousin is covered in Python - Generate flows using pydot.

Did you know https://diagrams.mingrammer.com/? Let's explore it using, of course, a Docker ready-to-use image.

What comes out​

Here is a diagram produced by this article, and nothing but text went in:

The command that produced it is a single line; the .py file is piped into a container and the .png lands in your current folder:

$ cat team.py | docker run -i --rm -v $(pwd):/out -u 1000:1000 gtramontina/diagrams:0.23.3▋

Why it works​

• The .py file is not executed on your machine: it's piped into the container, which contains Python, the diagrams library, Graphviz and the whole AWS/Azure/GCP/K8S icon sets.
• -v $(pwd):/out is what makes the generated image come back to your folder instead of dying with the container.
• -u 1000:1000 runs the container as you, so the produced file belongs to your user and not to root.

The source​

As always, for the demo, please start a Linux shell and run mkdir -p /tmp/docker-diagrams && cd $_ to create a folder called docker-diagrams in your Linux temporary folder and jump in it.

Please create a new file called team.py with the content that produced the diagram above:

from diagrams import Diagram
from diagrams.aws.compute import EC2
from diagrams.aws.database import RDS
from diagrams.aws.network import ELB

with Diagram("My Team", show=False, direction="TB"):?
    (
        ELB("Olivier")?
        >> [EC2("Christophe"), EC2("Jason"), EC2("Niki"), EC2("Rudy"), EC2("Stijn")]?
        >> RDS("Work together")?
    )

Then run the conversion command shown here above.

0.23.3 is the latest version available when writing this document. See https://hub.docker.com/r/gtramontina/diagrams/tags to retrieve the latest one.

Easy, right?

A real architecture​

Twenty lines of Python for a team chart is nice; here is the same exercise on an actual infrastructure:

from diagrams import Cluster, Diagram
from diagrams.k8s.compute import Pod, StatefulSet
from diagrams.k8s.network import Service
from diagrams.k8s.storage import PV, PVC, StorageClass

with Diagram("Stateful Architecture", show=False):?
    with Cluster("Apps"):?
        svc = Service("svc")
        sts = StatefulSet("sts")

        apps = []
        for _ in range(3):?
            pod = Pod("pod")
            pvc = PVC("pvc")
            pod - sts - pvc?
            apps.append(svc >> pod >> pvc)?

    apps << PV("pv") << StorageClass("sc")?

And the resulting image:

Crazy, right? And all of this without installing anything!

The Docker image code base is here: https://github.com/gtramontina/docker-diagrams, and you'll find plenty of other examples at https://github.com/mingrammer/diagrams.

Icons and other tools (reference, skip this for now)​

A tremendous list of icons/nodes is available on multiple pages at https://diagrams.mingrammer.com/docs/nodes/onprem. See OnPrem, AWS, Azure, GCP, IBM, K8S and also how to create our own (using local .png images): Custom.

And, since diagrams is far from being the only text-to-picture tool around, here is the list I keep coming back to:

• DB Diagram (see also Drawdb-app - Render your database model as png, Markdown, mermaid, ...)
• DBML-renderer, dbml-renderer renders DBML files to SVG images
• Graphviz, Graphviz is open source graph visualization software
• JSON Crack, seamlessly visualize your JSON data instantly into graphs (I've dedicated an article to it: Rendering a JSON file as a mind map)
• Kroki, creates diagrams from textual descriptions
• Mermaid, its live editor, the preview addon for vscode and the convert tool as a CLI tool
• Nomnoml, tool for drawing UML diagrams based on a simple syntax
• Pikchr, Pikchr (pronounced "picture") is a PIC-like markup language for diagrams in technical documentation
• Plantuml, generate diagrams from textual description
• Sequence diagram (seems based on Mermaid)
• Structurizr, a way to create Structurizr software architecture models based upon the C4 model using a textual domain specific language
• svgbob, convert your ascii diagram scribbles into happy little SVG
• Vega, A Visualization Grammar
• yEd Graph Editor, a graphical interface: you will need to drag & drop objects and resize them. It does not support text files like the other tools already mentioned here.

Conclusion​

Architecture diagrams that live in your repository, that you can diff and review like any other file, and that never require Python or Graphviz on your machine. The next time the infrastructure changes, you edit a line of text instead of dragging a box.

If you'd rather stay with a syntax you already know, Documentation as Code - Transform Your Infrastructure into Beautiful Diagrams with Python and Mermaid does the same trick with Mermaid.