---
id: MOD-005
type: module
status: active
title: Healthcheck Role
created: 2026-09-09
updated: 2026-09-09
tags: [module, healthcheck, docker, ansible]
related: [MOD-004, REQ-004, NFR-003]
source_paths:
- roles/healthcheck/
confidence: confirmed
---

# Healthcheck Role

## Responsibility

Post-update quality gate: verify that every Docker container on the host is
running and record the result in the update log.

## Source Paths

- `roles/healthcheck/tasks/main.yml` (single file, no subtasks)
- `roles/healthcheck/defaults/main.yml`

## Public Interfaces

- Playbook: `playbooks/os-updates-deb.yml` (runs after os-updates)
- Key variables: `healthcheck_fail_on_unhealthy` (default false),
  `healthcheck_logging_enabled` (derives from `os_update_logging_enabled`),
  `healthcheck_log_file` (reuses os-updates log path conventions).

## Important Flows

1. Detect Docker binary (`which docker`, tolerant).
2. If Docker present: list all container names and running container names
   (`docker ps -a` / `docker ps --filter status=running`), compute
   non-running set.
3. If Docker absent: neutral result (0 containers, passed).
4. Append a `quality_gate:` section (docker_installed, total/running counts,
   non-running list, healthcheck_passed) to
   `logs/<inventory>/<hostname>/update.log` via `blockinfile` delegated to
   localhost.
5. Fail the play when `healthcheck_fail_on_unhealthy` is true and any
   container is not running.

## Dependencies

- Shares log file conventions with [os-updates](./MOD-004-os-updates-role.md).

## Tests

- None automated.

## Notes For Agents

- The gate does not fail by default; set `healthcheck_fail_on_unhealthy`
  to make failures visible in CI-like runs.