Operator Framework 1.3.0

The Operator Framework team is proud to release version 1.3.0 of the Operator Framework!

OF 1.3.0 adds support for running one-shot commands via Pebble with the Container.exec method. This functionality uses the new Pebble “exec” API, which behaves similarly to lxd exec or kubectl exec – the Pebble CLI has a corresponding pebble exec command. The tool allows an operator to run a one-off command inside the workload container. It is very useful for troubleshooting, as well as performing maintenance tasks that haven’t yet been formalized as an action in a charm.

This release also includes a change to juju debug-code. The command now stops on all events and hooks, allowing charm authors to enter a debugging session without needing to specify a specific hook in advance. Charm authors can still access the old behavior by explicitly calling juju debug-code <app> --at <hook>.

OF 1.3.0 adds a mocked out filesystem to the testing harness. Charm authors can now attach and detach virtual storage, and read and write files to the test filesystem. This feature has been long requested, and allows for much more complete unit test coverage for charms.

Additionally, the charmed operator framework now exposes a “planned unit count,” to allow charms to handle HA config and similar features that require a peer count in advance of the peers actually coming online. The information supplied by this feature, comprising a single int that represents the number of peers (inclusive of the current unit) an application is expected to have, is intentionally minimalist. Charm authors should use this feature to save unnecessary execution of HA setup in an environment that doesn’t need it (or unnecessary non HA setup in an environment that does). Code paths using the feature should understand that the int can change, and that it does not include a guarantee that the units will be available. (If there is a deploy issue with a unit, for example, the planned unit count will not be reached until a human operator intervenes and resolves the issue.)

Beyond these highlights, 1.3.0 includes many minor features and bugfixes. A complete list follows:


  • Include task logs in ChangeError.str (#653)
  • Add support for storage to the testing harness.
  • Add send_signal to pebble.Client and model.Container (#669)
  • Add a test for restarting Pebble services on older Pebble versions (#658)
  • Add storage details to storage events #
  • Added support for One-shot commands #593
  • Added “planned unit count” to model. #597
  • Add support for the new wait-change API #595
  • Let ‘debug-code’ catch all events by default #565
  • Flatten nested dictionaries passed to action_set() #630
  • Add pebble replan, support serverside restart. #580
  • Added storage mappings to ContainerMeta as ContainerStorageMeta #601
  • Remove ops.relation module #606 (Requires/Provides functionality now lives in a library.)
  • Expose model uuid in ops.model.Model #563
  • Expose ‘limit’ in RelationMeta and improve ‘scope’ #552
  • Add user/group fields to Service (layer configuration) #540
  • Add __eq__ to ops.pebble.Service so layer service equality can be checked (#592)
  • Send a list of services to stop to pebble in restart() instead (#591)
  • Make Container.restart() semantics operate more like system services (#588)
  • Various documentation and testing harness improvements.
  • Streamlined build, test and release process.


  • Adjust the ops.model.Resources.fetch method to throw a NameError (#661)
  • Fix storage events with multiple hyphens #663
  • Exec test fixes and “for line in process.stdout” fix (#655)
  • Fixed issue with float to decimal conversion causing trouble with metrics. #609
  • Fixed exception with very large log messages by splitting them #632
  • Fix Pebble push() handling of binary files #574
  • Fix Container.restart() accidentally operating on strings, add a testcase #590
  • Various testing harness bugfixes.

@jnsgruk @vultaire @jameinel Please take a look at the above draft of the release notes for Operator Framework 1.3.0 (after looking at the feature list, I think that it is appropriate to call this 1.3.0).

This is basically a lightly edited dump of the logs, with documentation updates and bugfixes that don’t directly affect production rolled up into “various documentation and testing harness improvements.”

Let me know whether you think I should highlight anything else in the blurb at the top, of if any of the individual entries don’t make sense to you.

I feel like having a bit more of a highlight/discussion of a key feature like One Shot (at the least pointing at the documentation around how to use it) is useful as a key feature of the release. The debug-code change is also a bit of a change in behavior (it means that just a plain juju debug-code app will stop on all hooks, where you used to have to supply juju debug-code app --at hook.) I probably wouldn’t include #629 if we are actively reverting that change. (I think since we are reverting it, we probably shouldn’t do an official publish with ‘.update’ available)

Probably change “add eq” to "add __eq__" since markdown doesn’t like python arithmetic operators.

1 Like

Looking good – agree that we should make more of a feature of one-shot commands, and we should probably make sure we time the release such that Juju 2.9.17 is generally available to ensure people can use the new hotness! I know @benhoyt was working on some docs for one-shot, so they should land soon :slight_smile:

FYI, I made a couple of minor edits to the one-shot commands paragraph for accuracy.

Thanks for the edits, @benhoyt

(I made a bunch of edits myself, expanding the highlights section and dropping the probably-reverted .update change.)

1 Like

Updated again, with stuff that happened since October.