full system image updates

adr/ADR-004-full-system-image-updates.md

@@ -0,0 +1,130 @@
+# ADR-004: Full-System Image Updates
+
+## Status
+
+Accepted
+
+## Context
+
+An OTA architecture must define the unit of update.
+
+One possible approach is to treat the complete software stack as a single release artifact and distribute it as a prebuilt, tested system image.
+
+For firmware-based devices, a full image is often the only practical update unit. For embedded Linux and other more complex platforms, it is one of several available strategies.
+
+## Decision
+
+Use full-system image updates when the device software is released and maintained as a single product, and when reproducibility, a known system state, and reliable system-level rollback are more important than minimizing update size or supporting independent component lifecycles.
+
+## Decision Drivers
+
+Full-system image updates are preferred when:
+
+- the software stack is released as a single product;
+- the device must remain in one of a small number of predefined system states;
+- system-level rollback is required;
+- reproducibility is more important than minimizing update size;
+- the device fleet is sufficiently homogeneous;
+- image size and storage requirements are acceptable;
+- centralized release and validation of the complete system are practical.
+
+## Consequences
+
+### Positive
+
+- The image version identifies the version of the complete software system.
+- The device runs a predefined system state rather than an arbitrary combination of component versions.
+- The exact image installed on the device is the image that was validated before release.
+- Dependency resolution is not required during installation.
+- Diagnosis of the installed system version is simplified.
+- The approach integrates naturally with A/B layouts and system-level rollback.
+- The number of possible software configurations is reduced.
+- The software can be built, tested, signed, released, and rolled back as a single product.
+
+### Negative
+
+- Even a small change requires a new system image release.
+- Every image release requires full regression testing.
+- Unchanged components are transferred and written again.
+- Network traffic and installation time may increase.
+- Additional device storage may be required, especially for A/B layouts.
+- Individual components cannot easily maintain independent release cycles.
+- Hardware-specific differences may require multiple variants of the same product release.
+- Every image variant must be built, tested, signed, maintained, and assigned to the correct devices.
+
+## Special Considerations
+
+### Firmware
+
+For many microcontroller-based devices, full-image replacement is the natural and often the only practical OTA model.
+
+Such devices commonly do not provide:
+
+- a filesystem;
+- a package manager;
+- independently deployable software components;
+- a practical mechanism for updating only part of the firmware.
+
+In this context, OTA normally means replacing the complete firmware image.
+
+### Full-System Testing
+
+Full-system image updates do not reduce the required scope of testing.
+
+Even when only one component changes, the complete resulting image must be tested because the change may introduce regressions elsewhere in the system.
+
+The advantage is not that fewer tests are required. The advantage is that the exact image installed on the device is the same image that passed validation.
+
+## Limitations
+
+Full-system image updates are most effective when one software release corresponds to one clearly defined product version.
+
+The approach becomes more difficult to maintain when the fleet contains many devices that are functionally equivalent but differ in small hardware-dependent details, such as:
+
+- peripheral hardware revisions;
+- bundled peripheral firmware versions;
+- microcode state;
+- hardware-specific migration history;
+- other small platform-dependent differences.
+
+These differences may create several variants of the same release.
+
+Each variant must be:
+
+- built;
+- regression-tested;
+- signed;
+- stored and maintained;
+- assigned to the correct group of devices.
+
+If the number of variants grows quickly, the operational advantages of a single full-system image decrease while release and validation costs increase.
+
+## Applicability
+
+This approach is a strong choice when:
+
+- the software or firmware is treated as one deployable product;
+- the cost of an inconsistent system state is high;
+- physical recovery is difficult or expensive;
+- reliable rollback is required;
+- the fleet is relatively homogeneous;
+- releases are centrally built and validated.
+
+Other update strategies should be considered when:
+
+- components have independent lifecycles;
+- the fleet contains many small hardware variants;
+- network usage is a primary constraint;
+- available storage is severely limited;
+- some components must be updated much more frequently than the rest of the system;
+- full regression testing of every image variant is too expensive.
+
+## Alternatives Considered
+
+The following alternatives are addressed in separate ADRs:
+
+- package-based updates;
+- application-level updates;
+- container-based updates;
+- versioned filesystem trees;
+- hybrid update strategies.