Cloud architecture diagrams

I've seen a lot of discussion about cloud architecture diagrams recently, with people specifically asking how to create them, which tools to use, and where to get the icon sets. Many of the example cloud architecture diagrams that I see online are relatively generic, and look something like this.

This diagram shows that a number of AWS services are being used; including Route 53, Elastic Load Balancer, EC2 (with auto-scaling), and MySQL on RDS. It looks good, it's colourful, and it uses the appropriate icons from the AWS icon set. It's a decent first attempt because it helps to highlight which AWS services are in use. But that's also the biggest problem - it's an "infrastructure diagram", and is only telling you half of the story. Understanding which AWS services are being used is great, but I'd really like to also know how you are using them.

Deployment diagrams

Most software development teams would be better creating a "deployment diagram", which shows the mapping of deployable things (e.g. your applications and data stores) to things that exist in the infrastructure environment. UML has a deployment diagram, which allows you to show the mapping of deployable artifacts onto device nodes and execution environments. The C4 model also has a deployment diagram, which shows the mapping of C4 model containers (again, applications and data stores) onto things that exist in the infrastructure environment (which I call "deployment nodes"). Here's an example.

This diagram again shows the AWS services in use, but it also shows what they are being used for, through the inclusion of the web application and database. You can, of course, add more detail as needed; including VPCs, VLANs, firewalls, IP addresses, instance counts, scaling limits, etc. It's worth noting that the same advice applies to diagramming Docker and Kubernetes environments too - remember to show your own applications and data stores.

Summary

Many of the example cloud architecture diagrams you'll see online are good starting points but they only tell half of the story. To tell more of the story, favour deployment diagrams over infrastructure diagrams.