Skip to content

Predict and inspect a run

Impact Read only Writes config

The commands that show what a run would target, render and restart before it runs. Each row of the table gives one command, what it shows and its limits.

Note

Key answers

  • Predict a run: genconfig, then kolla_set_configs --check in each container; the meaning of exit codes 0, 1, 2 and 137 is in the same table CODE. --list-tasks is not useful (table below).
Goal Command Notes
List tags as Ansible sees them EXTRA_OPTS="--list-tags" kolla-ansible -i multinode deploy Works. Shows the inherited task tags (common appears nearly everywhere; list-tags-site.txt)
List hosts a run would target EXTRA_OPTS="--list-hosts" kolla-ansible -i multinode -t nova reconfigure Plays with &enable_<svc>_True patterns show 0 hosts: the groups are created at run time (Tags §2.6)
List tasks EXTRA_OPTS="--list-tasks" … Not useful: only include_tasks placeholders are shown (Tags §2.6)
Render configs without restarting kolla-ansible -i multinode genconfig [-t <svc>] [--limit <hosts>] Writes /etc/kolla/<svc>/ on the targets. All handlers are skipped. Also re-renders haproxy services.d for the tagged services
See what will restart on each host: docker exec -u root <container> /usr/local/bin/kolla_set_configs --check; echo $? 0 = every file listed in config.json's config_files matches its live copy (content, mode, owner). command, permissions, removed entries and stale optional files are not compared, so memcached ("config_files": []) always returns 0. 1 = a listed file differs or a non-optional one is missing from the container → restart on the next deploy/reconfigure/deploy-containers. 1 is also returned for a required source missing from /var/lib/kolla/config_files or an invalid config.json; the restarted container then fails kolla_set_configs at start. preserve_properties entries (e.g. prometheus extras already copied into the container) and, in practice, directory sources with subdirectories return 1 on every run (Tags §3). 137 is also treated as drift. 2 = an unexpected exception, such as a missing config.json or a newly rendered optional file not yet in the container (e.g. nova-compute release); the latter is real drift, and it gives 2 only if no entry listed before it differs (otherwise 1). On 2, or any code other than 0, 1 and 137, kolla_docker fails the check task instead of restarting CODE (kolla_docker.py:566-578,1071-1073, kolla docker/base/set_configs.py:60-65,135-136,160-211,217-253,280-296,407-410,427-432, kolla docker/base/start.sh:2,8). Details: Kolla images §3. Keep -u root: Kolla runs the check as root (kolla_docker.py:544-578), and containers that run as a service user cannot read the root-owned 0660 files in /var/lib/kolla/config_files
Check-mode run EXTRA_OPTS="--check --diff" kolla-ansible … reconfigure CODE kolla_docker does not declare check-mode support (kolla_docker.py:1031-1035), so Ansible skips it under --check (ansible 2.9.27 lib/ansible/module_utils/basic.py:1595-1596). Many tasks register outputs used later. NOT AVAILABLE Whether such a run fails or gives partial results; staging only
Pre-deployment checks kolla-ansible -i multinode prechecks [-t <svc>] Read-only (fact sheet E). -t <svc> skips the prechecks role (untagged) but runs <svc>/precheck.yml

To remember

Lumo: if you keep only 5 things from this page, keep these.

  • Predict a run with genconfig, then kolla_set_configs --check in each container; --list-tasks is not useful. CODE
  • genconfig writes /etc/kolla/<svc>/ on the targets and skips all handlers, but also re-renders haproxy services.d for the tagged services.
  • Exit 1 (or 137) means drift: a restart on the next deploy/reconfigure/deploy-containers; on 2 or any other code, kolla_docker fails the check task instead of restarting. CODE
  • Keep -u root on the check: containers that run as a service user cannot read the root-owned files in /var/lib/kolla/config_files.
  • Whether a --check --diff run fails or gives partial results is unknown: staging only. NOT AVAILABLE

What would you do?

Lumo: a situation you could meet on a real platform, and three ways to react. Pick the one you would choose: I will tell you what this page says about it. Nothing is recorded.

The check returns 2

You changed a glance option and ran kolla-ansible -i multinode -t glance genconfig. On a controller, you run docker exec glance_api /usr/local/bin/kolla_set_configs --check; echo $? (without -u root) and it prints 2. Your colleague concludes that the check is broken and proposes to go ahead with the production reconfigure.

What would you do?

See every choice explained
  • Avoid: Read 2 as "no drift" and run the reconfigure.. 0 is the code for "every listed file matches". 2 = an unexpected exception; on 2, kolla_docker fails the check task instead of restarting CODE.
  • Best choice: Re-run the same check with docker exec -u root, as Kolla does, and read the exit code then.. Keep -u root: Kolla runs the check as root, and containers that run as a service user cannot read the root-owned 0660 files in /var/lib/kolla/config_files. Then 0 = no drift, 1 (or 137) = drift, restart on the next run.
  • Works, but risky: Skip the check and preview the run with EXTRA_OPTS="--check --diff" on production instead.. kolla_docker does not declare check-mode support, so Ansible skips it under --check, and many tasks register outputs used later CODE. Whether such a run fails or gives partial results is not known NOT AVAILABLE: staging only.

Check yourself

Lumo: 2 quick questions to check the main ideas of this page. Choose an answer to see the explanation and the section that gives the evidence. Your score counts your first choices and stays in this browser only.

1. Is --list-tasks useful to predict a Kolla-Ansible run?
Show the answer

Answer: No: only include_tasks placeholders are shown. Row "List tasks" of the table: only include_tasks placeholders are shown.

2. How can you see, on a host, whether a container will be restarted?
Show the answer

Answer: Run kolla_set_configs --check inside the container, as root. After genconfig, docker exec -u root <container> /usr/local/bin/kolla_set_configs --check; the meaning of exit codes 0, 1, 2 and 137 is in the table CODE.