Lifecycle Events

Core Events

The Charmed Operator Framework implements the observer pattern, and responds to events and state changes communicated by the Juju controller. The most common events that Charm authors should consider handling explicitly are:

  • install
  • config-changed
  • start
  • upgrade-charm
  • update-status
  • <container>-pebble-ready
  • stop
  • remove
  • collect-metrics

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). There are additional events that your Charm may need to respond to, including those relating to application leadership, relations and actions which will be covered later.

Example Lifecycles

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

Core events in detail

install

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.

config-changed

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.

start

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.

pebble-ready

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 Charmed Operators, 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.

upgrade-charm

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.

update-status

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

stop

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.

remove

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.

Failure in handling events

If the code of the operator for handling a particular event fails, for example with an exception propagating outside of the event handler, Juju will retry the failed event handler with an exponential back-off, capped at five minutes.


Last updated a month ago.