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 |
Controls the behaviour of the analysis done when packing charms or explicitly requested by the analyze command. Optional. |
bases |
A list of environments (OS version and architecture) where charms must be built on and run on. It is required when the value of the type key is charm . |
charmhub |
Used for configuring charmcraft’s interaction with store servers. Optional. |
parts |
Configures the various mechanisms to obtain, process and prepare data from different sources that end up being a part of the final charm. It’s optional, and only used by the pack command. |
type |
The type of entity for which the present config exists. Required. Valid values: charm or bundle . |
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
In Charmcraft 3.0 and up, these keys will no longer be valid in charmcraft.yaml
. Use the environment variables CHARMCRAFT_STORE_API_URL
, CHARMCRAFT_UPLOAD_URL
and CHARMCRAFT_REGISTRY_URL
instead.
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>
registry-url: <registry 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 tosrc/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 onerequirements.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 thatbundle.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
andmod
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 thatbundle.yaml
andREADME.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 days ago.