How to create and share a charm library

See also:

This document details how to build and share your own charm libraries.

Contents:

Create a charm library

You’ve been unable to find an existing library with the intended functionality for your charm. As such, it’s time to learn how to create your own.

Let’s start from a charm that has no libraries at all:

$ ll lib
ls: cannot access 'lib': No such file or directory

The first step is create the bare library template using charmcraft create-lib:

# Initialise a charm library named 'demo'
$ charmcraft create-lib demo

Before creating a library, you must first register ownership of your charm’s name. See How to publish your charm to Charmhub.

This will create a file at $CHARMDIR/lib/charms/demo/v0/demo.py.

Charm libraries are always located according to the pattern: $CHARMDIR/lib/charms/<charm_name>/v<API>/<library_name>.py. See The location of a charm library inside a charm.

Developers can import the library from within their charm code using its fully-qualified path:

import charms.demo.v0.demo

That file is just a template we must fill, though. We can separate the content in three parts:

  • The module’s docstring.
    This will be the library’s documentation, automatically presented on Charmhub and updated whenever a new version of the library is published; markdown is supported, following the CommonMark specification.

  • The three metadata fields.
    LIBID is already assigned by Charmhub—make sure to never change it. LIBAPI and LIBPATCH are set to an initial state (0 and 1 correspondingly), which is fine for now, but in general note that LIBAPI must match the major version in the import path and LIBPATCH must match the current patch version (needs to be updated when changing).

  • The rest of the file.
    Here is where we will add all the library’s code. Some good examples to follow, depending on the intended use case, are:

    • The ingress library for the nginx-ingress-integrator charm. This implements the Requires/Provides pattern for relations.

    • The grafana dashboard library for the grafana-k8s charm. This provides a nice example of how cleanly a library can add functionality to a charm with minimal fuss or boiler plate, while providing a clean way to make that functionality available for re-use.

    • You might also keep an eye on operator-libs-linux on github, where Canonical is building a small collection of libraries for handling apt, snap and other system packages.

Publish a charm library

You’ve created your library and you’d like to share it with the world. To publish your library, simply execute charmcraft publish-lib followed by the full library path. This will upload the library content and also make it available for consumption by other charm authors.

$ charmcraft publish-lib charms.demo.v0.demo
Library charms.demo.v0.demo sent to the store with version 0.1

In order to be able to publish a charm library, you need to be signed into Charmcraft as a user that has permissions to publish libraries to this charm. In particular you need to be the owner of this charm or registered as a contributor to the charm—a status that can be requested via Discourse.

Update a charm library

You will eventually need to evolve the library’s content (new functionalities, bug fixing, documentation improvements, etc.). Every time you want to offer a new version of your library, simply call the publish-lib command again.

However, before publishing new versions, make sure to update the LIBAPI/LIBPATCH metadata fields inside the library file. Most times it is enough to just increment LIBPATCH but, if you’re introducing breaking changes, you must work with the major API version.

Additionally, be mindful of the fact that users of your library will update it automatically to the latest PATCH version with the same API version. To avoid breaking other people’s library usage, make sure to increment the LIBPAPI version but reset LIBPATCH to 0. Also, before adding the breaking changes and updating these values, make sure to copy the library to the new path; this way you can maintain different major API versions independently, being able to update, for example, your v0 after publishing v1.

Share a charm library

To share your charm library with developers:

  • Access your charm page on charmhub.io.
  • Go to the Libraries tab. image
  • Click on your library.
  • Use the URL to share your library with other charm developers.

Last updated 5 months ago.