Library

See also:

A charm library is a Python module designed to enable charm authors to easily share and reuse auxiliary logic related to charms, for example, logic related to the relations between charms. They are a great way to help other authors to write charms that can relate to yours. This document gives some general notes and highlights some notable examples to follow.

Contents:

General notes

  1. A library must comprise a single Python file. If you write a library that feels too “big” for a single file, it is likely that the library should be split up, or that you are actually writing a full on charm.

  2. Authors associate libraries with a specific charm, and publish them to Charmhub with a reference to the origin charm. This does not prevent re-use, modification, and sharing.

  3. The publishing tools around libraries are deliberately kept simple. Libraries are versioned, and uniquely identified, however.

Notable examples

The following charms have excellent libraries, confirming to best practices, and are great examples to follow if you’re writing your own library.

If you’d like to highlight other libraries that you have found useful, or share a library that you’re working on, drop a comment using the feedback link below.

grafana_dashboard

The grafana_dashboard library is a great example of the core use case for charm libraries: a charm wants to tell other charms how to interact with it. This library demonstrates how to integrate the grafana dashboard with a charmed service.

Redis

The Redis library implements a requires/provides pattern for redis. It’s useful both for interacting with redis, and as a reference for implementing this commonly used pattern yourself!

kubernetes_service_patch

The kubernetes_service_patch library is maintained by the Observability team, but is useful for most Kubernetes charms. It implements a workaround for an issue with service naming in Juju Core, and is an excellent example of how libraries can be used to share known good workarounds with the community, and extend or modify the core Juju feature set.

Ingress

Another fantastic and re-usable library for Kubernetes deploys, the Ingress library specifies how to interact with the nginx ingress integrator charm.

systemd

Stepping over to the world of “legacy estate” (bare metal machines and vms), the systemd library wraps calls to the systemctl command on the host. It provides quick access to a core set of commands for enabling, disabling, restarting, and reconfiguring services on bare metal and VMs. The library also integrates the output from systemctl with the charm logs, formalizes error checking, and turns some common multi step tasks, like masking and stopping a service, into a single call to the lib.

(If you’ve used charmhelpers in your reactive charms, you may recognize some of the code here, and in the other libraries that live at that link – we’re working on pulling selected bits of charmhelpers into standalone libraries, so that charms built with the Operator Framework can take advantage of the community knowledge built up in charmhelpers, without needing to take on the weight of the entire charmhelpers lib.)


Last updated 4 months ago.