How to contribute

Charmed OpenSearch is an open-source project developed and supported by Canonical that welcomes community contributions, suggestions, fixes, and constructive feedback.

If you would like to contribute a larger change, please get in touch with us first so we can help you shape the contribution.

Report an issue

Report bugs and feature requests on GitHub. For documentation issues, use the Give feedback button at the top of the relevant page to open a pre-filled GitHub issue.

Note

Please do not use GitHub issues for security topics. See the section below.

Report a security issue

Security issues should be reported through Launchpad, following the Ubuntu security disclosure process. Please do not file GitHub issues on security topics.

See also SECURITY.md in the repository.

Get in touch

If you have questions after reading this documentation or would like to discuss Charmed OpenSearch, get in touch through one of the following channels:

  • Chat with the Data team directly on Matrix.

  • Ask questions and share feedback on the Discourse forum.

  • To talk to Canonical about your use case or commercial support, use the business form.

Contribute code

If you would like to contribute, the following sections cover the building and testing for both source code and documentation.

Requirements

To build the charm locally, you will need to install Charmcraft (or charmcraftcache), as well as tox and Poetry. The easiest way to install the last two is with pipx:

pipx install tox
pipx install poetry
pipx install charmcraftcache

To run the machine charm locally with Juju, it is recommended to use LXD as your virtual machine manager. Instructions for running Juju on LXD can be found here.

This repository is a monorepo containing two charms:

  • machine/ — the machine charm (opensearch), which installs and manages OpenSearch from the OpenSearch snap on VMs and machine clusters.

  • kubernetes/ — the Kubernetes charm (opensearch-k8s), which deploys and manages OpenSearch as a container workload on Kubernetes.

Both of these charms are built on top of the shared opensearch-single-kernel-library. The related Charmed OpenSearch Dashboards charms (which live in the separate opensearch-dashboards-operator repository) are built on their own shared library, opensearch-dashboards-single-kernel-library.

Each charm is a self-contained project: build commands must be run from inside the corresponding directory.

Host and model prerequisites

For the machine charm on LXD, OpenSearch has a set of system requirements to function correctly. Some of those settings must be set using cloudinit-userdata on the model, while others must be set on the host machine. For the Kubernetes charm, use a Kubernetes model and follow the Kubernetes setup guidance instead of the LXD steps below.

On the host machine, create a sysctl configuration file and apply it:

sudo tee /etc/sysctl.d/opensearch.conf <<EOF
vm.swappiness = 0
vm.max_map_count = 262144
EOF

sudo sysctl -p /etc/sysctl.d/opensearch.conf

Create a cloud-init user-data file:

cat <<EOF > cloudinit-userdata.yaml
cloudinit-userdata: |
  postruncmd:
    - echo 'vm.max_map_count=262144' >> /etc/sysctl.conf
    - echo 'vm.swappiness=0' >> /etc/sysctl.conf
    - echo 'fs.file-max=1048576' >> /etc/sysctl.conf
    - sysctl -p
EOF

Note

Keep each postruncmd entry as a string. Cloud-init runs string entries through a shell, so the >> redirection works. Entries written as a YAML list are passed straight to execve(3) with no shell, so >> would become a literal argument to echo instead of appending to the file.

Then create a new model and set the previously generated file in it:

# Create a model
juju add-model dev

# Enable DEBUG logging
juju model-config logging-config="<root>=INFO;unit=DEBUG"

# Add cloudinit-userdata
juju model-config --file=./cloudinit-userdata.yaml

# Increase the frequency of the update-status event
juju model-config update-status-hook-interval=1m

Build and deploy

To build a charm, enter the corresponding directory and pack it:

# Clone and enter the repository
git clone https://github.com/canonical/opensearch-operator.git
cd opensearch-operator/machine   # or: cd opensearch-operator/kubernetes

# Build the charm locally
charmcraftcache pack

In a model for the chosen substrate, deploy the Ubuntu 24.04 artifact with a TLS relation (packing also produces a 22.04 artifact):

