Skip to content

Latest commit

 

History

History
92 lines (63 loc) · 4.23 KB

CONTRIBUTING.md

File metadata and controls

92 lines (63 loc) · 4.23 KB

Contributing to loki-operator

GitHub License GitHub Commit Activity GitHub Lines of Code GitHub Issues GitHub PRs GitHub Contributors GitHub Watchers

Overview

This documents explains the processes and practices recommended for contributing enhancements or bug fixing to the Loki Charmed Operator.

Setup

A typical development setup for charms created with the Charmed Operator Framework contains:

  • Charmcraft - Developer tooling for creating, building and publishing Charmed Operators
  • Juju - a Charmed Operator Lifecycle Manager (OLM), used for deploying and managing operators
  • Multipass - a lightweight Ubuntu virtual machine manager (optional)
  • MicroK8s - a low-ops Kubernetes distribution we’ll use for testing our Charmed Operator (optional if developing a Charmed Operator for Kubernetes)

Please follow this guide which will walk through the installation of these tools to get you started with charm development.

Developing

  • Prior to getting started on a pull request, we first encourage you to open an issue explaining the use case or bug. This gives other contributors a chance to weigh in early in the process.
  • To author PRs you should know what is jujuj and how operators are written.
  • The best way to get a head start is to join the conversation on our mattermost channel! or Discourse. The primary author of this charm is available on the Mattermost channel as @jose-masson.
  • All enhancements require review before being merged. Besides the code quality and test coverage, the review will also take into account the resulting user experience for Juju administrators using this charm. To be able to merge you would have to rebase onto the main branch. We do this to avoid merge commits and to have a linear Git history.
  • We use tox to manage all virtualenvs for the development lifecycle.

Testing

All default tests can be executed by running tox without arguments.

You can also manually run specific test environment:

tox -e lint         # check your code complies to linting rules
tox -e static       # run static analysis
tox -e unit         # run unit tests
tox -e integration  # run integration tests
tox -e fmt          # update your code according to linting rules

Unit tests are written with the Operator Framework test harness.

Build

In order to pack the charm locally so it could be deployed from a local path we use charmcraft.

From the charm's root folder:

$ charmcraft pack
Packing charm 'loki-k8s_ubuntu-20.04-amd64.charm'...
Created 'loki-k8s_ubuntu-20.04-amd64.charm'.

Code Overview

Charm code

This charm is represented by the LokiOperatorCharm class, which responds to the following events:

Juju Events

  • install: Makes sure the k8s service is using the correct ports.
  • config_change: Configures the charm.
  • loki_pebble_ready: Sets up the pebble layer and starts the service
  • upgrade_charm: Patches the ports of the k8s service (just as install) and configures the charm (just as config_change).
  • alertmanager_consumer.on.cluster_changed: Event provided by AlertmanagerConsumer. Further configures the charm to integrate with Alertmanager.

Design Choices

This Loki charm does not support (yet) the distributed deployment, only the standalone one.