# OpenStack-Helm: deploying OpenStack itself on Kubernetes

> openstack-helm is a collection of Helm charts that deploy OpenStack and the services around it onto Kubernetes, maintained on opendev and mirrored to GitHub. Its distinctive piece of engineering is the release notes system, where a commit trailer becomes a changelog entry in the packaged chart.

**openstack/openstack-helm** — Helm charts for deploying OpenStack on Kubernetes. Mirror of code maintained at opendev.org.

- Repository: https://github.com/openstack/openstack-helm
- Website: https://opendev.org/openstack/openstack-helm
- Stars: 578 · Forks: 264
- Language: Shell
- License: Apache-2.0
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/openstack-openstack-helm

## The charts deploy OpenStack, and much more than OpenStack

The goal of OpenStack-Helm is to provide a collection of Helm charts that simply, resiliently, and flexibly deploy OpenStack and related services on Kubernetes.

The scope in the repository is much wider than the OpenStack services themselves, and that is the first thing to notice when you look at the directory listing. Alongside the core services, there are aodh, barbican, blazar, cinder, cloudkitty, cyborg, designate, freezer, glance, gnocchi, heat, horizon, ironic, keystone, magnum, manila, masakari, mistral and nova side by side, there are the supporting pieces a real deployment needs. There is an etcd/ chart, a mariadb/ chart with mariadb-cluster and mariadb-backup variants, a memcached/ chart, an ldap/ chart, a grafana/ chart, a kibana/ chart, an elasticsearch/ chart, and a whole family of Elastic components with elastic-apm-server, elastic-filebeat, elastic-metricbeat, elastic-packetbeat, fluentbit and fluentd. There is a helm-toolkit/ directory, which is the shared chart library the others depend on, and directories for ca-issuer, ca-clusterissuer, cert-rotation, kube-dns and kubernetes-keystone-webhook.

That last group is the interesting one for anyone who has run OpenStack before. The certificate authority issuer charts, the cert-rotation chart and the keystone webhook are not OpenStack services, they are the pieces that make OpenStack work correctly in a Kubernetes cluster where TLS and admission control are managed by the platform.

The project is Apache-2.0 licensed, the primary language recorded for the repository is Shell, and the homepage is the opendev.org project page.

## The version matrix is narrow, and that is the point

The versions supported section is a table of the OpenStack, platform and Kubernetes version combinations that are tested and proved to work. That phrase, proved to work, is the standard the project is holding itself to.

There are three rows. OpenStack 2025.2, named Flamingo, on Ubuntu Noble for both host and image OS, with Kubernetes greater than or equal to 1.33 and less than or equal to 1.35. OpenStack 2026.1, named Gazpacho, on Ubuntu Noble for both, with the same Kubernetes range. And OpenStack 2026.2, named Hibiscus, on Ubuntu Resolute for both host and image OS, again with Kubernetes between 1.33 and 1.35.

The narrowness is the point rather than a limitation to apologise for. A Helm chart that deploys OpenStack is glue across two large moving systems, and pinning the matrix is how the project keeps that glue honest. The same Kubernetes range across all three rows also tells you the charts are not chasing the newest Kubernetes release.

One detail worth noting is that the host OS and the image OS are the same in every row, Ubuntu Noble twice and Ubuntu Resolute once. A deployment where the nodes run one distribution and the containers run another is outside what is listed as proved to work.

The Makefile carries a related default. BASE_VERSION is set to 2026.1.0, so a plain build produces the Gazpacho line, and the version can be overridden at build time.

## This GitHub repository is a mirror, and the work happens on opendev

The repository description says it plainly: Helm charts for deploying OpenStack on Kubernetes, mirror of code maintained at opendev.org. The homepage points at the opendev project, and the README lists the repositories that hold the actual work.

There are four. The OpenStack charts live in openstack-helm at opendev.org, and the OpenStack-Helm plugin is openstack-helm-plugin. Building the non-OpenStack images is openstack-helm-images, and building the OpenStack images is loci, which is the image builder that most OpenStack container work has used for years.

The code review link in the README points at review.opendev.org and its query covers three projects at once, openstack-helm plus openstack-helm-images plus loci, and it filters out abandoned changes. That single link is the clearest indication of how the project is organised: the charts, the images they pull and the builder that produces those images are reviewed together, because a chart change that expects a new image is only correct if all three move.

The communication channels follow the OpenStack convention rather than the GitHub one. There is an IRC channel #openstack-helm on oftc, a Slack channel with the same name which the README says is the preferable way of communication, and the Openstack-discuss mailing list with an openstack-helm subject prefix. The list of core team members is a link into the review system's admin interface rather than a file in the repository.

The repository is not archived and the last push was on 2026-10-20.

## Bugs go to Storyboard, not to GitHub

The Storyboard section is a small thing that tells you a lot about how this project works.

If you find an issue and want to make sure the team is aware of it, the README says you can do so on Storyboard. Bugs should be filed as stories in Storyboard, not GitHub.

The reasoning given for the reporting quality is practical: please be as much specific as possible while describing an issue, since usually having more context in the bug description means less effort for a developer to reproduce the bug and understand how to fix it.

There is also a triage note that is worth knowing before you file. Before filing a bug, try to identify if the issue is indeed related to the deployment process and not to the deployable software. A chart that fails to start because the application inside it has a bug is an upstream bug, and filing it here sends it to the wrong people.

