Event 'upgrade-charm'

Event > List of events > Lifecycle events > upgrade-charm

Source: ops.UpgradeCharmEvent

The upgrade-charm event is emitted for a unit that is undergoing an upgrade.

The event is emitted after the new charm code has been unpacked - therefore this event is handled by the callback method bound to the event in the new codebase.

The associated callback should be used to reconcile the current state written by an older version into whatever form is required by the current charm version. An example of a reconciliation that needs to take place is to migrate an old relation data schema to a new one.

  • Typically, operations performed on upgrade-charm should also be considered for install.
  • In some cases, config-changed can be used instead of install and upgrade-charm because it is guaranteed to fire after both.
  • Note that you cannot upgrade a Charmhub charm to the same version. However, upgrading a local charm from path works (and goes through the entire upgrade sequence) even if the charm is exactly the same.


Emission sequence

Scenario Example command Resulting events
Upgrade charm juju refresh stop (old charm) -> upgrade-charm (new charm) -> config-changed -> leader-settings-changed (if the unit is not the leader) -> start
Attach resource juju attach-resource foo bar=baz (same as above)

For sidecar charms, pebble-ready would be emitted as well, typically soon after the start event.

An upgrade does NOT emit:\

  • any relation events (unless relation data is intentionally modified in one of the upgrade sequence hooks)\
  • leader-elected

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.upgrade_charm, self._upgrade_charm)

The upgrade_charm event object does not expose any specific attributes.

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