File 'metadata.yaml'

List of files in the charm project > metadata.yaml

This document describes the metadata.yaml file in your charm project.

:warning: Starting 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.

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.


Expand to see a minimal valid `metadata.yaml`
name: mongodb
summary: A document database
description: A database that stores JSON-like data. 

Expand to see an example `metadata.yaml` file for a Kubernetes charm
name: super-k8s
summary: a really great charm
description: |
    This is a really great charm, whose metadata is suitably complete so as to
    demonstrate as many of the fields as possible.
maintainers:
    - Joe Bloggs <joe.bloggs@email.com>
docs: https://discourse.charmhub.io/t/9999

# The following three fields can be a single string, or a list of strings.
source: https://github.com/foo/super-k8s-operator
issues: https://github.com/foo/super-k8s-operator/issues/
website:
    - https://charmed-super.io/k8s
    - https://super-app.io

containers:
    super-app:
        resource: super-app-image
        mounts:
            - storage: logs
              location: /logs
    
    super-app-helper:
        bases:
            - name: ubuntu
              channel: ubuntu/20.04
              architectures:
                  - amd64
                  - arm64

resources:
    super-app-image:
        type: oci-image
        description: OCI image for the Super App (hub.docker.com/_/super-app)
    
    definitions:
        type: file
        description: A small SQLite3 database of definitions needed by super app
        filename: definitions.db

provides:
    super-worker:
        interface: super-worker

requires:
    ingress:
        interface: ingress
        optional: true
        limit: 1

peers:
    super-replicas:
        interface: super-replicas

storage:
    logs:
        type: filesystem
        location: /logs
        description: Storage mount for application logs
        shared: true

assumes:
    - juju >= 2.9.23 
    - k8s-api


The rest of this document describes all these keys. Click on a key below or scroll down to find out more.


Alternatively, expand to see the full spec at once
# (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>

# (Required) A short, one-line description of the charm
summary: <summary>

# (Required) A full description of the configuration layer
description: |
    <description>

# (Optional) A list of maintainers in the format "First Last <email>"
maintainers:
    - <maintainer>

# (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>]

# (Optional) A string (or a list of strings) containing a link (or links) to the charm source code.
source: <url> | [<urls>]

# (Optional) A string (or a list of strings) containing a link (or links) to the charm bug tracker.
issues: <url> | [<urls>]

# (Optional) A link to a documentation cover page on Discourse
# More details at https://juju.is/docs/sdk/add-docs-to-your-charmhub-page
docs: <url>

# (Optional) A list of terms that any charm user must agree with
terms:
    - <term>

# (Optional) True if the charm is meant to be deployed as a subordinate to a 
# principal charm
subordinate: true | false

# (Optional) A map of containers to be created adjacent to the charm. This field
# is required when the charm is targeting Kubernetes, where each of the specified
# containers will be created as sidecars to the charm in the same pod.
containers:
    # Each key represents the name of the container
    <container name>:
        # Note: One of either resource or bases must be specified.
        
        # (Optional) Reference for an entry in the resources field. Specifies 
        # the oci-image resource used to create the container. Must not be 
        # present if a base/channel is specified
        resource: <resource name>

        # (Optional) A list of bases in descending order of preference for use 
        # in resolving a container image. Must not be present if resource is 
        # specified. These bases are listed as base (instead of name) and 
        # channel as in the Base definition, as an unnamed top-level object list
        bases:
            # Name of the OS. For example ubuntu/centos/windows/osx/opensuse
            - name: <base name>

              # Channel of the OS in format "track[/risk][/branch]" such as used by
              # Snaps. For example 20.04/stable or 18.04/stable/fips
              channel: <track[/risk][/branch]>

              # List of architectures that this particular charm can run on
              architectures: 
                  - <architecture>
        
        # (Optional) List of mounted storages for this container
        mounts:
            # (Required) Name of the storage to mount from the charm storage
            - storage: <storage name>
            
              # (Optional) In the case of filesystem storages, the location to
              # mount the storage. For multi-stores, the location acts as the
              # parent directory for each mounted store.
              location: <path>

        # (Optional) UID to run the pebble entry process for this container as.
        # Can be any value from 0-999 or any value from 10,000 (values from 1000-9999 are reserved for users).
        # Default is 0 (root). Added in Juju 3.5.0.
        uid: <unix UID>

        # (Optional) GID to run the pebble entry process for this container as.
        # Can be any value from 0-999 or any value from 10,000 (values from 1000-9999 are reserved for user's primary groups).
        # Default is 0 (root). Added in Juju 3.5.0.
        gid: <unix GID>
    
# (Optional) Additional resources that accompany the charm
resources:
    # Each key represents the name of the resource
    <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>

# (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

# (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

# (Optional) Mutual relations between units/peers of this charm
peers:
    # 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

# (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: <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

# (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>

# (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>:

# (Optional) A set of features that must be provided by the Juju model to ensure that the charm can be successfully deployed. 
# See https://juju.is/docs/olm/supported-features for the full list.
assumes:
    - <feature_name>
    - any-of:
        - <feature_name>
        - <feature_name>
    - all-of:
        - <feature_name>
        - <feature_name>

Contents:

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:

||| | — | — | — | |juju <comparison predicate> <version number>

E.g., juju < 3.0.
E.g., juju >= 2.9 | The charm deploys iff the model runs agent binaries with the specified Juju version(s). |Since 2.9.23| |k8s-api | The charm deploys iff the underlying substrate for the model is Kubernetes. |Since 2.9.23|

