The Python library behind great charms
Project description
The Operator Framework
The Operator Framework provides a simple, lightweight, and powerful way of writing Juju charms, the best way to encapsulate operational experience in code.
The framework will help you to:
- model the integration of your services
- manage the lifecycle of your application
- create reusable and scalable components
- keep your code simple and readable
Getting Started
Charms written using the operator framework are just Python code. The intention is for it to feel very natural for somebody used to coding in Python, and reasonably easy to pick up for somebody who might be a domain expert but not necessarily a pythonista themselves.
The dependencies of the operator framework are kept as minimal as possible;
currently that's Python 3.5 or greater, and PyYAML (both are included by
default in Ubuntu's cloud images from 16.04 on).
A Quick Introduction
Operator framework charms are just Python code. The entry point to your charm is
a particular Python file. It could be anything that makes sense to your project,
but let's assume this is src/charm.py. This file must be executable (and it
must have the appropriate shebang line).
You need the usual metadata.yaml and (probably) config.yaml files, and a
requirements.txt for any Python dependencies. In other words, your project
might look like this:
my-charm
├── config.yaml
├── metadata.yaml
├── requirements.txt
└── src/
└── charm.py
src/charm.py here is the entry point to your charm code. At a minimum, it
needs to define a subclass of CharmBase and pass that into the framework's
main function:
from ops.charm import CharmBase
from ops.main import main
class MyCharm(CharmBase):
def __init__(self, *args):
super().__init__(*args)
self.framework.observe(self.on.start, self.on_start)
def on_start(self, event):
# Handle the start event here.
if __name__ == "__main__":
main(MyCharm)
That should be enough for you to be able to run
$ charmcraft build
Done, charm left in 'my-charm.charm'
$ juju deploy ./my-charm.charm
🛈 More information on
charmcraftcan also be found on its github page.
Happy charming!
Testing your charms
The operator framework provides a testing harness, so that you can test that
your charm does the right thing when presented with different scenarios, without
having to have a full deployment to do so. pydoc3 ops.testing has the details
for that, including this example:
harness = Harness(MyCharm)
# Do initial setup here
relation_id = harness.add_relation('db', 'postgresql')
# Now instantiate the charm to see events as the model changes
harness.begin()
harness.add_relation_unit(relation_id, 'postgresql/0')
harness.update_relation_data(relation_id, 'postgresql/0', {'key': 'val'})
# Check that charm has properly handled the relation_joined event for postgresql/0
self.assertEqual(harness.charm. ...)
Talk to us
If you need help, have ideas, or would just like to chat with us, reach out on IRC: we're in #smooth-operator on freenode (or try the webchat).
We also pay attention to Juju's discourse; most discussion at this stage is on IRC, however.
You can also deep dive into the API docs if that's your thing.
Operator Framework development
If you want to work in the framework itself you will need Python >= 3.5 and
the dependencies declared in requirements-dev.txt installed in your system.
Or you can use a virtualenv:
virtualenv --python=python3 env
source env/bin/activate
pip install -r requirements-dev.txt
Then you can try ./run_tests, it should all go green.
For improved performance on the tests, ensure that you have PyYAML installed with the correct extensions:
apt-get install libyaml-dev
pip install --force-reinstall --no-cache-dir pyyaml
If you want to build the documentation you'll need the requirements from
docs/requirements.txt, or in your virtualenv
pip install -r docs/requirements.txt
and then you can run ./build_docs.
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file ops-1.0.0.tar.gz.
File metadata
- Download URL: ops-1.0.0.tar.gz
- Upload date:
- Size: 107.6 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/3.1.1 pkginfo/1.4.2 requests/2.22.0 setuptools/45.2.0 requests-toolbelt/0.8.0 tqdm/4.30.0 CPython/3.8.5
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 1ddbb887a324aad22721f8271d93f6367097c0e906b248f8d3378bc3e7c04a2d |
|
| MD5 | 9caae5d0589308b89cda0d953b09273b |
|
| BLAKE2b-256 | 34ebe8ad8b4f74279b1a01dea44d689ec60ca86d28dc4f7038187642d8c4f99d |
File details
Details for the file ops-1.0.0-py3-none-any.whl.
File metadata
- Download URL: ops-1.0.0-py3-none-any.whl
- Upload date:
- Size: 65.6 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/3.1.1 pkginfo/1.4.2 requests/2.22.0 setuptools/45.2.0 requests-toolbelt/0.8.0 tqdm/4.30.0 CPython/3.8.5
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 0eb39158ccbb680c1d1c2039e42befa97024ecf88c7a129f437b6d3df0c559ed |
|
| MD5 | 9c8838ee3f10853a3d4f8ba65298af12 |
|
| BLAKE2b-256 | 7b0d64400b6382d3b3d50b71a2e3c7379c5702249ff0fb9a29882dd26245a54e |
