Version: v1.1

Unit Configuration

Introduction

This page is the reference for the cloud-managed Unit configuration document. The Unit configuration is a versioned JSON file pushed from AosCloud to the Communication Manager, defining per-Node operational policies such as alert thresholds, resource allocation ratios, labels, and scheduling priority.

For an architectural explanation of how the CM loads, validates, and distributes this configuration, see CM Unit Configuration.

JSON Schema

The Unit configuration is a JSON object with three top-level fields:

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

Top-Level Fields

Field	Type	Required	Description
`formatVersion`	string	Yes	Schema version of the configuration format. Identifies which fields and structure the document uses.
`version`	string	Yes	Semantic version of this configuration instance. Used for update ordering — each update must have a strictly higher version than the currently installed one.
`nodes`	array	No	Array of per-Node configuration objects. If omitted or empty, no Node-specific policies are applied.

Node Configuration Entry

Each element 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	Default	Description
`nodeGroupSubject`	object	Yes	—	Identifies the Node type (group) this entry applies to. Must contain a `codename` string field.
`node`	object	No	—	Identifies a specific Node by ID. Contains a `codename` string field matching the Node's ID. When present, this entry takes precedence over type-based matching.
`version`	string	No	`""`	Per-Node configuration version string.
`alertRules`	object	No	Not set	Alert threshold definitions for monitoring on this Node. See Alert Rules.
`resourceRatios`	object	No	Not set	Resource allocation ratios for service scheduling. See Resource Ratios.
`labels`	array of strings	No	`[]`	Labels assigned to this Node for scheduling and identification purposes.
`priority`	integer (uint64)	No	`0`	Node priority for service placement. Higher values indicate higher priority.

Identity Fields

The node and nodeGroupSubject fields use the same structure — an object with a codename field:

{
  "codename": "identifier-string"
}

node.codename — matches the Node's unique ID within the Unit
nodeGroupSubject.codename — matches the Node's type classification

Alert Rules

The alertRules object defines monitoring thresholds that trigger alerts when resource usage crosses defined boundaries. All fields are optional — only the rules you define are active.

{
  "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
    }
  }
}

Percentage-Based Rules (ram, cpu, partitions)

These rules use fractional thresholds (0.0–1.0) representing resource utilization percentage:

Field	Type	Required	Default	Description
`minTimeout`	string (ISO 8601 duration)	No	`0` (immediate)	Minimum duration the metric must exceed the threshold before an alert fires. Format: `PT{n}S`, `PT{n}M`, `PT{n}H`.
`minThreshold`	number (double)	Yes	—	Lower bound (0.0–1.0). Crossing below this value clears an active alert.
`maxThreshold`	number (double)	Yes	—	Upper bound (0.0–1.0). Crossing above this value triggers an alert.

For partitions, each entry additionally requires:

Field	Type	Required	Description
`name`	string	Yes	Partition name identifying which disk partition this rule monitors.

Points-Based Rules (download, upload)

These rules use absolute integer thresholds representing data transfer rates:

Field	Type	Required	Default	Description
`minTimeout`	string (ISO 8601 duration)	No	`0` (immediate)	Minimum duration the metric must exceed the threshold before an alert fires.
`minThreshold`	integer (uint64)	Yes	—	Lower bound (bytes/sec). Crossing below this value clears an active alert.
`maxThreshold`	integer (uint64)	Yes	—	Upper bound (bytes/sec). Crossing above this value triggers an alert.

Alert Rule Summary

Rule	Key	Threshold Type	Monitors
RAM	`ram`	Percentage (0.0–1.0)	RAM utilization
CPU	`cpu`	Percentage (0.0–1.0)	CPU utilization
Partitions	`partitions`	Percentage (0.0–1.0)	Per-partition disk usage
Download	`download`	Points (bytes/sec)	Download bandwidth
Upload	`upload`	Points (bytes/sec)	Upload bandwidth

Resource Ratios

The resourceRatios object defines how resources are proportioned for service scheduling on this Node. All fields are optional.

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

Field	Type	Required	Default	Description
`cpu`	number (double)	No	Not set	CPU allocation ratio for service scheduling.
`ram`	number (double)	No	Not set	RAM allocation ratio for service scheduling.
`storage`	number (double)	No	Not set	Storage allocation ratio for service scheduling.
`state`	number (double)	No	Not set	State storage allocation ratio for service scheduling.

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.

Node Resolution Logic

When the Communication Manager needs to resolve configuration for a specific Node, it applies the following precedence:

Match by Node ID — search the nodes array for an entry whose node.codename matches the target Node's ID. If found, use that entry.
Match by Node type — if no ID match exists, search for the first entry whose nodeGroupSubject.codename matches the target Node's type. If found, use that entry.
Default — if neither matches, an empty NodeConfig is returned (no alert rules, no resource ratios, no labels, priority 0).

In all cases, the resolved configuration has its version set to the Unit config's top-level version and its Node ID set to the target Node's actual ID.

This resolution strategy allows operators to:

Define type-level defaults that apply to all Nodes of a given type
Override specific Nodes by including an entry with a matching node.codename
Leave Nodes unconfigured (they receive empty defaults) if no matching entry exists

Resolution Example

Given this configuration:

