deeaitch/ota-reference-design
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Ref #03 - symplife

Browse Source
This commit is contained in:
deeaitch committed 2026-09-21 13:44:01 -04:00
1 parent 572d1f7acc
commit 3c94145491
1 file changed
+44 -153
Download Patch File Download Diff File Expand all files Collapse all files
docs/03-system-architecture.md
+44 -153
View File
@@ -1,177 +1,68 @@
# 03. OTA System Architecture: Responsibilities and Cooperation
# 03. OTA System Architecture: How the Parts Work Together
The previous chapter explored what a device updates and which mechanisms can deliver those changes. The next question is:
The previous chapter looked at what we update: a system image, an application, or data. Now let’s look at who does the work.
> **Which parts of the system cooperate to complete an update, and what is each part responsible for?**
An OTA update starts with a tested release and ends with a device running it successfully. Several parts of the system help it get there.
An image format or a package manager answers only part of that question. Someone must prepare a release, decide where it should go, determine whether installation is allowed, activate it, and establish whether it works.
This chapter introduces those responsibilities through a simple system update. The example uses a prepared system release activated by rebooting. Application and data updates can follow a similar structure, with different installation and activation mechanisms.
The roles below are architectural responsibilities, not a requirement to build a separate service for every box.
---
## 1. From Release Preparation to a Working Device
Consider a device running release N. A new release, N + 1, has been built and tested. An operator wants an eligible device to install it when local operating conditions permit.
## 1. The Big Picture
```text
Build and test
|
v
Release preparation -----> Artifact storage
| |
v | update content
Deployment management |
| |
| update assignment |
v v
Device: update manager <----> Installation mechanism
| |
| coordinate | prepare software
v v
Activation / boot control -> New software runs
^ |
| v
+-------------- Health assessment
Device state and results ------> Deployment management
Build and test a release
|
v
Publish update files
|
v
Server offers the release to selected devices
|
v
Device downloads and checks the update
|
v
Install -> Activate -> Check that it works
|
v
Report the result to the server
```
Release preparation establishes what is being published. Deployment management determines which devices should receive it. The device carries out the update and reports what actually happened.
The server decides which devices should receive a release. The device checks whether it can update now, carries out the work, and reports the result.
The arrows describe logical exchanges. They do not specify a network protocol, process boundary, or required direction for opening a connection.
Alongside the update files, it needs a few details: which version this is, which devices it supports, and how to verify it. The server also needs feedback. “Update offered” and “new version running” are different things.
## 2. Responsibilities Outside the Device
## 2. Who Does What?
### Release Preparation
**Release preparation and storage.** The software is built, tested, given a version, and published for download. The release includes information needed to check that the files are intact and come from an authorized source. Storage can be as simple as a file server.
The release process builds and tests the software, identifies its intended targets, and prepares the artifacts and metadata needed for delivery and verification.
**Deployment management.** This part chooses which devices receive which release and tracks their progress. For example, an operator might offer a release to a small test group before making it available to everyone.
A release identity must refer to specific content. Otherwise, a report that a device installed “release N + 1” would not reliably identify the software it received.
**OTA manager.** On the device, the manager organizes the update. It checks whether the release fits the device and whether local conditions allow the work. A device might download an update while busy, then wait until its current task finishes before restarting.
This responsibility also includes arranging authorization of the published release, such as signing artifacts or release metadata. Key handling and verification mechanisms belong to the security chapter.
**Installer.** This part knows how to install the software: write an image, install a package, or prepare a new set of files. Depending on the tool, it may also handle downloading and verification. The manager decides when to proceed; the installer knows how to do the installation.
### Artifact Storage
**Activation and boot control.** Installed software is not necessarily running yet. A system update may need a reboot into the new version. An application update may need only a service restart. For system updates, boot components must also handle cases where the new system cannot start the OTA manager.
Artifact storage makes update content available for retrieval. It may be a simple file server, an object store, or part of a larger update service.
**Health checks.** These check whether the new version can do its job. Linux starting successfully may not be enough: the main application might still fail. The results help the device decide whether to keep the new version or start recovery.
Serving a file does not by itself decide which device should install it. Likewise, successful download does not establish that installation or activation succeeded.
These are roles, not a shopping list of separate services. One tool may cover several of them. What matters is knowing who handles each step.
### Deployment Management
## 3. One Update, Start to Finish
Deployment management associates releases with devices or groups of devices. It may use hardware type, installed versions, or an operator's selection to determine eligibility.
Imagine a device running version 1. Version 2 is ready. In this example, the device can prepare the new system while keeping the previous one available for recovery.
It also receives progress and results. Its view can be delayed or incomplete when devices are offline. A requested version and a reported running version therefore need to remain distinguishable.
1. The server offers version 2 to the device.
2. The OTA manager checks that it fits this device and that an update is allowed now.
3. The installer downloads, verifies, and prepares version 2. Version 1 is still running.
4. When the device can restart, boot control selects version 2 and the device reboots.
5. Health checks test the essential functions. If they pass, the device confirms version 2. If they fail, it starts recovery. If the system cannot boot at all, the boot recovery mechanism must handle that earlier failure.
6. The device reports the outcome, including which version is now running.
These responsibilities can share one implementation in a small system. Separating them conceptually helps explain how the design can later accommodate different storage and deployment arrangements.
What if the network disappears? In this example, once the required files and verification information are available, the device can finish the local steps without the server. It sends its report when the connection returns. A broken connection alone does not mean the new software is broken.
## 3. Responsibilities on the Device
If the update itself is interrupted, the device needs enough saved information to work out what happened before continuing. We will look at storage, boot behavior, and recovery in later chapters.
### Update Management
Two ADRs explain the choices behind this example:
The update manager coordinates the operation. It evaluates the update assignment against local policy and state: whether the device is eligible, whether another update is in progress, and whether current conditions allow installation or activation.
- [ADR-011: Device-Controlled Update Execution](../adr/ADR-011-device-controlled-update-execution.md) — why let the device finish the update when the server is unreachable?
- [ADR-012: Separate Update Management from Installation](../adr/ADR-012-update-management-and-installation.md) — why separate deciding when to update from knowing how to install it?
For example, a device may download while in use but defer a restart until its current work is complete.
The manager tracks progress across the steps it coordinates. An interrupted operation must be reconciled with the actual installation and boot state before execution continues.
### Installation Mechanism
The installer understands how to prepare a particular update unit. It might write an image, install a package, prepare a filesystem tree, or replace a versioned data artifact.
Downloading and verification may be implemented here or in supporting components. The architecture must assign those duties explicitly; it does not need to duplicate them in the update manager.
This extends the distinction between OTA manager and package manager introduced in [ADR-005](../adr/ADR-005-package-based-updates.md). [ADR-012](../adr/ADR-012-update-management-and-installation.md) examines that separation as an architectural choice.
### Activation and Boot Control
Activation makes prepared software operational. For a system update, this may require selecting a boot target and restarting the device. For an application, it may require switching versions and restarting a service.
Boot control matters because the ordinary update manager may not run if the new system cannot boot. The design needs a defined owner for decisions made before that manager becomes available.
The next chapters will explain boot behavior and storage arrangements. At this level, the important distinction is between preparing software and making it active.
### Health Assessment
Health assessment supplies evidence that the activated version can perform its intended work. Reaching the Linux login prompt or starting the update agent may be insufficient for the product.
An application or dedicated health service might check essential functionality. The architecture must identify who provides the evidence and who uses it to confirm the update or initiate recovery.
A health check is a defined acceptance criterion, not proof that the release contains no defects.
## 4. What Participants Exchange
The update artifact is only one part of the exchange:
| Information | Purpose |
|---|---|
| Release metadata | Identifies content, intended targets, compatibility requirements, and verification information |
| Update assignment | Expresses which release a device is requested or permitted to install |
| Local execution state | Records the operation and the steps needed to continue or recover after interruption |
| Installation result | Describes what the installer prepared or changed and whether the operation completed |
| Health evidence | Supports the decision to accept an activated version or recover |
| Device report | Communicates observed versions, progress, and failures to deployment management |
These are logical categories, not six required files or API objects. One implementation may combine several of them.
The distinction between **requested**, **prepared**, **running**, and **confirmed** versions is especially useful. A device can finish installing N + 1 while still running N. It can also boot N + 1 without having confirmed its health.
In a hybrid design, the reported state may include separate platform, application, and content versions, as discussed in [ADR-010](../adr/ADR-010-hybrid-update-strategies.md).
## 5. Walking Through One Update
For this example, assume the device can prepare a candidate system while retaining a usable previous system. The exact storage mechanism is left to a later chapter.
1. **Publish the release.** The release process publishes tested content and the metadata needed to identify and verify it.
2. **Assign the release.** Deployment management makes N + 1 available to an eligible device.
3. **Evaluate local conditions.** The update manager checks applicability and policy. It can defer execution if the device is busy or lacks required resources.
4. **Retrieve, verify, and prepare.** The installation path obtains the content, verifies it as required, and prepares the candidate. Unverified content must not become the accepted active release. Verification and writing may be arranged differently by different installers.
5. **Request activation.** Once preparation succeeds and restart is allowed, the device selects the candidate for activation and reboots.
6. **Assess the running version.** The configured health checks determine whether the candidate meets the acceptance criteria.
7. **Confirm or recover.** The responsible local components confirm the candidate or follow the recovery path. A failure before userspace starts must be handled by components available at that stage.
8. **Report the outcome.** The device reports its observed state. If communication is unavailable, reporting is deferred according to the design's retry policy.
This sequence explains responsibilities rather than defining a universal state machine. The implementation must specify durable state transitions, retry behavior, and recovery rules for its chosen mechanisms.
## 6. Where Failures Cross Component Boundaries
Failures reveal responsibilities that a successful sequence can hide.
| Interruption | Architectural question |
|---|---|
| Network disappears during retrieval | Who retries or resumes, and how is incomplete content prevented from being activated? |
| The update manager restarts during installation | How does it determine whether installation is still running, failed, or completed? |
| Power is lost around activation | Which durable state tells the boot path what to attempt next? |
| The candidate cannot start the update manager | Which earlier component detects failure and selects a recovery path? |
| The candidate runs but fails an essential function | Who supplies health evidence and triggers the appropriate response? |
| The device confirms the release but its report is lost | How does the server learn the actual state without causing an unnecessary reinstall? |
The chapter's example chooses local execution and recovery after an update has been authorized and prepared. A server connection is not required to confirm the local boot result. [ADR-011](../adr/ADR-011-device-controlled-update-execution.md) explains the assumptions and trade-offs behind that choice.
Other systems may require external acceptance. They must define what happens when the external service is unreachable and whether loss of connectivity is itself a reason to reject the new version.
## 7. Authority and Trust Boundaries
Several decisions can look like a single “permission to update,” but serve different purposes:
- Release authorization establishes which software comes from an authorized publisher.
- Deployment policy determines which eligible device should receive a release.
- Local policy determines whether the device can perform the operation now.
- Health acceptance determines whether the activated software satisfies the configured operational checks.
A valid signature alone does not establish that a release is compatible with this device or safe to activate during its current work. A successful download does not establish an authorized source. A server assignment does not establish that the device actually installed the release.
The architecture needs to identify the component responsible for each check and the information it trusts. The security chapter will develop the mechanisms and threat model in detail.
## 8. Decisions to Explore Further
Two reference decisions develop the central boundaries introduced here:
- [ADR-011: Device-Controlled Update Execution](../adr/ADR-011-device-controlled-update-execution.md) considers devices that must complete local activation and recovery despite intermittent connectivity.
- [ADR-012: Separate Update Management from Installation](../adr/ADR-012-update-management-and-installation.md) considers how product policy can coordinate installation mechanisms without reimplementing them.
Neither decision prescribes a framework, transport protocol, or number of processes. Choices such as polling versus notifications and combined versus separate backend services can be evaluated once the operating constraints are clear.
The next chapter examines the boot process: which parts of this architecture can act before the operating system is available, and how responsibility passes from boot components to the running system.
Next, we will follow the boot process and see what happens before Linux and the OTA manager start.