Lifecycle events
The Operator Lifecycle Manager has a number of events which are important to understand, as they drive the execution of your charm code.
Event summary
install
The install event is emitted only one time, when charm code is first installed on a unit. This event gives the charm a chance to install any prerequisite packages which may be required to operate the supported application.
config-changed
The config-changed event is emitted repeatedly, under varying circumstances. This event invokes charm code would should ensure the current charm configuration is properly reflected in the configurations for the supported application. Each invocation of the charm for this event needs be idempotent - not making any changes to the environment (including restarting services) unless there is a corresponding change in the charm configuration.
start
The start event is emitted only one time, when Juju is ready for the service to start. The charm invocation should start the supported application, and ensure the application will continue to run - even through machine reboots - without further interactions from Juju or an administrator.
upgrade-charm
The upgrade-charm event is emitted each time Juju deploys a new revision of the charm code. This can only happen after the administrator issues the upgrade-charm command to Juju. This event allows the charm to make any transitions in state required. For example, the new revision may support a new configuration option, and needs to correctly handle the new option.
update-status
The update-status event is triggered on a 5-minute interval. This event can be used by the charm to determine the status of long running tasks, such as package installation, and update the status messaged reported to the Juju controller.
stop
The stop event is emitted only one time, when Juju is ready to destroy a unit. The charm invocation should graceful terminate all services for the supported application, and update any relevant cluster information to remove data related to the current unit.
Lifecycle
Other than update-status, all other lifecycle events are triggered in a predictable pattern after a specific action by the administrator.
Deploy / Scale-out
When the administrator deploys a new charm:
$ juju deploy ./hello.charm
Or, increases the number of units for an existing application:
$ juju add-unit -n 2 hello
Both cases will trigger the install cycle. This cycle will be emitted to each new unit, in a guaranteed order, and each event must be successful before the next event will be emitted:
install -> config-changed -> start
Configuration change
When the administraor issues a new configuration option:
$ juju config hello thing=foo
A single event will be emitted to each unit of the application:
config-changed
Charm upgrade
When the administraor initiates charm upgrade:
$ juju upgrade-charm hello
If Juju is able to find a newer revision of the charm, it will distribute the new code and emit a sequential pair of event to each unit:
upgrade-charm -> config-changed
Operator Framework
The Operator Framework uses the observer pattern in order to capture events emitted by Juju. The charm needs to specify the events it wants to observe, and provide a handler function in the __init__ function of it’s charm class:
class HelloCharm(CharmBase):
def __init__(self, *args):
super().__init__(*args)
self.framework.observe(self.on.install, self._on_install)