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:
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.
|Action||Example Command||Resulting Events|
Core events in detail
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 event is emitted in response to various events throughout a charm’s lifecycle:
- Immediately after the
- 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
- 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 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 event is triggered once the Pebble sidecar has started and a socket is available. This occurs both during
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 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
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 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.