File 'charmcraft.yaml'

List of files in the charm project > charmcraft.yaml

See also: How to configure Charmcraft

The charmcraft.yaml file is used to help instruct charmcraft what is in the charm directory, and therefore how the directory should be built. This document gives an overview of all the keys in this file. The type key is the most important.

Contents:

analysis

The analysis is an optional key that defines how the analysis done on the package will behave. This analysis is run implicitly as part of the pack command but can be called explicitly with the analyze command.

So far the only thing that can be configured is which attributes or linters will be ignored. The structure is:

analysis:
  ignore:
    attributes: [<check-name>,...]
    linters: [<check-name>,...]

bases

The bases key specifies a list of environments (OS version and architecture) where the charm must be built on and run on.

This key is required when packing a charm (when the type key is set to charm) but it is an error to specify it if the project is a bundle (when the type key is set to bundle). When packing in “destructive mode” the base(s) that match(es) the current environment will be used, otherwise an instance will be requested to LXD or Multipass for each specified base to pack in that environment.

This key supports a list of bases where the charm can be built, and where that build can run. Each item can be expressed using two different internal structures, a short and a long form. The long one is more explicit:

bases:
  - build-on:
      - name: <name>
        channel: <channel>
        architectures:
          - <arch>
    run-on:
      - name: <name>
        channel: <channel>
        architectures:
          - <arch>

The run-on part of each build-on is optional, and defaults to what’s specified in the corresponding ‘build-on’. And in both structures the list of architecture strings is also optional, defaulting to the machine architecture.

The short form is more concise and simple (at the cost of being less flexible):

bases:
  - name: <name>
    channel: <channel>
    architectures:
      - <arch>

It implies that the specified base is to be used for both build-on and run-on. And as above, the list of architecture strings is also optional, defaulting to the machine architecture.

Be sure to check this detailed documentation for more information and the different possibilities of these structures, including several examples.

charmhub

The charmhub key is an optional key used for configuring charmcraft's interaction with store servers.

This key allows for the configuration of two values—the base URL for the Charmhub API and the base URL to push binaries to Charmhub. These keys are also optional.

charmhub:
  api-url: <api url>
  storage-url: <storage url>

The key is used mostly in the context of “private” charm stores, defaulting to the standard Canonical services to operate with charms.

parts

A part is a declarative representation on how to add a source or component to the charm. It specifies the mechanisms to obtain, process and prepare individual subsets of the final artefact (each “part” of the “whole”).

Parts have logic encoded in plugins: a plugin is what has the knowledge into how to transform a given source declared in a part into a usable artefact for a charm.

The parts key is optional. If not included, it will default to a charm or bundle part (depending on the project type), which will use a charm or bundle plugin correspondingly.

Those two plugins and the reactive one, all detailed below, are provided by Charmcraft itself and can be used by other custom parts.

Other plugins are provided by the Craft Parts library (which is a Charmcraft dependency), check this supported plugins page. Furthermore, other plugins can be written if needed, refer to this writing local plugins documentation.

Beyond plugins, Charmcraft gives the possibility of using the full power of the parts lifecycle, allowing to add parts, and also to override and customise steps of a part’s lifecycle (pull, build, stage, and prime) using shell scripts directly sourced from charmcraft.yaml, both for custom written parts and the ones included by Charmcraft. Please refer to the Parts Lifecycle documentation to learn more about this.

The charm plugin

Used to pack a Charm that is based on the Operator Framework.

Supports the following configuration:

parts:
  charm:
    charm-entrypoint: <path to an entrypoint script>
    charm-requirements: <list of requirements files>
    charm-python-packages: <list of package names>
    charm-binary-python-packages: <list of package names>
    prime: <list of paths to extra files>

In detail:

• charm-entrypoint: The charm entry point, relative to the project directory. It is optional (new in charmcraft 1.2), if not defined defaults to src/charm.py.

• charm-requirements: A list of requirements files specifying Python dependencies. It is optional (new in charmcraft 1.2); if not defined, defaults to a list with one requirements.txt entry if that file is present in the project directory.

• charm-python-packages: A list of Python packages to install before installing requirements. These packages will be installed from sources and built locally at packing time. It is optional (new in charmcraft 1.4), defaults to empty.

• charm-binary-python-packages: A list of python packages to install before installing requirements and regular Python packages. Binary packages are allowed, but they may also be installed from sources if a package is only available in source form. It is optional (new in charmcraft 1.4), defaults to empty.

• prime: List of extra file and directory paths to include in the charm. Note that bundle.yaml, the entry point file and hooks are included automatically when packing a charm. Additionally, config.yaml, metrics.yaml, actions.yaml, lxd-profile.yaml, templates, version, lib and mod will be included if they exist in the project directory. It is optional.

The bundle plugin

Used to pack a charm bundle, a collection of charms which have been carefully combined and configured in order to automate a multi-charm solution.

Supports the following configuration:

parts:
  charm:
    prime: <list of paths to extra files>

In detail:

• prime: List of extra file and directory paths to include in the bundle. Note that bundle.yaml and README.md are included automatically when packing a bundle. Optional.

The reactive plugin

Used to pack charms using the reactive framework.

Note that this is a framework that has now been superseded by the Charmed Operator Framework, please use that framework instead of reactive. Support for reactive in Charmcraft is only to ease the transition of old charms into the new framework.

Supports the following configuration:

parts:
  charm:
    source: .
    plugin: reactive
    build-snaps: [charm]
    reactive-charm-build-arguments: <list of command line options>

The reactive_charm_build_arguments allows to include extra command line arguments in the underlying charm build call.

type

The type key is a required key. It indicates the type of entity for which the present config exists. Its value must be charm or bundle.

Last updated 4 months ago.