Skip to content

Find it fast

Typical operator questions and the section that answers them. The last column says how the answer is labelled there. To look something up by tag, by service or by term, use the tag index, the Components pages and the Glossary. The list of everything marked NOT AVAILABLE is What is not known.

Topic Question Go to Evidence there
Tags If I run -t nova reconfigure, what runs and what restarts? Reconfigure Nova §2 (sequence), Reconfigure Nova §3 (restarts per type of change), Reconfigure Nova §1.1 (command) CODE; whether every task reports unchanged on an unchanged cloud is NOT AVAILABLE
Tags What does a given tag execute, on which hosts, and which containers can restart? Tags §3 (master table) CODE; whether nothing restarts on an unchanged cloud is NOT AVAILABLE
Tags Does this tag touch the computes? Tags §3 ("Target hosts" column), Command quick lookup by tag (quick lookup) CODE
Tags Is this tag safe on its own? What does it do to VMs, APIs, networking and storage? Tags §3.1 (per-tag answers) CODE for what restarts; NOT AVAILABLE for what happens to VMs and traffic under nova, nova-cell, neutron, openvswitch, ovn and iscsi, for indirect effects of the other tags, and for the effect on other services of a HAProxy, Keystone, Placement, RabbitMQ or memcached restart
Restarts Why did containers restart although their config did not change (loop-notify)? Tags §2.4 CODE
Restarts Is a config change ever applied by a reload? What is the stop timeout? Repository architecture §4.3, Repository architecture §6, Risk register (R24) CODE
Restarts Can a service tag restart HAProxy, and how do I avoid it? Tags §2.2 (why), Reconfigure a single service §1.2 (--skip-tags haproxy), Risk register (R8) CODE; what keepalived does with the VIP meanwhile is NOT AVAILABLE
Compute impact Does nova-compute restart on every compute? Does libvirt restart with it? Reconfigure Nova §4, Nova deep dive §2.4 CODE
Compute impact Which inputs change nova.conf on every compute? Nova deep dive §2.3, Component dependencies §5 CODE
VM impact Do running VMs survive a nova_libvirt restart or recreate? Nova deep dive §5, Open questions (Q1) NOT AVAILABLE; what the container and its start path do is CODE
Data-plane impact Is VM network traffic interrupted when the OVS agent, openvswitch_vswitchd or the L3 agent restarts? Reconfigure Neutron §4, Risk register (R5, R6, R7), Open questions (Q2–Q4) NOT AVAILABLE; that the restarts happen is CODE
--limit What does --limit not limit? Reconfigure a single service §2 (row "Actions on hosts outside --limit"), Add a compute node §2, Findings (F8, F9) CODE
Batching How do I batch restarts: ANSIBLE_SERIAL or -e kolla_serial=N? Execution flow §5, Repository architecture §2, Write config first, apply in controlled batches §1.2 CODE
Batching What repeats per batch when serial is set? Tags §2.5 CODE
genconfig / deploy-containers How do I write the config without restarting, then apply it batch by batch? Write config first, apply in controlled batches §2, Write config first, apply in controlled batches §1.1 CODE
genconfig / deploy-containers What does each action do (deploy, reconfigure, upgrade, deploy-containers, genconfig, pull, stop, validate-config)? Execution flow §4 (action matrix) CODE
genconfig / deploy-containers Is reconfigure lighter than deploy? Repository architecture §4.2 CODE
kolla_set_configs --check How do I see what will restart before a run? Predict and inspect a run (row "See what will restart"), Pre-execution checklist (step 1) CODE
kolla_set_configs --check What does the check compare, what does it never compare, and what do its exit codes mean? Kolla images §3.1, Kolla images §3.2, Kolla images §3.3 CODE
Images and pull Why did deploy not pick up my rebuilt image? When are images pulled? Update container images §2, Update container images §1.1, Repository architecture §6 CODE
Images and pull What happens if I change the image tag and run deploy instead of upgrade? Update container images §4, Risk register (R12) CODE; whether Neutron's contract migrations then run under live old-version servers, and what the fleet-wide recreate (including openvswitch_vswitchd on every OVS host) does to running VMs and their traffic, are NOT AVAILABLE
One-shot containers Which bootstrap (one-shot) containers run on every deploy/reconfigure, and what do they run inside the image? Execution flow §6 (which ones still run on reconfigure), Kolla images §4 (what each one runs) CODE
Scaling What grows with the number of computes? How many operations at 100 or 500 computes? Compute scaling §2, Compute scaling §4.2 CODE for the remote-invocation, compare_container, image-pull and delegated fact-gathering counts; task-result totals, full-run invocation counts and timings are NOT AVAILABLE
Scaling Why is a --limit run slow on a large inventory? Compute scaling §6 (item 5), Risk register (R23) CODE; its duration is NOT AVAILABLE
Scaling How do I make runs cheaper at scale? Compute scaling §8 (ranked optimisations) recommendations; item 2 is labelled CODE
Adding a compute How do I add a compute node, and what else does the run touch? Add a compute node §1.1 (commands), Add a compute node §2 (what runs where) CODE
Membership What happens when a controller (a RabbitMQ or memcached member) is added or removed? Change control-plane membership §2, Change control-plane membership §1.1, Risk register (R3, R4) CODE for the restarts; the effect on flows and cached tokens is NOT AVAILABLE
common How do I push fluentd/cron (common) changes? Does -t common work, and does a service tag run common? Tags §2.1 (why -t common works in 2023.1 and a service tag no longer runs common), Apply common changes (fluentd, cron, kolla_toolbox) §3 (how common reaches hosts), Apply common changes (fluentd, cron, kolla_toolbox) §1.1 (command) CODE
Risks Which operations are dangerous, and what do I check before a run? Risk register (25 risks; R25 does not apply to 2023.1), Pre-execution checklist (pre-execution checklist) CODE for what Kolla does; NOT AVAILABLE for many VM and traffic outcomes
Not known What is not known? What is not known (everything marked NOT AVAILABLE, by topic), Open questions (open questions), Limits of the study (limits of the study), Kolla images §7 NOT AVAILABLE

