Kolla Ansible deploys an OpenStack cloud as a set of containers

A separate deliverable from the Kolla project

The Kolla Ansible is a deliverable project separated from the Kolla project, and that separation is the first thing to understand about it.

Kolla Ansible deploys OpenStack services and infrastructure components in Docker containers. The Kolla mission statement is given in the README as: to provide production-ready containers and deployment tools for operating OpenStack clouds. So one project produces the container images and the other produces the tooling that runs them, and Kolla Ansible is the tooling side.

The description in the repository metadata adds a second point that matters for anyone cloning from GitHub: this is a mirror of code maintained at opendev.org, and the homepage points there. The canonical repository, the review system, the issue tracker and the documentation all live on opendev.org, and the GitHub copy is a read-only mirror for convenience.

That arrangement is the norm for OpenStack projects, and it has a practical consequence. If you want to file a bug or send a patch, the README routes you to Gerrit, with the standard OpenStack Gerrit workflow, and the communication channels are the #openstack-kolla IRC channel on OFTC, Launchpad for bugs, blueprints and release tracking, and weekly meetings. The repository also carries a zuul.d directory of project gate job definitions, which is where the continuous integration job list lives, and a specs directory described as the community's key arguments about architectural shifts in the code base, which is where a design disagreement is settled before code is written.

The service list is the scope of the deployment

What Kolla Ansible installs is spelled out in two lists, and reading them is the fastest way to understand what you are getting.

The OpenStack services list runs from Aodh through to Watcher, and it is long. Aodh, Barbican, Bifrost, Blazar, Ceilometer, Cinder, CloudKitty, Cyborg, Designate, Glance, Heat, Horizon, Ironic, Keystone, Magnum, Manila, Masakari, Mistral, Neutron, Nova, Octavia, Skyline with its API server and console, Tacker, Trove and Watcher.

The infrastructure list is the part that shows what the deployment assumes underneath. Collectd, Prometheus and Grafana for performance monitoring. OpenSearch and OpenSearch Dashboards to search, analyze and visualize log messages. Etcd as a distributed reliable key-value store. Fluentd as a data collector for a unified logging layer. Gnocchi as a time-series storage database. HAProxy and Keepalived for high availability of services and their endpoints. MariaDB and Galera Cluster for highly available MySQL databases. Memcached as a distributed memory object caching system. Open vSwitch for use with Neutron. RabbitMQ as a messaging backend for communication between services. And Valkey as an in-memory data structure store.

Two observations follow from those lists. First, this is not a minimal cloud. Neutron with Open vSwitch, a Galera Cluster, RabbitMQ and a load balancer pair is a production topology, and a team that only wants Keystone and Glance for a private cloud is not the audience.

Second, the infrastructure choices are opinionated and replaceable only by editing configuration. Choosing Valkey and MariaDB and RabbitMQ is a decision Kolla makes for you, and the README is explicit that the project is highly opinionated out of the box but allows for complete customization, which permits operators with little experience to deploy OpenStack quickly and as experience grows modify the configuration to suit the operator's exact requirements.

That sentence is the design brief for the whole project. The first deployment is meant to work, and the second deployment is meant to be yours.

The CLI is a set of verbs, not a wizard

Kolla Ansible is driven by a command line tool with a name that has changed, since the project was split out of Kolla, and the installed entry points are visible in the package metadata.

Five commands are installed as scripts. The main one is kolla-ansible, and the other four are password tools: kolla-genpwd, kolla-mergepwd, kolla-readpwd and kolla-writepwd. That is a design decision worth noting. Deploying a cloud means generating secrets for a large set of services, and the practical problem is not generating them but keeping them stable across a re-deploy while still not leaving them in a file that ends up in version control. The four separate commands, generate, merge, read and write, suggest a workflow where a password file is generated once, kept outside the tree, and merged into per-deployment inventories.

The main tool carries its own set of subcommands, and the entry points listed in the metadata show the vocabulary: bootstrap-servers, certificates, check, deploy, deploy-bifrost, deploy-containers, deploy-servers, destroy and gather-fact. Deploy is split into deploy-servers and deploy-containers, and there is a separate BifrostDeploy command, which points at the bare-metal install path where the first host is bootstrapped with Bifrost before the rest of the cluster comes up.

The presence of a check command and of destroy alongside deploy is a sign of a tool meant to be re-run. Deploying a cloud is not a one-shot event in practice, because a service image changes, a host is replaced, a certificate expires, and the tool is expected to converge the running system to the described state rather than to be run once on a clean machine.

The dependency list is short and every entry has a licence

The requirements file is worth reading on its own, because it tells you what the tool actually does rather than what the documentation says it does.

