Event 'config-changed'
Event > List of events > Lifecycle events >
config-changed
Source:
ops.ConfigChangedEvent
This document describes the config-changed
event.
Contents:
Emission sequence
The config-changed
event is emitted in response to various events throughout a charm’s lifecycle:
- In response to a configuration change using the GUI or CLI.
- On networking changes (if the machine reboots and comes up with a different IP).
- Some time between the
install
event and thestart
event in the Startup Phase.
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.
There are many situations in which config-changed
can occur. In many of them, the event being fired does not mean that the config has in fact changed, though it may be useful to execute logic that checks and writes workload configuration. For example, since config-changed
is guaranteed to fire once during the startup sequence, some time after install
is emitted, charm authors might omit a call to write out initial workload configuration during the install
hook, relying on that configuration to be written out in their config-changed
handler instead.
Scenario | Example Command | Resulting Events |
---|---|---|
Create unit |
juju deploy foo juju add-unit foo
|
install -> config-changed -> start |
Configure a unit | juju config foo bar=baz |
config-changed |
Observing this event in Ops
In ops
, one typically interacts with config via a read-only facade. Charms, by design, aren’t able to mutate their own configuration by themselves (and thereby ignore an admin-provided configuration), or to configure other applications.
On a charm execution you can get config values by name:
# in MyCharm(CharmBase):
my_config = self.config['config-field'] # "foo"
And when the admin changes the configuration,
juju config my-charm config-field=bar
after receiving a config-changed
event, the new value will be available to the charm.
# in MyCharm(CharmBase):
my_config = self.config['config-field'] # "bar"
Configuration data can be accessed through the model by charm developers, as illustrated in the following snippet:
# ...
def _on_config_changed(self, event):
name = self.model.config["name"]
# ...
Notes:
There are a few things to consider when implementing this:
-
The
config_changed
event will ALWAYS happen at least once, when the initial configuration is accessed from the charm. -
The first time the
config-changed
event runs may be before thepebble-ready
event has completed. The config-change code should gracefully handle not being able to connect to a container/service. -
Multiple configuration values can be changed at one time through Juju, resulting in only one
config_changed
event – charm code must be able to process more than one config value changing at a time. -
If
juju config
is run with values the same as the current configuration, theconfig_changed
event will not run. Therefore, if you have a single config value, there is no point in tracking its previous value – the event will only be triggered if the value changes.
Last updated 3 months ago.