For a mirror repository, this is coherent. The GitHub copy is a read-only view of work reviewed on opendev, so a tracker there would be a second, unmonitored place for issues to go missing. Storyboard is the OpenStack-wide tracker and the project group for this one is identified in the link.

The README also states that the project is under active development, and invites contributions in any form: code review, code changes, usage feedback, updating documentation. That last category is unusual to see listed, and for a project with a wide chart surface it is probably the most useful contribution most people can make.

## Release notes are git trailers, not files

The release notes system is the most distinctive engineering decision in the repository, and it is worth understanding even if you never contribute a chart.

Release notes are written as git trailers in the commit that makes the change. If you update a chart, you add a Changelog: trailer to the last paragraph of the commit message, next to the Change-Id. The example in the README is:

```text
    neutron: fix the health probe for the OVN agent

    <body>

    Changelog: fixed
    Change-Id: I7d940919531125e2806b18fcb6cfe245d6b31450
```

The kind is one of added, changed, deprecated, removed, fixed and security, or skip when the change needs no release note. Without a description the commit subject is used.

Where the note lands is controlled by the commit itself. By default the note goes to the charts whose directories the commit touches, and a Charts: trailer overrides that, with examples such as Charts: barbican, keystone or Charts: all when a change affects every chart.

Then the build collects the notes. When building tarballs, the release notes belonging to the version being built are written into the artifacthub.io/changes annotation of the chart's Chart.yaml, which Artifact Hub renders as the chart's changelog. There is a validator for the commit message, run with python3 tools/check_commit_message.py before pushing.

The Makefile shows the two flags that control this. SKIP_ANNOTATIONS defaults to 0, and the comment explains that the annotation is written only for as long as it takes to package the chart, after which the file is restored. FULL_ANNOTATIONS defaults to 0 as well, and the reason is historical: a normal build carries only the release notes of the version it builds, but at a series bump the earlier versions were published without annotations, so that history had no version left to ride on and the charts are rebuilt once carrying all of it.

## Helm docs and packaging are driven from the Makefile

The Makefile at the repository root is where the packaging happens, and it is worth reading because it explains how the chart set is assembled.

It sets SHELL to /bin/bash explicitly, with a comment saying it is necessary to set this because some environments do not link sh to bash. It then defines the tool names it drives: HELM is helm, PYTHON is python3, and TASK is build, with HELM_DOCS pointing at tools/helm-docs. It also captures the host operating system and architecture from uname, which is what a packaging step needs to name its artefacts.

The chart list is derived from the filesystem rather than hard coded. CHART_DIRS is built from the directories that contain a Chart.yaml, and CHARTS is the sorted list of those directories together with helm-toolkit, which is always built first because the others depend on it.

The build then takes optional arguments. If VERSION is defined it is passed as a --version argument, and if PACKAGE_DIR is defined it is passed as a --destination, so a release build can stamp a version and put the artefacts somewhere specific without editing the file.

The rest of the repository follows the OpenStack conventions closely. There is a .gitreview file, which is the Gerrit configuration that makes the review.opendev.org workflow work, a .pre-commit-config.yaml for local checks, a CONTRIBUTING.rst, and a doc/ directory. The release note mechanics are documented in full in doc/source/devref/release-notes.rst, including how the legacy releasenotes/notes files are still picked up, which matters for anyone reading an old chart's changelog and wondering where it came from.

## Conclusion

Adopt openstack-helm if you want to run OpenStack on a Kubernetes cluster and accept that the supported version matrix is narrow, since the tested combinations cover three OpenStack releases against Kubernetes 1.33 to 1.35 on specific Ubuntu releases. Do not adopt it expecting a supported product with a predictable upgrade path, because it is a mirror of work done on opendev and the project says it is under active development. Before you deploy, pick a row in the version table and stay inside it, and note that bugs are filed in Storyboard rather than on GitHub, which is where you will also find the code review workflow.

## FAQ

### What is OpenStack-Helm?

It is a collection of Helm charts that deploy OpenStack and related services on Kubernetes, licensed under Apache 2.0. The repository is a mirror of code maintained at opendev.org, where the charts, the openstack-helm-images repository and the loci image builder are reviewed together.

### Which OpenStack and Kubernetes versions does OpenStack-Helm support?

The tested combinations are OpenStack 2025.2 (Flamingo) and 2026.1 (Gazpacho) on Ubuntu Noble, and 2026.2 (Hibiscus) on Ubuntu Resolute, all with Kubernetes from 1.33 to 1.35, for both host and image OS.

### How do I report a bug in OpenStack-Helm?

Bugs are filed as stories in Storyboard rather than on GitHub, and the README asks you to be as specific as possible and to check first whether the issue is in the deployment process rather than in the deployable software itself.

### How are release notes written in OpenStack-Helm?

They are git trailers in the commit that makes the change, with a Changelog: trailer next to the Change-Id. The kind is one of added, changed, deprecated, removed, fixed and security, or skip. During packaging the notes are written into the artifacthub.io/changes annotation of the chart's Chart.yaml, and a Charts: trailer overrides which charts a note lands on.

## Sources

- [Issues](https://github.com/openstack/openstack-helm/issues)
- [License: Apache-2.0](https://github.com/openstack/openstack-helm/blob/master/LICENSE)
- [openstack/openstack-helm on GitHub](https://github.com/openstack/openstack-helm)
- [Project website](https://opendev.org/openstack/openstack-helm)
- [README](https://github.com/openstack/openstack-helm/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/openstack-openstack-helm