Event '<relation name>-relation-broken'

doc
,
1

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 the relation-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.

2
3

This seems wrong:

  • It should probably say “relation-broken” instead of “created”.
  • I do not see either created nor broken during teardown - only departed.

I.e. I think it should be changed to:

For a peer relation, <peer relation name>-relation-broken never fires, not even during Teardown phase.

1 Like
4

@sed-i - your assessment seems mostly correct. relation-departed events may also be bouncing around during teardown too.

1 Like
5

Thanks for confirming. Yeah, relation departed fires on scaledown/teardown.

6

@sed-i thanks, fixed the created bit! @rwcarlsen is the existing message then correct? PS I’m thinking we can still improve on clarity.

7

I skimmed through it and everything seems right to me.

1 Like
8

I fixed the text in the note, it was still wrong.

9