Ah yes, documentation, we all love it! If you've even been in the ops space you'll be familiar with outdated documentation or sometimes no documentation. As the saying goes, "a picture is worth thousand words", I am a big fan of creating diagrams for my cloud designs. These can be high level block diagrams or more detailed as built or constructed diagrams.
What are the typical options when selecting a diagram tool?
- Cloud based
- Paid vs Open Source
- Local install
There are a couple of different options when it comes to cloud based, there are services that provide online diagram tools from within the web browser and allow you to save them either to their service or popular cloud storage providers like one drive. And there are others that connect directly to your cloud tenancy to help automatically generate diagrams based on the deployed configuration. Lucid charts is an example of this.
Paid vs Open Source
Let's face it, everyone has a budget, if you're a large enterprise this may not be a big factor. But, when it comes to documentation enabling everyone to document with accessible tools is a huge plus, if you can remove some of the financial burden with good open source tools this might be an option.
In the world of cloud this might seem crazy, but having apps that are locally installed may still be required or preferred. If we look at Office 365 for example, all of the functionality isn't present in the web based version compared to the local install. You may also be restricted by enterprise firewalls, proxies or have other data requirements e.g. region lock that requires you to keep your data close by. If you are chasing a local install this will narrow your search a bit.
AWS does try to help in this department, head over to the AWS architecture page you'll be able to download design guides and Visio templates (if you've got access to those products). I recommend checking out the design guides as they will give you guide lines to follow when you do start designing, the guides show how to design layouts like network with compute and dives further into which arrows to use etc. If you are using AWS CloudFormation for Infrastructure as Code (IaC) AWS does have the AWS CloudFormation designer which has a web based graphical tool, it can be a bit clunky and doesn't help to diagram anything outside of AWS that may be relevant.
What do I use
I wanted a tool that was installed locally and that could be installed on multiple different operating systems. I tend to move between Windows, Mac and Linux so Microsoft Visio was restrictive and running VM's to use design tools is less than ideal. I like to store my diagrams as part of the code repository so that it lives with the infrastructure code and is committed with any changes. I've found that keeping the diagram in the repo encourages more frequent changes to the diagram to keep it current. I also have trust issues, anything that connects to my cloud to automatically draw diagrams was going to be a tough sell for me personally, I can appreciate the idea though.
I have been using diagrams.net (draw.io) for over a year now, I have installed the local client across all three operating systems and it gets heavy use. I primarily use diagrams.net (draw.io) on MacOS and have found that the client receives frequent updates and hasn't broken in between Apples updates, which is nice. When I was originally searched for a design tool I didn't realise draw.io had a local install client, the actual link to the download can be tricky to find and is most easily accessible through the github repo:
diagrams.net (draw.io) has all the essential features you'd expect with the added bonus of providing third party shape support. And look automatic updates, yay!
Once you open the tool you'll be presented with general options around the type of diagram you want to create but the really cool part is the built in shapes, head over to more shapes and you'll find a bunch of shapes that you can enable. Simply enabling the AWS19 shapes gives you tones of sweet icons to get you up and running.
In a few minutes you can quickly create a diagram using simple drag and drop, the app has all of the typical features, grids, snap, layers etc. The resulting diagram can be exported in many different formats but I find that most commonly exporting to PNG to be embedded in other documents or tools is what is used most.
Like any new tool there will be some learning curve just working out where certain bits and pieces are. If you're familiar with Microsoft Visio, it's an easy transition. I do find the most common feature I do use is the search, but unlike Visio this one actually works! As you can imagine there are tones of services in AWS so most of the time you just want to type an AWS service like Lambda and get the icon to drag onto the drawing board.
On the radar
Something else to keep in mind is that AWS released a solution a couple of weeks ago to automatically draw diagrams for your live AWS infrastructure that is deployed within your own account. If you remember my previous comment about using a third part product to connect to my account and create diagrams, this actually mitigates that concern as you host the solution. AWS perspective aims to use live configuration data to generate diagrams. Now, as you can imagine, this isn't free. There is a bit to the design and I'm yet to try it out. I'll be looking to do a write up on perspective in the coming weeks.