DEV Community

loading...
Cover image for Infrastructure diagrams as code

Infrastructure diagrams as code

raoulmeyer profile image Raoul Meyer ・3 min read

Creating a diagram of your infrastructure is quite a tedious job. I noticed that when, for example, someone new wants to understand our architecture, I tend to grab a marker and draw it on a whiteboard. That works well, but it keeps all that information that we have at our disposal inside of our heads. Next time someone asks, I'd just draw it all over again, maybe missing some interesting parts.

To actually get all of the benefits of having these kind of diagrams available at all times, you want to keep them up to date. When you need a third party tool to do this, that makes the effort of updating them way higher than it needs to be.

That's why I built a very small Javascript library that allows you to generate diagrams with code. The goal is to specify your infrastructure in a way that reads naturally. If you want to check it out, go ahead an go to the Github repository.

How it works

Let's just dive straight into an example of how the library works. Imagine we want to plot an infrastructure containing a load balancer, some webservers behind that load balancer and some databases from which the webservers read. We want to generate the following diagram:

Example diagram

This is how we would set that up:

const { diagram, dac: { Client, Elb, Ec2Cluster, RdsCluster } } = window;

const client = new Client();
const loadbalancer = new Elb();
const webserver = new Ec2Cluster();
const databases = new RdsCluster();

client.getsDataFrom(loadbalancer);
loadbalancer.getsDataFrom(webserver);
webserver.getsDataFrom(databases);

diagram.render();

We first specify a list of things that make up our infrastructure. Then we specify how those things communicate with each other. In the end we render the diagram.

Other options we have for specifying the relationship between nodes are sendsDataTo() and exchangesDataWith(). The library offers an extensive list of (for now mostly AWS) infrastructure components that you can use. They will all get a nice icon and for some there's also a cluster variation available.

Advantages

Specifying your infrastructure diagrams as code has several advantages.

Because it's code, it can be quite verbose about what you're doing and why. That's good, because that allows you to capture the intent of relationships in your diagram. If that's not enough, you can even add comments to make things super clear.

It's easy to add this to your version control. And you can actually see what changed as well, and even why it changed if you add a good commit message. With special file formats that are often used by diagramming tools, this would be hard.

It's easy to keep up to date without any tooling required. Anyone with a text editor can update your docs. Now there's really no excuse anymore to not update technical documentation.

Conclusion

To me this approach seems very useful, as it lowers a barrier that I find quite high with the current tooling available. There are clearly big upsides to being able to create a digital version of a diagram in the same time that you would draw it.

If you want to try it out, check out the Github repository.

How do you document your infrastructure? What do you think of this approach? I'm very interested to know your thoughts! Also, if you know of any tools or libraries that do something similar, please let me know!

Discussion

pic
Editor guide
Collapse
cjbrooks12 profile image
Casey Brooks

Very nice! I'd be interested to hear more about how it works under-the-hood to draw those diagrams.

On another note, have you heard of Mermaid.js or PlantUML? They are both programming-ish languages for drawing diagrams like these, you might find them very useful for infrastructure documentation!

Collapse
raoulmeyer profile image
Raoul Meyer Author

Thanks! For now it's a very thin wrapper around the network module of vis.js. Vis.js does all the hard work here, I mostly configured it with all the right settings that make sense in this case (and added some icons).

Thanks for mentioning those! I've heard of both but haven't given them an extensive look yet. I do like the idea of the documentation being actual code, but some specialized markup like these libraries use of course also has a lot of advantages.

Collapse
mpermar profile image
Martín Pérez

Well done Raoul. I believe if you now get rid of the library itself you might actually be into something!

I mean, you could use some markup language to define the diagram, or just invent the syntax and then auto-generate the code as it seems it is going to be pretty repetitive.

Collapse
petertorres profile image
Pete Torres

Well done and thank you for writing this post! I realize tools such as Terraform provide the ability to generate GraphViz dot output, but it doesn't look pretty for complicated deployments. blast-radius improves on this, however I really appreciate how your solution provides a visual story similar to LucidChart diagrams.

Collapse
raoulmeyer profile image
Raoul Meyer Author

I hadn't heard of the tools you mention, they look very useful to me, maybe for a different use case though. Glad you like it!

Collapse
denisnutiu profile image
Denis Nuțiu

Interesting post, I'm gonna stick with Visio tho.

Collapse
raoulmeyer profile image
Raoul Meyer Author

No it's not, but for now it mostly contains AWS icons. You can add any icons you want though! You can read how to do that in the documentation on Github.

Collapse
neomaxzero profile image
Maximiliano

Nice! This looks quite interesting.

Collapse
antirek profile image
Dmitriev Sergey

I was inspired your diagrams, really. And write my own diagram-as-code solution: github.com/antirek/network-diagram based on cytoscape.js diagram ;)

Collapse
jwollner5 profile image
John 'BBQ' Wollner

This is an awesome idea and cleverly done. 👍

Collapse
raoulmeyer profile image
Raoul Meyer Author

That's very encouraging to hear, thanks!

Collapse
andy9775 profile image
Andy

If pulumi supported something like this it would be super cool.

Collapse
raoulmeyer profile image
Raoul Meyer Author

Yes I was actually thinking about it, it would be quite easy to write something that converts whatever infrastructure as code to a diagram like this.

I hadn't heard of pulumi before but at a first glance it looks awesome.

Collapse
shreyasht profile image
Shreyash

This is awesome! Is there a way I can contribute?

Collapse
raoulmeyer profile image
Raoul Meyer Author

Thanks!

Of course, you can contribute by creating a pull request in github. If you want to discuss first how to approach things, you can create an issue instead. Very much appreciated!