Adding a charm to the OpenStack ecosystem

Overview

After the initial implementation of a new charm, the charm needs to be added to the following systems in order to be fully part of our release process:

  • Gitea, the git server hosting the OpenStack projects.

  • Gerrit, the code review platform for contributing to the OpenStack projects.

  • Upstream Zuul, OpenDev’s CI system for the OpenStack projects, publishing test results to Gerrit reviews.

  • OSCI, Canonical’s CI system for the OpenStack charms, also publishing test results to Gerrit reviews.

  • Launchpad, the bug tracker and continuous delivery pipeline (publishing to CharmHub) for the OpenStack charms.

  • GitHub, where the OpenStack charms’ source code is mirrored.

  • CharmHub, where the charms are published.

  • Our release tools and documentation.

This document will guide you through the necessary steps. If in doubt, contact us.

Initial implementation

Put the initial implementation of your new charm in a temporary repository on GitHub. This repository will be used when doing the initial import to Gitea. Example: https://github.com/openstack-charmers/charm-nova-compute-nvidia-vgpu

Initial import to Gitea, Gerrit and upstream Zuul

Follow closely the OpenDev Project Creator’s Guide. In a nutshell this will ask you to:

Once the import has been performed, retire your original temporary repository. Example: https://github.com/openstack-charmers/charm-interface-magpie/pull/2

Note that it is possible to import a project with a default git branch named main instead of master. Example: https://review.opendev.org/c/openstack/project-config/+/827719/4/gerrit/projects.yaml

Gerrit and upstream Zuul boilerplate

Add a .gitreview file and a .zuul.yaml file to your project. Example: https://review.opendev.org/c/openstack/charm-neutron-api-plugin-arista/+/738573/

Mirroring to GitHub

This is not documented in the OpenDev Project Creator’s Guide but will be at some point. Create a project-config review in order to enable the mirroring from Gitea to GitHub. Example: https://review.opendev.org/c/openstack/project-config/+/739009

Once this gets merged, a daily job will create the mirror repository at https://github.com/openstack/charm-<my-new-thing>. Then next time a Gerrit review gets merged, the initial mirroring will be performed. This process is still somewhat brittle. If this doesn’t work, ask on the #opendev IRC channel of OFTC.

Launchpad bug tracker

Add your project to Launchpad with the following details:

  • Part of: openstack-charms

  • License: Apache

  • Maintainer: openstack-charmers

Example: https://launchpad.net/charm-nova-compute-nvidia-vgpu

Configure the bug tracker at https://bugs.launchpad.net/charm-<my-new-thing>/+configure-bugtracker with the following details:

  • Expire “Incomplete” bug reports when they become inactive

  • Search for possible duplicate bugs when a new bug is filed

  • Bug supervisor: openstack-charmers

OSCI

Add your project to OSCI’s list of known projects. Example: https://github.com/openstack-charmers/zosci-config/pull/29

Once landed, ask us to run the reload-config action on our zuul-scheduler charm.

Add an osci.yaml file to your project. Example: https://opendev.org/openstack/charm-aodh/src/branch/master/osci.yaml

If your functional tests require special environment variables in order to run, add them to OSCI. Example: https://github.com/openstack-charmers/zosci-config/pull/133

Juju Charm Layers Index

If your new charm is based on the Reactive framework, make sure the interfaces it requires are listed in the Juju Charm Layers Index. Otherwise create a pull request. Example: https://github.com/juju/layer-index/pull/110

Release Tools

The release-tools repository contains lists of all OpenStack charms:

Charmhub and Launchpad builders

Register your charm’s name on Charmhub. For example if your repository is named charm-<my-new-thing> do:

sudo snap install charmcraft --classic
charmcraft login
charmcraft register <my-new-thing>

Make sure your charm has a charmcraft.yaml file so it can be built by the Launchpad builders. They are responsible for building every commit of your project and publishing the resulting charm to Charmhub. Example: https://review.opendev.org/c/openstack/charm-openstack-loadbalancer/+/828162/4/charmcraft.yaml

Add your charm to the lp-builder-config. Example: https://github.com/openstack-charmers/release-tools/pull/187

Once landed, ask us to run the charmhub-lp-tools in order to create the corresponding Launchpad builder recipes:

charmhub-lp-tool sync --i-really-mean-it

Visit https://launchpad.net/charm-<my-new-thing> and for each recipe, click Authorize Charmhub uploads.

Once the master recipe has succeeded, your charm will be visible at https://charmhub.io/<my-new-thing>.

Create a Charmhub request to make OpenStack Charmers collaborator on your charm.

Documentation

Every charm must have a README file. Construct one by using the Charm README template.

Add your charm to the project’s list of charms and include a release note for the appropriate OpenStack Charms release. Example: https://review.opendev.org/c/openstack/charm-guide/+/821962

Add your charm to the upgrade documentation. Example: https://review.opendev.org/c/openstack/charm-deployment-guide/+/828183