# Deploy the self-signed-certificates operator
juju deploy self-signed-certificates --channel=1/stable --show-log --verbose

# Generate a CA certificate
juju config self-signed-certificates ca-common-name="CN_CA"

From machine/, deploy and relate the machine charm:

juju deploy -n 1 ./opensearch_ubuntu@24.04-amd64.charm --show-log --verbose
juju integrate self-signed-certificates opensearch

Alternatively, from kubernetes/ in a Kubernetes model, supply the workload image declared in metadata.yaml when deploying the locally packed charm:

juju deploy -n 1 ./opensearch-k8s_ubuntu@24.04-amd64.charm \
  --resource opensearch-image="$(awk '/upstream-source:/ {print $2}' metadata.yaml)" \
  --show-log --verbose
juju integrate self-signed-certificates opensearch-k8s

Note

The TLS settings shown here are for self-signed-certificates, which are not recommended for production clusters. The TLS Certificates Operator offers a variety of configurations. Read more on the self-signed-certificates Operator here.

Develop and test

Return to the repository root (cd .. after building a charm), then create a development environment and check your changes:

poetry install
tox run -e lint          # check code style
tox run -e format        # apply formatting fixes, if needed

For charm-logic changes, clone the opensearch-single-kernel-library and run tox run -e unit and tox run -e integration there, not in this repository. See Software testing for charms for details. This repository’s smoke-level integration tests run in CI.

The tutorial end-to-end test suite (requires Multipass and Spread) can be run from the repository root with:

tox -e tutorial-extract   # check tutorial commands without starting a VM
tox -e tutorial           # extract scripts + run the end-to-end tests in a VM

See tests/tutorial/ for the extraction scripts and the generated tasks.

Note

The code blocks in the documentation tutorial pages are extracted and run as part of the tutorial test suite. When editing docs/tutorial/*.md, make sure tox -e tutorial-extract still succeeds.

Review process

All enhancements require review before being merged. Code review typically examines code quality, test coverage, and the user experience for Juju administrators of this charm.

Please help us out in ensuring easy-to-review branches by rebasing your pull request branch onto the 2/edge branch. This also avoids merge commits and creates a linear Git commit history.

Familiarising yourself with the Ops framework will help you when working on new features or bug fixes.

Contribute documentation

The documentation lives in the docs/ folder of this repository and is built with Sphinx from MyST Markdown sources. It is published on canonical.com.

Prerequisites

Report a documentation issue

To report an issue with spelling, grammar, or technical content, file an issue on GitHub or use the Give feedback button at the top of the affected page.

Make a contribution

For a quick fix — a typo, a broken link, a small clarification — the easiest way is to click the pencil icon at the top of the documentation page (next to the Give feedback button). It takes you to the GitHub web editor for that page, where you can submit a pull request directly through the web interface.

For larger contributions:

  1. Create a branch (in the main repository or in a fork) from the current 2/edge and modify the documentation files as necessary.

  2. Raise a pull request against 2/edge to start the review process.

  3. Once the pull request is approved and all comments are addressed, it can be merged.

To preview and test the documentation locally:

cd docs
make run        # live-reload build served on http://127.0.0.1:8000

Before submitting, make sure the following checks pass:

cd docs
make html       # full build; fails on warnings
make linkcheck  # verify all external links
make lint-md    # Markdown linting
make spelling   # Vale spelling check
make woke       # inclusive-language check

Note

The documentation for OpenSearch Dashboards lives in the opensearch-dashboards-operator repository and is included here as a git submodule. Contribute Dashboards documentation changes upstream, in that repository.

The documentation follows the Diátaxis structure: tutorials, how-to guides, reference, and explanation each live in their own section and should not be mixed.

Code of conduct

This project follows the Ubuntu Code of Conduct. Maintainers reserve the right to remove any contributions that do not respect it.

Contributor agreement

Canonical welcomes contributions to Charmed OpenSearch. Please check out our contributor agreement if you’re interested in contributing to the solution.

We are hiring!

Also, if you truly enjoy working on open-source projects like this one, check out the career options we have at Canonical.