How to manage charms

See first: Juju | Build a charm, Charmcraft | Manage charms

Prepare your environment

You’ll need the following tools:

• Charmcraft. See Charmcraft | Manage Charmcraft.

• tox. See the tox installation instructions.

Instead of installing these tools manually, consider using the charm-dev Multipass blueprint or concierge to prepare your environment.

Initialise your charm project

Use Charmcraft to quickly initialise your charm project. This generates the folder structure, creates placeholder configuration and code files, and configures development tooling.

See more:

• Charmcraft | Manage charms > Initialize a charm (see also the best practice note on setting up a repository and considering your CI)

• Charmcraft | Manage charms > Add charm project metadata, an icon, docs

Develop your charm

The Charmcraft profile has configured some commands to help you develop your charm:

• Run tox to format and lint the code, and run static type checking and the charm unit tests.

• Run tox -e integration to run the charm integration tests.

• Run tox list to see the available commands.

Best practice

All charms should provide the commands configured by the Charmcraft profile, to allow easy testing across the charm ecosystem. It’s fine to tweak the configuration of individual tools, or to add additional commands, but keep the command names and meanings that the profile provides.

The following tools can also be useful during development:

• To prepare an environment for running integration tests, such as in continuous integration, use concierge or actions-operator.

• The charming-actions repository includes actions to ensure that libraries are up-to-date, publish charms and libraries, and more.

Best practice

The quality assurance pipeline of a charm should be automated using a continuous integration (CI) system.

The essence of a charm is the src/charm.py file. This is the entry point for your code whenever Juju emits an event, and defines the interface between Juju and the charm workflow.

See more:

• How to run workloads with a Kubernetes charm

• How to run workloads with a machine charm

• How to write and structure charm code

• How to write unit tests for a charm

• How to write integration tests for a charm

• How to manage logs

The next thing to do is add functionality to your charm. As you do that, you’ll frequently pack, test, and debug your charm.

One of the powers of charms is their reusability. As such, do not try to duplicate functionality already achieved by an existing charm – rather, make your charm take advantage of the charm ecosystem by supporting integrating with existing charm solutions for observability, identity, scaling, and so on.

This also helps you stay compliant with another fundamental rule in charms, namely that, following the Unix philosophy, each charm should do one thing and do it well.

See more:

• Make use of core Juju functionality

  • How to manage storage

  • How to manage resources

  • How to manage secrets

• Add functionality

  • Charmcraft | Add runtime details to a charm

  • How to manage actions

  • Manage configuration

  • How to manage opened ports

• Charmcraft | Manage charms > Pack a charm

• Juju | Manage charms > Deploy a charm (you’ll need to follow the “Deploy a local charm” example)

• Juju | Manage charms > Debug a charm

Publish your charm

When you’re ready, you’ll publish your charm on Charmhub.

See more:

• Charmcraft | Publish a charm on Charmhub (see especially the note on requesting formal review for your charm)

If your charm depends on resources that are binary files, make sure to provide binaries for all the CPU architectures you intend to support.

A charm is software: while there can be milestones, there is never a finish line. So, keep investing in every bit of your charm so that it looks and feels professional – from polishing metadata (including an icon, a website, docs, and so on) through polishing features (for example, working to ensure correct and reliable behavior, adding libraries so people can quickly integrate with your charm, and so on) all the way to turning it into a successful open source project with a community that enjoys it and wants to contribute to it.