Docker versus Podman as the container engine of a Kolla-Ansible deployment¶
What is compared¶
Kolla-Ansible 2026.1 supports two container engines, chosen with one variable in globals.yml:
kolla_container_engine: "docker" # the default; or "podman"
The images, the roles and the commands of kolla-ansible are the same. What changes is on the hosts: which daemon
or tool runs the containers, where their volumes live, which commands an operator types, and what a restart of the
engine does to the platform. This page compares the two from an operator's side, and says what the supported
migration between them costs. It does not recommend one.
What is the same¶
- Images and configuration. The same Kolla images, the same
/etc/kolla/<container>/configuration files, the samekolla_logsvolume behind/var/log/kollaon the host. - The
kolla-ansiblecommands.deploy,reconfigure,upgrade,check,stopwork with either engine. - Restarts managed by systemd, with both engines. In 2026.1, Kolla-Ansible writes one systemd unit per container,
kolla-<container>-container.serviceunder/etc/systemd/system/, and lets systemd restart the containers (ansible/module_utils/kolla_systemd_worker.py). With Docker the units depend ondocker.service; with Podman onnetwork-online.target.
What is different¶
| Aspect | Docker | Podman |
|---|---|---|
| Engine process | A daemon, dockerd, that all containers depend on |
No central daemon; each container is started by Podman under its systemd unit |
| Restarting the engine | systemctl restart docker restarts every container of the host (they stop with the daemon and come back through their systemd units), unless Docker's live-restore is used (the bootstrap servers guide warns about it) |
No daemon to restart; upgrading the Podman package does not by itself restart running containers |
| Volume path on the host | /var/ (docker_volumes_path) |
/var/ (podman_volumes_path) |
| Commands in runbooks | docker ps, docker logs, docker exec |
podman ps, podman logs, podman exec (the troubleshooting guide says to use podman instead of docker where applicable) |
| Registry configuration | Docker's daemon configuration (daemon.json: insecure-registries, mirrors), written by bootstrap-servers |
Podman's own registries configuration; how bootstrap-servers handles it lives in the openstack.kolla collection and was not checked here |
| Libvirt guests at host shutdown | tools/ |
tools/ |
| Prechecks | Checking Docker version against docker_version_min, and the Docker SDK for Python |
Those two checks do not apply |
Most pages of this repository, and most of the upstream examples, use Docker commands and paths. With Podman, an operator translates them: same subcommands, the other volume path.
Migrating from one to the other¶
The advanced configuration guide describes a supported migration, in both directions. In outline: the operator
changes kolla_container_engine in globals.yml and nothing else, stops every virtual machine of the cloud (the guide
says rolling migration is not supported and the migration can fail otherwise), and runs the guide's
migrate-container-engine command. Its playbook prepares the hosts (container-engine-migration role), redeploys
everything with the new engine (site.yml with kolla_action: deploy), then runs post-deploy.
The guide warns that the container volumes are migrated to the new engine, and that the old engine's packages are
removed from the system with all their resources and data. So: a full outage of every instance, and a backup of
the databases and of /etc/kolla first (see
backing up and restoring MariaDB). This page gives no
commands for it on purpose: follow the guide of your release, on a lab first.
What an operator gains and loses¶
| Docker | Podman |
|---|---|
| The default: most examples and runbooks use it | Fewer examples; every Docker command in a runbook needs translating |
| One daemon to watch; one restart that can restart every container | No daemon whose restart takes every container down; more units to look at |
daemon.json handled by bootstrap-servers |
Registry settings in Podman's own configuration |
| Moving away later is a full outage (migration) | Same in the other direction |
Validity and limits¶
- Written from Kolla-Ansible 2026.1:
doc/source/admin/advanced-configuration.rst(Migrate container engine),doc/source/user/troubleshooting.rst,ansible/group_vars/all/common.yml(kolla_container_engine, volume paths),ansible/module_utils/kolla_systemd_worker.py,ansible/migrate-container-engine.yml,ansible/roles/prechecks/tasks/{service_checks,package_checks}.yml, and the libvirt guests unit files undertools/. Not run on a lab for this page. Statusdraft. - What a Podman package upgrade does to running containers depends on the distribution's packaging; it was not tested here.
- The host preparation (
bootstrap-servers, thebaremetalrole) is in theopenstack.kollacollection, installed byinstall-deps. Its Docker side was read for the bootstrap-servers page (stable/2026.1); its Podman side (the collection'spodmanrole) was read neither there nor here, so whatbootstrap-serversinstalls and configures on a Podman host is not described on either page. - Not covered: rootless Podman (Kolla-Ansible runs the containers as root), Podman's own auto-update, and Podman's registries configuration.
Related¶
- pull fails with "http: server gave HTTP response to HTTPS client": the Docker side of registry configuration
- deploy, reconfigure, upgrade and the others
- Kolla-Ansible 2026.1: advanced configuration, troubleshooting
- Podman: commands
Provenance: written by agent:ozarland-author, from the Kolla-Ansible 2026.1 documentation and code. Reviewed in its pull request (see the page history). Checked by a human operator: not yet.
Worked for you, or not? Tell us in one line: your release, your topology, and what happened.