1.5.0

The Operator Framework team is proud to release version 1.5.0 of the Operator Framework! This is a modestly sized release with a few new, non breaking features.

Highlights

• Harness support for simulating storage mounts during testing - allowing disk IO to mounted filepaths and sharing data between shared mounts in charm and workload (via e.g. pebble operations) containers. This should "just work" - as long as you use the storage mount paths provided via e.g. self.model.storages['storage-name'][0].location which you should already be doing anyway (right?).
• New Container.push_path and Container.pull_path methods for recursively pushing/pulling directories to/from workload containers.
• We've begun to implement complete type annotations to improve auto-completion and robustness. Over the next release or so type annotation coverage will continue to improve.

Complete List of Changes

• Modify Harness.set_leader to be more robust, less finicky by @rwcarlsen in #733
• Harness add_layer merge support. by @alesstimec in #738
• Edited test charm to support metadata v2, drop untested v1 fields by @pengale in #748
• Harness: support mocking storage mounts by @rwcarlsen in #734
• More typing by @PietroPasotti in #744
• Typing for storage.py by @PietroPasotti in #749
• Fixes address info value getter by @PietroPasotti in #757
• Typing utils by @PietroPasotti in #755
• PR template. by @pengale in #746
• Typing for model.py by @PietroPasotti in #756
• Recursively push+pull files/dirs to containers by @rwcarlsen in #754

New Contributors

• @alesstimec made their first contribution in #738

Full Changelog: 1.4.0...1.5.0

1.4.0

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

This is largely a bugfix release, but it also includes a few small, non breaking features.

Highlights

• Memory efficient push of file(s) to pebble
• Testing harness more closely matches live environment behavior
• Added flag to test with "real pebble". Use this to write tests that use an actual running Pebble rather than a fixture
• Add Container.isdir and Container.exists helpers

Complete List of Changes

• Memory-efficient push via pebble by @Vultaire in #666
• remove_path succeeds even if path does not exist by @sed-i in #677
• Make the storage harness work when metadata keys have hyphens by @rbarry82 in #680
• docfix: mention add_relation_unit in the docstring for add_relation by @sed-i in #683
• conformed list_files behaviour on failure with pebble's by @PietroPasotti in #686
• Add real pebble tests to our CI by @rwcarlsen in #687
• FIX remove_path docstring to relfect current behaviour. by @Abuelodelanada in #698
• Fix incorrect variadic arg wrangling in get_services by @rwcarlsen in #702
• add tox config for real pebble tests by @rwcarlsen in #704
• skip broken ipython version to fix CI by @rwcarlsen in #710
• Add Container.isdir and Container.exists helpers by @rwcarlsen in #709
• Added notes on cutting a release to HACKING.md by @pengale in #714
• Avoid issuing relation_changed events with no data delta by @mmanciop in #705
• Updated docs on planned units. by @pengale in #716
• expose the departing unit on RelationDeparted events by @rwcarlsen in #712
• DEPATING -> DEPARTING by @PietroPasotti in #717
• Implement send-signal for harness by @sed-i in #715
• notes about documentation for contributers by @rwcarlsen in #720
• Fixing updated link in docstrings by @Abuelodelanada in #722
• Harness: add test for an empty config file by @sed-i in #728
• begin_with_initial_hooks now sets post install status correctly by @pengale in #727
• Add checks config fields and get_checks API by @benhoyt in #668
• Memory-efficient pull via pebble by @Vultaire in #667

New Contributors

• @PietroPasotti made their first contribution in #686
• @rwcarlsen made their first contribution in #687
• @Abuelodelanada made their first contribution in #698

Full Changelog: 1.3.0...1.4.0

ops 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 --at .

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:

Features:

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.

Bugfixes:

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.

Full Changelog: 1.2.0...1.3.0

ops 1.2.0

A new release of the Charmed Operator Framework.

This release adds support for new ways of writing operators for kubernetes. Having your operator in a sidecar of the workload provides much more control over how the workload is running and configured. This adds attributes like Charm.unit.containers to interact with the other containers that are part of your pod. There is also updated testing infrastructure for ensuring that your charm is instantiating services in the shared containers correctly.

