---
id: MOD-004
type: module
status: active
title: OS Updates Role
created: 2026-09-09
updated: 2026-09-09
tags: [module, os-updates, ansible]
related: [MOD-005, NFR-003, NFR-006, REQ-004]
source_paths:
- roles/os-updates/
confidence: confirmed
---

# OS Updates Role

## Responsibility

Upgrade Debian packages with optional mirror rewrite, kernel-based reboot
handling, and controller-side update logging.

## Source Paths

- `roles/os-updates/tasks/main.yml` → `update_mirrors.yml` (optional),
  `upgrade_packages.yml` → `logging_preflight.yml`, `reboot.yml`,
  `logging_postflight.yml`
- Templates: `sources.list.j2`, `sources.list-deb822.j2`
- Handlers: apt cleanup, apt autoremove

## Public Interfaces

- Playbook: `playbooks/os-updates-deb.yml` (chains
  [healthcheck](./MOD-005-healthcheck-role.md))
- Key variables: `os_update_auto_upgrade`, `os_also_update_mirror` (false),
  `os_update_mirrors` (main + security mirror),
  `os_update_version_codename` (role default: host facts;
  `group_vars/debian.yml` hardcodes `trixie`),
  `os_update_debian_codenames` (trixie, bookworm, bullseye),
  `os_update_reboot_on_proxmox` (false),
  `os_update_logging_enabled` (true), `os_update_log_dir` (/ansible/logs),
  `os_update_log_file` (logs/<inventory>/<hostname>/update.log).

## Important Flows

1. Mirror rewrite (only when `os_also_update_mirror`) with
   `ignore_errors: true`; only whitelisted Debian codenames are rewritten in
   `sources.list.d`.
2. Preflight logging: refresh cache, record start epoch/ISO, parse
   `apt list --upgradable` into names/versions/count.
3. `apt upgrade: full` (notifies cleanup/autoremove handlers).
4. Reboot decision: compare running kernel (`uname -r`) vs newest installed
   `linux-image-*`; skipped on LXC (`virtualization_type != lxc`). On
   `proxmox` group hosts the reboot is deferred unless
   `os_update_reboot_on_proxmox`. Otherwise: async `/sbin/reboot`,
   `wait_for_connection` (10s delay, 600s timeout), downtime and kernel
   after reboot recorded.
5. Postflight logging: duration, upgrade result, reboot details, kernel
   before/after appended to the update log (`delegate_to: localhost`).

## Dependencies

- None (ansible.builtin only). Paired with healthcheck at playbook level.

## Tests

- None automated.

## Notes For Agents

- Logging facts are shared with the healthcheck role via the same log file
  and start timestamp conventions.
- Old-style module names (apt, file, blockinfile) remain here; use FQCN for
  new tasks.