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"] # ...
Configuration cannot be changed from the charm code.