2.5 KiB
Decision 0001: Minimal, Module-Driven Ansible
Status: accepted
Date: 2026-09-07
Context
The first Seriatim implementation surrounded ordinary Ansible operations with preflight inspection, fingerprints, sidecar build state, manual drift logic, and recovery behavior. Much of that machinery duplicated behavior already provided by Ansible modules or addressed threats and failure modes outside the MVP. The result was harder to understand, review, and maintain than the deployment it represented.
The proof-of-concept roles in rakestraw-ansible demonstrate the preferred
style: direct module use, shallow task flow, small public interfaces, and
loops only for genuinely uniform resources.
Decision
Roles in this workspace will express the required end state with the most direct suitable Ansible module and trust that module's documented idempotence, change detection, check-mode behavior, and error handling.
Additional inspection or state machinery is justified only when a selected requirement falls outside that module contract. In particular:
- Do not use
stat, package queries, content comparisons, or account lookups merely to decide whether to invoke an idempotent module. - Gather state when it is genuinely needed to control application behavior, such as determining whether an imperative build command's output is missing.
- Treat a successful module invocation as establishing its documented postcondition. Verify the role's implementation in repository-local tests rather than adding production tasks that immediately re-prove it.
- Do not introduce fingerprints, checksums, sidecar state, staged replacement, custom drift recovery, or abstractions without an explicit acceptance criterion and rationale.
- Keep role variables to meaningful consumer choices. Do not expose every fixed argument of an upstream build command as a public interface.
- Test the intended operating contract and idempotent convergence. Do not build a speculative hardening test matrix into the MVP.
Consequences
Feature roadmaps describe the simplest viable implementation shape, and implementation plans must justify any material complexity beyond it. Reviews should remove logic that merely reimplements a module's contract.
Potential security hardening and unusual recovery behavior may be recorded for future consideration without becoming part of the initial implementation. This accepts that an MVP role may fail plainly when the managed host contains malicious, corrupted, or unsupported state rather than attempting automatic recovery from every condition.