Service Lifecycle

Introduction

This section documents the complete lifecycle of services within AosCore — from the moment a desired-state update arrives from AosCloud through scheduling, image deployment, runtime execution, monitoring, and eventual removal. Understanding the service lifecycle is essential for OEMs integrating with AosEdge, as it governs how workloads are deployed, managed, and updated on Units in the field.

The service lifecycle is a collaborative process between the Communication Manager (CM) and Service Manager (SM). CM receives the desired state from the cloud and determines what should run and where. SM on each Node handles the actual image acquisition, container setup, execution, and monitoring of service instances.

Lifecycle Overview

A service progresses through the following high-level stages:

Stage	Component	Description
Desired-state reception	CM	Cloud sends a desired-state message specifying which Deployable Items and Instances should be active
Scheduling and placement	CM	CM determines which Node should run each Instance based on runtime capabilities, resource capacity, labels, and priority
Image deployment	SM	SM downloads, verifies, and stores the OCI service image and its layers
Instance launch	SM	SM configures networking, storage, and resource limits, then starts the service using the appropriate runtime
Runtime monitoring	SM	SM monitors CPU, RAM, disk, and network usage; generates alerts when thresholds are exceeded
State reporting	SM → CM	SM reports instance states back to CM, which aggregates and forwards status to the cloud
Update or removal	CM → SM	When a new desired state arrives, CM instructs SM to stop outdated instances and start new ones

Desired-State Reconciliation

AosCore operates on a declarative desired-state model. Rather than receiving imperative commands ("start service X"), the system receives a complete description of what should be running and continuously reconciles toward that target.

When CM receives a new desired state from AosCloud, it:

1. Compares the desired state against the current running state
2. Determines which Deployable Items need to be downloaded or removed
3. Schedules Instances to Nodes based on placement constraints
4. Sends UpdateInstances commands to each Node's SM with the list of instances to start and stop
5. Monitors progress and reports the overall status back to the cloud

This reconciliation loop ensures that the Unit converges to the desired state even after failures, restarts, or network interruptions.

Service Instance States

Each service instance on a Node transitions through a defined set of states managed by the Service Manager:

State	Description
Activating	Instance is being prepared — image layers are being set up, networking configured, and the runtime is starting the process
Active	Instance is running normally and passing health checks
Inactive	Instance has been stopped gracefully (e.g., removed from desired state)
Failed	Instance encountered an error — the runtime process exited unexpectedly or a resource limit was exceeded

At the CM level, instances are tracked with a broader lifecycle perspective:

State	Description
Active	Instance is scheduled and should be running on a Node
Disabled	Instance exists but is intentionally not running
Cached	Instance data is retained locally but the instance is not part of the current desired state

Runtime Types

The Service Manager supports multiple runtime types through a pluggable runtime interface. Each runtime determines how a service instance is executed on the Node:

• Container runtime — runs services as OCI containers with namespace isolation, cgroup resource limits, and dedicated network namespaces
• Rootfs runtime — runs services directly on a prepared root filesystem without full container isolation
• Boot runtime — manages services that are started as part of the system boot process

The runtime assigned to an instance depends on the Node's available runtimes (reported in RuntimeInfo during SM registration) and the service's requirements.

Storage and State Management

Services can have two types of persistent storage:

• Storage path — writable storage for the service instance, preserved across restarts but cleared on service removal
• State path — persistent state that survives service updates, allowing services to maintain data across version upgrades

The SM manages these paths per-instance, ensuring proper isolation between instances and cleanup when instances are permanently removed.

Section Contents

This section covers the service lifecycle in detail across the following pages:

• Desired State Model — how the desired-state reconciliation works, including the data structures and convergence logic

• Scheduling and Placement — how CM assigns instances to Nodes based on capabilities, resources, labels, and priority

• Image Deployment Pipeline — the end-to-end flow from image download through verification to local storage

• Runtime Types — detailed documentation of each supported runtime and their characteristics

• Service Instance States — complete state machine with all transitions and triggers

• Storage State — how service storage and state paths are managed across updates and restarts

Related Pages

• Key Concepts — definitions of Service, Instance, Deployable Item, and other core terms
• Architecture Overview — how CM and SM interact at the system level
• Service Manager — SM component architecture and submodules
• Deployment Flows — the broader update flow including SOTA and FOTA