A language to specify Platform Architecture
Software isn’t hardware. While it takes time to build, assemble and ship a hardware product, software can literally be built, assembled and shipped at the speed of light. Organizations adopting cloud-based infrastructure even abstracts the last bits of hardware away and truly let you write infrastructure-as-code: gone are the days where you were filling out an Excel sheet about which kind of hardware you’d like shipped into your datacenter — it’s one click and — boom — your Kubernetes cluster is ready: in the cloud, and ready for you to publish your deployment.
That means, your place in among your competitors delivering similar software products like you is only limited by the speed with which your engineers can communicate and develop software. And this competition is rising. So the inevitable question is:
How do we communicate effectively and efficiently about how we build large-scale software systems? How do you keep pace and still make all perspectives of the software development process be heard, so that systems are well thought-thru and not sloppy? How do you involve collegues with specializations like Networking, Security, Site-Reliability, Cost planning and share ideas with them quickly but precisely?
Within my projects as Architect, I have found that visuals are extremely powerful for communication. However, the visual cues that are used must be
- intuitive, i.e. obvious in what they mean (usually, there’s no time in meetings to explain them)
- simple, i.e. drawable with a few strokes only, so you can easily click them
together in any whiteboarding tool as well as sketch them on a physical whiteboard - abstractable, i.e. it must be possible to leave out cues that are on a more fine-grained level-of-detail or add them in in order to target an overall picture to a specific audience or concern. A good analogue for this requirement are maps, that add or remove visual cues on different zoom-levels.
Without further ado, here is a description about the primitives I use when visualizing architecture. Let me know your perspective: Which way of representing architecture do you use?
Node: Represent a machine, that has an identity within a network (e.g. a physical workstation / virtual machine / container / etc.) within a solid box. The caption on that box can be the name, purpose or label of the machine or it can be something more specific (e.g. the DNS name, IP address) or more general (e.g. service type, e.g. “Kubernetes node”).
Network Communication: Represent network communication between machines with a solid arrow. The direction of the communication should represent which system initiates communication with the other system (not necessarily how the payload data flows). E.g. who initiates TCP connectivity or who sends UDP packages.
Data Flow: If you additionally want to model (payload) data flow (and the direction of initiation of communication is not equal to the data flow) use a thick solid arrow (in addition) to model in which direction the (meaningful) dataflow happens.
(Virtual) Networks: In case of infrastructure-as-a-service, define which nodes share the same (virtual) network by placing them inside a box with dashed line. The caption of the dashed box may be the name of the virtual network or it’s IP address / subnet mask.
Subnets: If the virtual network is divided into several subnets, divide them by adding different compartments via dashed lines. Denote the subnet IP address / subnet mask, as required.
Network Peering: If virtual networks need to communicate with one another, connect them via double-solid lines to indicate network peering.
Additional Network Interfaces / Public Endpoints: If a node has multiple network interfaces attached — or it has a private and public IP address / hostname — add additional interfaces via the “lollipop
notation”. In the example, notice how “external party” contacts “VM Instance 2” via its public IP address / DNS record while “VM Instance 1” contacts
“VM Instance 2” directly.
Network Security Group / Firewall: Sometimes it can be helpful to add the firewalls / network security groups surrounding a specific system to visualize that certain communication
requires additional firewall clearance. The firewall can be visualized by a thin dotted line and its clearance by a diamond.
Deployment Location and Datacenter: If resources are deployed to different locations or datacenter, they can be placed inside a big “box” grouping all resources deployed to said location. Those boxes should be displayed in light gray to distinguish them from nodes.
Connectivity to (on-prem) endpoints via VPN: Notice that one way to connect ressources from the Cloud to on-premise is via a VPN tunnel linking the cloud network with the on-premise network. A
VPN tunnel should be represented via a “hose” through which all connections (arrows) between nodes needs to be drawn.
Connectivity to (on-prem) public endpoints: Another way to connect to on-prem endpoints is to use their public DNS record (if available), see “Additional Network Interfaces / Public Endpoints”.
Templating / Scaling: If a node can be instantiated multiple times, you can represent this by visualizing multiple nodes shaded behind each other. It helps to describe what the scaling factor for such a scale set is and what it’s lower / upper bounds.
Triggers / Actors: It is always a good idea to put a human into a technical picture: it enforces UX thinking as well as customer orientation and helps a reader find a place where to get started. You can specify the role (ex.: “Developer”) of said user, specify the use case (ex.: “git push”) or even add the developer machine as a “laptop primitive” including the (thick) client the user would use (ex.: “VSCode”).
Triggers / Automation: If a process / communication between systems is initiated by an automation trigger (e.g. schedule based), indicate this by a looping arrow on the initiating system.
Deployed Components: If further drilldown into a node is required, you can specify the deployed artifacts / components by using rounded boxes inside of the node.
