Conventions and evidence labels¶
This page defines the two evidence labels used on every page of the 2024.1 study and the impact classes shown on operation pages. It also says how the pages are built.
Note
Key answers
- Two labels only: CODE, shown by the 2024.1 sources with a
path:linecitation nearby, and NOT AVAILABLE, not established by them (Evidence labels). - An impact class is a "can": it says that at least one command of the page has that impact (Operation impact classes).
- Changed in 2024.1 for
writes-config:genconfigstill restarts no container, but it can pull the fluentd image when the image is absent CODE (Operation impact classes).
Evidence labels¶
The same two labels are used everywhere, and this is their single definition. The study rests only on reading source code; nothing was run against a host, and no run is used as evidence.
- CODE shown by the sources, with a
path:linecitation nearby: kolla-ansible2024.1-eom(commit890396f; unprefixed paths, relative toansible/, plustools/...), the kolla image repository2024.1-eomwhen the path has akollaprefix (e.g. kolladocker/base/set_configs.py:556-559), ansible-collection-kolla2024.1-eomwhen the path has anansible-collection-kollaprefix (e.g. ansible-collection-kollaroles/baremetal/tasks/main.yml:2-3), the Ansible source when the path has anansible-core 2.16.20prefix or starts withlib/ansible/, and the--list-tagsand--list-taskslistings in Ansible listings (ansible-core 2.16.20's own parse of the playbooks). - NOT AVAILABLE the sources do not establish it.
The fact sheets use the words FACT and NOT AVAILABLE for the same two levels.
Kolla-Ansible 2024.1 accepts ansible-core 2.15 to 2.16 (tools/kolla-ansible:10-11); only 2.16.20 was read, so a
statement about ansible-core holds for 2.16.20, and what 2.15 does is NOT AVAILABLE.
Operation impact classes¶
An operation page lists its impact classes in its front matter, and the site shows them under the page title. A page can carry several classes: a class says that at least one command of the page has that impact, not that all do. A class is used only where the corpus supports it:
| Class | Meaning | Support in the corpus |
|---|---|---|
read-only |
The corpus says the command changes nothing. | prechecks (tools/, kolla_action=precheck): the row "Pre-deployment checks" of Predict and inspect a run and fact sheet E §5. The task files it reaches (roles/, every roles/, roles/, roles/) use only wait_for, assert, fail, stat, getent, group_by, set_fact, kolla_container_facts, kolla_container_volume_facts and command/shell calls that read state, such as {{ kolla_container_engine }} --version with changed_when: false (roles/) or the new RabbitMQ queue listing (roles/) CODE. On the same page, genconfig writes config (next class), and whether a check-mode run fails or gives partial results is NOT AVAILABLE. |
writes-config |
The command renders config and restarts no container. | genconfig (kolla_action=config, tools/): row genconfig of Execution flow §4 (config written, all container restarts skipped) and step 1 of the Pre-execution checklist. Every handler that starts, restarts or recreates a container with kolla_container carries when: kolla_action != "config", except keystone's two database-upgrade handlers, guarded by kolla_action == "upgrade" (roles/), MariaDB's first-node start, notified only from roles/, and etcd's upgrade restart, an include_tasks handler guarded by kolla_action == "upgrade" (roles/) CODE. The Ussuri exception, the nova-hyperv role, does not exist in 2024.1 (no such directory under ansible/roles/). Changed in 2024.1: the command is not limited to files any more. The common role's config step runs kolla_container ensure_image on the fluentd image whenever enable_fluentd is on (roles/), and that pulls the image when it is not on the host (module_utils/) CODE. No running container changes. |
pulls-images |
The command downloads images; running containers do not change. | pull never changes running containers CODE: every role's pull.yml except swift's and ceph-rgw's imports service-images-pull, whose only task runs kolla_container pull_image for each enabled container mapped to the host and notifies no handler (roles/); swift's pull.yml runs pull_image directly, one task per image (roles/), and ceph-rgw's is empty. See Update container images §1.1, row pull of Execution flow §4 and R11. |
restarts-on-drift |
The command can restart containers, only if drift is detected. | The "Restarts" convention of the command sections and the definition of drift; the "Containers that can restart" column of Tags §3. The drift test is compare_container, the same for the Docker and the Podman worker (module_utils/, module_utils/) CODE. |
recreates-containers |
The command recreates containers (stop, rm, create, start) when their image or parameters differ. | The entry "restart vs recreate" of the Glossary; Update container images §2; R12. The recreate branch is module_utils/ (Docker) and module_utils/ (Podman) CODE. |
critical |
The page covers an operation rated Critical in the risk register. | The Severity column of the Risk register: R7, R12, R14, R15 and R16. |
maintenance-window |
The corpus asks to plan the operation as a maintenance. | The Precautions of R3 ("Plan as a maintenance") and of R10 ("Maintenance window"). |
recovery |
The page is a backup or recovery procedure. | mariadb_backup and mariadb_recovery, two commands of the wrapper that run their own playbooks (tools/; ansible/, ansible/) CODE: Database operations, fact sheet E §9 and the rows "backup" and "recovery" of fact sheet B §1.3. |
How pages are built¶
- Every page: a title, an introduction of one to three sentences, a "Key answers" note when the study has one for the page, the body, and a closing "Related" list.
- Callouts are the five GitHub alerts: note, tip, important, warning and caution.
- Operation pages: the commands come first, in section 1 or directly under the introduction, and follow the
conventions of the command sections. The impact
classes are shown under the title. Risks are cited by number (R1 to R30) and link to the Risk
register. R25 ("
-t commonbelieved to reconfigure fluentd/cron") does not apply to 2024.1:commonis a play of its own, taggedcommon(site.yml:88-103), so-t commonruns it CODE. Risks and verification steps, when a page has them, are in its last numbered sections.
Related¶
- Method and limits of the study — how the sources were read, and the limits of a source-only study
- What is not known — everything marked NOT AVAILABLE, by topic
- Glossary — the terms the study uses, with the place where each is defined
- Operations — the operation pages, each with its impact classes and risks
- Risk register — the 30 risks, with their likelihood and severity (R25 does not apply to 2024.1)
To remember
Lumo: if you keep only 5 things from this page, keep these.
- The 2024.1 study rests only on reading source code; nothing was run against a host, and no run is used as evidence.
- CODE means shown by the 2024.1 sources, with a
path:linecitation nearby. - NOT AVAILABLE means the sources do not establish it.
- An impact class says that at least one command of the page has that impact, not that all do.
pulldownloads images and never changes running containers;genconfigrestarts no container but can pull the fluentd image when it is absent. CODE
Check yourself
Lumo: 4 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.
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.