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

Charm metadata

The only file that must be present in a charm is metadata.yaml, in the root directory. A metadata file must be a valid yaml dictionary, containing at least the following fields:

  • name is the charm name, which is used to form the charm URL.
    • It can only contain a-z, 0-9, and -; must start with a-z; must not end with a -; and may only end with digits if the digits are not directly preceded by a space. Stick with names like foo and foo-bar-baz and you needn't pay further attention to the restrictions.
  • summary is a one-line description of the charm.
  • description is a long-form description of the charm and its features. It will also appear in the juju GUI.
  • tags is a descriptive tag that is used to sort the charm in the store.

Here's a valid metadata file:

    name: mongodb
    summary: An open-source document database, and the leading NoSQL database
    description: |
      MongoDB is a high-performance, open source, schema-free document- oriented
      data store that's easy to deploy, manage and use. It's network accessible,
      written in C++ and offers the following features:
      - Collection oriented storage
      - easy storage of object-style data
      - Full index support, including on inner objects
      - Query profiling
      - Replication and fail-over support
      - Efficient storage of binary data including large objects (e.g. videos)
      - Auto-sharding for cloud-level scalability (Q209) High performance,
      scalability, and reasonable depth of functionality are the goals for the
      project.

With only those fields, a metadata file is valid, but not very useful. Charms for use in the Charm Store should always set the following fields as well, for categorization and display in the GUI:

  • maintainer is the name and email address for the main point of contact for the development and maintenance of the charm. The maintainer field should be in the format Charm Author Name <author@email>.

  • maintainers is a list of people who maintain the charm. Use the yaml sequence format when there are more than one person maintaining the project.

  • tags is a list containing one or more of the following:

    • analytics
    • big_data
    • ecommerce
    • openstack
    • cloudfoundry
    • cms
    • social
    • streaming
    • wiki
    • ops
    • backup
    • identity
    • monitoring
    • performance
    • audits
    • security
    • network
    • storage
    • database
    • cache-proxy
    • application_development
    • web_server

In almost all cases, only one tag will be appropriate. The categories help keep the Charm Store organised.

Juju Charm Store metadata Listing

  • min-juju-version Charms can declare the minimum Juju version the code is compatible with. This is useful when the code uses features introduced in a specific version of Juju. When supplied this value is the lowest version of Juju controller that will run the charm.

Storage

Storage can also be declared in a charm's metadata, as such:

storage:
  data:
    type: filesystem
    description: junk storage
    shared: false # not yet supported, see description below
    read-only: false # not yet supported, see description below
    minimum-size: 100M
    location: /srv/data

A metadata file defines the charm's relations, and whether it's designed for deployment as a subordinate service.

  • subordinate should be set to true if the charm is a subordinate. If omitted, the charm will be presumed not to be subordinate.
  • provides, requires, and peers define the various relations the charm will participate in.
  • if the charm is subordinate, it must contain at least one requires relation with container scope.

Resources

resources allows you to add blobs that your charm can utilize.

resources:
  example:
    type: file # "file" is the only type supported currently
    filename: example.tar.gz
    description: example resource

Payloads

You can use the payloads section of metadata.yaml to help the user of a charm better understand the purpose of payloads such as LXC, KVM and docker. This is especially useful in large and complex deployments.

Payloads are defined by creating a class for the payload, such as monitoring or kvm- guest, and then assigning a type:

payloads:
    monitoring:
        type: docker
    kvm-guest:
        type: kvm

Payloads can be viewed using juju list-payloads and managed from the charm hook using the following commands:

  • payload-register
  • payload-unregister
  • payload-status-set

See the Hook tools documentation for further details on these payload commands.

Extra-bindings

extra-bindings represents an extra bindable endpoint that is not a relation. These are useful when you want to have Juju provide distinct addresses for an application on one or more spaces. For example, adding this section to a YAML file for an application called "foo":

extra-bindings:
  cluster:
  public:

Will permit you to deploy the charm using --bind to deploy on units that have access to the "admin-api", "public-api", and "internal-api" spaces with a' different network interface and address for each binding, using this:

juju deploy ~/path/to/charm/foo --bind "cluster=admin-api public=public-api internal-api"

And running network-get cluster --primary-address will return only the address coming from the "admin-api" space.

Endpoint names are strings and must not match existing relation names from the Provides, Requires, or Peers metadata sections. The values beside each endpoint name must be left out (i.e. "foo": <anything> is invalid).

Other available fields are:

  • series is a list of series that the charm supports.
    • It can include code names of Ubuntu releases such as 'trusty' or 'xenial'.
    • It can also include code names for non-Ubuntu series such as 'centos7'.
  • terms lists the terms the user must agree to before using the charm.
  • min-juju-version the minimum version of Juju this charm is compatible with.

Other field names should be considered to be reserved; please don't use any not listed above to avoid issues with future versions of Juju.