Architecture Overview
Introduction
This page provides a detailed architectural view of AosCore — the software stack running on each AosEdge Unit. It describes the four main components, their internal submodules, how they communicate, and how they are distributed across Nodes within a Unit.
Use this page as a reference map when reading the detailed component pages that follow. Each component section below links to its dedicated documentation for deeper coverage.
System Architecture Diagram
The following diagram shows the complete AosCore architecture within a Unit, including both Main Node and Secondary Node deployments:
loading...Legend:
- Purple — Communication Manager (CM): cloud connectivity and orchestration
- Green — Service Manager (SM): service lifecycle and execution
- Yellow — Identity and Access Manager (IAM): security and identity
- Red — Message Proxy (MP): inter-node communication
Component Distribution
AosCore components are distributed across Nodes based on their role within the Unit:
| Node Role | Components | Purpose |
|---|---|---|
| Main Node | CM, SM, IAM | Runs the full stack including cloud connectivity |
| Secondary Node | SM, IAM, MP | Runs services locally; MP bridges communication to the Main Node's CM |
The Main Node is the single point of cloud connectivity for the entire Unit. Secondary Nodes communicate with the cloud indirectly through the Message Proxy, which routes messages to and from the Main Node's Communication Manager.
Communication Manager (CM)
The Communication Manager is the central orchestrator on the Main Node. It maintains the WebSocket connection to AosCloud, processes desired-state updates, and coordinates all other components.
Process: aos_communicationmanager
Subcomponents
| Module | Responsibility |
|---|---|
communication | WebSocket-based JSON cloud protocol — connects to AosCloud, sends/receives messages, handles service discovery, reconnection, and message acknowledgment |
smcontroller | gRPC server that SM instances connect to — distributes service deployment commands, collects status, monitoring data, and logs from all Nodes |
networkmanager | Manages network resources for the Unit — DNS server, IP subnet allocation, network pool management for service containers |
unitconfig | Handles Unit-level configuration — loads and provides JSON configuration to other components |
iamclient | Client interface to IAM — obtains TLS certificates, system identity, and credential change notifications for cloud reconnection |
database | Local SQLite storage with schema migration — persists CM operational state |
config | CM process configuration loading and validation |
Key Interfaces
- Cloud (outbound): WebSocket connection to AosCloud using a JSON protocol (protocol version 7). CM performs service discovery, then establishes a persistent WebSocket for bidirectional messaging.
- SM (inbound gRPC): CM runs a gRPC server (
SMService) that SM instances on all Nodes connect to. Through this interface, CM pushes instance updates and receives status, monitoring, alerts, and logs. - IAM (outbound gRPC): CM acts as a client to IAM for certificate provisioning, identity information, and credential lifecycle events.
Service Manager (SM)
The Service Manager handles the complete lifecycle of service instances on its Node — from image acquisition through container execution to monitoring and teardown.
Process: aos_servicemanager
Subcomponents
| Module | Responsibility |
|---|---|
imagemanager | Manages OCI service images — handles image download coordination, storage, and layer management |
launcher | Starts and stops service instances — supports multiple runtime types (container, native) through a pluggable runtime interface |
resourcemanager | Enforces resource limits — CPU, memory, and storage quotas for service instances |
networkmanager | Configures per-service networking — CNI plugin execution, traffic monitoring, network namespace management |
monitoring | Collects Node-level resource metrics — CPU, RAM, disk usage for the Node and individual service instances |
alerts | Generates alert events from journal entries — watches systemd journal for configured alert patterns |
logprovider | Collects and forwards service logs — system logs and per-instance logs on request |
smclient | gRPC client connecting to CM's smcontroller — registers the SM, receives commands, sends status and telemetry |
iamclient | Client interface to IAM — obtains service-level TLS credentials for the gRPC connection to CM |
database | Local SQLite storage with schema migration — persists service state, image metadata |
Key Interfaces
- CM (outbound gRPC): SM connects to CM's
smcontrolleras a gRPC client. It registers itself (reporting Node ID, runtime capabilities, resource capacity), then receives instance update commands, and reports back status, monitoring data, alerts, and logs. - IAM (outbound gRPC): SM obtains TLS certificates from IAM for securing its gRPC connection to CM.
Identity and Access Manager (IAM)
The Identity and Access Manager handles all security-related concerns — certificate lifecycle, Node identity, provisioning, and access control.
Process: aos_iamanager
Subcomponents
| Module | Responsibility |
|---|---|
identhandler | Manages system identification — interfaces with hardware or software identity sources (VIS identifier plugins) to establish the Unit's identity |
iamserver | gRPC server exposing IAM services — provides both public (certificate requests) and protected (provisioning, node management) APIs to other components |
iamclient | Client interface for IAM-to-IAM communication — used in multi-Node setups where secondary IAM instances communicate with the Main Node's IAM |
currentnode | Provides current Node information — system info, Node ID, and Node type for the local Node |
database | Local SQLite storage with schema migration — persists certificate metadata, Node registrations |
config | IAM process configuration loading and validation |
Key Interfaces
- Public API (inbound gRPC): Exposes certificate request and renewal services. CM and SM connect here to obtain and refresh their TLS credentials.
- Protected API (inbound gRPC): Exposes provisioning operations, Node controller functions, and certificate management. Used during initial Unit provisioning and Node registration.
- Node Controller: Manages the registration and lifecycle of Nodes within the Unit — tracks which Nodes are active and their certificate status.
Message Proxy (MP)
The Message Proxy enables multi-Node Units by bridging communication between Secondary Nodes and the Main Node's Communication Manager. It runs only on Secondary Nodes.
Process: aos_messageproxy
Subcomponents
| Module | Responsibility |
|---|---|
cmclient | Client interface to CM — connects to the Main Node's CM to relay messages on behalf of the Secondary Node's components |
communication | Manages the inter-node transport layer — supports multiple transport backends including Xen vchan (for Xen-based virtualization) and socket-based communication; handles secure channel establishment and message routing |
filechunker | Handles large file transfers — splits files into chunks for reliable transfer across the inter-node transport |
imageunpacker | Processes received service images — unpacks OCI image layers received from the Main Node for local SM consumption |
logprovider | Forwards logs to CM — collects logs from the local Node and archives them for transmission to the Main Node |
iamclient | Client interface to IAM — obtains TLS credentials for securing inter-node communication |
config | MP process configuration loading and validation |
Key Interfaces
- CM (outbound, inter-node transport): MP connects to the Main Node's CM through the inter-node transport (vchan or socket). It relays desired-state commands to the local SM and forwards status/telemetry back to CM.
- SM (local): MP provides the local SM with image data (unpacked layers) and forwards CM commands to it.
- IAM (outbound gRPC): MP obtains certificates from the local IAM instance for securing its transport connections.
Inter-Component Communication Patterns
gRPC Communication
All local inter-component communication uses gRPC with Protocol Buffers, defined in the
aos_core_api repository:
| Proto Package | Latest Version | Purpose |
|---|---|---|
servicemanager | v5 | SM ↔ CM interface — instance management, status reporting, monitoring |
iamanager | v5/v6 | IAM public and protected APIs — certificates, provisioning, node management |
communicationmanager | v3 | Update scheduler interface — external update manager integration |
All gRPC connections are secured with mutual TLS (mTLS). Each component obtains its certificates from the local IAM instance.
Cloud Communication
The CM-to-cloud connection uses a WebSocket-based JSON protocol (not gRPC):
- Service Discovery: CM sends an HTTPS request to the configured service discovery URL to obtain the cloud WebSocket endpoint
- WebSocket Connection: CM establishes a persistent WebSocket connection to AosCloud
- JSON Messages: All cloud protocol messages are JSON-encoded with transaction IDs for request-response correlation and acknowledgment tracking
- Reconnection: CM implements exponential backoff reconnection with configurable timeouts
Inter-Node Communication
On multi-Node Units, the Message Proxy provides the transport between Nodes:
- Transport backends: Xen vchan (for Xen hypervisor environments) or TCP sockets (for other configurations)
- Secure channels: TLS-encrypted communication channels authenticated with IAM-issued certificates
- Message routing: MP multiplexes multiple logical channels (CM channel, IAM channel) over a single transport connection
Build Configuration
Each component can be independently included or excluded from the build using CMake options:
-DWITH_CM=ON|OFF # Communication Manager
-DWITH_SM=ON|OFF # Service Manager
-DWITH_IAM=ON|OFF # Identity and Access Manager
-DWITH_MP=ON|OFF # Message Proxy
This allows building Node-specific images — for example, a Main Node image with CM+SM+IAM (no MP), or a Secondary Node image with SM+IAM+MP (no CM).
Related Pages
- Architecture — section overview and component summary table
- Communication Manager — detailed CM documentation
- Service Manager — detailed SM documentation
- Identity and Access Manager — detailed IAM documentation
- Message Proxy — detailed MP documentation
- Unit and Node Model — how Units and Nodes relate
- Key Concepts — terminology and foundational concepts