This section will cover the files contained within a charm. We’ll start with those included in the
charmcraft init template first, and then cover some additional files you may come across.
We briefly covered the files contained within a charm during our “Hello, World!” introduction. In this section we will cover this in more detail. Firstly, a reminder of that structure we created with
# Documentation ├── README.md # The front page documentation for your charm ├── LICENSE # Your Charm's license, we recommend Apache 2 # Charm specification and requirements ├── metadata.yaml # Charmed Operator package description and metadata ├── requirements.txt # PyPI requirements for the charm runtime environment # Runtime features ├── config.yaml # Configuration schema for your operator ├── actions.yaml # Day 2 action declarations, e.g. backup, restore # Development files ├── requirements-dev.txt # PyPI requirements for development environment ├── run_tests # Bash script to run charm tests # Charm code and tests ├── src # Top-level source code directory for charm │ └── charm.py # Minimal operator using Charmed Operator Framework └── tests # Top-level directory for charm tests ├── __init__.py └── test_charm.py # Skeleton unit tests for generated charm
A Markdown file that is displayed on the homepage for the Charm on Charmhub. Generally, this README should detail the charm’s behaviour, how to deploy the charm, and provide links to resources for the supported application. This is a critical part of the Charm’s documentation, and is often the first experience potential users will have with the Charm.
Charmcraft pre-populates the LICENSE file with the Apache 2 license. Before publication, it is important that you consider the implications of this and select a license appropriate for your use case. If you’re unsure about which license to select, choosealicense.com can help you. For most charms, we recommend Apache 2 to allow for simple modification, redistribution and packaging by the Charmhub community.
Contains descriptive information about the Charm, its requirements and its interfaces. There are two types of information: identifying and configuration.
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 the Juju OLM how, and where to deploy the Charm depending on the intended platform, storage requirements, resources and possible relationships. The full specification for
metadata.yaml can be found on Discourse.
A standard Python requirements file used to declare, and pin the version of any Python libraries required by Charm in production. This will be pre-populated with
ops - the Charmed Operator Framework. Any dependencies specified here will be bundled with the Charm when it is built with
Contains the definitions for all possible configuration values supported by the charm. Each configuration item is defined with a type, default value, and description. For further details on configuration, see Handling configuration.
Contains the definitions for all manual actions supported by the Charm. In addition to the name of the supported commands,
actions.yaml also contains descriptions and a list of parameters for each action. For further details on actions, see Defining actions.
requirements.txt, this is a standard Python requirements file, but specifies only those dependencies that are used during development. Examples of this might include testing libraries, linters, etc. These dependencies will not be bundled with the Charm when it is built.
A Bash script used as a helper for running unit tests. By default, it is set up to lint with
flake8, and start unit tests with Python unittest. You may choose to manage this activity differently as your Charm grows or testing requirements increase. Some Charm authors use tox for this purpose.
The default entry point for a charm. This file must be executable, and should include a shebang to indicate the desired interpreter. For many charms, this file will contain the majority of the Charm code. It is possible to change the name of this file, but additional changes are then required to enable the Charm to be built with
This is the companion to
src/charm.py for unit testing. It is pre-populated with standard constructs used by
unittest and Harness. More detail is covered in Unit testing.
Alongside those listed above, you might come across the following during charm development:
This file is specified in the root of your charm directory, and is used to help instruct
charmcraft what is in the directory, and therefore how it should be built. Currently, this file is only mandatory if you’re packing a Bundle. By default,
charmcraft will try to find this file inside the directory where it was invoked, but its location can be specified using the
--project-dir option with
charmcraft. The file is made up of the following fields:
||The type of entity for which the present config exists. Supported values are
||No (see below)||A
||No (see below)||A list of files and directories to include in the built artifact. This currently applies to bundles, but will be used for charms in future versions of
charmhub map spec:
||No||Base URL for the Charmhub API - default used if not set. Used mostly in the context of “private” charm stores.|
||No||Base URL to push binaries to Charmhub - default used if not set. Used mostly in the context of “private” charm stores.|
parts map spec:
||No||Map containing specific content to packing a bundle. Currently supports just one field:
bundle map spec:
||No||A list of files to include when packing the bundle.
type: bundle charmhub: # these fields are set to the default value to illustrate field usage # likely not required in most cases api_url: https://api.charmhub.io storage_url: https://storage.snapcraftcontent.com parts: bundle: # bundle.yaml is included automatically prime: ["README.md"]
The manifest is generated automatically by the
charmcraft tool when a charm or bundle is packed. It is used by Charmhub and
charmcraft to identify the version, build time, OS name and version at build time and the architectures the charm can run on. Implementation details can be found here.
Last updated 17 days ago.