0 Fork 0

Files

T

jakman85andClaude Opus 5.5 250fb54154 docs: bring the specification in line with the accepted implementation

The operator ruled the implementation repo's main (50c8719) the latest
and accepted state. Sync the spec to it.

Accepted changes are reflected: one bare-metal environment, TrueNAS bulk
storage, R2 off-cluster backup, CloudNativePG, single-node VPN gateway
with Cilium fail-closed, inbound WireGuard, per-app auth sidecars,
Renovate, the CI gate as approver, and the pm-agent. New ADR-0017..0025;
ADR-0016 corrected and accepted; R-* IDs unchanged, eight amended.

Where the implementation has simply not met a requirement, the
requirement stands and the shortfall is recorded in docs/16-known-gaps.md.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

2026-11-08 22:46:00 -06:00

2.6 KiB

Raw Permalink Blame History

ADR-0009 — Automated updates: Flux image automation + Renovate

Status: Superseded by ADR-0023 (2026-11-08)
Date: 2026-08-15
Serves: R-UPD-01, R-UPD-02, R-UPD-03
Supersedes: —

Context

Services must advance to the latest stable version on a schedule with no human, no AI, and no hand-authored GitOps change (R-UPD-02). This must coexist with GitOps (git = source of truth) and must be safe (stable-only, health-gated, reversible).

Decision

Split by artifact type:

Container image tags → Flux image-update-automation. Per-service ImagePolicy declares the acceptable range/channel (semver range or stable tag regex). Flux's image-reflector scans the registry on an interval (the schedule) and image-automation advances the running version. The policy is the human-authored intent; the version advance is machine-performed — no human/AI edits a tag (R-UPD-02).
Helm charts / manifests → Renovate. Renovate opens version-bump PRs; allowed update classes auto-merge on green CI. Major/breaking bumps may require review per policy.
VM guests → in-guest auto-update (unattended-upgrades/dnf-automatic) declared in the VM's cloud-init (06).

Default write-back behavior: image-automation commits the resolved version back to git (machine- authored) so history is auditable; a per-service escape hatch allows digest-tracking of a mutable stable tag for zero-commit updates where the operator prefers it. Per-service update policy (channel, range, cadence, pin, autoRollback) lives in the ServiceDefinition (13).

Alternatives considered

Argo CD Image Updater — bolt-on to Argo; we chose Flux (ADR-0004) whose image automation is first-class.
latest/stable mutable tag + scheduled rollout restart only — simplest but loses version visibility and semver guardrails; offered only as the per-service digest-tracking escape hatch.
Human/AI-authored bumps — explicitly prohibited by R-UPD-02.

Consequences

Hands-off updates satisfied via declared policy, not manual/AI edits (R-UPD-02).
Safety rails required and are acceptance gates: stable-only, health-gated rollout, auto-rollback on failed health, pin escape hatch, and alerting on update failure (10, 11).
Registry rate-limits/credentials for cadence scanning must be handled.
Machine write-back commits will appear in history — an intended, auditable artifact, not a violation of "no hand-authored change."

2.6 KiB Raw Permalink Blame History