Visualizing infrastructure with dot and graphviz

Complex infrastructure is difficult to comprehend. That’s where DOT graphs can help.

I build infrastructure for a living. Usually this involves many micro-services interacting with one-another. The network of calls and responsibilities quickly become difficult to comprehend. Sometimes whiteboards and notepads can help to demystify a system but I find documentation as code a much better solution (especially when many developers need on-boarding).

The DOT file syntax is a super simple format for describing graph like interactions between nodes and it’s perfectly suited to infrastructure documentation. By defining a DOT file that describes your system you can then process it with Graphviz and generate SVG or PNG visualizations. You can then incorporate these images into your README.md or build pipeline so that any developer can quickly understand your system.

DOT file

Here is an example DOT file describing a system that handles IOT data streams with a public-api, private vpc, and kinesis pipeline. Don’t worry about the details, just use it as a reference for the outputted image that comes next.

/*
  This is a graphviz dot file
  See https://www.graphviz.org/doc/info/ for help
*/
digraph{
  graph [fontname = "monospace", fontsize="10", color="grey", fontcolor="grey"];
  node [fontname = "monospace",shape="box",style="filled"];
  edge [fontname = "monospace",color="blue", fontcolor="blue",fontsize="10"];
  /* 
    define components in the clusters they belong to
  */
  subgraph clusterProvider{
    label="3rd party"
    "user"
    "app"
    "provider-backend"[label="3rd party\nbackend"]
    "provider-developer" 
  }
  subgraph clusterPublicSubnet {
    label="public subnet"
    "public-api"
    "admin-api"
    "admin-gui"
  }
  subgraph clusterPrivateSubnet {
    label="private subnet"
    "IOT Gateway"
    "resource-service"
    "state-service"
    "DynamoDB" [shape="cylinder"]
    "RDS" [shape="cylinder"]
    "Kinesis"
  }
  subgraph clusterCustomerService {
    label="customer service"
   "customer-service"
  }
  subgraph clusterFleet {
    label="things"
    "thing" [shape="circle", color=""]
  }
  /* 
   define calls between existing components
  */
  "user" -> "app"
  "app" -> "provider-backend"
  "provider-backend" -> "public-api"[label="x-auth-token=API_KEY"]
  "public-api" -> "state-service" [label=" get thing\nlocation"]
  "public-api" -> "resource-service" [label=" get user,"]
  "resource-service" -> "RDS" [dir="both", label="read/write\nnon-transient\nresources"]
  "customer-service" -> "admin-gui"[label="manage users"]
  "customer-service" -> "provider-developer"[label="issue api key"]
  "admin-gui" -> "admin-api"
  "admin-api" -> "resource-service"[label="add users"]
  "IOT Gateway" -> "Kinesis"
  "Kinesis" -> "DynamoDB" [label="upsert \nthing state"]
  "state-service" -> "DynamoDB" [label="read \nthing state"]
  "thing" -> "IOT Gateway" [ label="thing\ntelematics\nstream" ] 
}

Building

dot demo.dot -T svg -o demo.svg

Results

Conclusion

As you can see, Graphviz DOT images provide a very clear and useful overview of complex infrastructure. As a consultant I often generate this graphs for my clients and keep the images and the DOT files in an overview repository for later editing.

I hope this tip proves useful to you too.