Node Configuration

Introduction

This page documents the Node configuration — the static configuration section within the IAM (Identity and Access Manager) configuration file that defines a Node's identity and hardware discovery parameters. This configuration is read at IAM startup and determines how the Node identifies itself to the rest of the AosEdge system.

The Node configuration is distinct from the Unit Configuration, which is a cloud-managed document defining operational policies. The Node configuration is a local, static file set during provisioning and not modified at runtime by the system.

For an architectural explanation of how Node identity is established and reported, see Node Identity.

Configuration Location

The Node configuration is embedded within the IAM component's JSON configuration file as the nodeInfo object. The IAM configuration file is typically named aos_iamanager.json and placed on the filesystem during provisioning.

{
  "nodeInfo": {
    /* Node identity and hardware discovery fields */
  },
  /* ... other IAM configuration sections ... */
}

The IAM reads this file at startup and uses the nodeInfo section to initialize the CurrentNode handler, which collects and reports the Node's identity to the Main Node.

NodeInfo Fields

The nodeInfo object contains the following fields:

Field	Type	Required	Default	Description
nodeIDPath	string	No	/etc/machine-id	Path to the file containing the Node's unique identifier. The first line of this file is used as the Node ID.
nodeName	string	Yes	—	Human-readable name for this Node (reported as the Node title).
nodeType	string	Yes	—	Classification of the Node's role within the Unit (e.g., "main", "secondary"). Used for Node group matching in Unit configuration.
maxDMIPS	integer (uint64)	Yes	—	Maximum processing capacity of this Node in Dhrystone MIPS. Used by the scheduler for service placement decisions.
cpuInfoPath	string	No	/proc/cpuinfo	Path to the file containing CPU information. Parsed to discover CPU model, core count, and architecture.
memInfoPath	string	No	/proc/meminfo	Path to the file containing memory information. Parsed to discover total RAM available on this Node.
provisioningStatePath	string	No	/var/aos/.provisionstate	Path to the file where the Node's provisioning state is persisted.
architecture	string	No	Not set	CPU architecture override (e.g., "arm64", "amd64"). If set, overrides the architecture discovered from cpuInfoPath.
architectureVariant	string	No	Not set	CPU architecture variant (e.g., "v8", "v7"). Applied to all CPUs discovered from cpuInfoPath.
os	string	No	Not set	Operating system type (e.g., "linux"). Reported as part of Node identity.
osVersion	string	No	Not set	Operating system version string (e.g., "5.15.0"). Reported alongside the OS type.
attrs	object	No	{}	Key-value map of custom Node attributes. Used for scheduling labels and Node classification.
partitions	array	No	[]	Array of partition definitions describing storage volumes available on this Node.

Partition Configuration

Each entry in the partitions array defines a storage partition that the Node reports as available:

Field	Type	Required	Description
name	string	Yes	Logical name for this partition (e.g., "services", "state", "rootfs").
types	array of strings	No	Classification tags for this partition (e.g., ["services"], ["state", "layers"]). Used by the scheduler to match service storage requirements to available partitions.
path	string	Yes	Filesystem path to the partition mount point. The system queries this path to determine the partition's total size.

At startup, the IAM queries each partition's mount point to determine its total size using filesystem statistics. If a partition path is not mounted or inaccessible, the total size is reported as zero with a warning logged.

Node ID Discovery

The Node ID is read from the file specified by nodeIDPath (default: /etc/machine-id). The first line of this file is used as the Node's unique identifier within the Unit.

This file-based approach allows the Node ID to be:

• Set during image provisioning (baked into the filesystem image)
• Generated at first boot (e.g., by systemd-machine-id-setup)
• Assigned by hardware-specific tooling during manufacturing

The Node ID must be unique within the Unit. If two Nodes report the same ID, the system cannot distinguish between them.

Provisioning State

The provisioning state file (at provisioningStatePath) persists the Node's current state across restarts. The file contains a single string value representing the state:

