Creating config.yaml and configuring charms
The charm author can use the optional
config.yaml file to define a charm’s configuration. This file also becomes available to the end user if they choose to download the charm in order to inspect it.
If this file is used, it must contain a dictionary of
options, in which every setting is named by the key and defined by the value.
The following fields are available for an option:
type: can be
description: contains an explanation of what the user might achieve by altering the setting along with valid values.
default: contains a default value for the option. This value must be of the appropriate type and be coherent for the given charm.
The only required field is
type. Omitting it will cause an error to be generated by the charm proof tool indicating the option is not compliant with Charm Store policy.
Some options may need to be set, but depending on the nature of the charm it may not be feasible to provide a default value. The author should list any such options in the
description field. See Application configuration for information on configuring an application at deployment time.
A null default value is accepted for any option type (providing a non-null value is not mandatory). The following formats are valid:
What to expose to users
The charm configuration is deliberately somewhat restrictive, in the hope of encouraging charmers to expose only features that are clear and comprehensible. The user doesn’t want to configure the software - they want to configure the service, which exists at a higher level of abstraction. A charm with a single opinionated
tuning option is, from this perspective, infinitely superior to one that exposes 6 arcane options that correspond directly to flags or config settings for the software.
In short, the config is part of the user interface for the charm - it needs to be concise and as easy to understand and use as possible. If you’re considering using base64 encoding to slip structured data through the deliberately restrictive configuration language, you’re probably “Doing It Wrong”.
Your charm should operate correctly with no explicit configuration settings. The first time someone uses your charm, they’re likely to run
juju deploy yourcharm and see what happens; if it doesn’t work out of the box on the first go, many potential users won’t give it a second try.
Sample config.yaml files
The MediaWiki has some simple but useful configuration options:
options: name: default: Please set name of 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: Admin users to create, user:pass type: string debug: default: false type: boolean description: turn on debugging features of mediawiki