Core lifecycle events

See also:

The Charmed Operator Framework implements the observer pattern, and responds to events and state changes communicated by the Juju OLM controller.

All lifecycle events are triggered in a predictable pattern following a specific action by the administrator (with the exception of update-status, which triggers on an interval). For example:

Action Example Command Resulting Events
Deploy juju deploy ./hello-operator.charm install -> config-changed -> start -> pebble-ready
Scale juju add-unit -n 2 hello-operator install -> config-changed -> start -> pebble-ready
Configure juju config hello-operator thing=foo config-changed
Upgrade juju upgrade-charm hello-operator upgrade-charm -> config-changed -> pebble-ready
Remove juju remove-application hello-operator stop -> remove

This document describes the most common such events, which charm authors should consider handling explicitly.

For more events that your charm may need to respond do, see leadership, relations and actions.



The install event is emitted once per unit at the beginning of a charm’s lifecycle. Associated callbacks should be used to perform one-time initial setup operations and prepare the unit to execute the application. Depending on the charm, this may include installing packages, configuring the underlying machine or provisioning cloud-specific resources.


The config-changed event is emitted in response to various events throughout a charm’s lifecycle:

  • Immediately after the install event
  • After a relation is created
  • After an application leader is elected
  • In response to a configuration change using the GUI or CLI
  • Immediately before the start event
  • In response to a unit joining a relation
  • In response to a change to an existing relation

Callbacks associated with this event should ensure the current charm configuration is properly reflected in the underlying application configuration. Invocations of associated callbacks should be idempotent and should not make changes to the environment, or restart services, unless there is a material change to the charm’s configuration, such as a change in the port exposed by the charm, addition or removal of a relation which may require a database migration or a “scale out” event for high availability, or similar.

Callbacks must not assume that the underlying applications or services have been started.


The start event is triggered immediately after the first config-changed event. Callback methods bound to the event should be used to ensure that the charm’s software is in a running state. Note that the charm’s software should be configured to persist in a started state without further intervention from Juju or an administrator.


The pebble-ready event is triggered once the Pebble sidecar has started and a socket is available. This occurs both during start and upgrade-charm events, or any other time that a Unit’s pod is rescheduled or restarted on Kubernetes. For charms, Pebble is the method used for starting charm workloads. Callback methods bound to the event should be used to ensure that the charm’s workload is started.


The upgrade-charm event is emitted each time a new revision of the charm code is deployed (triggered when an administrator issues the juju upgrade-charm command). 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.


By default, the update-status event is triggered by the Juju controller at 5-minute intervals. This event can be used to monitor the health of deployed charms and determine the status of long running tasks (such as package installation), updating the status message reported to the OLM accordingly. The interval can be configured model-wide, for example: juju model-config update-status-hook-interval=1m


The stop event is emitted only once: when the Juju controller is ready to destroy the unit. When handling the stop event, Charms should gracefully terminate all services for the supported application and update any relevant cluster/leader information to remove or update any data relating to the current unit. Additionally, the callback should ensure that the software will not automatically start again on reboot.


The remove event is emitted only once: when the Juju controller is ready to remove the unit completely. The stop event is emitted prior to this, and all necessary steps for handling removal should be handled there.

Last updated 25 days ago.