Community Session, building a state machine diagram for Juju

juju
#1

This work was inspired by the discussions of @erik-lonroth and @jamesbeedy

We will be working on a state machine diagram for Juju and charms. Here is the WIP: Miro | Online Whiteboard for Visual Collaboration

The meeting will start at 4pm UTC, just after today’s sidecar charming session. Please find the link to the event in the community calendar. We will be joined by two engineers from the Operator Framework team.

This will be an open session and everyone is invited to collaborate.

Thanks,
Pedro.

2 Likes
#2

Hey @pedroleaoc I’ve worked a bit more on the diagram today and you might want to check it out. I had a lot of comments added in and I compressed the diagram alot.

I’d love to work more on this with you.

1 Like
#3

Did you have a plan for this making its way into docs for juju?

#4

Hi Erik, I will try to bring some Juju people and charmers to the weekly meeting this Thursday to get their final feedback on the diagram. I am happy to publish it asap after that :slight_smile:

2 Likes
#5

The diagram has now been worked on and currently looks like this.

This is an eyeopener to at least me on the complexity of developing Juju charms. Having this will at least help.

We definitely need to cut this up into pieces, stages, in how to develop charms…

image
image1918×793 215 KB

[Update 2022-May-06]… here is a graph derived from the above. (Source)

Screenshot from 2022-05-06 08-53-28
Screenshot from 2022-05-06 08-53-281092×1105 42.4 KB

1 Like
#6

@pedroleaoc - I think we need to have a serious talk about this diagram as it now has become an important reference. I’m using it all the time when onboarding new developers and new community members.

But it is also extremely unsatisfying that it is both not true, complete or optimized.

Today to my horror, I also discovered a “new” hook and I know there are more in there which are not documented nor referenced.

Its very, very bad that this resource is not complete and 100% true since its monumental to understanding how Juju works.

Why can’t we get to a point where this diagram i stable? Its been on the map for years now and still its in flux.

@tmihoc

3 Likes
#7

You are right, Erik. As most pieces of documentation, we need to find the sweet spot between having enough information for it to be useful while avoiding overwhelming complexity. To be completely honest, I wasn’t very successful finding this balance.

IMHO We need to put four kinds of people in one room with the goal of producing a clear diagram:

  • charmers
  • @tmihoc
  • someone from the charming team
  • someone from the Juju Core team

What do you think, Dora?

1 Like
#8

I agree that such a diagram could be very helpful, that it’s important for it to be accurate, and that a team set up consisting of charmers, charming team, Juju core team, and me makes sense. I would love to be involved in it, especially since right now it is one of my goals to understand the architecture of Juju. Before any meetings, however, I think it would be useful to have a bunch of lists (e.g., hooks, etc.) and work from there.

1 Like
#9

Are we making progress here? Can we make it happen?

2 Likes
#10

Hi all, were such a diagramming meeting at some point to happen, please let me know as I’m very interested in the result :slight_smile:

2 Likes
#11

I think its more work needed here as this is very much needed to understand why and what drives this state-diagram.

For example, its still not OBVIOUS to many why you need all these states, especially for relations.

This affects where I place code and without knowing the reasons for using this, or that, relation its very hard to make good decisions.

1 Like
#12

I think the way that the current diagram (Miro | Online Whiteboard for Visual Collaboration) is structured results in a bit of confusion between states, events, and hooks. Probably what we’re after is not a ‘state diagram’ but more of a ‘hook execution flowchart’. Because for example after executing a config-changed there is no guarantee that the status is going to be active; maybe the charm dev decides that in that particular situation the charm will need to be put in maintenance and wait e.g. for a relation.

So I think I’m going to give it a shot while I study these things to rework the diagram to separate more clearly between what are the hooks (as ‘points in time where the charm has a chance to do things’) and what is the execution flow in which they can occur. So something more of a flow-driven: user does X -> hook A triggers -> hook B triggers -> if X -> hook C triggers else hook D triggers.

I think this diagram should not mention the status of the charm at all.

#13

Or is there another more up-to-date diagram that I should be looking at? That one seems to include a bunch of todo’s still

1 Like
#14

Absolutely right, you can change it if you like.

Or is there another more up-to-date diagram that I should be looking at?

No not really, the todo:s are all stuff I or nobody yet has managed to cover. This diagram is still “WIP” … Its the best material there is unfortunately.

If you are able to improve it - please involve @tmihoc since this would be a central piece of the documentation of juju going forward…

#15

Yes, I’ll try to push a meeting to gather some knowledge and make it more ‘complete’, since I also believe it’d be really helpful

3 Likes
#16

Update: yesterday we had part 2 of a workshop session to work out an ‘official’ reference diagram! Time to polish it a bit and find a place for it in the documentation, but it’s definitely coming :slight_smile:

#17

Update: as anticipated last Friday during the Community Workshop, we did big steps towards finalizing the graph. Also includes appendices with nice UML-y graphs to detail some event sequence scenarios and defer() behaviour. Take a look! We’re still discussing where exactly to publish it, but your feedback is already welcome :slight_smile:

https://github.com/PietroPasotti/charm-events/blob/main/README.md

Any reference to status (‘active’) is gone from the graph; instead see Unit and Workload Statuses reference doc

2 Likes
#18

How/where do resources fit in these diagrams?

What happens after I juju attach-resouce?

1 Like
#19

Good question! According to Using resources | Developer guide you’ll get a upgrade-charm and that’s it. Or are you talking about what happens ‘behind the scenes’ and how to access the resource?

#20

Ah, I see. That’s what I was looking for. Just to be extra clear: the sequence is juju attach-resource -> upgrade-charm -> config-changed?