Charm Anatomy

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.

Contents:

• Template files

  • README
  • LICENSE
  • metadata.yaml
  • requirements.txt
  • config.yaml
  • actions.yaml
  • requirements-dev.txt
  • run_tests
  • src/charm.py
  • tests/test_charm.py

• Other files

  • charmcraft.yaml
  • manifest.yaml
  • version
  • icon.svg

Template files

In our “Hello, World!” introduction we briefly mentioned the various files contained within a charm. In this section we will cover this topic in more detail. Firstly, a reminder of the structure we created with charmcraft init:

# 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

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 19 days ago.