How to make your charm configurable
Charms should always deploy with considered defaults that enable the application to start with as little friction as possible. That said, there are cases when it may be prudent to expose application configuration to the administrator. This should be a point of consideration for the charm developer; configuration is one of the few interfaces a charm developer can expose to an administrator, and thus it should be carefully designed.
One way to think about this is what are the necessary configuration options to configure the service the application provides. If you find the configuration specification too restrictive, and find yourself passing in lots of base64 encoded structures, you may want to rethink the approach.
As demonstrated in the “Hello, World!” guide, charm configuration is defined in a single file named
config.yaml. The file should contain a single YAML map named
options, in which each key is the name of a configuration setting and corresponds to a map of fields that defines the configuration option.
Each configuration option can define three fields:
||Specifies the data type of the configuration option. Possible values are:
||Contains an explanation of the configuration item and the resulting behaviour. Might also include a list of acceptable values.||No|
||Defines the default value for the option. Must be of the appropriate type and a sane default value in the context of the charm.||No|
In some cases, it may be awkward or impossible to provide a sensible default. In these cases, ensure that it is noted in the description of the configuration option. It is acceptable to provide
null configuration defaults or simply omit the
default field, for example:
Example configuration specification
config.yaml is provided below:
options: name: default: Wiki description: The name, or Title of the Wiki type: string skin: default: vector description: skin for the Wiki type: string logo: default: description: URL to fetch logo from type: string admins: default: description: Comma-separated list of admin users to create: user:pass[,user:pass]+ type: string debug: default: false type: boolean description: turn on debugging features of mediawiki
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"] # ...
There are a few things to consider when implementing this:
config_changedevent will ALWAYS happen at least once, when the initial configuration is accessed from the charm.
The first time the
config-changedevent runs may be before the
pebble-readyevent 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_changedevent - charm code must be able to process more than one config value changing at a time.
juju configis run with values the same as the current configuration the
config_changedevent 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.
Configuration cannot be changed from within the charm code.
Last updated 2 months ago.