Operations¶

What Kolla-Ansible 2024.1 commands do when they run against a live platform, read from the source of the unmodified
site.yml, its roles and ansible-core 2.16.20. Nothing was run against a host.
Real kolla-ansible (2024.1) invocations with what they select, their scope and their impact.
Note
Key answers
- A service tag also touches the HAProxy frontends of the service, Keystone registration, for most services DB
creation and schema sync (Neutron's DB sync on every
deployandreconfigure), and hosts outside--limit. Still holds in 2024.1: it does not touchcommon, because no role has ametadependency on it (Reconfigure a single service §2). A controller membership change is a fleet-wide restart event for every messaging consumer; new in 2024.1, the etcd role adds a new member itself (Change control-plane membership §2). What adding a compute withdeploy --limittouches: Add a compute node §2. - First 2024.1 run on a cloud deployed by 2023.1: expect restarts whose operator config did not change: the
systemd unit text changed (F16), RabbitMQ quorum queues are on by default
(F17), and
nova_computeandcinder_volumeget a newhostnqnfile. How to see them before the run: Predict and inspect a run §2; what to settle first: Pre-execution checklist §2. - Recommended pattern:
genconfig, thendeploy-containers --limitbatch by batch, with its caveats CODE (Write config first, apply in controlled batches §2). New in 2024.1: every play setsmax_fail_percentage, default 100, which never stops a play early; lower it to stop a rolling run on failures (§1.3). Why a small change can create a large workload: Why a small change creates a large workload. - Leave HAProxy alone:
--skip-tags haproxy(Reconfigure a single service §1.2). Pushcommonchanges:-t common, which runs the common play (site.yml:88-103); still in 2024.1,-t chronyselects nothing, as there is no chrony role (Applycommonchanges (fluentd, cron, kolla_toolbox) §1.1). New in 2024.1: the common play's config step can pull the fluentd image,genconfigincluded. - Add a compute:
bootstrap-servers,pullanddeploy, each with--limit(Add a compute node §1.1). Per-tag quick lookup of hosts touched, possible restarts and one-shot containers: Command quick lookup by tag.
Operations catalogue¶
One row per operation page, in the order of the navigation. The commands are copied from each page. The impact classes are defined in Operation impact classes. The risk numbers are those the page cites, in its text or in its "Related" list.
| Operation | Commands covered | Impact | Risks |
|---|---|---|---|
| Pre-execution checklist | kolla-ansible genconfigdocker exec -u root <c> /usr/kolla-ansible pullkolla-ansible mariadb_backupkolla-ansible prechecks (first 2024.1 run)and the openstack checks of its steps 5 and 6 |
writes-config |
– |
| Predict and inspect a run | EXTRA_OPTS="--list-tags" kolla-ansible -i multinode deployEXTRA_OPTS="--list-hosts" kolla-ansible -i multinode -t nova reconfigureEXTRA_OPTS="--list-tasks" …kolla-ansible -i multinode genconfig [-t <svc>] [--limit <hosts>]docker exec -u root <container> /usr/ (Podman: podman exec -u root …)EXTRA_OPTS="--check --diff" kolla-ansible … reconfigurekolla-ansible -i multinode prechecks [-t <svc>] |
read-only, writes-config |
– |
| Reconfigure a single service | kolla-ansible -i multinode -t keystone reconfigurekolla-ansible -i multinode -t nova --skip-tags haproxy reconfigure |
restarts-on-drift |
R8, R14, R19, R20, R23, R24 |
| Reconfigure Nova | kolla-ansible -i multinode -t nova reconfigurekolla-ansible -i multinode -t nova-api reconfigurekolla-ansible -i multinode -t nova-cell reconfigure |
restarts-on-drift |
R1, R2, R3, R24 |
| Reconfigure Neutron | kolla-ansible -i multinode -t neutron reconfigurekolla-ansible -i multinode -t neutron reconfigure --limit network01kolla-ansible -i multinode -t openvswitch reconfigure --limit compute042 |
restarts-on-drift, critical |
R5, R6, R7 |
Apply common changes (fluentd, cron, kolla_toolbox) |
kolla-ansible -i multinode -t common reconfigurekolla-ansible -i multinode -t common reconfigure --limit 'compute[0:49]' |
restarts-on-drift |
R2, R25 |
| Write config first, apply in controlled batches | kolla-ansible -i multinode -t nova-cell genconfigkolla-ansible -i multinode -t nova-cell deploy-containers --limit 'compute[0:9]'kolla-ansible -i multinode -t nova-cell deploy-containers --limit 'compute[10:19]'ANSIBLE_SERIAL=10 kolla-ansible -i multinode -t nova reconfigureANSIBLE_SERIAL=10 kolla-ansible -i multinode -t nova reconfigure -e kolla_max_fail_percentage=0 |
writes-config, restarts-on-drift |
R1 |
| Update container images | kolla-ansible -i multinode pullkolla-ansible -i multinode -t nova pull --limit computekolla-ansible -i multinode upgradeANSIBLE_SERIAL=20 kolla-ansible -i multinode -t nova upgradekolla-ansible -i multinode prune-images --yes-i-really-really-mean-it |
pulls-images, recreates-containers, critical |
R7, R11, R12, R13, R17 |
| Add a compute node | kolla-ansible -i multinode bootstrap-servers --limit compute501kolla-ansible -i multinode pull --limit compute501kolla-ansible -i multinode deploy --limit compute501 |
– | R14, R23 |
| Change control-plane membership | no command line in its command section; its scenario reads -t nova,neutron reconfigure |
restarts-on-drift, maintenance-window |
R3, R4 |
| Database operations | kolla-ansible -i multinode mariadb_backupkolla-ansible -i multinode mariadb_recovery |
recovery |
R15, R18 |
| Stop and destroy | kolla-ansible -i multinode stop --yes-i-really-really-mean-it -t heat --limit control03kolla-ansible -i multinode destroy --yes-i-really-really-mean-it |
critical |
R15, R16 |
| Command quick lookup by tag | -t <tag> reconfigure for 15 tags (new rows: letsencrypt, etcd)reconfigure (no tag)deploy-containers -t Xgenconfig -t Xpull -t X |
restarts-on-drift, writes-config, pulls-images |
by tag, in the "Risks" bullet of the component pages |
Assumed deployment¶
Every scenario assumes the same deployed state: 3 controllers, 2 network nodes, 3 computes, 1 storage node and 1
monitoring node, with Keystone, Glance, Placement, Nova, Neutron/OVS, Cinder/LVM, Heat and Horizon. The container engine
is Docker, the 2024.1 default (kolla_container_engine: "docker", group_vars/all.yml:92) CODE; where a page
describes the Podman path, it says so.
Conventions used by the command sections¶
These two lists apply to the command sections of every operation page and to the Command quick lookup by tag.
The examples assume:
- the inventory is
/etc/kolla/multinode(adapt-i); globals.ymlandpasswords.ymlare in/etc/kolla;- Ansible is ansible-core 2.16 (
tools/kolla-ansible:10-11accepts 2.15 to 2.16; only 2.16.20 was read).
Conventions:
- Scope = plays and hosts touched.
- Restarts = containers that can restart (only if drift is detected).
- One-shot = bootstrap containers that run regardless of drift.
Drift¶
Drift means what compare_container detects: a missing container, a changed image or container parameter (16
comparisons), kolla_set_configs --check reporting a change, or a systemd unit file whose text differs from the
rendered template (module_utils/kolla_container_worker.py:58-65, module_utils/kolla_container_worker.py:67-89)
CODE. The check reads kolla_set_configs --check per engine. With Docker, exit code 1 or 137, or a client error from
the exec, is drift (module_utils/kolla_docker_worker.py:146-181). With Podman, new in 2024.1, a container that is not
running is drift, 1 is drift, and any other non-zero code fails the task (module_utils/kolla_podman_worker.py:428-453)
(Kolla images §3). The
unit-file comparison is what makes the first 2024.1 check report drift for a container whose unit 2023.1 wrote
(F16).
Code guarantees and environment dependence¶
On the operation pages:
- The code guarantees = what Kolla will do (tasks, restarts) given the inputs.
- Depends on the environment = what that does to VMs and APIs; mostly NOT AVAILABLE in these sources.
These two notions head the columns of the tables in Reconfigure Nova §5 ("Guaranteed by code", "Depends on environment") and Reconfigure Neutron §4 ("code-guaranteed", "environment-dependent").
The evidence labels CODE and NOT AVAILABLE are defined once, in the Conventions and evidence labels.
Three mechanisms that explain almost every surprise¶
Three mechanisms explain almost every surprise on the operation pages, so they are restated here, each with the section that establishes it:
- Config drift ⇒ full container stop/start. It is never a reload. Still holds in 2024.1: the stop timeout is
docker_graceful_timeout, 60 s by default (group_vars/all.yml:139), passed to the module asgraceful_timeoutindocker_common_options(group_vars/all.yml:151). Each container runs under akolla-<name>-container.servicesystemd unit, and a restart goes through that unit (module_utils/kolla_docker_worker.py:439-459,module_utils/kolla_podman_worker.py:602-617,module_utils/kolla_systemd_worker.py:106-113). Changed in 2024.1: the unit names the engine,ExecStop=/usr/bin/${engine} stop ${name} -t ${graceful_timeout}(module_utils/kolla_systemd_worker.py:32) (Repository architecture §6). - Loop-notify. One changed container in a role's loop restarts every container of that role on that host (Tags §2.4).
- Global inputs.
enable_*flags, group membership and passwords are rendered into per-host files on every host (Component dependencies §5).
Related¶
- Tags §3 (what each tag executes)
- Risk register (risks R1–R30)
- Technical findings (the 2024.1 findings F16 and F17 behind the first 2024.1 run)
- Nova deep dive §5 (nova-libvirt restarts)
- Tag index and What is not known (tag index, everything marked NOT AVAILABLE)
- Repository architecture §2 (the CLI →
playbook mapping and the
kolla_serialpass-through rules) - Tags (tag semantics)
- Conventions and evidence labels (evidence labels)