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.

Contents:

• Configuration specification
  • Example configuration specification
• Using configuration

Configuration specification

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:

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:

• default:
• default: ‘’
• default: ""

Example configuration specification

An example 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

Using configuration

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:

• 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 the pebble-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 the config_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 2 months ago.