The Boolean expressions are defined as below:

any-of The sub-expression is satisfied if any of the provided child expressions is satisfied.
all-of The sub-expression is satisfied if all of the provided child expressions are satisfied.

Examples:


Expand to see a simple example
assumes:
    - juju >= 2.9.23
    - k8s-api

Expand to see an example with a nested expression
assumes:
    - any_of:
        - juju >= 2.9
        - k8s-api

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

containers:
  <container name>:
    resource: <resource name>
    bases:
      - name: <base name>
        channel: <track[/risk][/branch]>
        architectures:
          - <architecture>
    mounts:
      - storage: <storage name>
        location: <path>
    uid: <unix UID>
    gid: <unix GID>

Examples:

Expand to see an example with `resource` and `mounts`
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

In charmcraft.yaml this is now the title key.

display-name: |
  <display name>

docs

See also: How to create an effective README file for your charm

In charmcraft.yaml this is now the documentation subkey under the links 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

In charmcraft.yaml this is now under the links key.

# (Optional) A string (or a list of strings) containing a link (or links) to the charm bug tracker.
issues: <url> | [<urls>]

maintainers

In charmcraft.yaml this is now the contact subkey under the links 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: Resource

Purpose: The resources key is where you defines 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:


Expand to see an example 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

In charmcraft.yaml this is now under the links key.

# (Optional) A string (or a list of strings) containing a link (or links) to the charm source code.
source: <url> | [<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

In charmcraft.yaml this is now under the links 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 arbitrary keywords>

In addition to the official fields and keywords mentioned above, a metadata.yaml file may also contain other arbitrary keywords. 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.

Prior discussions/context around metadata

Relevant documents

I think we should have a description field for a relation, that would explain the intent behind the relation, e.g., “enabling scrape of the /metrics endpoint by technology like Prometheus that supports the OpenMetrics format”. This information would be extremely valuable for a contributor approaching a charm codebase, as well as CharmHub, when we start displaying with which other charms does this one interoperate.

2 Likes

According to https://github.com/canonical-web-and-design/charmhub.io/issues/1171#issuecomment-976579707, CharmHub uses the categories keyword in the metadata to enable the search filters on the search page.

Could someone update this document with this info and the supported categories, please?

Hi Heitor

I left that field out deliberately. Both the tags and categories fields are only really relevant to the older charm store, which will be going away in the not too distant future. These fields are basically a no-op, and probably aren’t of great use in metadata.

Updated the spec to fix the key in container mount which should have been storage not name

A follow up to the discussion on tags and categories is here

cc: @heitor :slight_smile:

Can we now use assumes instead of placeholder images? How?

That would be very helpful! The relations (provides, requires, and peer) and containers are the only fields that do not have a description field.

AFAIK, the assumes functionality is implemented, but currently behind a feature flag. There has been a short term fix though, which means that you can deploy “charm only” charms on Kubernetes by just not specifying a containers map.

@achilleasa will be able to confirm when the assumes stuff lands, and we should update this doc with the supported options when that happens.

Thanks, I’ll give it a try. My impression was that not specifying a container would need to be paired with assumes juju >= 2.9.18.

If you are using a recent 2.9 release you can enable support for enforcing assumes sections in charm metadata as follows: juju controller-config 'features=[charm-assumes]'.

If you enable the flag, juju show-model will also report the features that are supported on the currently active model.

To disable: juju controller-config 'features=[]'.

Juju will parse and store assumes blocks but will not actively enforce them unless the flag is set. We are currently working on a doc page for describing the supported set of features charms can assume and will be launching the feature once the docs have been completed.

To try this out, add an assumes section (see this example) to the charm metadata.yaml like:

assumes:
  - k8s-api

The above syntax is quite flexible (you can nest requirements in any-of/all-of blocks and also provide version constraints) and is described in detail here.

Just wanted to let you know that we have completed the doc-related tasks for the assumes feature and, unless something changes, it will be going live with Juju 2.9.23.

@niemeyer @jameinel this doesn’t seem like a bad idea to me. Adding a description field to the spec won’t require any work Juju/OF end, but could be used by Charmhub for displaying some context around the relations a given charm supports?

I definitely like the idea of having a description field for how this charm interacts with that relation.

For the record, the description field for the relation would be used to power the “Integration description” on the WIP CharmHub Integrations page.

There have been some recent discussions about making some additional metadata fields available for links associated with a given charm, as part of a wider discussion about improving charm documentation.

The main purpose of this, would be to provide simple way for charm authors to point to the upstream website, issue tracker and source code for the charm. Support for this is currently mixed: charm authors can use the publisher page to set a homepage and contact link, but not an issue tracker - and some older (imported) charms have bought their issue tracker along with them from the older charm store.

The snapcraft folks actually already tackled this problem (spec).

We already have the maintainers field, which is analogous to snapcraft’s contact field. My proposition is that we add the fields website, issues and source-code to this spec. This would then enable the store and charmhub folk to read this data and use it to display relevant links on the various charm pages on Charmhub consistently across all charms if it is present?

/cc @jameinel @roadmr @jkfran @gomboli @danieleprocida @hollyhall

3 Likes

The in-progress work for snaps will also benefit Charmhub, and the following URL fields will be available :

“donations” “contact” “issues” “website” “source”

I believe this covers the ones you proposed.

  • Daniel

Ah interesting - so if we stick with those names, the store will natively understand them from metadata.yaml?