Event > List of events> Relation events >
<relation name>-relation-broken
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
Source:
ops.charm.RelationBrokenEvent
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
. 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.
Contents:
Emission sequence
There are two main operations which cause a <relation name>-relation-broken
event to occur:
Scenario | Example Command | Resulting Events |
---|---|---|
Unit removal | juju remove-unit --num-units 1 bar |
(foo/0): *-relation-departed (bar/0): *-relation-broken -> stop -> ... |
Relation removal | juju remove-relation foo bar |
(all units): *-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
-broken
hook 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 therelation-ids
tool, and the-broken
hook 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.
Observing this event in Ops
In Ops, you can observe the event like you would any other:
self.framework.observe(
charm.on.<relation name>_relation_broken,
self._on_<relation name>_relation_broken
)
The RelationBrokenEvent
event object does not expose any specific attributes.