Start from a situation

Seven operator situations and the pages to open first. Each row restates what the linked pages say; the linked pages are the reference.

Situation Open first What is there
I have an incident: where do I start? Troubleshooting, then its symptom index What an operator sees, what the study says the code does, and the section that establishes it. During an incident, the portal can tell what Kolla will do given the inputs: tasks and restarts. What that does to VMs and APIs depends on the environment and is mostly NOT AVAILABLE in these sources.
A problem with Nova, for example nova_compute restarted on every compute after a reconfigure Reconfigure Nova §4, Troubleshooting, "Containers restarted that should not have", Nova Whether all compute nodes are affected and whether nova-compute restarts on every compute; the symptom rows about restarts; the starting point for Nova, with where the study covers it.
Investigate RabbitMQ RabbitMQ, Troubleshooting, "Investigate a component" Where the study covers how to operate RabbitMQ, its impact, its dependencies and the evidence, what to check around a run and what stays open. The health gate that the Pre-execution checklist (step 5) names for RabbitMQ: cluster status, no partitions.
The impact of restarting or reconfiguring a service: what restarts? Reconfigure a single service §3, Tags §3, Troubleshooting, "Services, VMs and traffic during and after a restart" The sequence, impact, risks and verification of -t <svc> reconfigure; what a tag executes, on which hosts, and which containers can restart; what the code shows about a restart and what is open. Every statement about data-plane or VM impact is NOT AVAILABLE.
A maintenance operation and its prerequisites, for example replace a controller or update images Change control-plane membership §1.1, Update container images, Pre-execution checklist, Tags §3.1 What removing or replacing a controller restarts (R3, R4); how pull, deploy, reconfigure and upgrade treat images; the eight checks to make before every production run; per tag, whether it is safe on its own, and its prerequisites.
A failed VM deployment: an instance fails to boot or to be scheduled Troubleshooting, "Cases the study does not solve" The study does not diagnose a runtime failure of OpenStack: no container or VM behaviour is used as evidence. For this case it offers the dependencies and the restarts read from the code, and marks the rest as open.
Perform a Day-2 operation safely Pre-execution checklist, Predict and inspect a run, Write config first, apply in controlled batches §2 The eight checks to make before every production run; the commands that show what a run would target, render and restart; the recommended pattern, genconfig then deploy-containers --limit batch by batch, with its caveats CODE. What a run does to VMs and APIs depends on the environment and is mostly NOT AVAILABLE in these sources (Code guarantees and environment dependence).

Where the final-objective questions are answered

Question Short answer Details
If I execute a specific tag, exactly what happens? The tagged plays run on all their hosts. The haproxy frontend of that service, if it has one, is re-rendered. common does not run: in 2023.1 it is its own play, tagged common only. For API services, Keystone registration and DB-sync containers run (Neutron's included, on deploy and reconfigure). Handlers restart drifted containers, plus their role siblings Tags §3, Reconfigure a single service §2, Components
Which OpenStack components are affected? The tagged service, plus HAProxy (only if its frontend changed). fluentd/cron/kolla_toolbox only under -t common or a run without tags (if common drifted) Reconfigure a single service §2
Which compute nodes will receive changes? Every compute in the play's host patterns (common, nova, nova-cell, neutron, openvswitch, iscsi, …) runs the tasks. Restarts happen where drift exists, usually all or none, because inputs are global Compute scaling §2, Reconfigure Nova §4
Will containers restart or be recreated? Restart (systemd unit restart, stop timeout docker_graceful_timeout, 60 s) on config drift. Recreate on image or parameter change. Siblings in the same role restart too. On a run with nothing to apply, a restart needs a notifying task that reports changed, and check-containers reports changed only for a missing or not-running container, a differing compared parameter, a missing or differing systemd unit file, or a kolla_set_configs --check exit 1/137 or Docker client error CODE. Whether no notifying task reports changed on an unchanged cloud is NOT AVAILABLE, with one known exception CODE: containers whose config.json has an entry that kolla_set_configs --check always reports as drift (e.g. prometheus_server once files exist under /etc/kolla/config/prometheus/extras/: that preserve_properties entry has no perm) restart on every deploy/reconfigure Repository architecture §4.3, Tags §3, Tags §2.4, Kolla images §3
Can running VMs be impacted? The restarts that the study traces to running VMs include nova_libvirt (frequent, via loop-notify), OVS/vswitchd and the L3 agent CODE. Whether VMs survive a libvirt restart, and whether their traffic is interrupted, is NOT AVAILABLE Nova deep dive §5, Risk register R1/R6/R7, Findings Q1–Q4
What is the execution order? site.yml play order (no dependency resolver); within a role: register → config → check → bootstrap → flush Execution flow
Which tasks can take hours with hundreds of computes? Per-compute task chains multiplied by ⌈C/forks⌉ waves, serial fact gathering under --limit, image pulls (one per container placed on the compute, Component dependencies §5), per-batch waits under serial Compute scaling §3–4
Why does a small change generate a large workload? Global inputs are rendered into per-host files; loop-notify; every run re-executes the full per-host chain Compute scaling §5, Why a small change creates a large workload
How can I minimise the operational impact? genconfig + diff + deploy-containers --limit batches; narrow tags with --skip-tags haproxy; ANSIBLE_SERIAL; pre-pull; fact caching and pipelining; avoid global drift Pre-execution checklist, Operations, Compute scaling §8