diff --git a/adr/ADR-004-full-system-image-updates.md b/adr/ADR-004-full-system-image-updates.md new file mode 100644 index 0000000..d00ea56 --- /dev/null +++ b/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.