Relation events

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.


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 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:

  • relation: the ops.model.Relation instance, involved in this event
  • app: the remote ops.model.Application that has triggered this event
  • unit: the remote ops.model.Unit that has triggered this event.

Last updated 6 months ago. Help improve this document in the forum.