Charm anatomy
See also:
You have initialised your charm by running charmcraft init. This has created a lot of different files. This document describes these files and their purpose. It also describes a few additional files that you might come across at this stage.
Contents:
Template files
When you ran charmcraft init to initialise your charm, this produced the following list of template files:
# 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
Each of these files is described briefly below.
README
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.
LICENSE
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 not sure which license to select, choosealicense.com can help you. For most charms, we recommend Apache 2, as this will allow for simple modification, redistribution, and packaging by the Charmhub community.
metadata.yaml
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 in the metadata reference.
requirements.txt
A standard Python requirements file used to declare and pin the version of any Python libraries required by a 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 charmcraft pack.
config.yaml
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.
actions.yaml
Contains the definitions for all the 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-dev.txt
As with 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.
run_tests
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.
src/charm.py
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 charmcraft.
tests/test_charm.py
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.
Other files
Alongside the files listed above, during charm development you might also come across the following:
charmcraft.yaml
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 the directory should be built. Currently, this file is mandatory only if you’re packing a Bundle.
More information can be found in the charmcraft Configuration document.
manifest.yaml
The manifest.yaml file 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, as well as the architectures that the charm can run on. An example can be found here. This manifest contains a simplified version of the charmcraft.yaml file that is used to verify whether a machine charm is compatible with the running system.
More information can be found in the Charmcraft Configuration document.
version
When your charm is published to Charmhub, an attempt is made to automatically determine the version if there is metadata for a version control system in the path. In order, Charmhub checks for git, hg (Mercurial), and bzr (Bazaar). If a metadata path is found, one of the following commands is used to check for version information:
git describe --dirty --always
hg id -n
bzr version-info
If there is no version control metadata, Charmhub will look for a version file, which can be used to manually specify the version which should be displayed.
Finally, if all of these fail, the version will match the revision of your charm.
icon.svg
An 100px x 100px SVG icon used for display on Charmhub. For more information please see this post.
Last updated 2 months ago.