How to draw diagrams of juju deployments (WIP draft)

juju
, ,
1

This is just a braindump, not official guidelines!

Wdyt so far?

Juju deployments can be complex. We have juju relations between charms, but also tcp/http/whatever traffic between workloads. We also have multiplicity. We also have models, controllers and clouds.

Diagrams can be very useful for making sure everyone is on the same page.

“Freestyle” mermaid diagrams

Pros and cons

Pros:

  • Mermaid diagrams are plain-text so can be conveniently version-controlled.
  • GitHub, PyCharm, Obsidian, … can render mermaid diagrams natively.
  • You can prototype and share from the browser: https://mermaid.live

Cons:

  • “Freestyling” diagrams means there is no common language and it is therefore difficult to produce diagrams that are inherently consistent and/or that everyone will understand.
  • Little control over how diagrams are rendered, and sometimes it’s quite off.
  • Not (yet) supported in discourse.

Relation view

Technically, relations are between charms, not between units.

  • When the focus is on relations, do not draw units, only apps.
  • TODO: how to depict that one of the charms in the diagram is a subordiante?

image

(edit a copy of this diagram)

If you want to be explicit about the endpoint names on both sides of the relation,

image
image1067×278 26.6 KB

(edit a copy of this diagram)

Machine view

In machine view we have regular binaries / snaps.

  • Think if you really need to draw relation lines – as far as the binaries/snaps are concerned, everyone is equal.

Also note that:

  • There could be a different principal charm for every subordinate unit.
  • The subordinate leader is not necessarily in the same machine as the principal leader.

image
image1087×129 7.23 KB

(edit a copy of this diagram)

When you have a complex subordiante deployment, drawing relation lines could be helpful:

image
image1071×281 21.3 KB

(edit a copy of this diagram)

Controller/model view

  • Each controller/model in its own subgraph
  • If there is only one model in each controller, then a single subgraph is better (no need to nest)
  • TODO: come up with good guidelines

image
image1078×623 43.8 KB
(edit a copy of this diagram)

“Freestyle” draw.io diagram

tls
tls1568×744 49.8 KB

Other ideas

2

@tmihoc wdyt?

1 Like
3

Love the direction this is taking! I think there should be one more level you can drill down to: the ‘databag view’. We can use as inspiration jhack’s show-relation view, which I think is quite intuitive. The arrows in that case should link databag to unit, not unit to unit.

4

Hi @sed-i ,

When we first discussed this I did not have an answer, but I’ve pinned it and thought about it some more, and now I do:

What I recommend now is the c4 model for visualizing software architecture plus its companion tool, structurizr.

  • It is not freestyle. Rather, it is very opinionated in a way that promotes clarity. (I can elaborate.)
  • It’s code-based and, in fact, model based. Individual diagrams are disposable artifacts – what matters, and what you can version-control etc etc., is the model. (I can elaborate.) PS You can export to Mermaid, PlantUML, and other formats.

We’ve started using this combination for Juju docs:

https://juju.is/docs/juju :

https://juju.is/docs/juju/tutorial :

  • image
  • image

I’ve hit a couple of limitations but, so far, I have been able to work around them – plus the pros much outweigh the cons (at least, for me).

Not entirely sure how we can tackle the needs for the charming docs yet, but hoping we can figure that out together.

5

Nice!

  • Where do you keep the source of the diagrams?
  • Do we have some control over rendering? The default font seems too small

Exporting to mermaid offers some solution to the two above, but not sure if you’d want the source of truth to be mermaid.

6

I’m thinking we can keep the source in juju/docs (where we currently keep no docs but where I’d like us to start tracking all issues related to juju.is docs).

The structurizr tool does allow some control over rendering. And we can export to other formats and then process further with other tools, if necessary (though for simplicity etc. I’d personally stick to just one tool and format, namely, structurizr, because I like the c4model it implements and the model-driven way in which it implements it).