Event '<relation name>-relation-joined'

doc
,
1

Event > List of events> Relation events > <relation name>-relation-joined

See also: A charm’s life, The lifecycle of charm relations, Discussion on hooks: relation-departed and relation-broken, Relation-broken hook not running in peers relation, Charm hooks

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.

relation-joined is emitted when a unit joins in an existing relation. The unit will be a local one in the case of peer relations, a remote one otherwise.

By the time this event is emitted, the only available data concerning the relation is

  • the name of the joining unit.
  • the private-address of the joining unit.

In other words, when this event is emitted the remote unit has not yet had an opportunity to write any data to the relation databag. For that, you’re going to have to wait for the first relation-changed event.

Contents:

Emission sequence

From the perspective of an application called foo, which can relate to an application called bar:

Scenario Example Command Resulting Events
Create unit juju integrate foo bar *-relation-created -> *-relation-joined -> *-relation-changed
Create unit juju add-unit bar -n 1 *-relation-joined -> *-relation-changed

For a peer relation, <peer relation name>-relation-joined will be received by peers some time after a new peer unit appears. (And during its setup, that new unit will receive a <peer relation name>-relation-created).

For a peer relation, <peer relation name>-relation-joined will only be emitted if the scale is larger than 1. In other words, applications with a scale of 1 do not see peer relation joined/departed events. If you are using peer data as a means for persistent storage, then use peer relation-created instead.

relation-joined can fire multiple times per relation, as multiple units can join, and is the exact inverse of relation-departed. That means that if you consider the full lifecycle of an application, a unit, or a model, the net difference of the number of *-relation-joined events and the number of *-relation-departed events will be zero.

Observing this event in Ops

In ops, you can observe this event like you would any other:

# in MyCharm.__init__
self.framework.observe(
  self.on.foo_relation_joined, 
  self._on_foo_relation_joined)

The RelationJoinedEvent object does not expose any specific attributes, but the unit attribute always refers to the unit that just joined the relation.

2
3