Juju state machine documentation and visualization

I’m using this description of Juju state machine, which has helped me alot understanding how juju works from a charming perspective.

It was provided to me by @Dmitrii some time ago, but I have looked for something like this more official, and also perhaps more up to date? (I fear its even not the same today).

Does someone know if there is some official, up-to-date and documented version of this except the one I already have?

As you can see here in what I think is the “best” source, Event Cycle the documentation lacks many parts and examples. Its missing visualization, it doesn’t provide examples for hooks frameworks (only reactive), missing both basic documentation but also examples from the operator framework etc.

I’m going to try to create some sort of tutorial here, but I struggle here since the official documentation I would like to reference is so bad on this topic and the quality of the sources are also weak.

I’ll try draft up a tutorial during the coming week and see there it goes.


… I’m seeing this for example now when I’m exploring this:

2020-09-06 12:20:00 INFO juju.worker.uniter.operation runhook.go:145 skipped "master-relation-created" hook (missing)

The above tells me that a hook named “relation-created” is fired which I can’t find the docs…

This tells me that the state-diagram I have can’t be up-to-date and that the event-cycle looks different than I thought and I’m not sure where this hooks is called and when etc.

Hi Erik,

The <relation-name>-relation-created hook family was added in Juju 2.8 to address some stateful application initialization uses-cases. I think the event lifecycle docs haven’t been updated yet (ping @juju-developers).


relation-created is particularly useful in a scenario where you want to use application relation data (introduced in 2.7.0) on a peer relation which is supposed to replace leader data - bug Bug #1859769 “[2.7.1] peer relation (and its app relation data) ...” : Bugs : juju has some particularities as to why that was introduced.

Operator Framework does not even expose leader data and expects that developers use app relation data with peer relations.

I think the diagram is quite useful for understanding main loop-like semantics of how units operate. Looking at it now, I think it could be enhanced by adding some information about sources of events and the context available in them.

Event objects in the framework do a better job at exposing the context than what was available before:

1 Like

Thanx @Dmitrii - the diagram you provided has been fundamental to my understanding of the event-loop of juju and critical to understanding juju. For me at least.

I would love to see this material more part of the official documentation, rather than an image in my github repo and hidden away in a beginner level tutorial.

I don’t know what I would do without it really.

1 Like

@juju-developers @Dmitrii - any chance of getting a new shiny state-machine-diagram published with information related to how its traversed, context etc?

I’m in the process of writing up a tutorial covering relations and it feels wrong not to be able to reference quality material from the upstream project for this purpose.

I hate to have to use my own =D 0

1 Like

We would love to get something put together. As well as the event cycle doc referenced the the first post, there’s also

But it doesn’t yet reference the relation created hook so there’s some significant work required to get things updated. It’s definitely something we need to deal with.

1 Like

Getting juju core documentation in place, in perfect shape is of course of critical importance in every possible way. I’d love to see this happening.

“A painting will never be better, than the work you put down in its foundation.”

Documentation is definitely a focus for us at the end of this cycle and going forward through next cycle. We’re currently focused on a tutorial series for initial user experience.

1 Like

I love to hear that! I think this is likely the most significant thing you can do to grow juju and get people on board.

I’m also working on a tutorial on relations which I would love to get out there once I have completed it.

I can share a preview code with you @jameinel to get some initial feedback?

Certainly. I look forward to seeing it.

1 Like
1 Like