I’ve managed to come a long way with implementing relations, but now when I’m implementing more complex charms with many relations, I have found myself ending up in a bit of a mess in my code. Using various of events which may or may not be right. I definitely need to step back a bit to understand more about relations and look for help.
First, I would love to know about some up-to-date documentation that covers all the different states/hooks that are executed as part of relations where information is found about:
When (under what conditions) they are fired and what data is available.
What responsibilities the developer have in the different hooks vs what juju takes care of.
Why a developer should/must implement them.
Examples on how a developer should implement them.
I’ve studied a few charms, and I see most people are using either “on_relation_created”, “on_relation_joined”, “on_relation_changed”. But I can’t see any pattern on what people put in them. It seems very “free-form” at the moment. E.g. You pick one and be happy about it?
More questions arise around “peer” relations. Are they different? Do they follow a different state transition diagram? What data is available etc…
These things should mostly be covered by Juju | Relations. Did you already take a look at that and was it not clear from doing so, or did you not see that yet?
Would be good to understand gaps in those docs and make sure we get them updated as appropriate.
I think those two points should be made clear in the Operator Framework docstrings, that is used to build the online ops docs. Currently, the docs are not clear about those points.
I think that the existing docs provide a pretty nice reference framework if you already understand relations, and want to review what relation events are available, and when they fire. The “Event Types” table in the doc at Juju | Relations tells you when each relation hook will fire, under what circumstances, for example.
I think what’s missing is a doc explaining why there are five relation events, and why you might want to use an individual event over another. We can work on putting that together.
For now, know that most of the time, you can just use the “relation changed” hook, similarly to how you would use a “config changed” hook. The other relation events allow you to react more quickly to a new relation, in circumstances where you might not need all of the information in the relation, or cleanly handle scale down and teardown events.
Oh, there is quite a bit of commenting needed here. I’m not sure I know exactly where to start… I’ll give it a try:
There is no information about in what ORDER the “events” are fired.
The introduction to “peer” events does not explain differences or why they exist and if they behave differently than normal hooks/events.
The description of “peer” relations differ from the description of normal events.
The peer events are also missing what order.
The “limit” option is elsewhere described as being ignored by Juju. Has that changed?
No information about if juju “enforces” or how juju acts on the various “options”. Like the " optional" parameter doesn’t tell us what will happen if set to “false”.
The description and reference of “connections” in “limit” is not clear as what that really means . Is it applications relating to it? Is it units? “Connections” is not a Juju term and is confusing.
The information about what information (data) is available in the different relational hooks is not described. The information that is in the table(s) I think is incomplete.
