53 lines
2.4 KiB
Markdown
53 lines
2.4 KiB
Markdown
# 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 a locally built executable is missing or has
|
|
the wrong application version.
|
|
- 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.
|