See also: A charm’s life, The lifecycle of charm relations, Discussion on hooks: relation-departed and relation-broken - #2 by cory_fu, Relation-broken hook not running in peers relation - #2 by cory_fu
relation-broken is a “teardown” event and is emitted when a relation is being removed; when a unit participating in a relation is being removed, even if the relation is otherwise still alive (through other units); or when an application involved in a relation is being removed.
This event is run only once per unit per relation and is the exact inverse of
relation-created indicates that relation data can be accessed;
relation-broken indicates that relation data can no longer be read-written.
The event indicates that the relation under consideration is no longer valid, and that the charm’s software must be configured as though the relation had never existed. It will only be called after every hook bound to
RelationDepartedEvent has been run. If a hook bound to this event is being executed, it is guaranteed that no remote units are currently known locally.
There are two main operations which cause a
<relation name>-relation-broken event to occur:
juju remove-unit --num-units 1 bar
*-relation-broken -> stop -> ...
juju remove-relation foo bar
*-relation-departed -> *-relation-broken
Of course, removing the application altogether, instead of a single unit, will have a similar effect and also trigger these events.
It is important to note that the
-brokenhook might run even if no other units have ever joined the relation. This is not a bug: even if no remote units have ever joined, the fact of the unit’s participation can be detected in other hooks via the
relation-idstool, and the
-brokenhook needs to execute to allow the charm to clean up any optimistically-generated configuration.
Also, it’s important to internalise the fact that there may be multiple relations in play with the same name, and that they’re independent: one
-broken hook does not mean that every such relation is broken.
For a peer relation,
<peer relation name>-relation-broken will never fire, not even during the Teardown phase.
In Ops, you can observe the event like you would any other:
RelationBrokenEvent event object does not expose any specific attributes.