Glossary¶
Lumo
You do not need to learn this page by heart. On every other page, the first time one of these terms appears it is underlined: hover it or tap it to see its meaning here, and where it is defined.
The terms the study uses, with the place where each is defined. Each meaning holds for Kolla-Ansible 2024.1-eom
and ansible-core 2.16.20; a term that only applied to an earlier release says so.
| Term | Meaning in this study | Defined in |
|---|---|---|
| loop-notify | When any item of a looped task changes, ansible-core 2.16.20 marks the whole task changed and notifies the handlers of every executed (non-skipped) item (lib/, lib/; a skipped item returns at task_executor.py:483). Kolla's config.yml and check-containers.yml loop over <role>_services with notify: "Restart {{ item.key }} container" (e.g. roles/), so a change that concerns one container restarts every container of that role on that host CODE. |
Tags §2.4; as a finding: Findings (F1) |
common_run |
Ussuri only. The per-host fact that guarded the common role, run through role dependencies in the first play in which a host appeared. In 2024.1 no file in ansible/ or tools/ mentions it: common is a play of its own with the common tag (site.yml:88-103), run once per run that executes that play CODE. |
Repository architecture §5.1 |
COPY_ALWAYS / COPY_ONCE (config_strategy) |
COPY_ALWAYS, the default (group_vars/): kolla_set_configs copies the config and applies permissions on every container start. COPY_ONCE: only on the first start of a container (kolla docker/), and the restart handler then always recreates the container, so only a recreate re-applies config (module_utils/, module_utils/) CODE. |
Kolla images §2.3, Kolla images §3.5; Repository architecture §7 (item 4) |
kolla_container (kolla_container_engine) |
New in 2024.1. The module that drives every container of the service roles; it replaces kolla_docker, which is gone, with the same 15 actions (library/). It uses a Docker worker when container_engine is docker and a Podman worker otherwise (library/); the roles pass kolla_container_engine, default docker (group_vars/) CODE. |
Repository architecture §6 |
| one-shot container | A container that Kolla-Ansible starts with kolla_container start_container, detach: False, restart_policy: oneshot and a variable that selects a branch of the image's start script (e.g. roles/); the branch ends in exit 0 before the service command (kolla docker/). It is started directly, not through systemd: with Docker it gets no unit file (module_utils/); with Podman a unit file is written at creation but not used to start it (module_utils/) CODE. In the command sections of the Operations pages, "One-shot" means bootstrap containers that run regardless of drift. |
Kolla images §4; the convention of the command sections is in Operations |
| drift | What compare_container detects: a missing container, a changed image or container parameter, a systemd unit file that would change, or kolla_set_configs --check reporting a difference (module_utils/). With Docker the check counts as a difference on exit 1, on an exec killed with 137, or on a failed docker exec (module_utils/); with Podman on exit 1, a failed exec, or a container that is not running, and any other exit code is an error (module_utils/) CODE. |
Operations, "Drift"; mechanism: Repository architecture §4.3 |
| restart vs recreate | The restart handler calls recreate_or_restart_container: recreate (stop → rm → create → start) when the image or parameters differ or under COPY_ONCE, otherwise restart, a systemd RestartUnit of the container's kolla-<name>-container.service (Docker module_utils/; Podman module_utils/; module_utils/). Both are full stop/start cycles; the unit's stop waits up to docker_graceful_timeout (60 s) (module_utils/, group_vars/) CODE. The same holds with Docker and with Podman. |
Repository architecture §4.3 |
flush_handlers |
meta: flush_handlers is where the notified restart handlers run: at the end of most deploy.yml (e.g. roles/), or else at the end of the play. The loadbalancer role (haproxy, keepalived, proxysql) deliberately defers to the end of its play (roles/) CODE. |
Execution flow §1 (row "Handler flush points"), Execution flow §3 (step 6) |
serial / batch (kolla_serial, ANSIBLE_SERIAL) |
serial splits a play into batches; each batch completes the whole play, handlers included, before the next starts (ansible-core 2.16.20 lib/). For reconfigure and upgrade the wrapper sets kolla_serial from ANSIBLE_SERIAL (tools/); for deploy, pass -e kolla_serial=N yourself (tools/). Changed in 2024.1: the etcd play has no serial key, so kolla_serial does not batch it (site.yml:470-481) CODE. |
Execution flow §5, Execution flow §1; Repository architecture §2 |
max_fail_percentage |
New in 2024.1. Set on almost every play from <service>_max_fail_percentage, then kolla_max_fail_percentage, then 100 (e.g. site.yml:95-99). ansible-core 2.16.20 compares the hosts failed in the current batch with the batch size (lib/, lib/), so with the default 100 it never stops a play early CODE. |
Execution flow §5 |
run_once / delegate_to |
run_once: the task runs once per play, or once per batch when kolla_serial > 0, since each batch is a separate run of the play and run_once only ends the host loop of that run (ansible-core 2.16.20 lib/, lib/) CODE. delegate_to: the step runs on another host; groups['<grp>'][0] is the target of almost every run_once/delegate_to bootstrap step, including for hosts outside --limit. |
Tags §2.5; Repository architecture §8; Reconfigure a single service §2 (row "Actions on hosts outside --limit") |
genconfig |
The CLI command for kolla_action=config (tools/): it writes the config, compares no container, and all container restarts are skipped. Changed in 2024.1: the common role's config step runs ensure_image on the fluentd image, which pulls it when it is absent (roles/) CODE. The Ussuri exception, the nova-hyperv handlers, does not exist: 2024.1 has no nova-hyperv role (Pre-execution checklist). |
Execution flow §4 (row genconfig); Repository architecture §2 |
deploy-containers |
Runs the role's deploy-containers.yml (tools/), which in 50 of the 53 roles that have one is only import_tasks: check-containers.yml (e.g. roles/), plus the handlers it notifies: no config is written, and no bootstrap, Keystone registration or loadbalancer configuration runs (the loadbalancer includes require deploy, reconfigure, upgrade or config, site.yml:324-326). The exceptions are mariadb, which also looks up the cluster (roles/), swift, which runs its start.yml (roles/), and ceph-rgw, whose file is empty CODE. |
Execution flow §4 (row deploy-containers); Write config first, apply in controlled batches §1.1 |
KOLLA_BOOTSTRAP / KOLLA_UPGRADE / KOLLA_OSM |
Variables, sent with an empty value (module_utils/), that select a one-shot branch of an image's start script; the branch tests only whether the variable is set (e.g. kolla docker/). What each one runs differs per image CODE. |
Kolla images §4 |
| CODE / NOT AVAILABLE | The two evidence labels: shown by the sources, with a path:line citation nearby; or not established by the sources. The fact sheets use FACT and NOT AVAILABLE for the same two levels. |
Conventions and evidence labels |
kolla_action |
The extra-var that the wrapper passes with a sub-command (-e kolla_action=<action>, e.g. tools/); every service role's tasks/main.yml is a dynamic include_tasks: "{{ kolla_action }}.yml" (e.g. roles/) CODE. |
Repository architecture §2, Repository architecture §4.1 |
compare_container |
The kolla_container action run by check-containers.yml (e.g. roles/): it compares the container's definition and its systemd unit file, and runs kolla_set_configs --check inside the running container (module_utils/) CODE. |
Repository architecture §4.3 |
kolla_set_configs --check |
The in-container check whose exit code decides config drift. It compares only the config_files entries of config.json (kolla docker/); the file is unchanged since 2023.1 CODE (F14). |
Kolla images §3; by hand: Predict and inspect a run |
config.json (config_files, command, permissions) |
The manifest, read from /var/, that tells kolla_set_configs which files to copy to their final location, and names the command to start, written to /run_command (kolla docker/) CODE. |
Repository architecture §7 (item 4); Kolla images §2.3 |
| global inputs | enable_* flags, group membership and passwords, which are rendered into per-host files on every host. Examples: the RPC transport URL lists every host of the RPC group with its password (group_vars/), and the cron logrotate list follows the global enable_* flags (roles/) CODE. |
Component dependencies §5; Why a small change creates a large workload |
| waves, forks | A task on H hosts needs ⌈H/F⌉ waves, where F is the number of forks. This is a counting model: ansible-core 2.16.20 starts at most min(forks, batch size) workers and queues a host's task only on a free worker (lib/, lib/) CODE. |
Compute scaling §1, Compute scaling §4.1 |
| scope legend D, Ctl, C, C×S, H, Cond | How often a task runs: once per deployment, per controller, per compute, per compute and container, per host, or only when a condition holds. | Compute scaling §3 |
| Rn, Fn, Qn | Risk numbers R1–R30, finding numbers F1–F17 and open-question numbers Q1–Q21. Each risk, finding and question is a section with its own anchor, so links to them land on the item. | Risk register; Findings; Open questions |
Related¶
- Conventions and evidence labels — the two evidence labels and the operation impact classes
- Find it fast — typical operator questions and the section that answers them
- Tag index — from a tag to its component page
- Components — one page per component, with its service card
- What is not known — everything marked NOT AVAILABLE, by topic
Lumo: ready for the next step? Take your time: you can come back to this page whenever you need it.
Lumo: nicely done! One more page on your journey.