Node Identity

Introduction

Every Node in an AosEdge Unit must establish and maintain a unique identity. This identity enables the system to distinguish Nodes from one another, route operations to the correct Node, track provisioning state, and report hardware capabilities to the cloud.

Node identity in AosCore is managed by two cooperating subsystems within the Identity and Access Manager (IAM):

• CurrentNode handler — runs on every Node and collects the local Node's identity information (Node ID, type, hardware capabilities, provisioning state)
• Node Manager — runs on the Main Node and maintains a registry of all Nodes in the Unit, tracking their state and connectivity

This page describes how a Node's identity is established at startup, what information constitutes that identity, how it is reported to the Main Node, and how the system-level identity (system ID and unit model) relates to per-Node identity.

Node Identity Components

A Node's identity is represented by the NodeInfo structure, which combines static configuration with dynamically discovered hardware information:

Field	Source	Description
node_id	Configuration file	Unique identifier for this Node within the Unit
node_type	Configuration file	Classification of the Node's role (e.g., "main", "secondary")
title	Configuration file	Human-readable Node name
max_dmips	Configuration file	Maximum processing capacity (Dhrystone MIPS)
total_ram	System discovery (/proc/meminfo)	Total RAM available on this Node
os_info	Configuration file	Operating system type and version
cpus[]	System discovery (/proc/cpuinfo) + config	CPU model, cores, threads, architecture
partitions[]	Configuration + filesystem query	Storage partitions with names, types, and total sizes
attrs[]	Configuration file	Key-value attributes (e.g., MainNode, AosComponents)
state	Provisioning status file	Current Node state (unprovisioned, provisioned, paused, error)
is_connected	Runtime state	Whether the Node is currently reachable by the Main Node

The node_id is the primary identifier. It is read from a dedicated file on the filesystem (path specified in configuration as nodeIDPath). This file-based approach allows the Node ID to be set during image provisioning or hardware setup, independent of the IAM configuration itself.

CurrentNode Handler

The CurrentNode handler (currentnode::CurrentNodeHandler) is responsible for collecting and providing the local Node's identity information. It runs on every Node in the Unit.

Initialization

At startup, the CurrentNode handler initializes the Node's identity by:

1. Reading the Node ID from the file specified by nodeIDPath in the configuration
2. Setting static fields from configuration — Node type, title, max DMIPS
3. Discovering total RAM by reading the system memory information file (typically /proc/meminfo)
4. Collecting CPU information from the system CPU info file (typically /proc/cpuinfo), enriched with architecture and variant from configuration
5. Setting OS information from configuration (OS type and version)
6. Loading custom attributes from configuration (key-value pairs)
7. Enumerating partitions from configuration, querying the filesystem for each partition's total size
8. Reading provisioning state from the provisioning status file — if the file does not exist, the Node is considered unprovisioned

State Management

The CurrentNode handler tracks two mutable aspects of Node identity:

• Provisioning state — transitions between unprovisioned, provisioned, paused, and error. State changes are persisted to the provisioning status file so they survive restarts.
• Connected state — indicates whether the Node is currently connected to the Main Node's IAM. This is a runtime-only state (not persisted).

When either state changes, the handler notifies all registered listeners. The IAM client (on Secondary Nodes) subscribes to these notifications to report state changes to the Main Node.

Listener Pattern

Other IAM components subscribe to Node info changes through the listener interface:

CurrentNodeHandler
    ├── GetCurrentNodeInfo()     → returns current NodeInfo snapshot
    ├── SetState(state)          → updates provisioning state, notifies listeners
    ├── SetConnected(connected)  → updates connectivity, notifies listeners
    ├── SubscribeListener(...)   → registers for change notifications
    └── UnsubscribeListener(...) → removes listener registration

The IAM client is the primary listener — when Node info changes, it sends the updated information to the Main Node's IAM through the RegisterNode stream.

System Identity

System identity is distinct from Node identity. While Node identity identifies a specific computing element, system identity identifies the Unit as a whole:

Field	Description
system_id	Unique identifier for the entire Unit (established during provisioning)
unit_model	Hardware platform model designation (e.g., a product SKU)
version	System version string

System identity is provided by the identifier module — a pluggable component within IAM. Two identifier plugins are supported:

File Identifier

The file identifier reads system identity from local files:

• systemIDPath — file containing the system ID
• unitModelPath — file containing the unit model (optionally with version, separated by ;)
• subjectsPath — file containing subject claims

This plugin is used in non-automotive deployments where identity is statically provisioned on the filesystem.

VIS Identifier

The VIS (Vehicle Information Service) identifier connects to a VIS server via WebSocket and retrieves identity from vehicle data paths:

• Attribute.Vehicle.VehicleIdentification.VIN — used to derive the system ID
• Attribute.Aos.UnitModel — provides the unit model
• Attribute.Aos.Subjects — provides subject claims (subscribed for runtime changes)

This plugin is used in automotive deployments where the vehicle's VIN serves as the system identity anchor. If no VIN is available, the VIS identifier generates a UUID as the system ID.

Subjects

