ota-reference-design/adr/ADR-012-device-controlled-update-execution.md

ADR-012: Device-Controlled Update Execution

Context

A remotely deployed embedded Linux device may lose its connection after learning about an available update or preparing it for installation. The server controls which releases are available to the device, but cannot always stay in contact throughout the update.

ADR-011 describes how the device checks for updates. Once an update has been selected and approved, a separate question remains: who controls the steps needed to complete it?

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. For a device that can check its essential functions locally, this would make acceptance of an otherwise healthy update depend on 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 provide the server control over release availability assumed here. 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.