State	File Content	Meaning
unprovisioned	File does not exist	Node has not been provisioned — no certificates or identity established
provisioned	"provisioned"	Node is fully provisioned with valid certificates
paused	"paused"	Node is provisioned but temporarily suspended

If the provisioning state file cannot be read (parse error), the Node enters the error state.

When the Node transitions to unprovisioned, the provisioning state file is deleted. For all other states, the file is created or overwritten with the state string.

Hardware Discovery

The IAM uses the configured paths to discover hardware capabilities at startup:

CPU Discovery

The cpuInfoPath file (default: /proc/cpuinfo) is parsed to extract:

• CPU model name
• Number of CPU cores
• Architecture information (can be overridden by the architecture and architectureVariant fields)

If the architecture field is set in configuration, it overrides the architecture discovered from the CPU info file for all CPUs. Similarly, architectureVariant is applied to all discovered CPUs.

Memory Discovery

The memInfoPath file (default: /proc/meminfo) is parsed to extract the total RAM available on the Node. This value is reported as part of the Node's identity and used by the scheduler for memory-aware placement.

Partition Size Discovery

For each partition in the partitions array, the system queries the filesystem at the specified path to determine the total size of the mounted filesystem. This provides the scheduler with accurate storage capacity information.

Complete Example

A full nodeInfo configuration with all fields populated:

{
  "nodeInfo": {
    "cpuInfoPath": "/proc/cpuinfo",
    "memInfoPath": "/proc/meminfo",
    "nodeIDPath": "/etc/machine-id",
    "nodeName": "Main Node",
    "nodeType": "main",
    "maxDMIPS": 10000,
    "architecture": "arm64",
    "architectureVariant": "v8",
    "os": "linux",
    "osVersion": "5.15.0",
    "provisioningStatePath": "/var/aos/.provisionstate",
    "attrs": {
      "MainNode": "true",
      "AosComponents": "cm,sm,iam"
    },
    "partitions": [
      {
        "name": "services",
        "types": ["services"],
        "path": "/var/aos/services"
      },
      {
        "name": "state",
        "types": ["state", "layers"],
        "path": "/var/aos/state"
      },
      {
        "name": "rootfs",
        "path": "/"
      }
    ]
  }
}

Minimal Example

A valid nodeInfo configuration with only required fields (all others use defaults):

{
  "nodeInfo": {
    "nodeName": "Secondary Node",
    "nodeType": "secondary",
    "maxDMIPS": 5000
  }
}

With this minimal configuration:

• Node ID is read from /etc/machine-id
• CPU info is read from /proc/cpuinfo
• Memory info is read from /proc/meminfo
• Provisioning state is stored at /var/aos/.provisionstate
• No custom attributes or partitions are defined
• Architecture and OS information are not reported

Field Name Case Sensitivity

All field names in the IAM configuration JSON are parsed case-insensitively. For example, "nodeIDPath", "NodeIDPath", and "NODEIDPATH" are all equivalent. The canonical form uses camelCase as shown in the examples above.

Relationship to Other Configuration

The Node configuration interacts with other parts of the AosCore configuration system:

Configuration	Relationship
Unit Configuration	The nodeType field determines which Unit configuration entry applies to this Node (matched via nodeGroupSubject.codename).
SM nodeConfigFile	The Service Manager stores the cloud-managed per-Node configuration (alert rules, resource ratios, labels, priority) at this path (default: {workingDir}/aos_node.cfg). This is a different file from the IAM's static Node identity configuration.
SM resourcesConfigFile	Hardware resource definitions consumed by the SM (default: /etc/aos/resources.cfg). Complements the partition information in nodeInfo.

Related Pages

• Node Identity — architectural overview of how Node identity is established and reported
• Unit Configuration — cloud-managed per-Unit policies that reference Node types
• Configuration Reference — overview of the AosCore configuration system
• Unit and Node Model — the hierarchical relationship between Units and Nodes
• Service Scheduling and Placement — how Node attributes and capacity influence service placement
• Identity and Access Manager — the IAM component that consumes this configuration