Charm configuration

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 string, int, float, or boolean.
• 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:

• default:
• default: ''
• default: ""

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".

Default configuration

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