Event 'upgrade-charm'

doc
,
1

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.

Contents:

Emission sequence

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

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.

2
3

We need to include attaching resources as a trigger for this event.

1 Like
4
5

Hey! I think we should add that a pod rescheduling/deletion in k8s will trigger this sequence as well.

6

Is it possible for pebble-ready to be emitted before the start event? The docs here seem to indicate that pebble-ready is guaranteed to fire after start—can we rely on this ordering?

7

Re-reading that document, it appears so.

8

@ppasotti Are you replying to Raúl’s message or my message? If my message, by “appears so” do you mean (1) it appears that pebble-ready can be emitted before the start event or (2) that pebble-ready is guarantted to fire after start?

9

@carlcsaposs I was replying to you, sorry for omitting the quote. According to the document you referenced, pebble-ready is apparently guaranteed to be fired only after start (in the startup sequence).

I also edited this doc to avoid the ambiguity.

1 Like
10

Thank you Pietro!

1 Like
11

Is it still true that the juju refresh command triggers a stop event? I checked with jhack tail and it only detects the upgrade_charm and config_changed events…

12

IIRC that might be a difference between machine and kubernetes models. What substrate did you test on?

13

I tested it in an LXD cloud. And yeah, LXD clouds trigger only upgrade_charm and config_changed, while Microk8s clouds trigger what the docs specify.

14

thanks for checking. I updated the emission sequence

1 Like