Ansible/scripts/addons/webgui/docs/PATCH-WAVES.md

Patch-wave options and reports - WebGUI 2.1.0rc9 / Core 3.3.0rc8

This guide describes add-on presentation of the Core-provided patch contract. It does not grant approval to install updates, reboot targets or perform repeated runs.

Prepare and review

New run uses the public catalog for optional inputs. The Windows-only Continue patching after reboot control advertises the live catalog hint (false in this Core release). It starts as Inherit, not an explicit true override. Blank inputs stay omitted; inventory/role defaults are authoritative. To explicitly forbid continuation in a particular run, choose false and review the normalized override.

Reboot when required, Reboot delay (minutes) and Reboot message are separate catalog controls. Enabling reboot must not implicitly enable continuation. Delay and message apply only to an AIM-initiated reboot; the message is not part of the report. The review highlights explicit vs inherited reboot, delay and continuation values. Core still revalidates scope/options/schema revision before execution.

On Windows, each Core patch wave delegates the reviewed update categories to one native ansible.windows.win_updates install invocation with module reboot disabled. Windows Update and the collection own ordering inside that wave; AIM evaluates its reviewed reboot policy only after the native wave returns. With post-reboot continuation disabled, the run stops after an approved AIM reboot and another discovery requires a new reviewed run. Enabling continuation explicitly permits Core to rediscover and start another native wave after reboot within the same run, up to its 12-wave safety limit. There is no WebGUI follow-up scheduler or automatic replay. Linux keeps Core's native package-manager behavior and shared reboot-message/delay semantics; Windows cycle fields are not fabricated on Linux reports.

Reading a report

Field or condition	Meaning in the UI
Core succeeded + continuation_required true	Successful wave, but further patching needs review. The job is not relabeled failed.
remaining_updates_known false	Remaining updates are not established. Do not show an empty pending list as zero remaining updates or reuse a pre-reboot queue.
remaining_updates_known true	Pending is the final read-only discovery for the selected scope and recorded time, not current compliance or an expanded install queue.
No remaining_updates_known field	Historical shape. Missing wave fields stay unestablished; no inferred post-reboot queue.
reboot_deferred true	A reboot remains required with automatic reboot disabled. Installation success and reboot status remain separate.
reboot_reasons_before	Bounded native reboot sources reported by ansible.windows.win_reboot_info before patching. These are observations from that run, not a live probe.
blocked_reason preexisting_reboot_required	Core's independent preflight observed a prerequisite reboot; new patch work did not start on that path.
blocked_reason cycle_limit_reached	Core stopped bounded continuation; a new decision is needed, never an automatic replay.
failed_updates	Per-update title/ID, unsigned and hex HRESULT, fixed reason and safe message supplied by Core.
install_not_allowed / 0x80240016	May indicate an active installer or mandatory reboot; not proof of a pre-existing reboot by itself.
Check mode	Observations/predictions, never proof of installation or an actual reboot.

The normal report summary keeps the pre/post reboot observations, performed/deferred flags, reviewed delay, cycle count and continuation policy visible when supplied. Pending-list display suppression is a presentation decision when Core says the list is not authoritative. It does not modify stored data: the retained structured JSON still provides the exact approved report body for inspection.

Report-slot complete is availability, while payload data.complete describes update evidence. Neither independently proves the host is fully patched. Native target outcomes, Core result-validation failures and per-host reports remain separate.

Historical data and permissions

Old reports retain their reviewed schema. No migration rewrites old patch outcomes or adds missing fields. Only retained WebGUI jobs contribute to host history; no terminal run tracking, inventory writes, raw logs or new credential storage are introduced. Report reads remain owner-or-admin and job deletion removes linked evidence. The Checkmk configuration-content retention opt-in is unchanged.

Controller acceptance

Use Core's current SANITY.md under the actual executor context on a disposable, approved target. Confirm native win_updates wave behavior, the default stop after an AIM-performed reboot, explicit post-reboot continuation behavior, read-only final discovery, reboot-disabled/pre-existing-reboot cases and a bounded failure record. Compare actual effects and reported fields, not old task counts. Do not deliberately patch or reboot production systems merely to exercise a user-interface feature.