metadata.yaml file¶
This document describes the metadata.yaml file in your charm project.
Caution
tarting with Charmcraft 2.5, the metadata.yaml file is created
automatically from information you provide in the charmcraft.yaml file. For
backwards compatibility, Charmcraft will continue to allow the use of the
metadata.yaml file, but you may not duplicate keys across the two files.
Important
The charmcraft.yaml file follows keywords similar to snaps. On the other hand, the
metadata.yaml does not. As a result, when charmcraft pack generates the file, some
keywords may differ – e.g., the title key from charmcraft.yaml is rendered as
display-name in metadata.yaml.
This file contains identifying and configuration information about the charm. Identifying information is used to describe the charm, its author, and its purpose; it is indexed by Charmhub to enable easy discovery of charms. Configuration information is provided by the charm author to inform Juju how and where to deploy the charm depending on the intended platform, storage requirements, resources, and possible integrations.
The file is a YAML dictionary and consists of a number of keys and their values. There
are 3 keys that are required for all charms: name, summary, and
description. Then, also keys that are required only for Kubernetes
charms, e.g., containers. Additionally, 15+ optional keys. Finally, any
number of arbitrary keys; these can serve to keep track of other choices a charmer might
make.
The rest of this document describes all these keys. Click on a key below or scroll down to find out more.
assumes¶
Status: Optional. Recommended for Kubernetes charms.
Purpose: The assumes key allows charm authors to explicitly state in the metadata
of a charm various features that a Juju model must be able to provide to ensure that the
charm can be successfully deployed on it. When a charm comes preloaded with such
requirements, this enables Juju to perform a pre-deployment check and to display
user-friendly error messages if a feature requirement cannot be met by the model that
the user is trying to deploy the charm to. If the assumes section of the charm metadata
is omitted, Juju will make a best-effort attempt to deploy the charm, and users must
rely on the output of juju status to figure out whether the deployment was successful.
The assumes key is available since 2.9.23.
Structure: The key consists of a list of features that can be given either directly
or, depending on the complexity of the condition you want to enforce, nested under one
or both of the boolean expressions any-of or all-of, as shown below. In order for a
charm to be deployed, all entries in the assumes block must be satisfied.
assumes:
- <feature_name>
- any-of:
- <feature_name>
- <feature_name>
- all-of:
- <feature_name>
- <feature_name>
The supported feature names are as below:
|
The charm deploys if and only if the model runs agent binaries with the specified Juju version(s). |
Since 2.9.23 |
|
The charm deploys if and only if the underlying substrate for the model is Kubernetes. |
Since 2.9.23 |
The Boolean expressions are defined as below:
|
The sub-expression is satisfied if any of the provided child expressions is satisfied. |
|
The sub-expression is satisfied if all of the provided child expressions are satisfied. |
Examples:
Simple example
assumes:
- juju >= 2.9.23
- k8s-api
Example with a nested expression
assumes:
- any_of:
- juju >= 2.9
- k8s-api
charm-user¶
Important
charm-user was added in Juju 3.6.0. Currently is only supported on Kubernetes charms
and has no effect on machine charms.
Status: Optional. Recommended for Kubernetes charms.
Purpose: The charm-user key allows charm authors to specify that their charm hook
code does not need to be run as root. This key, in addition to uid + uid fields in
containers, allows charms to be run rootless. The value of root ensures the charm
runs as root. Both sudoer and non-root will run as a user other than root. In the
case of the value sudoer, the charm will be run as a user with access to sudo to
elevate it’s privileges.
Structure: The key consists of a single value. One of root, sudoer or
non-root.
# (Optional) What kind of user is required to run the charm code.
# It can be one of root, sudoer or non-root.
# Added in Juju 3.6.0. If not specified, root is assumed.
charm-user: <one of root, sudoer or non-root>
containers¶
See also:
resources
Status: Required for Kubernetes charms (except for proxy charms running on Kubernetes).
Purpose: The containers key allows you to define a map of containers to be created
adjacent to the charm (as a sidecar, in the same pod).
Structure: This key consists of a list of containers along with their specification.
Each container can be specified in terms of resource, bases, uid, gid and
mounts, where one of either the resource or the bases subkeys must be defined, and
mounts is optional. resource stands for the OCI image resource used to create the
container; to use it, specify an OCI image resource name (that you will then define
further in the resources block). bases is a list of bases to be used
for resolving a container image, in descending order of preference; to use it, specify a
base name (for example, ubuntu, centos, windows, osx, opensuse), a
channel, and an architecture. mounts is a list
of mounted storages for this container; to use it, specify the name of the storage to
mount from the charm storage and, optionally, the location where to mount the storage.
And, starting with Juju 3.5.0, uid and gid are the UID and, respectively, GID to run
the Pebble entry process for this container as; they can be any value from 0-999 or any
value from 10,000 (values from 1000-9999 are reserved for users) and the default is 0
(root).
containers:
<container name>:
resource: <resource name>
bases:
- name: <base name>
channel: <track{ref}`/risk][/branch]>
architectures:
- <architecture>
mounts:
- storage: <storage name>
location: <path>
uid: <unix UID>
gid: <unix GID>
Examples:
Example
containers:
super-app:
resource: super-app-image
mounts:
- storage: logs
location: /logs
description¶
Status: Required.
Purpose: The description key is where you provide a full description of the
configuration layer.
Structure:
description: |
<description>
devices¶
# (Optional) Device requests for the charm, for example a GPU
devices:
# Each key represents the name of the device
<device name>:
# (Required) The type of device requested
type: gpu | nvidia.com/gpu | amd.com/gpu
# (Optional) Description of the requested device
description: <description>
# (Optional) Minimum number of devices required
countmin: <n>
# (Optional) Maximum number of devices required
countmax: <n>
display-name¶
Important
In recipes this is now the title key.
display-name: |
<display name>
docs¶
See also:
How to create an effective README file for your charm <https://juju.is/docs/sdk/charm-documentation>_
Important
In recipes this is now the links.documentation key.
# (Optional) A link to a documentation cover page on Discourse:
docs: <url>
extra-bindings¶
# (Optional) Extra bindings for the charm. For example binding extra network
# interfaces. Key only map, value must be blank. Key represents the name.
extra-bindings:
# Key only map; key represents the name of the binding
<binding name>:
issues¶
Important
In recipes this is now the links.issues key.
# (Optional) A string (or a list of strings) containing a link (or links) to the charm
# bug tracker.
issues: <url> | {ref}`<urls>]
maintainers¶
Important
In recipes this is now the links.contact key.
# (Optional) A list of maintainers in the format "First Last <email>"
maintainers:
- <maintainer>
name¶
# (Required) The name of the charm. Determines URL in Charmhub and the name
# administrators will ultimately use to deploy the charm. E.g. `juju deploy <name>`
name: <name>
peer¶
# (Optional) Mutual relations between units/peers of this charm
peer:
# Each key represents the name of the relation as known by this charm
<relation name>:
# (Required) The interface schema that this relation conforms to
interface: <interface name>
# (Optional) Maximum number of supported connections to this relation
# endpoint. This field is an integer
limit: <n>
# (Optional) Defines if the relation is required. Informational only.
optional: true | false
# (Optional) The scope of the relation. Defaults to "global"
scope: global | container
provides¶
# (Optional) Map of relations provided by this charm
provides:
# Each key represents the name of the relation as known by this charm
<relation name>:
# (Required) The interface schema that this relation conforms to
interface: <interface name>
# (Optional) Maximum number of supported connections to this relation
# endpoint. This field is an integer
limit: <n>
# (Optional) Defines if the relation is required. Informational only.
optional: true | false
# (Optional) The scope of the relation. Defaults to "global"
scope: global | container
requires¶
# (Optional) Map of relations required by this charm
requires:
# Each key represents the name of the relation as known by this charm
<relation name>:
# (Required) The interface schema that this relation conforms to
interface: <interface name>
# (Optional) Maximum number of supported connections to this relation
# endpoint. This field is an integer
limit: <n>
# (Optional) Defines if the relation is required. Informational only.
optional: true | false
# (Optional) The scope of the relation. Defaults to "global"
scope: global | container
resources¶
See also: Juju | Resource (charm)
Purpose: The resources key is where you define the resources mentioned under the
resource key of the containers key.
Structure:
# (Optional) Additional resources that accompany the charm
resources:
# Each key represents the name of a resource
# mentioned in the 'resource' subkey of the 'containers' key.
<resource name>:
# (Required) The type of the resource
type: file | oci-image
# (Optional) Description of the resource and its purpose
description: <description>
# (Required: when type:file) The filename of the resource as it should
# appear in the filesystem
filename: <filename>
Examples:
#xample with an OCI-image resource
resources:
super-app-image:
type: oci-image
description: OCI image for the Super App (hub.docker.com/_/super-app)
source¶
Important
In recipes this is now the links.source key.
# (Optional) A string (or a list of strings) containing a link (or links) to the charm source code.
source: <url> | {ref}`<urls>]
storage¶
# (Optional) Storage requests for the charm
storage:
# Each key represents the name of the storage
<storage name>:
# (Required) Type of the requested storage
type: filesystem | block
# (Optional) Description of the storage requested
description: <description>
# (Optional) The mount location for filesystem stores. For multi-stores
# the location acts as the parent directory for each mounted store.
location: <location>
# (Optional) Indicates if all units of the application share the storage
shared: true | false
# (Optional) Indicates if the storage should be made read-only (where possible)
read-only: true | false
# (Optional) The number of storage instances to be requested
multiple:
range: <n> | <n>-<m> | <n>- | <n>+
# (Optional) Minimum size of requested storage in forms G, GiB, GB. Size
# multipliers are M, G, T, P, E, Z or Y. With no multiplier supplied, M
# is implied.
minimum-size: <n>| <n><multiplier>
# (Optional) List of properties, only supported value is "transient"
properties:
- transient
subordinate¶
# (Optional) True if the charm is meant to be deployed as a subordinate to a
# principal charm
subordinate: true | false
summary¶
# (Required) A short, one-line description of the charm
summary: <summary>
terms¶
# (Optional) A list of terms that any charm user must agree with
terms:
- <term>
website¶
Important
In recipes this is now the links.website key.
# (Optional) A string (or a list of strings) containing a link (or links) to project websites.
# In general this is likely to be the upstream project website, or the formal website for the
# charmed offering.
website: <url> | [<urls>]
Other keys¶
In addition to the keys mentioned above, a metadata.yaml file may also contain other
arbitrary keys. These can serve to keep track of other choices a charmer might make. In
some cases these become semi-official, being adopted by many charmers and even
incorporated into CI processes. An example is
upstream-source.