`leader-elected` event

Source: ops.charm.LeaderElectedEvent
See also: Core lifecycle events, Leader, How to implement leadership

The leader-elected event is emitted for a unit that is elected as leader. A unit receiving it can be guaranteed that it will have leadership for approximately 30 seconds (from the moment the event is received). After that time, juju might have elected a different leader.

Leadership can change while a hook is running. (you could start a hook on unit/0 who is the leader, and while that hook is processing, you lose network connectivity for a long time [more than 30s], and then by the time the hook notices, juju has already moved on to another leader.)

Juju doesn’t guarantee that a leader will see every event: if the leader unit is overloaded long enough for the lease to expire, then juju will elect a different leader. Events that fired in between would be received units that are not leader yet or not leader anymore.


Emission sequence

  • leader-elected is always emitted after peer-relation-created. However, by the time relation-created runs, juju may already have a leader.
  • charms that flip into an error state will attempt to re-run the event that caused the error when a human operator runs “juju resolve” on the charm.
  • When a leader loses leadership it only sees the leader-settings-changed event, just like all the other non-leader units. Therefore, leader-elected is only ever received if right now, you are the leader.
  • On scale-down, if the leader was one of the units removed, then one of the remaining units will be elected as leader and see the leader-elected event; all the other remaining units will see leader-settings-changed.


This section is about how to ‘cause’ this event.

It is not possible to select a specific unit and ‘promote’ that unit to leader, or ‘demote’ an existing leader unit. Juju has control over which unit will become leader after the current leader is gone.

However, you can cause leadership change by destroying the leader unit or killing the jujud-machine service in operator charms.

  • non-k8s models: juju remove-unit <leader_unit>
  • operator charms: juju ssh -m <id> -- systemctl stop jujud-machine-<id>
  • sidecar charms: ssh into the charm container, source the /etc/profile.d/juju-introspection.sh script, and then get access to a whole bunch of helpful shell functions, including juju_stop_unit.

That will cause the lease to expire inside 60s, and another unit of the same application will be elected leader and receive leader-elected.

Disclaimer: see juju/1958542 for a known bug with this.

It is also possible to cause leadership change ‘indirectly’, by scaling down an application. Typically if you deploy multiple units from the start (e.g. juju deploy --num-units 10) then the leader unit will probably not be unit/0, but, say, unit/8. At that point, if you scale down to below the leader unit (e.g. -4), a leadership change will occur and some other unit (impossible to predict which one) will receive leader-elected.

Disclaimer: for a known issue with this see: pytest-operator/42

Observing this event in Ops

In Ops, you can register event hooks to observe leadership change,

self.framework.observe(self.on.leader_elected, self._on_leader_elected)

With Ops, you can test for leadership with self.unit.is_leader() (ops.model.Unit.is_leader).

When writing unit tests with the OF harness, leadership is set with self.harness.set_leader(True) (ops.testing.Harness.set_leader).

Behind the scenes, OF uses the hook-tools is-leader, leader-set and leader-get to interact with juju regarding leadership.

Last updated 6 days ago.