Ansible/scripts/docs/PLAYBOOKS.md

Playbooks and reporting contracts

Current AIM 3.3.0rc8. The catalog is authoritative for typed inputs, requirements and report declarations.

Run options omitted by a caller remain inherited from inventory/role defaults. Core requires explicit compatible hosts and final scope review; group shortcuts expand to deduplicated explicit hosts. aim_debug adds only selected diagnostics, not raw API output.

Normal terminal operations validate existing Vault passwords before launch and retain the workflow on a typo. New-encryption/create prompts stay native. Catalog connections use inventory/Vault credentials; automatic replay is never performed after launch.

Catalog audit

Key	Platforms	Report schema
checkmk_install_agent	linux, windows	checkmk_agent_state_v1
checkmk_update_scripts_config	linux, windows	checkmk_agent_config_v1
checkmk_read_windows_config	windows	checkmk_user_config_v1
checkmk_cleanup_scripts	linux, windows	managed_cleanup_preview_v1
debug_test_connection	linux, windows	None; native target outcomes/progress
debug_show_disk_usage	linux, windows	filesystem_usage_v1
debug_detect_host_roles	linux, windows	host_capabilities_v1
maintenance_export_event_logs	windows	event_log_export_v1
maintenance_start_stopped_services	windows	service_start_summary_v1
maintenance_patch_os	linux, windows	patch_summary_v1
maintenance_reboot_hosts	linux, windows	None; native target outcomes/progress
sophos_apply_baseline	sophosxgs	None; native target outcomes/progress
sophos_apply_customer	sophosxgs	None; native target outcomes/progress
pfsense_apply_baseline	pfsense	None; native target outcomes/progress

Customer Sophos profiles share the catalogued customer operation; their five concrete playbooks remain unchanged and publish no operation payload. Firewall policies, connection test and reboot behavior were not redesigned for reporting.

Schema and operational details

See OPERATION_RESULTS.md for field meanings and missing/partial/ check-mode behavior. Read CHECKMK.md for managed filename/section ownership. Role READMEs retain local default settings. list_playbooks exposes the current typed input definitions and resolved report schemas; add-ons need not keep copies of this table.

OS patch reporting

The catalog exposes os_patching_reboot, os_patching_reboot_delay_minutes, os_patching_reboot_message, Windows categories, and the Windows-only os_patching_rescan_after_reboot flag. The message/delay apply only when AIM initiates a reboot.

Windows delegates each current patch wave to one native ansible.windows.win_updates state: installed invocation with reboot: false. The module/WUA owns selection and sequencing inside that selected category wave; AIM does not loop individual updates or use accept_list to manufacture its own scheduler. Per-update records returned by the module are normalized for reporting.

If the completed wave requires reboot, AIM either defers it or performs the reviewed message/delay/reboot. By default (os_patching_rescan_after_reboot: false) that reboot ends the run, so another wave requires a new operator-approved execution. When explicitly enabled, AIM may start another native wave after reboot; continuation is defensively bounded to 12 wave invocations. A failed wave is never automatically replayed.

If a wave finishes without reboot, AIM performs one final read-only discovery for reporting only. Windows reports expose individual installed and failed updates, bounded HRESULT classifications, continuation_required, and whether the reported pending list is authoritative.

Linux snapshots use dpkg-query/RPM before and after the existing operation, retaining architecture and parallel installed version sets. Every net difference is published; intermediate no-net-change transactions are not observable from snapshots. No package stdout scraping or guessed versions. Check mode never claims installation.

Service recovery

Initial stopped/eligible/excluded states, actual attempts and post-start observations are all separate. failed_to_start gives fixed reasons and numeric codes where known. The default fail-on-error policy still fails the run after a report is published.

Security

Catalogs, roles and inventory are trusted controller code. Report schemas are reviewed public data contracts, not automatic secret scanners. Operator-owned Checkmk config can contain credentials; its reader filters known secret/command fields and publishes redacted paths. No general raw-file/data export was enabled.