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 is no longer inherited by every role: 2023.1 roles have no meta dependencies and the common play is tagged common only (site.yml:86-97). The linked list-tags-site.txt is the Ussuri parse, where common appears nearly everywhere
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. Every container restart handler is skipped (when: kolla_action != "config"). Also re-renders haproxy services.d for the tagged services: the service includes of the loadbalancer play run for config and each service's loadbalancer.yml imports loadbalancer-config with tags: always (tools/kolla-ansible:540-542; site.yml:339-341; roles/nova/tasks/loadbalancer.yml:2-7; roles/loadbalancer-config/tasks/main.yml:2-4; roles/haproxy-config/tasks/main.yml:14). The loadbalancer handlers are skipped too (roles/loadbalancer/handlers/main.yml:17), so a later -t <svc> run finds that file unchanged and does not restart HAProxy: copy services.d before genconfig to diff it, and apply a frontend change with -t haproxy reconfigure or a run without tags
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 optional entries whose source is absent are not compared, so memcached ("config_files": []) always returns 0. 1 = a listed file differs or is missing from the container, optional files included (a newly rendered optional file such as nova-compute release is drift, exit 1; in Ussuri it gave 2) → 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 (no perm, so the mode check never matches) 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. On 2, or any code other than 0, 1 and 137, kolla_docker fails the check task instead of restarting CODE (module_utils/kolla_docker_worker.py:155-190, library/kolla_docker.py:399-412, kolla docker/base/set_configs.py:36-60, :64-72, :165-242, :245-298, :556-582, kolla docker/base/start.sh:3, :11). Details: Kolla images §3. Keep -u root: Kolla runs the check as root (module_utils/kolla_docker_worker.py:155-162), 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 (library/kolla_docker.py:345-349), so Ansible skips it under --check (ansible-core 2.14.18 lib/ansible/module_utils/basic.py:520-521). 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 play, site.yml:79-84) 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 every container restart handler, but also re-renders haproxy services.d for the tagged services, so a later -t <svc> run no longer restarts HAProxy for that change.
  • 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.