Unit Configuration

Introduction

The Unit Configuration module (unitconfig) within the Communication Manager is responsible for managing the Unit-level configuration that defines per-Node settings such as alert rules, resource ratios, labels, and scheduling priority. This configuration arrives from AosCloud as part of the desired-state flow, is persisted locally as a JSON file, and is distributed to each Node in the Unit.

This page covers the configuration format, the lifecycle of a configuration update, version management, and how per-Node configuration is resolved and distributed.

Role and Responsibilities

The unitconfig module handles four primary responsibilities:

1. Loading — reads the persisted Unit configuration JSON file at startup
2. Checking — validates an incoming configuration update (version comparison, per-Node validation) before applying it
3. Updating — persists the new configuration to disk and distributes per-Node configuration to all Nodes
4. Providing — serves per-Node configuration to other CM modules on demand

The module implements two interfaces consumed by other CM components:

Interface	Purpose
UnitConfigItf	Check, update, and query the status of the Unit configuration
NodeConfigProviderItf	Retrieve the resolved configuration for a specific Node

Configuration Format

The Unit configuration is a JSON document with the following top-level structure:

{
  "formatVersion": "7",
  "version": "2.0.0",
  "nodes": [
    { /* per-node configuration */ }
  ]
}

Top-Level Fields

Field	Type	Description
formatVersion	string	Schema version of the configuration format
version	string	Semantic version of this configuration instance (used for update ordering)
nodes	array	Array of per-Node configuration objects

Per-Node Configuration

Each entry in the nodes array defines configuration for a specific Node or Node type:

{
  "version": "1.0.0",
  "node": {
    "codename": "node-1"
  },
  "nodeGroupSubject": {
    "codename": "mainType"
  },
  "alertRules": { /* ... */ },
  "resourceRatios": { /* ... */ },
  "labels": ["mainNode"],
  "priority": 1
}

Field	Type	Required	Description
node	object	No	Identifies a specific Node by its codename (Node ID). If omitted, the entry applies by Node type.
nodeGroupSubject	object	Yes	Identifies the Node type (group) this configuration applies to
version	string	No	Per-Node configuration version
alertRules	object	No	Alert threshold definitions for this Node
resourceRatios	object	No	Resource allocation ratios for service scheduling
labels	array of strings	No	Labels assigned to this Node for scheduling and identification
priority	integer	No	Node priority for service placement (higher value = higher priority)

Node Resolution Logic

When resolving configuration for a specific Node, the module uses the following precedence:

1. Match by Node ID — if a nodes entry has a node.codename matching the target Node ID, that entry is used
2. Match by Node type — if no ID match is found, the first entry whose nodeGroupSubject.codename matches the Node's type is used
3. Default — if neither matches, an empty configuration is returned with the Unit config version and the target Node ID set

This allows operators to define type-level defaults while overriding specific Nodes when needed.

Alert Rules

The alertRules object defines monitoring thresholds that trigger alerts:

{
  "alertRules": {
    "ram": {
      "minTimeout": "PT1S",
      "minThreshold": 0.1,
      "maxThreshold": 0.9
    },
    "cpu": {
      "minTimeout": "PT2S",
      "minThreshold": 0.3,
      "maxThreshold": 0.8
    },
    "partitions": [
      {
        "name": "services",
        "minTimeout": "PT3S",
        "minThreshold": 0.5,
        "maxThreshold": 0.9
      }
    ],
    "download": {
      "minTimeout": "PT5S",
      "minThreshold": 100,
      "maxThreshold": 200
    },
    "upload": {
      "minTimeout": "PT6S",
      "minThreshold": 300,
      "maxThreshold": 400
    }
  }
}

Rule	Threshold Type	Description
ram	Percentage (0.0–1.0)	RAM usage alert thresholds
cpu	Percentage (0.0–1.0)	CPU usage alert thresholds
partitions	Percentage (0.0–1.0)	Per-partition disk usage thresholds (identified by name)
download	Points (bytes/sec)	Download bandwidth alert thresholds
upload	Points (bytes/sec)	Upload bandwidth alert thresholds

Each rule includes:

• minTimeout — minimum duration (ISO 8601 duration format) the metric must exceed the threshold before an alert fires
• minThreshold — lower bound; crossing below this clears the alert
• maxThreshold — upper bound; crossing above this triggers the alert

Resource Ratios

The resourceRatios object defines how resources are proportioned for service scheduling on this Node:

{
  "resourceRatios": {
    "cpu": 50,
    "ram": 51,
    "storage": 52,
    "state": 53
  }
}

Field	Description
cpu	CPU allocation ratio
ram	RAM allocation ratio
storage	Storage allocation ratio
state	State storage allocation ratio

