5.0 KiB
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.