Kolla-Ansible deploys OpenStack services as Docker containers, making installation and upgrades far simpler than traditional package-based methods. Each OpenStack component – Nova, Neutron, Keystone, Glance, Horizon – runs in its own container, isolated and easy to manage. This guide walks through installing OpenStack using Kolla-Ansible on Debian 12 (Bookworm) for an all-in-one single-node deployment.
We are deploying Kolla-Ansible 21.0.0, which ships OpenStack 2025.2 (Flamingo) – the latest coordinated OpenStack release. Debian 12 Bookworm is the supported Debian version for this release. The entire deployment runs on Docker 29.3.0 with Python 3.11 and Ansible-core 2.19.x under the hood.
Prerequisites
Before starting, make sure your environment meets these requirements:
- Debian 12 (Bookworm) server with root access
- Minimum 16 GB RAM (32 GB recommended for running workloads)
- At least 4 CPU cores
- 80 GB free disk space minimum
- 2 network interfaces – one for management traffic (
ens3), one for Neutron external/provider network (ens4). Using the same interface for both will lock you out of SSH when Neutron/OVS takes over the interface - A static IP on the management interface
The two-NIC requirement is critical. In an all-in-one deployment, Neutron’s Open vSwitch agent takes full control of the external interface to create the provider bridge. If that interface is also your management/SSH interface, you lose connectivity immediately. For lab testing with a single NIC, you can create a VLAN sub-interface or a dummy interface for the external network – but a second physical or virtual NIC is the clean approach.
Step 1: Update System and Install Dependencies
Start by updating Debian 12 and installing the packages Kolla-Ansible needs to build Python dependencies and manage the deployment.
sudo apt update && sudo apt upgrade -yInstall the required development libraries and tools:
sudo apt install -y python3-full python3-venv python3-dev gcc libffi-dev libssl-dev gitKolla-Ansible requires the en_US.UTF-8 locale. On Debian 12, this is disabled by default. Enable and generate it:
sudo sed -i 's/# en_US.UTF-8 UTF-8/en_US.UTF-8 UTF-8/' /etc/locale.gen && sudo locale-genConfirm the locale is now available:
locale -a | grep en_USYou should see en_US.utf8 in the output, confirming the locale was generated successfully.
Step 2: Install Docker on Debian 12
Kolla-Ansible deploys all OpenStack services as Docker containers, so Docker must be installed from the official Docker repository. Do not use the docker.io package from Debian repos – it is too old.
Add Docker’s GPG key and repository:
sudo apt install -y ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpgAdd the Docker repository to your APT sources:
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/nullInstall Docker Engine:
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-pluginEnable and start Docker, then verify it is running:
sudo systemctl enable --now docker
sudo docker versionThe output should show Docker version 29.x, confirming the installation from the official repository.
Step 3: Create Python Virtual Environment and Install Kolla-Ansible
Kolla-Ansible and its dependencies should be installed in an isolated Python virtual environment. The --system-site-packages flag is required because Kolla-Ansible needs access to the system dbus Python module for managing systemd services during bootstrap.
python3 -m venv --system-site-packages ~/kolla-venv
source ~/kolla-venv/bin/activateUpgrade pip, then install Ansible-core, the Docker Python SDK, and Kolla-Ansible:
pip install -U pip
pip install ansible-core docker kolla-ansibleThis installs Kolla-Ansible 21.0.0 with all required Python dependencies. Verify the installed version:
kolla-ansible --versionYou should see version 21.0.0 reported, corresponding to the OpenStack 2025.2 Flamingo release.
Install the Ansible Galaxy dependencies that Kolla-Ansible requires:
kolla-ansible install-depsThis downloads the required Ansible collections and roles used during deployment.
Step 4: Configure Kolla-Ansible for OpenStack Deployment
Kolla-Ansible uses configuration files in /etc/kolla/ and an Ansible inventory file. Create the directory and copy the default configuration templates:
sudo mkdir -p /etc/kolla
sudo chown $USER:$USER /etc/kolla
cp -r ~/kolla-venv/share/kolla-ansible/etc_examples/kolla/* /etc/kolla/Copy the all-in-one inventory file to your home directory for easy access:
cp ~/kolla-venv/share/kolla-ansible/ansible/inventory/all-in-one ~/all-in-oneGenerate Passwords
Kolla-Ansible needs unique passwords for all OpenStack services. Generate them automatically:
kolla-genpwdThis populates /etc/kolla/passwords.yml with randomly generated passwords for every service – Keystone, MariaDB, RabbitMQ, Horizon, and others. You can view the Keystone admin password later to log into the Horizon dashboard.
Edit globals.yml
The main configuration file is /etc/kolla/globals.yml. Open it for editing:
vi /etc/kolla/globals.ymlFind and set the following values. You can uncomment existing lines or add them. Replace interface names and IP addresses to match your environment:
# Base container OS - must be debian for Debian 12 host
kolla_base_distro: "debian"
# Management network interface - used for API endpoints and inter-service communication
network_interface: "ens3"
# External network interface - Neutron/OVS takes this over for provider networks
# MUST be a different interface from network_interface to avoid SSH lockout
neutron_external_interface: "ens4"
# Internal VIP address - use an unused IP on your management network
# For all-in-one without HA, this points to the single node
kolla_internal_vip_address: "192.168.1.100"
# Disable HAProxy for single-node deployment
enable_haproxy: "no"
# Disable Cinder (block storage) - not needed for basic deployment
enable_cinder: "no"
# Disable Heat (orchestration) - not needed for basic deployment
enable_heat: "no"
# Disable ProxySQL - required for single-node deployments
# Without this, MariaDB connections fail through the proxy
enable_proxysql: "no"
# Use QEMU virtualization type for VMs on virtual machines or hosts without nested virt
# Change to "kvm" on bare metal with hardware virtualization support
nova_compute_virt_type: "qemu"A few key points on this configuration:
kolla_base_distro: "debian"tells Kolla to pull Debian-based container images for all servicesnetwork_interfaceandneutron_external_interfacemust be different interfaces. The external interface gets attached to the OVS bridge and loses its IP configurationkolla_internal_vip_addressshould be an IP on the management network subnet that is not already in use. For a single-node setup, this becomes the address for API endpointsenable_proxysql: "no"is required on single-node deployments – without this, MariaDB fails to accept connections- Set
nova_compute_virt_typeto"kvm"if your host has hardware virtualization (bare metal). Use"qemu"for nested virtualization or virtual machines
Step 5: Bootstrap Servers
The bootstrap step prepares the host system for OpenStack deployment. It installs required system packages, configures Docker daemon settings, and sets up the environment. Make sure your virtual environment is active before running Kolla-Ansible commands:
source ~/kolla-venv/bin/activate
kolla-ansible bootstrap-servers -i ~/all-in-oneThis takes a few minutes. When it completes, you should see a PLAY RECAP with zero failures:
PLAY RECAP *********************************************************************
localhost : ok=45 changed=14 unreachable=0 failed=0 skipped=38 rescued=0 ignored=0If the bootstrap fails with a dbus module error, confirm you created the venv with --system-site-packages. The dbus Python module is a system package that cannot be installed via pip.
Step 6: Run Pre-deployment Checks
Before deploying, run the prechecks to validate that the host configuration, Docker setup, and network settings are correct:
kolla-ansible prechecks -i ~/all-in-oneA successful precheck run produces a clean PLAY RECAP with no failures:
PLAY RECAP *********************************************************************
localhost : ok=90 changed=0 failed=0 skipped=62 rescued=0 ignored=0Common precheck failures include: port 3306 already in use by a local MariaDB instance (remove it or stop the service), missing Docker, or incorrect interface names in globals.yml. Fix any reported issues before moving to deployment.
Step 7: Deploy OpenStack on Debian 12
With prechecks passing, run the full deployment. This pulls Docker images for every OpenStack service, creates containers, and configures them according to your globals.yml settings:
kolla-ansible deploy -i ~/all-in-oneThis is the longest step – expect 15 to 30 minutes depending on your internet speed and hardware. Kolla-Ansible pulls container images for Keystone, Nova, Neutron, Glance, Horizon, MariaDB, RabbitMQ, Memcached, and supporting services, then starts and configures each one.
When the deployment completes successfully, the PLAY RECAP shows zero failures. If the deploy fails partway through, fix the issue and run the deploy command again – Kolla-Ansible is idempotent and picks up where it left off.
Step 8: Post-deployment and Access OpenStack Dashboard
Run the post-deploy step to generate admin credentials and finalize the setup:
kolla-ansible post-deploy -i ~/all-in-oneThis creates the /etc/kolla/admin-openrc.sh file containing OpenStack admin credentials. Source it to authenticate with the OpenStack CLI:
source /etc/kolla/admin-openrc.shInstall the OpenStack CLI client to interact with your cloud from the command line:
pip install python-openstackclientVerify the deployment by listing the running OpenStack services:
openstack service listYou should see services like keystone, nova, neutron, glance, and placement listed with their endpoints.
Verify that all containers are running:
sudo docker ps --format "table {{.Names}}\t{{.Status}}" | head -20You should see dozens of containers with status “Up” – one for each OpenStack service component.
Access Horizon Dashboard
Open a browser and navigate to the VIP address you configured:
http://192.168.1.100Log in with username admin. To retrieve the admin password:
grep keystone_admin_password /etc/kolla/passwords.ymlThe value after keystone_admin_password: is your Horizon login password. Once logged in, you can manage projects, networks, compute flavors, and cloud images in Glance through the web interface.
Troubleshooting Kolla-Ansible Deployment
Here are solutions to common issues encountered during Kolla-Ansible deployment on Debian 12.
MariaDB Port 3306 Already in Use
If prechecks or deploy fail with a port 3306 conflict, a local MariaDB or MySQL server is running. Kolla deploys its own containerized MariaDB and needs that port free:
sudo systemctl stop mariadb
sudo systemctl disable mariadbOr remove it entirely if not needed:
sudo apt purge mariadb-server -yLocale Error During Bootstrap
If bootstrap fails with locale-related errors, the en_US.UTF-8 locale is not generated. Run the locale fix from Step 1:
sudo sed -i 's/# en_US.UTF-8 UTF-8/en_US.UTF-8 UTF-8/' /etc/locale.gen && sudo locale-genThen re-run the bootstrap step.
dbus Module Not Found
The error ModuleNotFoundError: No module named 'dbus' during bootstrap means the virtual environment does not have access to system Python packages. The fix is to recreate the venv with the correct flag:
deactivate
rm -rf ~/kolla-venv
python3 -m venv --system-site-packages ~/kolla-venv
source ~/kolla-venv/bin/activate
pip install -U pip ansible-core docker kolla-ansible
kolla-ansible install-depsProxySQL Connection Failures on Single Node
If services fail to connect to MariaDB after deployment, ProxySQL may be interfering. On single-node deployments, ProxySQL is unnecessary and can cause connection routing issues. Confirm enable_proxysql: "no" is set in /etc/kolla/globals.yml, then redeploy:
kolla-ansible deploy -i ~/all-in-oneSSH Lockout After Deployment
If you lose SSH access after the Neutron deployment phase, you likely used the same interface for both network_interface and neutron_external_interface. Neutron’s OVS agent takes over the external interface and removes its IP configuration. You need console access (IPMI, VM console, or physical KVM) to fix the configuration. Set neutron_external_interface to a different interface, then redeploy.
Destroying and Starting Over
If the deployment is broken beyond repair and you want to start fresh, Kolla-Ansible has a destroy command that removes all containers, volumes, and configuration:
kolla-ansible destroy -i ~/all-in-one --yes-i-really-really-mean-itThis removes everything deployed by Kolla. You can then re-run from the bootstrap step. If you have also deployed OpenStack on Rocky Linux, the destroy and redeploy process works the same way.
Conclusion
You now have a working OpenStack cloud on Debian 12 deployed through Kolla-Ansible 21.0.0. The containerized approach makes future upgrades straightforward – pull new images and run kolla-ansible upgrade instead of wrestling with package conflicts across dozens of services.
For production use, add a second controller node for high availability, enable TLS on all API endpoints, configure Cinder for persistent block storage, and set up regular database backups. Monitor container health with docker ps and OpenStack service status through the Horizon dashboard or CLI.
