Graph module to visualize models

Posted on Posted in blog, technical

With the ISO 3.4 release, we have open-sourced the graph module. The graph module is an internal tool we use at Inmanta to turn models into pictures. In this blog post, I’ll explain how you can use it, too. 

The graph module has two modes: class diagrams and instance diagrams. A class diagram shows all the entity types defined and the relations between them. An instance diagram shows the instances that exist in the model.

(This tutorial assumes you have Inmanta installed, the installation instructions can be found at docs.inmanta.com).

Class Diagram

Class diagrams can be used to show the internal structure of a model (or module). It shows all the entities, their relations and attributes.

Let’s say we want to use the PostgreSQL Inmanta module to manage a PostgreSQL server.  But we have never used this module before. Before diving into the docs, we want to have a quick overview of what is in there. So we make a class diagram!

First we make a simple project to work in:

cookiecutter gh:inmanta/inmanta-project-template project_name=graph_test --no-input

Then we open the main.cf file and add:

import graph # import the graph module, loads all the magic import postgresql # import the module we want to graph   graph::ClassDiagram(    name="test_diagram", # give the output file a name    moduleexpression=["postgresql::.*"] # select what has to go in the diagram )

Now we execute a specific export command to produce the diagram:

inmanta -vv export -j out.json --export-plugin=classdiagram

What we get now, is a file called test_diagram.puml. This is a plantuml file. Plantuml is a tool to make class diagrams using a human writable format. Using the tool plantuml (or via the online tool), we can export the plantuml file into an image.

plantuml test_diagram.puml

The result is this:

So in 4 easy steps you can visualise any Inmanta model.

Instance Diagram

An instance diagram allows you to make a diagram of specific instances in your model.

Instance diagrams are very versatile. In the past they have been used to make wiring diagrams for physical devices, network diagrams, deployment diagrams (showing what goes where), component diagrams and more.

The most difficult part here is that models have many instances in it (thousands or even millions). So it is important to be able to filter exactly the things you need. For this, we have a little language to specify filters.

The way it works, is that you specify which types you want in the diagram and which relations.

For example, with this main file:

import graph # import the graph module, loads all the magic  h = std::Host(name="testhost", os=std::linux) std::Package(host=h, name="vim", state="installed") std::Package(host=h, name="jq", state="installed") std::Package(host=h, name="inmanta", state="installed")  graph::Graph(     name="hostgraph",     config=""" std::Host std::Package std::Package.host """ )

We select the types std::Host and std::Package and the relation std::Package.host. This will show all the Hosts in the model and the Packages deployed on them.

We can make the diagram as follows:

inmanta -vv export  -j x.json --export-plugin=graph

This will produce a file called hostgraph.dot which is a graphviz file. If graphviz is installed on your system, it will also produce hostgraph.png:

In this diagram the difference between Hosts and Packages is not very clear. This can be improved by adding additional options to the selectors:

graph::Graph(     name="hostgraph",     config=""" std::Host[shape=square] std::Package[label="Package {name}"] std::Package.host """ )

This makes the Hosts into squares and adds the word Package to the packages.

Or even better:

graph::Graph(     name="hostgraph",     config=""" std::Host[shape=square, container=true] std::Package std::Package.host[type=contained_in] """ )

This puts the packages inside the host.

Conclusion

The graph module gives you the full advantage of making models: it allows you to make diagrams for free.

It is a tool I have always had a double relation with. It is not the nicest code Inmanta has ever produced (more of the opposite), it is not particularly great, but it works.

And it is useful. Every time I have to produce diagrams for customer presentations and trainings, I’m happy it is there. No hours spent turning my code into diagrams by hand. I’ve even come to the point where I draft architectures and models in Inmanta code first, as it is has become the easiest way for me to make diagrams.

By open-sourcing it, we give this power to you. I hope it benefits you as much as it benefits me.