Event > List of events> Relation events
See also: Charm lifecycle, The lifecycle of charm relations, How to integrate with other charms
Before juju v.3.0, ‘integrations’ were called ‘relations’. Remnants of this persist in the names, options, and output of certain commands, and in integration event names.
If a charm has any relations, it typically may want to be notified of when the relation is created or destroyed, when a remote unit joins or leaves, or when a unit other than itself (local or remote) changes the relation data. Relation events allow charms to observe changes to the juju model in all of these situations.
Contents:
Complete list of relation events
All relation events are tied to a specific relation. You can’t just observe “any change to any relation’s data”: you need to individually register observers to each relation.
For this reason, the relation events are prefixed with a <relation name> placeholder. The real name of the event will depend on how the charm refers to the relation.
-
<relation name>-relation-created; emitted when a new relation is created. -
<relation name>-relation-broken; emitted when a relation is broken. -
<relation name>-relation-joined; emitted when a new unit joins in an existing relation. -
<relation name>-relation-departed; emitted when a unit departs from an existing relation. -
<relation name>-relation-changed; emitted when another unit has touched the relation data.
Relation event triggers
Relation events trigger as a response to changes in the juju model relation topology. When a new relation is created or removed, events are fired on all units of both involved applications.
| Scenario | Example Command | Resulting Events |
|---|---|---|
| Relate | juju integrate foo:a bar:b |
(foo): a-relation-created -> a-relation-changed(bar): b-relation-created -> b-relation-changed
|
| Remove relation | juju remove-relation foo:a bar:b |
(foo): a-relation-broken(bar): b-relation-broken
|
If you have two already related applications, and one of them gains or loses a unit, then the newly added unit will receive the same event sequences as if it had just been related (from its point of view, the relation is ‘brand new’), while the units that were there already receive a -relation-joined event.
Similarly if a unit is removed, that unit will receive -relation-broken, while the ones that remain will see a -relation-departed.
| Scenario | Example Command | Resulting Events |
|---|---|---|
| Add unit | juju add-unit foo -n 1 |
(foo): a-relation-created -> a-relation-changed(bar): b-relation-joined -> b-relation-changed
|
| Remove relation | juju remove-unit foo:a --num-units 1 |
(foo): a-relation-broken(bar): b-relation-departed
|
-relation-changed events are not only fired as part of these event sequences, but also whenever a unit touches the relation data.
As such, contrary to many other events, -relation-changed events are mostly triggered by charm code (and not by the cloud admin doing things on the juju model).
Relation events in ops
In ops, all relation events inherit from ops.charm.RelationEvent, which gives them the following attributes: