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.

Template Files

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 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 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.

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 on Discourse.

requirements.txt

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 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 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 those listed above, you might come across the following during charm development:

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 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 charmhub map spec:

The parts map spec:

The bundle map spec:

An example charmcraft.yaml file:

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"]

manifest.yaml

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.