1.5.3

What's Changed

This is a bug-fix/patch release for ops 1.5 advancing the Operator Framework in a number of key areas including:

Typing

Typing is now complete for all ops modules and static checks for all using pyright.

• Typing framework.py by @PietroPasotti in #772
• Typed ops.pebble.py by @PietroPasotti in #773
• Typing charm.py by @PietroPasotti in #791
• Fix model types by @PietroPasotti in #810
• Typing main by @PietroPasotti in #811
• Typed ops/testing.py by @PietroPasotti in #828

Documentation

Various documentation improvements.

• Update docs for unset param in update_config by @swalladge in #768
• cleaned up logging output by @PietroPasotti in #797
• Fix docstring by @zmraul in #802
• Added further documentation to define_event function in framework.py #830 by @nishant-dash in #831
• Documented and checked ActionEvent.set_results with "Stdout" key by @PietroPasotti in #809
• doc fix for config-changed by @PietroPasotti in #804

Testing

The Harness now tries harder to behave like production code would.

• Make Harness more strict in validating relation data contents (on write) by @PietroPasotti in #786
• Address storage testing quirks by @rwcarlsen in #763
• fixed issues with relation data read by @PietroPasotti in #795
• Remove overzealous Harness.add_storage error check. by @rwcarlsen in #781
• added config backend to simulate more closely juju's own by @PietroPasotti in #787
• Include departing unit info for harness-initiated events by @rwcarlsen in #790

Improved error reporting

• Improved error message for invalid storage key usage by @rwcarlsen in #771
• Better error for relation data access in relation-broken events by @rwcarlsen in #765
• downgrade breaking-change exception to just a warning by @rwcarlsen in #822

Bugfixes

• Fix incorrect kwarg handling in testing backend storage_list by @rwcarlsen in #820
• Allow network-get to return hostnames where previously IPaddr were expected by @PietroPasotti in #823
• Use --file for relation-set; avoid shell argument length limits by @rbarry82 in #805
• Fixed bug in ops.Model where non-string keys could be used to write relation data by @PietroPasotti in #788

Misc

• Added a very basic smoke test. Run it with tox -e smoke by @pengale in #800
• require tests to pass on a commit before we publish it to pypi by @rwcarlsen in #815
• Remove harcoded value for self.model_uuid by @Abuelodelanada in #782
• Test observe(decorated-method) by @PietroPasotti in #808

New Contributors

• @swalladge made their first contribution in #768
• @zmraul made their first contribution in #802
• @nishant-dash made their first contribution in #831

Full Changelog: 1.5.2...1.5.3

1.5.2

This is a bug-fix/patch release for ops 1.5 addressing a few important issues including:

• Fix harness model uuid to use the correct/current format used by juju (#782).
• Include the missing departing unit attribute on relation-departed events when using the harness (#790).
• Remove restrictive limits on the number and size of relation data items that can be set (#805).
• Fix type annotations that were causing failures in Ubuntu xenial based environments - i.e. python 3.5 (#810).

Notably, this release was carefully crafted to not break your code. If it does - please complain loudly and we will address problems after completing a good, forceful facepalm.

1.5.1

This release mistakenly excluded one important bugfix. Please skip it - use 1.5.2 instead.

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).