Event '<relation name>-relation-broken'

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
• Observing this event in Ops

Emission sequence

There are two main operations which cause a <relation name>-relation-broken event to occur:

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.

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.