Skip to content

Conventions and evidence labels

This page defines the two evidence labels used on every page and the impact classes shown on operation pages. It also says how the pages are built.

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:line citation nearby: kolla-ansible 2023.1-eol (unprefixed paths, relative to ansible/, plus tools/...), the kolla image repository 2023.1-eol when the path has a kolla prefix (e.g. kolla docker/base/set_configs.py:556-559), ansible-collection-kolla 2023.1-eol when the path has an ansible-collection-kolla prefix (e.g. ansible-collection-kolla roles/baremetal/tasks/main.yml:2-3), the Ansible source when the path has an ansible-core 2.14.18 prefix, and the --list-tags and --list-tasks listings in Ansible listings (Ansible'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.

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: the row "Pre-deployment checks" of Predict and inspect a run says "Read-only", and fact sheet E §5 found no module that modifies state in the precheck files. The study titled the section that became that page "Inspection (no changes)". 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 Docker container. genconfig: row genconfig of Execution flow §4 (config written, all container restarts skipped) and step 1 of the Pre-execution checklist, which lists the handlers without the kolla_action != "config" guard and why none of them restarts a container. The Ussuri exception, the nova-hyperv role, does not exist in 2023.1.
pulls-images The command downloads images; running containers do not change. pull never changes running containers CODE (Update container images §1.1); row pull of Execution flow §4; 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.
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.
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: 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 R25; R25 does not apply to 2023.1) and link to the Risk register. Risks and verification steps, when a page has them, are in its last numbered sections.
  • 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 25 risks, with their likelihood and severity (R25 does not apply to 2023.1)

To remember

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

  • The 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 sources, with a path:line citation 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.
  • pull downloads images and never changes running containers. CODE

Check yourself

Lumo: 3 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. What does the evidence label CODE mean?
Show the answer

Answer: It is shown by the sources, with a path:line citation nearby. CODE means shown by the sources, with a path:line citation nearby. The study rests only on reading source code; nothing was run against a host, and no run is used as evidence. Read the section.

2. What does the evidence label NOT AVAILABLE mean?
Show the answer

Answer: The sources do not establish it. NOT AVAILABLE means the sources do not establish it. Read the section.

3. An operation page carries an impact class. What does that class say?
Show the answer

Answer: That at least one command of the page has that impact. A page can carry several classes: a class says that at least one command of the page has that impact, not that all do. Read the section.