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:
nameis the charm name, which is used to form the charm URL.
- It can only contain
-; 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-bar-bazand you needn't pay further attention to the restrictions.
- It can only contain
summaryis a one-line description of the charm.
descriptionis a long-form description of the charm and its features. It will also appear in the juju GUI.
tagsis 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:
maintaineris 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>.
maintainersis a list of people who maintain the charm. Use the yaml sequence format when there are more than one person maintaining the project.
tagsis a list containing one or more of the following:
In almost all cases, only one tag will be appropriate. The categories help keep the Charm Store organised.
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
subordinateshould be set to true if the charm is a subordinate. If omitted, the charm will be presumed not to be subordinate.
peersdefine the various relations the charm will participate in.
- if the charm is subordinate, it must contain at least one
requiresrelation with container scope.
Other available fields are:
seriesis 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'.
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.
Payloads provide a means for the charm author to get information from a deployed charm. This is especially useful in large and complex deployments. For instance, the author may want to check the status of some element of the deployment such as a Docker container.
Payloads are defined in the
payloads section of
metadata.yaml by assigning
a class and type. Classes refer to simply the name of the payload and the type
describes the nature of the payload. Both are author-defined and are not
validated by Juju.
The most common types of payload are based on Docker, KVM, and LXD.
As an example, below the following class/type pairs are defined: 'monitoring/docker', 'kvm- guest/kvm', and 'lxd-container/lxd':
payloads: monitoring: type: docker kvm-guest: type: kvm lxd-container: type: lxd
Payloads can be viewed using [juju list-payloads][list-payloads] and managed from the charm hook using the following commands:
See the [Hook tools documentation][hook-payloads] for further details on these payload commands.