In addition to static identity, the identifier module manages subjects — a set of identity claims associated with the Unit that can change at runtime. Subjects represent group or user associations (e.g., fleet membership, owner identity) and are reported to the cloud as part of the Unit's identity. When subjects change, all subscribed listeners are notified.

Node Registration with Main Node IAM

In a multi-Node Unit, Secondary Nodes register their identity with the Main Node's IAM through a bidirectional gRPC streaming connection.

Registration Flow

1. The Secondary Node's IAM client establishes a RegisterNode bidirectional stream to the Main Node's IAMPublicNodesService
2. Upon connection, the IAM client sends the local NodeInfo as the first message on the stream
3. The Main Node's Node Controller receives the NodeInfo, extracts the node_id, and links the stream handler to that Node ID
4. The Main Node's Node Manager stores the Node information (in cache and persistent storage) and notifies listeners of the new or updated Node
5. The Node Manager marks the Node as connected

Ongoing Communication

Once registered, the bidirectional stream serves two purposes:

• Outgoing (Secondary → Main): The Secondary Node sends updated NodeInfo whenever its state changes (provisioning state transitions, connectivity changes)
• Incoming (Main → Secondary): The Main Node forwards operations to the Secondary Node — provisioning requests, key creation, certificate application, pause/resume commands

Disconnection Handling

When a Secondary Node disconnects:

• The Node Controller detects the stream closure and unlinks the handler
• The Node Manager marks the Node as disconnected (is_connected = false)
• The Node's information remains in the registry (it is not removed)
• The IAM client on the Secondary Node attempts to reconnect at a configurable interval (nodeReconnectInterval)

Node Manager Storage

The Main Node's Node Manager persists Node registrations to a local database. This ensures that:

• Node information survives Main Node restarts
• The system knows which Nodes belong to the Unit even if they are temporarily disconnected
• Connection state is not persisted (always starts as disconnected on restart)
• Unprovisioned Nodes are removed from storage (they re-register when provisioned)

Node States and Transitions

A Node's provisioning state follows this lifecycle:

┌─────────────────┐
│  unprovisioned  │ ← Initial state (no provisioning file exists)
└────────┬────────┘
         │ Provisioning completes
         ▼
┌─────────────────┐
│   provisioned   │ ← Normal operational state
└────────┬────────┘
         │ PauseNode RPC        │ Error condition
         ▼                      ▼
┌─────────────────┐    ┌─────────────────┐
│     paused      │    │      error      │
└────────┬────────┘    └─────────────────┘
         │ ResumeNode RPC
         ▼
┌─────────────────┐
│   provisioned   │
└─────────────────┘

State transitions are triggered by:

• Provisioning — moves from unprovisioned to provisioned (managed by the provisioning workflow)
• Pause/Resume — the cloud can pause a Node (preventing new workloads) and resume it via the IAMNodesService RPCs
• Deprovisioning — moves back to unprovisioned (removes the provisioning status file and clears storage)
• Error — set when the Node encounters an unrecoverable error during state initialization

Configuration

Node identity is configured in the IAM configuration file (aos_iamanager.cfg). The relevant section:

Parameter	Description
nodeIDPath	Path to the file containing the Node ID
nodeType	Node type classification string
nodeName	Human-readable Node title
maxDMIPS	Maximum DMIPS capacity
cpuInfoPath	Path to CPU information (e.g., /proc/cpuinfo)
memInfoPath	Path to memory information (e.g., /proc/meminfo)
provisioningStatePath	Path to the provisioning state persistence file
architecture	CPU architecture override (e.g., arm64)
architectureVariant	CPU architecture variant (e.g., v8)
os	Operating system type (e.g., linux)
osVersion	Operating system version
attrs	Map of custom Node attributes
partitions[]	Array of partition definitions (name, types, path)

gRPC API for Node Identity

Node identity is exposed through the following gRPC services:

IAMPublicCurrentNodeService (local)

Available on every Node's public IAM server:

RPC	Description
GetCurrentNodeInfo	Returns the current Node's NodeInfo
SubscribeCurrentNodeChanged	Server-streaming RPC that pushes NodeInfo updates

IAMPublicNodesService (Main Node)

Available on the Main Node's public IAM server:

RPC	Description
GetAllNodeIDs	Returns IDs of all registered Nodes
GetNodeInfo	Returns NodeInfo for a specific Node by ID
SubscribeNodeChanged	Server-streaming RPC that pushes Node changes
RegisterNode	Bidirectional stream for Secondary Node registration

IAMNodesService (Main Node, protected)

Available on the Main Node's protected IAM server:

RPC	Description
PauseNode	Pauses a Node (transitions to paused state)
ResumeNode	Resumes a paused Node (transitions back to provisioned)

Related Pages

• Identity and Access Manager — IAM component overview and architecture
• Certificate Handler — per-Node certificate lifecycle management

• Provisioning and Enrollment — how Nodes establish their initial cryptographic identity

• Unit and Node Model — Unit and Node hierarchy, Node attributes, and component distribution
• Architecture Overview — system-wide component relationships
• Multi-Node Architecture — how multiple Nodes coordinate within a Unit