{
  "formatVersion": "7",
  "version": "3.0.0",
  "nodes": [
    {
      "nodeGroupSubject": { "codename": "compute" },
      "priority": 5,
      "labels": ["general"]
    },
    {
      "node": { "codename": "gpu-node-1" },
      "nodeGroupSubject": { "codename": "compute" },
      "priority": 10,
      "labels": ["gpu", "high-perf"]
    }
  ]
}

A Node with ID gpu-node-1 and type compute → resolves to the second entry (ID match, priority 10)
A Node with ID cpu-node-2 and type compute → resolves to the first entry (type match, priority 5)
A Node with ID sensor-1 and type sensor → resolves to empty defaults (no match, priority 0)

Version Management

Unit configuration uses semantic versioning (semver) for ordering updates:

Rule	Behavior
Higher version	Accepted — configuration is updated
Same version	Rejected — returns "already exists" error
Lower version	Rejected — returns "wrong state" error

Version comparison follows standard semver rules, including pre-release version ordering.

Exception: if the current configuration state is absent (no configuration has ever been installed) or failed (the current configuration is corrupt), the version check is skipped. This allows initial installation and recovery from broken states.

Configuration States

The Unit configuration module tracks its state as one of three values:

State	Meaning	Trigger
`absent`	No configuration file exists on disk	Initial state, or file not found at startup
`installed`	Configuration is loaded and active	Successful load at startup, or successful update
`failed`	Configuration file exists but cannot be parsed	Parse error during load at startup

State transitions:

                    ┌──────────────────────────┐
                    │                          │
                    ▼                          │
    ┌─────────┐  load OK   ┌───────────┐  update OK
    │ absent  │───────────▶│ installed │◀──────────┘
    └─────────┘            └───────────┘
         │                       ▲
         │                       │ update OK
         │    ┌────────┐         │
         └───▶│ failed │─────────┘
   load err   └────────┘

Persistence

The Unit configuration is persisted to a local JSON file (default path: {workingDir}/aos_unit.cfg). The file:

Is written with permissions 0600 (owner read/write only)
Contains the complete Unit configuration JSON document
Is read at CM startup to restore the last known configuration
Is overwritten atomically on each successful update

Complete Example

A full Unit configuration with all fields populated:

{
  "formatVersion": "7",
  "version": "2.0.0",
  "nodes": [
    {
      "version": "1.0.0",
      "node": {
        "codename": "node-1"
      },
      "nodeGroupSubject": {
        "codename": "mainType"
      },
      "alertRules": {
        "ram": {
          "minTimeout": "PT1S",
          "minThreshold": 0.1,
          "maxThreshold": 0.2
        },
        "cpu": {
          "minTimeout": "PT2S",
          "minThreshold": 0.3,
          "maxThreshold": 0.4
        },
        "partitions": [
          {
            "name": "partition1",
            "minTimeout": "PT3S",
            "minThreshold": 0.5,
            "maxThreshold": 0.6
          },
          {
            "name": "partition2",
            "minTimeout": "PT4S",
            "minThreshold": 0.6,
            "maxThreshold": 0.7
          }
        ],
        "download": {
          "minTimeout": "PT5S",
          "minThreshold": 100,
          "maxThreshold": 200
        },
        "upload": {
          "minTimeout": "PT6S",
          "minThreshold": 300,
          "maxThreshold": 400
        }
      },
      "resourceRatios": {
        "cpu": 50,
        "ram": 51,
        "storage": 52,
        "state": 53
      },
      "labels": [
        "mainNode"
      ],
      "priority": 1
    },
    {
      "version": "1.0.0",
      "node": {
        "codename": "node-2"
      },
      "nodeGroupSubject": {
        "codename": "secondaryType"
      },
      "labels": [
        "secondaryNode"
      ],
      "priority": 2
    }
  ]
}

Minimal Example

A valid Unit configuration with only required fields:

{
  "formatVersion": "7",
  "version": "1.0.0",
  "nodes": [
    {
      "nodeGroupSubject": {
        "codename": "type1"
      },
      "priority": 0
    }
  ]
}

Field Name Case Sensitivity

All field names in the Unit configuration JSON are parsed case-insensitively. For example, "formatVersion", "FormatVersion", and "FORMATVERSION" are all equivalent. However, the canonical form uses camelCase as shown in the examples above.

CM Unit Configuration — architectural overview of how the CM manages Unit configuration (loading, validation, distribution)
Configuration Reference — overview of the AosCore configuration system
Desired State Model — how Unit configuration is delivered as part of the desired-state flow
Key Concepts — terminology including Unit, Node, and Verification
Unit and Node Model — the hierarchical relationship between Units and Nodes
Alerts and Thresholds — how alert rules are consumed by the monitoring pipeline

Introduction​

JSON Schema​

Top-Level Fields​

Node Configuration Entry​

Identity Fields​

Alert Rules​

Percentage-Based Rules (ram, cpu, partitions)​

Points-Based Rules (download, upload)​

Alert Rule Summary​

Resource Ratios​

Node Resolution Logic​

Resolution Example​

Version Management​

Configuration States​

Persistence​

Complete Example​

Minimal Example​

Field Name Case Sensitivity​

Related Pages​