This version of the doc is no longer supported. Please check out the stable docs for the latest in Juju.

Charm configuration

The optional config.yaml file defines how a service running the charm can be configured by its user.

If config.yaml exists, it must contain a dictionary of options, in which each possible setting is named by the key and defined by the value. An option definition must contain all of the following fields:

  • type can be string, int, float, or boolean. The default type is string.
  • description should contain an explanation of what the user might achieve by altering the setting along with valid values.
  • default should contain a value of the appropriate type. If set as default: with no trailing characters, it is treated as null (which is always a valid value in this context).

Any option without these three fields will generate a Warning from the the charm proof tool indicating the option is not compliant with charm store policy. This policy allows older versions of juju to safely unset values.

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 ont 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