There are eleven entries, and the comments group them by purpose. Password hashing is bcrypt at 4.3.0 or later. Password generation is cryptography at 2.1 or later. Hashicorp Vault is accessed through hvac at 0.10.1 or later. Templating is Jinja2 at 3 or later. Ansible and its json_query support are ansible-core at 2.20 or later but below 2.22, with jmespath at 0.9.3 or later. Ini parsing is oslo.config at 5.2.0 or later, password generation also uses oslo.utils at 3.33.0 or later, and the CLI is cliff at 4.7.0 or later.

The requirements themselves are short enough to read in one go:

bcrypt>=4.3.0 # Apache-2.0
cryptography>=2.1 # BSD/Apache-2.0
hvac>=0.10.1 # Apache-2.0
Jinja2>=3 # BSD License (3 clause)
ansible-core>=2.20,<2.22 # GPLv3

The Vault entry is the interesting one. A tool that deploys a database, a message broker and a dozen services needs somewhere to keep their passwords, and hvac is the client library for doing that, so the deployment can draw secrets from Vault rather than from a file in the repository.

The version constraints are tight where it matters. ansible-core is pinned below 2.22, which is the sort of upper bound that exists because a major Ansible release changes behaviour in ways the playbooks do not yet handle. Pinning below a version and requiring at least another is standard practice in a tool that runs privileged changes on a fleet of machines, where a surprise in the orchestration layer is expensive.

The comments also carry licence identifiers, and they are the whole list of dependencies in one place: Apache-2.0, BSD, MIT and GPLv3, with GPLv3 attached to ansible-core. The project itself is Apache-2.0 per the package metadata, and the LICENSE file is at the root of the repository.

The repository is mostly playbooks, with tests and tools around them

The directory listing is dominated by ansible, and the rest of the tree is arranged around it.

The ansible directory holds the playbooks that deploy the services and the infrastructure components in Docker containers. The etc directory holds a reference etc structure which requires configuration of a small number of configuration variables to achieve a working All-in-One deployment, which is the key operational detail: a single-machine install is the baseline, and the production shapes are reached by editing that reference structure. The kolla_ansible directory holds the password generation script, the tools directory holds tools for interacting with Kolla Ansible, and the doc directory holds documentation, with a separate deploy-guide directory at the root as well.

Then there are the parts that say how the project is run rather than what it runs. The tests directory contains functional testing tools, and the requirements files split into requirements-core.yml, requirements.txt and requirements.yml, which is the usual OpenStack pattern of separating what runs the deployment from what the tests need. There are tox.ini, a setup.cfg and a pyproject.toml, and the build is pbr based, with setup.py reduced to a shim that calls setuptools with pbr enabled, which is how OpenStack packages get their version from git tags rather than from a hardcoded field. The pyproject requires Python 3.12 or newer and lists classifiers through 3.14, and the project entry point for the main CLI is kolla-ansible.

The contrib directory is where the interesting extras sit, with demo scenarios for Heat, Magnum and Tacker, and a development environment for Vagrant. The releasenotes directory contains the release notes of all features added, and the specs directory holds the architectural arguments. The zuul.d directory holds the project gate job definitions, and the top-level .ansible-lint configuration with its own rules directory suggests the playbooks are linted as strictly as the Python is.

What a first deployment actually involves

The README does not contain a command sequence, and that is a deliberate choice rather than an omission. It points at two documents instead: the Kolla Ansible documentation at docs.openstack.org, and the Developer Quickstart for getting started.

The reason is visible in the structure. A deployment needs an inventory of hosts, a set of passwords, a choice of deployment shape, and configuration for the services, and the shape of that depends on whether the cluster is a single all-in-one machine, a split control plane and compute, a highly available deployment with Galera and Keepalived, or a bifrost bootstrap. Any single command sequence in the README would be wrong for most readers.

What a reader can take from the repository itself is the shape of the work. Copy the reference configuration from the etc directory, fill in the small number of variables it names, generate the passwords with the password tooling rather than by hand, then drive the deployment with the CLI. The check command exists for validating a configuration before it is applied, certificates for the certificate handling the services need, bootstrap-servers and deploy-servers for the host preparation, and deploy-containers for the service containers themselves.

The second operational point is the destruction path. There is a destroy command, and an Ansible project that can tear down what it built is a different kind of tool from one that can only build. A team that has to test a configuration change, or that has to rebuild a failed node, will use the same verbs repeatedly, which is why the CLI is a set of verbs rather than a single guided flow.

Editorial conclusion

Kolla Ansible suits an operator or a platform team that wants a working OpenStack cloud from containers without assembling the service set, the database and the load balancer by hand, and who is prepared to read the configuration rather than treat it as a wizard. It is the wrong tool for a heterogeneous estate where different sites need different deployment shapes, because the deliverable is opinionated out of the box and the customisation path runs through the configuration, and it is the wrong tool if you need to run OpenStack without containers. Before you adopt it, read the Developer Quickstart, decide the deployment shape early since the etc directory and the sample inventory assume one, and check the AI policy the contributing guide links, because OpenStack projects are explicit about how generated code enters their trees.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. openstack/kolla-ansible on GitHub
4. Project website
5. README