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
  • stop

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
Scale juju add-unit -n 2 hello-operator install -> config-changed -> start
Configure juju config hello-operator thing=foo config-changed
Upgrade juju upgrade-charm hello-operator upgrade-charm -> config-changed
Remove juju remove-application hello-operator remove -> stop

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. 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.

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.


Last updated 2 months ago.