See our updated documentation (https://juju.is/docs/sdk/constructs) for how the new structure works.

This also includes fixes for:

• #475 (lp:1914415) Ensure the Relation.app attribute is set correctly
• #507 Network-get can return empty addresses

ops 1.1.0

This is a maintenance release, which includes tweaks to the README and some
docstrings, a __repr__ method for the several Stored* classes, and support
for charms that include an empty actions.yaml.

1.0.1:

• Don't skip interfaces without names: they don't have names on k8s

1.0.0

• We added quite a few docstrings, and a test that will fail if something
  is missing docstrings.

• We're more tolerant of missing fields in the output of network-get,
  which can happen in some situations.
  Thanks to @johnsca for this one.

• Charm authors can run self.config from a charm method instead of having
  to do self.model.config.
  Thanks to @johnsca for this one.

• Some ways of installing ops can result in not loading the libyaml
  extensions from PyYAML, giving a performance penalty. ops will warn
  when this happens so it can be remedied, but it would also warn when
  running the test suite which raises the barrier for developers wanting to
  contribute to ops itself. So now we ignore that.
  Thanks to @johnsca for this one.

• The hooks_disabled context manager can now be nested.
  Thanks to @stub42 for this one.

• When using Juju for storage (either automatically by running on
  kubernetes with a new enough Juju, or manually via passing
  use_juju_for_storage=True to main), events defered would never be
  re-emitted. This is #438, found with help from @davigar15.

• ObjectEvents now have a __repr__ which lists all events it knows about,
  which can be helpful when debugging (or even developing) a complex charm.

• sys.breakpointhook is only set from main, not from
  Framework.__init__, meaning it won't interfere with using the
  breakpoint() builtin from tests.

• tests will now fail if a docstring is missing (or malformed).

This is version 0.10.0 of `ops`, the Operator Framework for Juju charms.

Changes include:

• deleting a non-existent key from relation data will no longer fail.
  Thanks to @stub42 for the fix.

• calling begin_with_initial_hooks() on the testing harness of a charm
  that has a relation that isn't set up before the call will no longer fail.
  Thanks to @zzehring for the fix.

• the testing harness now starts with default config values, specified in the
  same way as for actions.yaml and metadata.yaml (i.e. snippets if given,
  otherwise from the canonical yaml file).
  Thanks to @johnsca for the work.

• some classes now have custom __repr__ methods that should aid debugging.

• event deferral and reëmission is now logged (at DEBUG).

• if use_juju_for_storage is specified for a charm running in a Juju that does
  not support this feature, a clear and explicit error is raised.

• the public attributes of model are now immutable. This is to discourage
  people from overwriting these attributes in tests, given there is a fair
  amount of internal state. Please use the harness instead (or mocking if you
  must).

• the test suite now passes on Windows, and we run the full suite on Windows for
  every commit, as we do for linux and macos.

0.9.0 highlights:

Release highlights:

• Controller-side storage is now used automatically (i.e. without the
  charm author needing to set the use_juju_for_storage flag on
  main) when we're sure it's needed. It can still be forced on or
  off via that flag to main.

• A workaround for Juju's lp:1880637 to address #293, so
  pod.set_spec's k8s_resources works as expected. But note #387,
  as "as expected" might not be as you expect.

• If charm code is run in an environment that does not set
  JUJU_VERSION, default to 0.0.0 instead of raising an exception. This
  means all the feature checks will fail, but the charm can still
  progress. Please let us know if this is not what you want; this
  impacts #372.

• Charm authors can now use harness.hooks_disabled() as a context
  manager to run a block of code without events being fired for them.
  Without this you'd have to wrap that code in disable/enable
  pairs.

This is version 0.8.0 of `ops`, the Operator Framework for Juju charms.

Changes include:

• testing Harness updates

  • Harness.begin_with_initial_hooks() will cause the testing Harness to
    emit all of the events that Juju normally does while a charm is
    'starting'. (install, leader-elected, etc.). While most unit tests
    should be more focused on a single hook interaction, this gives a bit more
    confidence that the whole initialization step of the charm operates in a
    good manner.

  • Harness.get_pod_spec() allows a test to introspect what pod spec was set
    in response to their update event. Eg.,

    harness = Harness(MyCharm)
    # ... initial setup
    harness.begin()
    harness.update_config({'foo': 'bar'})
    pod_spec, k8s_resources = harness.get_pod_spec()
    self.assertIsNone(k8s_resources)
    self.assertEqual(pod_spec['blah']['blah'], 'bar')
    

  • Harness.cleanup() is now available to ensure that any temporary
    files/directories created by the harness are cleaned up. For unittest you
    would use this as:

    harness = Harness(MyCharm)
    self.addCleanup(harness.cleanup)
    ...
    

    This is currently only relevant if you are running tests that make use of
    resources (either add_oci_resource or add_resource). However, it is good
    practice to start making use of it, in case there are other resources
    associated with Harness that will need to be cleaned up.

  • Harness.add_resource() is now also available so that you can feed your
    charm code file content that it would get from resource-get.

• You no longer need to call ops.lib.autoimport before your first call to
  ops.lib.use; you only need to do it if the library information is out of
  date (e.g. if you installed or otherwise altered what the system would find).
  Also a lot more logging of the process of autodiscovery has been added.
  Thanks to @stub42 for pointing out how needing the first call was
  counter-intuitive, and the process hard to debug.

• Libraries used via ops.lib.use can now have subpackages or modules.

• dispatch-aware charms that set JUJU_DISPATCH_PATH before calling into the
  framework caused the framework to think the Juju it was running on supported
  dispatch, even if the version was clearly too old for that. This meant that
  non-initial hooks were never called on these charms on those
  Jujus. Unfortunately charms created with charmcraft 0.3 fell into this
  category. The framework now looks directly at the Juju version to determine
  dispatch support. Thanks to @gnuoy for finding reporting this.