Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[pull] master from canonical:master #16

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

[pull] master from canonical:master #16

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 0 additions & 2 deletions .flake8
View file
Open in desktop

This file was deleted.

24 changes: 18 additions & 6 deletions .github/workflows/framework-tests.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,21 @@ name: Operator Framework Tests
on: [push, pull_request]

jobs:
unit-tests:
lint:
runs-on: ubuntu-latest

steps:
- uses: actions/checkout@v2
- name: Set up Python 3
uses: actions/setup-python@v2

- name: Install tox
run: pip install tox

- name: Run linting
run: tox -e lint

test:
runs-on: ${{ matrix.os }}

strategy:
Expand All @@ -18,10 +32,8 @@ jobs:
with:
python-version: ${{ matrix.python-version }}

- name: Install dev dependencies
run: |
pip install -r requirements-dev.txt
- name: Install tox
run: pip install tox

- name: Run unit tests
run: |
python -m unittest
run: tox -e unit
2 changes: 2 additions & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,3 +9,5 @@ __pycache__
.venv
venv
.vscode
.coverage
/.tox
276 changes: 102 additions & 174 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,193 +1,103 @@
# The Charmed Operator Framework

This Charmed Operator Framework simplifies [Kubernetes
operator](https://charmhub.io/about) development for
[model-driven application
management](https://juju.is/model-driven-operations).

A Kubernetes operator is a container that drives lifecycle management,
configuration, integration and daily actions for an application.
Operators simplify software management and operations. They capture
reusable app domain knowledge from experts in a software component that
can be shared.

This project extends the operator pattern to enable
[charmed operators](https://juju.is/universal-operators), not just
for Kubernetes but also operators for traditional Linux or Windows
application management.
This Charmed Operator Framework simplifies [operator](https://charmhub.io/about) development
for [model-driven application management](https://juju.is/model-driven-operations).

Operators emerged from the Kubernetes community; an operator is software that drives lifecycle
management, configuration, integration and daily actions for an application. Operators simplify
software management and operations. They capture reusable app domain knowledge from experts in a
software component that can be shared.

This project extends the operator pattern to enable
[charmed operators](https://juju.is/universal-operators), not just for Kubernetes but also
operators for traditional Linux or Windows application management.

Operators use a [Charmed Operator Lifecycle Manager
(Charmed OLM)](https://juju.is/operator-lifecycle-manager) to coordinate their
work in a cluster. The system uses Golang for concurrent event
processing under the hood, but enables the operators to be written in
Python.
(Charmed OLM)](https://juju.is/operator-lifecycle-manager) to coordinate their work in a cluster.
The system uses Golang for concurrent event processing under the hood, but enables the operators to
be written in Python.

## Simple, composable operators

Operators should 'do one thing and do it well'. Each operator drives a
single microservice and can be [composed with other
operators](https://juju.is/integration) to deliver a complex application.
Operators should 'do one thing and do it well'. Each operator drives a single microservice and can
be [composed with other operators](https://juju.is/integration) to deliver a complex application.

It is better to have small, reusable operators that each drive a single
microservice very well. The operator handles instantiation, scaling,
configuration, optimisation, networking, service mesh, observability,
and day-2 operations specific to that microservice.
It is better to have small, reusable operators that each drive a single microservice very well.
The operator handles instantiation, scaling, configuration, optimisation, networking, service mesh,
observability, and day-2 operations specific to that microservice.

Operator composition takes place through declarative integration in
the OLM. Operators declare integration endpoints, and discover lines of
integration between those endpoints dynamically at runtime.
Operator composition takes place through declarative integration in the OLM. Operators declare
integration endpoints, and discover lines of integration between those endpoints dynamically at
runtime.

## Pure Python operators

The framework provides a standard Python library and object model that
represents the application graph, and an event distribution mechanism for
distributed system coordination and communication.
The framework provides a standard Python library and object model that represents the application
graph, and an event distribution mechanism for distributed system coordination and communication.

The OLM is written in Golang for efficient concurrency in event handling
and distribution. Operators can be written in any language. We recommend
this Python framework for ease of design, development and collaboration.
The OLM is written in Golang for efficient concurrency in event handling and distribution.
Operators can be written in any language. We recommend this Python framework for ease of design,
development and collaboration.

## Better collaboration

Operator developers publish Python libraries that make it easy to integrate
your operator with their operator. The framework includes standard tools
to distribute these integration libraries and keep them up to date.
Operator developers publish Python libraries that make it easy to integrate your operator with
their operator. The framework includes standard tools to distribute these integration libraries and
keep them up to date.

Development collaboration happens at [Charmhub.io](https://charmhub.io/) where
operators are published along with integration libraries. Design and
code review discussions are hosted in the
[Charmhub forum](https://discourse.charmhub.io/). We recommend the
[Open Operator Manifesto](https://charmhub.io/manifesto) as a guideline for
high quality operator engineering.
Development collaboration happens at [Charmhub.io](https://charmhub.io/) where operators are
published along with integration libraries. Design and code review discussions are hosted in the
Charmhub [discourse]. We recommend the [Open Operator Manifesto](https://charmhub.io/manifesto)
as a guideline for high quality operator engineering.

## Event serialization and operator services

Distributed systems can be hard! So this framework exists to make it much
simpler to reason about operator behaviour, especially in complex deployments.
The Charmed OLM provides [operator services](https://juju.is/operator-services) such
as provisioning, event delivery, leader election and model management.
Distributed systems can be hard! So this framework exists to make it much simpler to reason about
operator behaviour, especially in complex deployments. The Charmed OLM provides
[operator services](https://juju.is/operator-services) such as provisioning, event delivery,
leader election and model management.

Coordination between operators is provided by a cluster-wide event
distribution system. Events are serialized to avoid race conditions in any
given container or machine. This greatly simplifies the development of
operators for high availability, scale-out and integrated applications.
Coordination between operators is provided by a cluster-wide event distribution system. Events are
serialized to avoid race conditions in any given container or machine. This greatly simplifies the
development of operators for high availability, scale-out and integrated applications.

## Model-driven Operator Lifecycle Manager

A key goal of the project is to improve the user experience for admins
working with multiple different operators.
A key goal of the project is to improve the user experience for admins working with multiple
different operators.

We embrace [model-driven operations](https://juju.is/model-driven-operations)
in the Charmed Operator Lifecycle Manager. The model encompasses capacity,
storage, networking, the application graph and administrative access.
We embrace [model-driven operations](https://juju.is/model-driven-operations) in the Charmed
Operator Lifecycle Manager. The model encompasses capacity, storage, networking, the application
graph and administrative access.

Admins describe the application graph of integrated microservices, and
the OLM then drives instantiation. A change in the model is propagated
to all affected operators, reducing the duplication of effort and
repetition normally found in operating a complex topology of services.
Admins describe the application graph of integrated microservices, and the OLM then drives
instantiation. A change in the model is propagated to all affected operators, reducing the
duplication of effort and repetition normally found in operating a complex topology of services.

Administrative actions, updates, configuration and integration are all
driven through the OLM.
Administrative actions, updates, configuration and integration are all driven through the OLM.

# Getting started

A package of operator code is called a charmed operator or “charm. You will use `charmcraft`
to register your operator name, and publish it when you are ready.

```
$ sudo snap install charmcraft --beta
charmcraft (beta) 0.6.0 from John Lenton (chipaca) installed
```

Charmed operators written using the Charmed Operator Framework are just Python code. The goal
is to feel natural for somebody used to coding in Python, and reasonably
easy to learn for somebody who is not a pythonista.

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
A package of operator code is called a charmed operator or “charm. You will use `charmcraft` to
register your operator name, and publish it when you are ready. There are more details on how to
get a complete development environment setup over in the
[documentation](https://juju.is/docs/sdk/dev-setup)

Make an empty directory `my-charm` and cd into it. Then start a new charmed operator
with:

```
$ charmcraft init
All done.
There are some notes about things we think you should do.
These are marked with ‘TODO:’, as is customary. Namely:
README.md: fill out the description
README.md: explain how to use the charm
metadata.yaml: fill out the charm's description
metadata.yaml: fill out the charm's summary
```

Charmed operators are just Python code. The entry point to your charmed operator can
be any filename, by default this is `src/charm.py` which must be executable
(and probably have `#!/usr/bin/env python3` on the first line).

You need a `metadata.yaml` to describe your charmed operator, and if you will support
configuration of your charmed operator then `config.yaml` files is required too. The
`requirements.txt` specifies any Python dependencies.

```
$ tree my-charm/
my-charm/
├── actions.yaml
├── config.yaml
├── LICENSE
├── metadata.yaml
├── README.md
├── requirements-dev.txt
├── requirements.txt
├── run_tests
├── src
│   └── charm.py
├── tests
│   ├── __init__.py
│   └── my_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
`main` function:

```python
from ops.charm import CharmBase
from ops.main import main
Charmed Operators written using the Charmed Operator Framework are just Python code. The goal
is to feel natural for somebody used to coding in Python, and reasonably easy to learn for somebody
who is not a pythonista.

class MyCharm(CharmBase):
def __init__(self, *args):
super().__init__(*args)
self.framework.observe(self.on.start, self.on_start)
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).

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 [`charmcraft`](https://pypi.org/project/charmcraft/) can
> also be found on its [github page](https://github.com/canonical/charmcraft).

Happy charming!
For a brief intro on how to get started, check out the
[Hello, World!](https://juju.is/docs/sdk/hello-world) section of the documentation!

# Testing your charmed operators

The operator framework provides a testing harness, so you can check your
charmed operator does the right thing in different scenarios, without having to create
a full deployment. `pydoc3 ops.testing` has the details, including this
example:
The operator framework provides a testing harness, so you can check your charmed operator does the
right thing in different scenarios, without having to create a full deployment.
`pydoc3 ops.testing` has the details, including this example:

```python
harness = Harness(MyCharm)
Expand All @@ -204,36 +114,54 @@ self.assertEqual(harness.charm. ...)
## Talk to us

If you need help, have ideas, or would just like to chat with us, reach out on
[Charmhub Chat](https://chat.charmhub.io/charmhub/channels/juju).
the Charmhub [Mattermost].

We also pay attention to [Charmhub discourse](https://discourse.charmhub.io/)
We also pay attention to the Charmhub [Discourse]

You can also deep dive into the [API docs] if that's your thing.
You can deep dive into the [API docs] if that's your thing.

[discourse]: https://discourse.juju.is/c/charming
[API docs]: https://ops.rtfd.io/
[discourse]: https://discourse.charmhub.io
[api docs]: https://ops.rtfd.io/
[sdk docs]: https://juju.is/docs/sdk
[mattermost]: https://chat.charmhub.io/charmhub/channels/charm-dev

## Operator Framework development

To work in the framework itself you will need Python >= 3.5 and the
dependencies in `requirements-dev.txt` installed in your system, or a
virtualenv:
To work in the framework itself you will need Python >= 3.5. Linting, testing, and docs automation
is performed using [`tox`](https://tox.readthedocs.io/en/latest/).

virtualenv --python=python3 env
source env/bin/activate
pip install -r requirements-dev.txt
The following are likely to be useful during development:

Then you can try `./run_tests`, it should all go green.
```sh
# Run linting and unit tests
tox

For improved performance on the tests, ensure that you have PyYAML
installed with the correct extensions:
# Run tests, specifying whole suite or specific files
tox -e unit
tox -e unit test/test_charm.py

# Format the code using isort
tox -e fmt

apt-get install libyaml-dev
pip install --force-reinstall --no-cache-dir pyyaml
# Generate a local copy of the Sphinx docs in docs/_build
tox -e docs
```

If you want to build the documentation you'll need the requirements from
`docs/requirements.txt`, or in your virtualenv
For more in depth debugging, you can enter any of `tox`'s created virtualenvs
provided they have been run at least once:

pip install -r docs/requirements.txt
```sh
# Enter the unit testing virtualenv
source .tox/unit/bin/activate

# Enter the linting virtualenv
source .tox/lint/bin/activate
```

and then you can run `./build_docs`.
For improved performance on the tests, ensure that you have PyYAML
installed with the correct extensions:

```sh
apt-get install libyaml-dev
pip install --force-reinstall --no-cache-dir pyyaml
```
18 changes: 0 additions & 18 deletions build_docs
View file
Open in desktop

This file was deleted.

Loading