Skip to content

Commit

Permalink
Update README.md -- implemented all the suggestions
Browse files Browse the repository at this point in the history 
and also fixed a couple more typos
  • Loading branch information
@tmihoc
tmihoc authored Oct 26, 2023
1 parent f2c3c4c commit d793113
Showing 1 changed file with 35 additions and 35 deletions.
70 changes: 35 additions & 35 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,49 +1,51 @@
# The `ops` library


The `ops` library is a Python framework for developing and testing Kubernetes and machine charms. While charms can be written in any language, `ops` defines the latest standard, and all new charms are encouraged to use Python with `ops`. The library is an official component of the Charm SDK, itself a part of [the Juju universe](https://juju.is/).
The `ops` library is a Python framework for developing and testing Kubernetes and machine [charms](https://juju.is/docs/sdk/charmed-operators). While charms can be written in any language, `ops` defines the latest standard, and charmers are encouraged to use Python with `ops` for all charms. The library is an official component of the Charm SDK, itself a part of [the Juju universe](https://juju.is/).

> - `ops` is [available on PyPI](https://pypi.org/project/ops/).
> - The latest version of `ops` requires Python 3.8 or above.
||||
|-|-|- |
|| [Juju](https://juju.is/docs/juju) | Learn how to quickly deploy, integrate, and manage charms on any cloud with Juju. <br> _It's as simple as `juju deploy foo`, `juju integrate foo bar`, ..., on any cloud._ |
|| [Juju](https://juju.is/docs/juju) | Learn how to quickly deploy, integrate, and manage charms on any cloud with Juju. <br> _It's as simple as `juju deploy foo`, `juju integrate foo bar`, and so on -- on any cloud._ |
||||
|| [Charmhub](https://charmhub.io/) | Sample our existing charms on Charmhub. <br> _A charm can be a cluster ([OpenStack](https://charmhub.io/openstack-base), [Kubernetes](https://charmhub.io/charmed-kubernetes)), a data platform ([PostgreSQL](https://charmhub.io/postgresql-k8s), [MongoDB](https://charmhub.io/mongodb), etc.), an observability stack ([Canonical Observability Stack](https://charmhub.io/cos-lite)), an MLOps solution ([Kubeflow](https://charmhub.io/kubeflow)), and so much more._ |
||||
|:point_right:| [Charm SDK](https://juju.is/docs/sdk) | Write your own charm! <br> _Juju is written in Go, but our SDK supports easy charm development in Python._ |
|:point_right:| [Charm&nbsp;SDK](https://juju.is/docs/sdk) | Write your own charm! <br> _Juju is written in Go, but our SDK supports easy charm development in Python._ |

## Give it a try

Let's use `ops` to build a Kubernetes charm:

### Set up

> See [Charm SDK | Set up your development environment automatically > Set up an Ubuntu `charm-dev` VM with Multipass](https://juju.is/docs/sdk/dev-setup#heading--automatic-set-up-an-ubuntu-charm-dev-vm-with-multipass). <br> Choose the MicroK8s track.
> See [Charm SDK | Set up an Ubuntu `charm-dev` VM with Multipass](https://juju.is/docs/sdk/dev-setup#heading--automatic-set-up-an-ubuntu-charm-dev-vm-with-multipass). <br> Choose the MicroK8s track.

### Write your charm

On your Multipass VM, create a charm directory and use Charmcraft to initialise your charm file structure:

```
mkdir my-new-charm
cd my-new-charm
```shell-script
mkdir ops-example
cd ops-example
charmcraft init
```
This has created a standard charm directory structure. Poke around.
This has created a standard charm directory structure. Poke around.

Note that the `metadata.yaml` file shows that what we have is an example charm called `my-new-charm`, which uses an OCI image resource `httpbin` from `kennethreitz/httpbin`.
Things to note:

Note that the `requirements.txt` file lists the version of `ops` to use.
- The `metadata.yaml` file shows that what we have is an example charm called `ops-example`, which uses an OCI image resource `httpbin` from `kennethreitz/httpbin`.

Note that the `src/charm.py` file imports `ops` and uses `ops` constructs to create a charm class `MyNewCharmCharm`, observe Juju events, and pair them to event handlers:
- The `requirements.txt` file lists the version of `ops` to use.

```
- The `src/charm.py` file imports `ops` and uses `ops` constructs to create a charm class `OpsExampleCharm`, observe Juju events, and pair them to event handlers:

```python
import ops
...
class MyNewCharmCharm(ops.CharmBase):

class OpsExampleCharm(ops.CharmBase):
"""Charm the service."""

def __init__(self, *args):
Expand All @@ -68,19 +70,18 @@ class MyNewCharmCharm(ops.CharmBase):
# Learn more about statuses in the SDK docs:
# https://juju.is/docs/sdk/constructs#heading--statuses
self.unit.status = ops.ActiveStatus()
...
```

> See more: [`ops.PebbleReadyEvent`](https://ops.readthedocs.io/en/latest/index.html#ops.PebbleReadyEvent)
Note that the `tests/test_charm.py` file imports `ops.testing` and uses it to set up a testing harness:
- The `tests/unit/test_charm.py` file imports `ops.testing` and uses it to set up a testing harness:

```
```python
import ops.testing
...

class TestCharm(unittest.TestCase):
def setUp(self):
self.harness = ops.testing.Harness(MyNewCharmCharm)
self.harness = ops.testing.Harness(OpsExampleCharm)
self.addCleanup(self.harness.cleanup)
self.harness.begin()

Expand Down Expand Up @@ -108,50 +109,49 @@ class TestCharm(unittest.TestCase):
self.assertTrue(service.is_running())
# Ensure we set an ActiveStatus with no message
self.assertEqual(self.harness.model.unit.status, ops.ActiveStatus())
...
```

> See more: [`ops.testing.Harness`](https://ops.readthedocs.io/en/latest/#ops.testing.Harness)

Explore further, start editing the files, or skip ahead and pack the charm:

```
```shell-script
charmcraft pack
```

If you didn't take any wrong turn or simply left the charm exactly as it was, this should work and yield a file called `my-new-charm_ubuntu-22.04-amd64.charm` (the architecture bit may be different depending on your system's architecture). Use this name and the resource from the `metadata.yaml` to deploy your example charm to your local MicroK8s cloud:
If you didn't take any wrong turn or simply left the charm exactly as it was, this has created a file called `ops-example_ubuntu-22.04-amd64.charm` (the architecture bit may be different depending on your system's architecture). Use this name and the resource from the `metadata.yaml` to deploy your example charm to your local MicroK8s cloud:

```
juju deploy ./my-new-charm_ubuntu-22.04-amd64.charm --resource httpbin-image=kennethreitz/httpbin
```shell-script
juju deploy ./ops-example_ubuntu-22.04-amd64.charm --resource httpbin-image=kennethreitz/httpbin
```

Congratulations, you’ve just built your first Kubernetes charm using Ops!
Congratulations, you’ve just built your first Kubernetes charm using `ops`!

### Clean up

> See [Charm SDK | Set up your development environment automatically > Clean up](https://juju.is/docs/sdk/dev-setup#heading--automatic-set-up-an-ubuntu-charm-dev-vm-with-multipass).
> See [Charm SDK | Clean up](https://juju.is/docs/sdk/dev-setup#heading--automatic-set-up-an-ubuntu-charm-dev-vm-with-multipass).
## Next steps

### Learn more
- Read our [user documentation](https://juju.is/docs/sdk/ops), which includes other guides showing `ops` in action.
- Dig into the [`ops` API reference](https://ops.readthedocs.io/en/latest/).
- Read our [user documentation](https://juju.is/docs/sdk/ops), which includes other guides showing `ops` in action
- Dig into the [`ops` API reference](https://ops.readthedocs.io/en/latest/)

### Chat with us

Read our [Code of conduct](https://ubuntu.com/community/code-of-conduct) and:
- Join our chat: [Mattermost](https://chat.charmhub.io/charmhub/channels/ops).
- Join our forum: [Discourse](https://discourse.charmhub.io/).
- Join our chat: [Mattermost](https://chat.charmhub.io/charmhub/channels/ops)
- Join our forum: [Discourse](https://discourse.charmhub.io/)

### File an issue

- Report an `ops` bug using [GitHub issues](https://github.com/canonical/operator/issues).
- Raise a general https://juju.is/docs documentation issue on [GitHub | juju/docs](https://github.com/juju/docs).
- Report an `ops` bug using [GitHub issues](https://github.com/canonical/operator/issues)
- Raise a general https://juju.is/docs documentation issue on [GitHub | juju/docs](https://github.com/juju/docs)

### Make your mark

- Read our [documentation contributor guidelines](https://discourse.charmhub.io/t/documentation-guidelines-for-contributors/1245) and help improve a doc.
- Read our [codebase contributor guidelines](HACKING.md) and help improve the codebase.
- Write a charm and publish it on [Charmhub](https://charmhub.io/).
- Read our [documentation contributor guidelines](https://discourse.charmhub.io/t/documentation-guidelines-for-contributors/1245) and help improve a doc
- Read our [codebase contributor guidelines](HACKING.md) and help improve the codebase
- Write a charm and publish it on [Charmhub](https://charmhub.io/)

0 comments on commit d793113

Please sign in to comment.