Deployment Flows
Introduction
This section documents the end-to-end deployment flows in AosCore — from the moment AosCloud triggers an update through orchestration by the Communication Manager (CM), execution by Update Managers (UMs) and the Service Manager (SM), to final Verification and status reporting. Understanding these flows is essential for OEMs integrating with AosEdge, as they govern how software and firmware reach production Units in the field.
AosCore supports two primary deployment mechanisms:
- SOTA (Software Over The Air) — deploys service images, layers, and Unit configuration changes through the CM Update Manager and Service Manager
- FOTA (Firmware Over The Air) — deploys firmware and system-level components through the CM and external Update Managers
Both mechanisms share a common orchestration model but differ in what is being deployed and which components execute the actual update.
Deployment Architecture
The deployment flow involves coordination between cloud, CM, and on-Node components:
| Component | Role in Deployment |
|---|---|
| AosCloud | Sends desired-state messages containing target Deployable Items, instances, and component versions |
| CM (Update Manager) | Receives desired state, determines what changed, downloads images, and orchestrates the update state machine |
| CM (Update Scheduler) | Exposes gRPC API for external systems to trigger SOTA/FOTA updates and subscribe to progress notifications |
| Image Manager | Downloads, verifies, and stores Deployable Item images (OCI layers, firmware blobs) |
| Service Manager (SM) | Executes SOTA deployments — starts and stops service instances with new image versions |
| Update Manager (UM) | Executes FOTA deployments — applies firmware updates to system components (rootfs, bootloader, etc.) |
Deployment Trigger
Deployments are triggered when AosCloud sends a new desired-state message to the Unit. The desired state contains the complete target configuration:
- Node states — which Nodes should be active or paused
- Unit configuration — target configuration version
- Deployable Items — service images and firmware components with versions and integrity digests
- Instances — which services to run, how many, with what priority and placement labels
- Certificates — TLS certificates needed for image Verification
The CM Update Manager compares the incoming desired state against the current state. If differences are detected, an update cycle begins.
External systems can also trigger updates through the UpdateSchedulerService gRPC API:
| RPC | Purpose |
|---|---|
StartSOTAUpdate | Triggers a software update cycle |
StartFOTAUpdate | Triggers a firmware update cycle |
SubscribeNotifications | Streams real-time SOTA/FOTA progress notifications |
Update Orchestration
Once triggered, the CM Update Manager drives the deployment through a sequential state machine:
| State | Action |
|---|---|
| Downloading | Image Manager downloads all required Deployable Item images with integrity Verification |
| Pending | Downloads complete; system is ready to proceed |
| Installing | Node state changes and Unit configuration are applied |
| Launching | Service instances are started (SOTA) or firmware updates are applied (FOTA) |
| WaitingActive | System waits for all instances/components to reach their target state (10-minute timeout) |
| Finalizing | Deployable Items are committed as the installed set; full status is reported to AosCloud |
If any step fails, the state machine resets and error information is reported to AosCloud. If a new desired state arrives during an in-progress update, the current update is cancelled and the new one begins — ensuring the Unit always converges toward the most recent target.
SOTA vs FOTA
While both deployment types share the same orchestration state machine, they differ in scope and execution:
| Aspect | SOTA (Software) | FOTA (Firmware) |
|---|---|---|
| What is deployed | Service images (OCI containers) and layers | System components (rootfs, bootloader, firmware) |
| Executor | Service Manager on each Node | External Update Manager (UM) process |
| Impact | Services are relaunched with new versions | Node may require reboot |
| Scope | Individual services on specific Nodes | System-level components across the Unit |
| Rollback | SM stops old instances, starts new ones | UM supports Revert before Apply |
FOTA Update Protocol
For firmware updates, CM communicates with registered Update Managers through a dedicated gRPC protocol
(updatemanager/v2). CM sends commands and the UM reports status:
| CM Command | Purpose |
|---|---|
PrepareUpdate | Instructs UM to download, verify, and prepare component images |
StartUpdate | Instructs UM to apply the update (system must remain revertible) |
ApplyUpdate | Commits the update permanently (no rollback after this point) |
RevertUpdate | Rolls back to the previous version (sent if StartUpdate fails) |
The UM reports its UpdateStatus after each command completes, including per-component state (INSTALLED,
INSTALLING, ERROR).
Crash Recovery
The Update Manager persists its state on every transition. If the CM process restarts during an update, it resumes from the last persisted state with the stored desired status. This prevents partial deployments from leaving the Unit in an inconsistent state.
Section Contents
This section covers deployment flows in detail across the following pages:
- Update Flow Overview — end-to-end sequence from cloud trigger through download, installation, and Verification to completion
- SOTA vs FOTA — detailed comparison of software and firmware update mechanisms, including when each is used
- Update Handler State Machine — the complete state machine for FOTA Update Managers, including module interfaces and reboot handling
- Rollback and Recovery — how failed updates are detected, reverted, and reported
Related Pages
- Key Concepts — definitions of Deployable Item, Deployment Bundle, Verification, and other core terms
- Architecture Overview — how CM, SM, IAM, and MP interact at the system level
- Update Manager (CM module) — detailed documentation of the CM Update Manager internals
- Service Lifecycle — how services are deployed and managed after a SOTA update completes
- Service Manager — SM component that executes SOTA deployments on each Node