Highlighting Charm Libraries

The Operator Framework has a nice, streamlined facility for creating and sharing library files. The curious may read the detailed docs here. In general, it is important to know that:

  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.

So how do you write a library? Giving the above linked docs a read through is a start. You might also want to take a look at some examples. The following charms have excellent libraries, using best practices, and you should feel free to use them to inform your own library authorship

Example Libraries

grafana_dashboard (link)

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 (link)

This library implements a requires/providers 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 (link)

This library is maintained by the Observability team, but is useful for most kubernetes charm. 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 (link)

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

systemd (link)

Stepping over to the world of “legacy estate” (bare metal machines and vms), this 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.)

Comments and questions are welcome. The comments in this thread are also an appropriate place to share libraries that you’re working on, or highlight libraries that you have found to be useful!