81 lines
4.7 KiB
Markdown
81 lines
4.7 KiB
Markdown
# ADR-011: Device-Controlled Update Execution
|
|
|
|
* **Status:** Proposed
|
|
* **Date:** 2026-09-21
|
|
|
|
## Context
|
|
|
|
This educational example considers remotely deployed embedded Linux devices with intermittent connectivity. A backend assigns authorized releases, but a device may lose contact after receiving an assignment or preparing an update.
|
|
|
|
The device can evaluate local operating conditions and has a locally available activation and recovery mechanism. Its essential post-update health checks can be evaluated without contacting the deployment service.
|
|
|
|
The architectural question is which participant controls execution once the device has accepted an update assignment. Requiring a remote command for every step would make progress and recovery depend on continued connectivity.
|
|
|
|
## Decision
|
|
|
|
Let the backend manage release assignment and fleet deployment policy. Let the device coordinate the local execution of an accepted update within that authorization and its local operating policy.
|
|
|
|
After the required content and verification information are available, local activation, health acceptance, and recovery must not require a live connection to the deployment service.
|
|
|
|
Keep enough durable local state to reconcile an interrupted operation with installation and boot state. Report progress and the resulting software state when connectivity permits. Treat backend knowledge as a potentially delayed observation of the device.
|
|
|
|
This decision assigns responsibility to the device as a whole. It does not require the userspace update manager to handle failures that occur before it can run.
|
|
|
|
## Decision Drivers
|
|
|
|
- Connectivity may disappear during an update.
|
|
- Local conditions determine when disruptive operations are permissible.
|
|
- A candidate that fails to boot cannot rely on its own update agent for recovery.
|
|
- Loss of reporting connectivity should not alone invalidate a locally healthy release.
|
|
- Operators need to distinguish intended deployment state from observed device state.
|
|
|
|
## Alternatives Considered
|
|
|
|
### Server-Controlled Execution of Every Step
|
|
|
|
The server authorizes each transition separately, including activation and confirmation.
|
|
|
|
This provides tighter online coordination, but a communication outage can leave an operation waiting for a command. It does not remove the need for local handling of boot failures or interrupted writes. It is less suitable for the assumed connectivity model.
|
|
|
|
### Local Execution with Mandatory Remote Acceptance
|
|
|
|
The device installs and boots independently but requires the backend to accept the candidate before confirmation.
|
|
|
|
This can be appropriate when external service behavior is part of release acceptance. In this example, it would couple an otherwise healthy local update to network availability. Such a design also needs an explicit timeout and recovery policy for unavailable remote acceptance.
|
|
|
|
### Fully Autonomous Release Selection
|
|
|
|
The device selects any compatible authorized release without a backend assignment.
|
|
|
|
This can fit simpler products, but does not meet the example's need for centrally controlled release assignment. Local execution autonomy does not imply authority to select arbitrary releases.
|
|
|
|
## Consequences
|
|
|
|
### Positive
|
|
|
|
- Prepared updates can complete or recover during a backend outage.
|
|
- Local operational constraints can delay activation without a remote command round trip.
|
|
- Boot failure handling remains available independently of the deployment service.
|
|
- Requested and observed software states have explicit meanings.
|
|
|
|
### Negative
|
|
|
|
- The device needs durable execution state and interruption handling.
|
|
- Backend status may remain uncertain until the device reconnects.
|
|
- Remote cancellation cannot take effect immediately on an offline device.
|
|
- Backend and device policies need clear precedence and reconciliation rules.
|
|
|
|
## Notes
|
|
|
|
The implementation must define when an assignment is accepted, any expiry or cancellation rules, and the points at which an operation may safely be stopped. A backend cancellation cannot undo an activation that already occurred while the device was offline.
|
|
|
|
Repeated assignments and repeated reports must be reconciled with the operation identity and actual device state. They must not blindly repeat destructive installation steps.
|
|
|
|
This decision does not choose polling, push notifications, storage layout, or the boot failure detection mechanism. It assumes those mechanisms can support the stated local responsibilities; later chapters must establish how.
|
|
|
|
## Applicability
|
|
|
|
This choice fits devices whose local health can be assessed offline and whose recovery must remain available during communication failures.
|
|
|
|
Consider external acceptance when successful operation fundamentally depends on a remote system. Specify how to distinguish failure of the candidate from failure of that system or the network.
|