deploy, reconfigure, upgrade and the others¶
Context¶
Kolla-Ansible has one playbook, site.yml, and most commands run it with a different kolla_action. Knowing what
each action does on a running platform, and what --limit and --tags really narrow, is what makes the difference
between a change that restarts one service and one that restarts the whole control plane. This page sorts the
commands by what they change, and gives a safe sequence for a configuration change. It follows the Kolla-Ansible
2026.1 operating guide and the CLI and roles of that release.
Topology¶
Not specific to a topology. Everything below runs on the deploy host, from the virtual environment that holds the Kolla-Ansible version of the running platform.
Network design¶
Not affected.
Storage design¶
Not affected.
Inventory and configuration layout¶
The commands read the inventory (-i, several allowed), /etc/kolla/globals.yml, /etc/kolla/passwords.yml and the
overrides under /etc/kolla/config/ (see laying out the configuration).
Keep that directory in version control, and commit before each run, so that "what changed" has an answer.
What each command changes¶
From kolla_ansible/cli/commands.py and the operating guide, 2026.1:
| Command | kolla_action |
What it does to running containers | Risk |
|---|---|---|---|
prechecks |
precheck |
Nothing; checks ports, files, variables before a deploy | read-only |
genconfig |
config |
Writes the configuration files under /etc/ on the hosts; no container restarts, so not applied yet |
state-changing (files) |
validate-config |
config_validate |
Validates the generated configuration files; reports under /var/ |
read-only |
check |
check |
Checks container status | read-only |
pull |
pull |
Downloads images; no container changes | read-only for services |
deploy |
deploy |
Writes configuration, bootstraps what is new (databases, users, endpoints), creates missing containers, restarts containers whose configuration or definition changed | state-changing |
reconfigure |
reconfigure |
In most roles the same tasks as deploy (reconfigure.yml imports deploy.yml) |
state-changing |
deploy-containers |
deploy-containers |
Checks and updates containers without generating configuration | state-changing |
upgrade |
upgrade |
Runs each role's upgrade tasks: new images, database migrations, rolling restarts where the role supports them | state-changing; see the upgrade playbook |
post-deploy |
post-deploy |
Writes admin-openrc.sh on the deploy host |
state-changing (local file) |
stop |
stop |
Stops containers; needs --yes-i-really-really-mean-it |
state-changing, outage |
destroy |
destroy |
Removes containers and volumes; needs --yes-i-really-really-mean-it; --include-images and --include-dev remove more |
destructive |
deploy and reconfigure restart a container only when something changed. Kolla-Ansible compares each running
container with what it should be (image, volumes, environment) and runs kolla_set_configs --check inside it against
the newly generated files (compare_container in ansible/module_utils/kolla_docker_worker.py); only containers that
differ are restarted. So a reconfigure after a change in one service's override restarts that service only, even
without --tags. What --tags saves is time, and exposure to changes you did not mean to apply.
The run's changed count does not count restarts. On a 2026.1 all-in-one lab, a full reconfigure after a change
in Glance's override ended with changed=22 (bootstrap containers of 5 services,
Keystone user registration, Fernet key distribution …) and restarted glance_api only. The restarts show as
Notify handlers to restart containers for <service> among the changed tasks; docker inspect -f
'{{.Name}} {{.State.StartedAt}}' before and after the run confirms them.
Narrowing a run¶
--tags <service> selects plays and tasks by tag. In site.yml each service's play is tagged with its name
(nova, neutron, keystone, mariadb, loadbalancer …), and the HAProxy configuration of a service is tagged with
the service name too, so --tags nova also updates Nova's frontends in HAProxy. Fact gathering is tagged always and
always runs.
--limit <hosts> restricts the hosts. Kolla-Ansible still gathers facts for every host (the gather-facts play
delegates it to the limited hosts), so an unreachable host still fails the run. The operating guide warns: "using
the ansible --limit option is not recommended", because of known bugs with how register: interacts with it (bug
2054348; upgrading parts of Nova is the guide's example). Use it where the upstream documentation does (adding
compute nodes, removing hosts, batching bootstrap-servers), and test other uses on a lab.
-e kolla_serial=<n or %> runs each play in batches of hosts (a rolling run); the bootstrap servers guide uses it
with bootstrap-servers. Beware with reconfigure and upgrade: in the 2026.1 CLI these two commands add
-e kolla_serial=0 themselves, and they add it after the operator's own -e options (kolla_ansible/ansible.py
appends the command's variables last; Ansible keeps the last value). A -e kolla_serial=… given to reconfigure or
upgrade is therefore overridden and the run is not rolling. Seen on a lab: kolla-ansible reconfigure … -e
kolla_serial=1 ran ansible-playbook with -e kolla_serial=1 -e kolla_action=reconfigure -e kolla_serial=0, in
that order.
Never combine --limit with clustered services in a way that leaves the cluster without its other members in the
play when membership changes (MariaDB, RabbitMQ): the upstream guide asks to include all controllers (--limit
control) when controllers are added or removed.
A safe sequence for a configuration change¶
- Change
globals.ymlor the override, commit it. - Read-only:
kolla-ansible prechecks -i <inventory>(or with--tags <service>). -
Generate and look at the result without applying it:
⚠️ State-changing. Rewrites the configuration files under
/etc/kolla/<container-config-dir>/on the hosts. Running containers keep their current configuration until they restart; a container restarted for another reason (a host reboot, a crash) picks up the new files. Undo: revert the change and rungenconfigagain.kolla-ansible genconfig -i <inventory> --tags <service> kolla-ansible validate-config -i <inventory> --tags <service> # on a host, compare with what the container runs: sudo docker exec -u root <container> diff /etc/<service>/<file> /var/lib/kolla/config_files/<file>Inside the container,
/var/lib/kolla/config_files/is the bind mount of/etc/kolla/<container-config-dir>/on the host (named after the container, for example/etc/kolla/glance-api/or/etc/kolla/nova-compute/), wheregenconfigwrote the new files;/etc/<service>/holds the files the service runs with. That directory isdrwxrwx--- root root, anddocker execruns as the service user (glanceforglance_api), hence-u root; without itdifffails withPermission denied.validate-configexits 0 even when it finds errors: read the reports, which it writes on the deploy host (delegate_to: localhost), under/var/log/kolla/config-validate/<host>/<project>/<service-name>/*.err. On 2026.1 the Glance report holds twoERRORlines for options Kolla-Ansible itself sets (os_glance_tasks_store/filesystem_store_datadir is not part of the sample config, same foros_glance_staging_store); compare with a report taken before your change. -
Apply it:
⚠️ State-changing. Restarts the containers of that service whose configuration changed, on every host where it runs, all at once (see the
kolla_serialremark above). API calls to that service fail briefly; for agents of the data plane (Neutron agents,nova_compute,openvswitch), say what a restart interrupts before running it. If the change touches the service's HAProxy frontends (TLS, ports, external endpoints),--tags <service>also restarts thehaproxycontainers, backups first, then the host holding the VIP: every API behind the VIPs is briefly interrupted. Undo: revert the change and run the same command.kolla-ansible reconfigure -i <inventory> --tags <service> -
Verify: the run ends with
failed=0, the service's containers arehealthy(docker ps), and a real API call works.
Key choices and their consequences¶
| Choice | Alternative(s) | Why this one here | Consequence in operation |
|---|---|---|---|
reconfigure --tags <service> for one service |
A full reconfigure |
Shorter, and does not apply unrelated pending changes | Pending changes in other services stay unapplied until the next full run; know what is pending |
A full reconfigure from time to time |
Tags only | Proves the whole configuration still applies | Long; restarts whatever drifted |
genconfig + validate-config before applying |
Apply directly | See the files before any restart | One more step |
kolla_serial for rolling runs |
All hosts at once | Keeps some containers up while others restart | Works with deploy and bootstrap-servers; with reconfigure and upgrade the CLI overrides it (above) |
--limit only where upstream documents it |
--limit for everything |
Known bugs (bug 2054348) | Some changes need a full-inventory run |
What went wrong during deployment¶
Nothing observed for this page. The common traps it is written against:
- a
deployrun "to fix one thing" that also applied every pending change inglobals.yml; --limitexcluding the hosts a task delegates to or registers results on;- a newer Kolla-Ansible on the deploy host than the platform's release:
deploythen deploys the new images, which is an upgrade without the upgrade tasks.
Version notes¶
Written against Kolla-Ansible 2026.1 (cliff-based CLI, kolla_ansible/cli/commands.py). Command names and the
--yes-i-really-really-mean-it guard are those of that release. reconfigure.yml importing deploy.yml holds for the
roles read (Glance, MariaDB, Nova cell); check a role before relying on it for another service.
Lessons learned¶
- Read the run's
changedtasks before believing that "nothing restarted". - Keep the deploy host's Kolla-Ansible pinned to the platform's release.
- Prefer one service at a time with
--tags, and a fullreconfigurein a maintenance window.
Validity and limits¶
- Written from the Kolla-Ansible 2026.1 operating guide,
kolla_ansible/cli/commands.py,ansible/site.yml,ansible/gather-facts.yml, some roles'reconfigure.yml, andansible/module_utils/kolla_docker_worker.py. - Lab run, 2026-10-27, Kolla-Ansible 22.2.0 (2026.1) all-in-one, Docker, no HAProxy: the safe sequence ran end to end
on Glance (
debug = Truein/etc/kolla/config/glance.conf):prechecks --tags glance15 s,genconfig10 s (no container restarted),validate-config23 s, the in-containerdiff(with-u root) showed the change,reconfigure --tags glance76 s restartedglance_apionly (healthy 11 s later). The undo (override removed, fullreconfigurewithout--tags) took 647 s and restartedglance_apionly.-e kolla_serial=1overridden by the CLI'skolla_serial=0(command line observed).--limit localhostwith an unreachable host in the inventory failed inGather facts for all hosts (if using --limit)(UNREACHABLE, rc 4). - Not run on the lab:
deploy,deploy-containers,upgrade,pull,check,post-deploy,stop,destroy; a rolling run (kolla_serialwithdeploy);--limitacross real hosts and bug 2054348; the HAProxy restart by--tags <service>(HAProxy disabled on the lab); restarts on several hosts at once. Statusdraft. docker exec … diffassumes the image hasdiff; most Kolla images do, not checked for each.- Not covered: Podman specifics,
migrate-container-engine, Bifrost commands,nova-libvirt-cleanup,rabbitmq-reset-state.
Related¶
- Adding a compute node: a documented use of
--limit - From 2025.1 to 2026.1: the upgrade sequence
- Rotating the secrets in passwords.yml
- Kolla-Ansible 2026.1: operating Kolla, advanced configuration
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.