Adding a charm to the OpenStack ecosystem


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.

  • Charmed OpenStack Info, where the information about Charmed OpenStack is declared.

  • 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:

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:

Note that it is possible to import a project with a default git branch named main instead of master. Example:

Gerrit and upstream Zuul boilerplate

Add a .gitreview file and a .zuul.yaml file to your project. Example:

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:

Once this gets merged, a daily job will create the mirror repository at<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


Configure the bug tracker at<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


Add your project to OSCI’s list of known projects. Example:

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

Add an osci.yaml file to your project. Example:

If your functional tests require special environment variables in order to run, add them to OSCI. Example:

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:

Charmed OpenStack Info

The charmed-openstack-info repository contains the definitions for the OpenStack, Ceph, OVN and supporting charms. Add an entry for the new charm in the appropriate file under the charmed_openstack_info/data/lp-builder-config/ directory. Example:

The format of the lp-builder-config files is defined in the CharmProject class.

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:

Add your charm to the lp-builder-config. Example:

Once merged, a CI job gets executed which takes care of sync’ing the changes into Launchpad. Example:

Visit<my-new-thing> and for each recipe, click Authorize Charmhub uploads.

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

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


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:

Add your charm to the upgrade documentation. Example:

Often the introduction of a new charm coincides with a newly supported feature. In this case, supporting documentation should be submitted in the form of a management how-to (or as an addition to an existing how-to). If the deployment of the new feature is non-trivial then a overlay bundle that summarises the deployment should be included in the how-to (see sub-section Feature overlay bundles).

Feature overlay bundles

An overlay bundle for a feature should include placeholder variables that are intended to be replaced with values that are in accordance with the user’s local environment and/or the intended cloud design. Consider the following overlay excerpt:

series: $SERIES


    charm: ch:ceph-fs
    channel: $CHANNEL_CEPH
    num_units: 2
      source: $OPENSTACK_ORIGIN

     charm: ch:ganesha
     channel: $CHANNEL_OPENSTACK
     vip: $VIP

The overlay may optionally include a variables section that makes use of YAML substitution. For example:


  data-port: &data-port br-ex:$OVN_DATA_PORT
  osd-devices: &osd-devices $OSD_DEVICES
  network-space: &network-space $SPACE

Wherever the string, for example, *network-space appears in the overlay it will be replaced by the value given by $SPACE.

The feature should be deployable during (or after) the deployment of a cloud - as per the Juju documentation: How to add an overlay bundle.