These ratios are used by the service scheduler to determine how much of each resource type is available for service instances on a given Node.

Configuration Lifecycle

Startup (Load)

At initialization, the module reads the Unit configuration from the file path specified in the CM configuration (aos_cm.cfg). Three outcomes are possible:

Outcome	Resulting State	Behavior
File exists and parses successfully	installed	Configuration is active and ready for distribution
File does not exist	absent	No configuration is active; the module waits for a cloud-pushed update
File exists but fails to parse	failed	Error is recorded; the module cannot distribute configuration until a valid update arrives

Check (Pre-validation)

Before applying a new configuration, the CheckUnitConfig operation validates it:

1. Version comparison — the new version must be strictly greater than the current version (semantic versioning). Same or lower versions are rejected.
2. Per-Node validation — for each Node in the Unit, the module resolves the applicable Node configuration from the new config and delegates validation to the NodeConfigHandler (which forwards the check to the target Node's SM instance).

If the current state is not installed (e.g., absent or failed), the version check is skipped to allow recovery from a broken state.

Update (Apply)

When UpdateUnitConfig is called with a validated configuration:

1. The version is verified (same rules as check, skipped if state is absent)
2. The new configuration is serialized to JSON and written to the local file (permissions: 0600)
3. The state transitions to installed
4. For each registered Node, the module resolves the applicable per-Node configuration and pushes it via the NodeConfigHandler

Node Info Change (Reactive Distribution)

The module subscribes to Node state change notifications via the NodeInfoProvider. When a Node's information changes (e.g., a Node reconnects or registers):

1. If the Unit config state is not installed, the update is skipped
2. The module checks the Node's current config version against the Unit config version
3. If the versions differ (or the Node has an error state), the resolved per-Node configuration is pushed to that Node

This ensures that Nodes that were offline during a configuration update receive the latest configuration when they reconnect.

Version Management

Unit configuration uses semantic versioning (semver) for ordering:

• Updates must have a strictly higher version than the currently installed configuration
• Attempting to apply the same version returns an "already exists" error
• Attempting to apply a lower version returns a "wrong state" error
• Pre-release versions (e.g., 1.0.0-alpha) are compared according to semver rules

This prevents configuration rollback and ensures monotonic progression of the configuration state.

Status Reporting

The module reports its status through GetUnitConfigStatus, which returns:

Field	Description
version	The currently installed configuration version (empty if absent)
state	One of: absent, installed, failed
error	Error details (populated only when state is failed)

This status is included in the Unit status reports sent to AosCloud, allowing the cloud to track which configuration version each Unit is running.

Integration with Other CM Modules

The unitconfig module interacts with several other CM components:

┌─────────────────────────────────────────────────────────┐
│                  Communication Manager                   │
│                                                         │
│  ┌──────────────┐     ┌──────────────────────────────┐ │
│  │ Cloud Comms  │────▶│        Unit Config            │ │
│  │ (desired     │     │                              │ │
│  │  state)      │     │  ┌────────┐  ┌───────────┐  │ │
│  └──────────────┘     │  │ JSON   │  │ Version   │  │ │
│                       │  │Provider│  │ Manager   │  │ │
│  ┌──────────────┐     │  └────────┘  └───────────┘  │ │
│  │ Node Info    │────▶│                              │ │
│  │ Provider     │     │  ┌────────────────────────┐  │ │
│  └──────────────┘     │  │  Node Config Resolver  │  │ │
│                       │  └────────────────────────┘  │ │
│  ┌──────────────┐     └──────────────┬───────────────┘ │
│  │ SM Controller│◀───────────────────┘                  │
│  │ (distributes │     (per-node config)                 │
│  │  to Nodes)   │                                       │
│  └──────────────┘                                       │
└─────────────────────────────────────────────────────────┘

Component	Interaction
Cloud Communication	Delivers new Unit configuration from AosCloud desired-state messages
Node Info Provider	Supplies the list of registered Nodes and their types; notifies when Node state changes
SM Controller (via NodeConfigHandler)	Receives per-Node configuration and distributes it to the appropriate SM instance on each Node
Other CM modules (via NodeConfigProviderItf)	Query resolved per-Node configuration (e.g., for resource scheduling decisions)

Related Pages

• Communication Manager — parent overview of all CM subcomponents
• Architecture Overview — high-level view of all AosCore components
• Update Manager — how CM processes desired-state updates (which include configuration)

• SM Controller — how CM distributes commands (including config) to SM instances

• Key Concepts — terminology including Unit, Node, and Verification
• Unit and Node Model — the hierarchical relationship between Units and Nodes