> For the complete documentation index, see [llms.txt](https://asus-isg-aidc.gitbook.io/guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://asus-isg-aidc.gitbook.io/guide/latest/portal/infrastructureplannerintroduction/nodemanagement.md).

# Node Management

| Developer | Last modified |
| --------- | ------------- |
| AIDC Team | 2026/07/17    |

![Node Management Feature](https://pub-f334ff01208c4e6195b80133ac6e6030.r2.dev/portal/nodeManagement/Node_Management.png)

## Feature Goal

### Aim

The Node Management feature provides a centralized interface for managing system nodes (servers) across the cluster. It enables users to:

* View and monitor all nodes in the system
* Add new nodes individually or import via CSV
* Organize nodes into groups for better management
* Edit node configurations and network settings
* Export node data for backup or reporting
* Manage node groups (create and delete)

### User Story

**As a** system administrator\
**I want** to manage all nodes and their configurations in one place\
**So that** I can efficiently organize, monitor, and maintain the cluster infrastructure

## Feature Description

### 3.1 Location

* **Route**: `/NodeManagement`
* **Navigation Path**:
  * Side Menu: `Deploy` → `Node Management`
* **Access Level**: Requires authenticated user with node management permissions

### 3.2 Reference Feature

**Related Features**:

* **Deployment Overview** (`/DeploymentOverview`): Monitor deployment jobs and node statistics
* **OS Provisioning** (`/OSProvisioning`): Create deployment jobs for nodes
* **Image Management** (`/ImageBuilder`): Build OS images for node deployment

**Dependencies**:

* Node Devices API for CRUD operations
* License activation service for validation
* CSV parser for bulk import

### 3.3 Operation Requirements

**Prerequisites**:

1. User must be authenticated and logged into the system
2. User must have node management permissions
3. Active license (checked on save operations)

**Access Permissions**:

* View nodes and groups
* Add/edit/delete nodes
* Create/delete node groups
* Import/export node data

### 3.4 Operation Flow

**Main Workflow**:

1. **Initial Page Load**
   * System authenticates user
   * Fetches node list with pagination (default: 10 nodes per page)
   * Loads available node groups
   * Displays nodes in grouped table format
2. **Viewing Nodes**
   * User views nodes organized by groups
   * User can expand/collapse group sections
   * User can adjust page size (10/50/100 per page)
   * User navigates through pages using pagination controls
3. **Searching and Filtering**
   * User enters keywords in search bar
   * System filters nodes by: hostname, IP addresses, MAC addresses, model
   * Results update in real-time
   * Table maintains grouping structure
4. **Adding Single Node**
   * User clicks "Modify Nodes" → "Add Nodes"
   * System opens add node dialog with form
   * User fills required fields (Group, Hostname, Model, BMC IP/MAC, Eth0 IP/MAC)
   * User configures NIC Ports, Interface Mapping, and IP addresses as needed
   * User optionally adds password
   * User clicks save
   * System validates and creates node
5. **Importing Multiple Nodes (CSV)**
   * User clicks "Import" button
   * User selects CSV file
   * System parses and validates CSV data
   * System displays preview of nodes to be imported
   * User confirms import
   * System creates all nodes in batch
6. **Editing Node**
   * User clicks action menu (⋮) on node row
   * User selects "Edit"
   * System opens edit dialog with current values
   * User modifies fields (hostname is read-only)
   * User clicks save
   * System validates and updates node
7. **Selecting Multiple Nodes**
   * User clicks checkboxes to select multiple nodes
   * User clicks "Modify Nodes" → "Move to Group"
   * User selects target group from submenu
   * System moves all selected nodes to new group
8. **Creating Node Group**
   * User clicks "Modify Groups" → "Add Group"
   * System opens add group dialog
   * User enters group name
   * System validates name (no special chars, not reserved keyword)
   * User clicks create
   * System creates new group
9. **Deleting Node Groups**
   * User clicks "Modify Groups" → "Delete Groups"
   * System shows list of all groups
   * User clicks delete icon next to group(s)
   * System confirms deletion
   * User clicks save
   * System deletes empty groups
10. **Exporting Node Data**
    * User clicks "Export" button
    * System opens export dialog
    * User enters filename
    * User clicks export
    * System generates CSV file and downloads

### 3.5 UI Review

![Node Management UI Interface](https://pub-f334ff01208c4e6195b80133ac6e6030.r2.dev/portal/nodeManagement/Node_Management_UI_Interface.png)

The Node Management interface consists of a single main section with action buttons:

#### Header Actions

**Import/Export(No.1)**:

* **Import Button**: Upload CSV file to bulk add nodes
* **Export Button**: Download all nodes data as CSV

**Search Bar(No.2)**:

* Search bar supporting multiple keywords
* Real-time filtering across all node fields
* Search matches: Hostname, Serial Number, Model, IP addresses, MAC addresses

**Modify Nodes Menu(No.3)**:

* Add Nodes: Create new node manually
* Move to Group: Relocate selected nodes to different group (submenu shows available groups)

**Modify Groups Menu(No.4)**:

* Add Group: Create new node group
* Delete Groups: Remove existing groups

#### Node Table

**Grouping Header(No.5)**:

* Nodes organized by "Node Group"
* Collapsible group headers showing group name and count
* Visual hierarchy with indentation

**Table Columns**:

* Node Group: Group name
* Hostname: Node hostname
* Serial Number: Hardware serial
* Model: Hardware model
* BMC IP: BMC network address (clickable link)
* BMC MAC: BMC hardware address
* Eth IP 0: Primary ethernet IP
* Eth MAC 0: Primary ethernet MAC
* Status: Node status indicator (see **Status Values** below)
  * **Up**: Reachable and fully verified via SSH
  * **Down**: Unreachable (network timeout)
  * **Unknown**: Reachable but SSH verification failed (e.g. wrong credentials). May still be online.
* Actions: Row menu (⋮) with Edit/Delete options

**Hidden Columns** (available via column Option panel, No.6):

* Additional ethernet interfaces (Eth1-3)
* Bond interfaces (Bond0-3)
* InfiniBand interfaces (IB0-7)

**Features**:

* Row selection with checkboxes
* Column sorting
* Expandable column Options panel

#### Footer Actions(No.7)

* Page size selector (10/50/100 nodes per page)
* Pagination controls showing current page and total pages
* Previous/Next navigation arrows
* Warning indicator when CSV import pending
* Change counter during batch edit mode
* Cancel button (for CSV import)
* Save button (primary action)

### 3.6 Operation & Expected Result

#### Operation 1: View and Navigate Nodes

**Steps**:

1. Navigate to `/NodeManagement`
2. Wait for page to load

**Expected Result**:

* Page displays nodes grouped by node group
* Default page size shows 10 nodes
* Pagination shows current page (e.g., "1 - 5" for 5 total pages)
* Groups are expandable/collapsible

***

#### Operation 2: Search for Nodes

**Steps**:

1. Enter keyword(s) in search bar

**Expected Result**:

* Table filters in real-time
* Matches found in: Hostname, Serial Number, Model, IPs, MACs
* Grouping structure preserved
* Multiple keywords use AND logic

***

#### Operation 3: Add Single Node

![Add Node](https://pub-f334ff01208c4e6195b80133ac6e6030.r2.dev/portal/nodeManagement/Node_Management-Add_Node-1.png)

**Steps**:

1. Click "Modify Nodes" → "Add Nodes" (No.1)
2. Fill in required fields (No.2):
   * Select Node Group
   * Enter Hostname
   * Enter Model
   * Enter BMC IP and MAC
   * Enter Eth0 IP and MAC
3. Optionally enter password and additional network interfaces
4. Click Save (No.3)

**Expected Result**:

* Form validates all required fields
* IP addresses validated (standard IPv4 or CIDR for IB interfaces)
* MAC addresses validated (format: XX:XX:XX:XX:XX:XX)
* Password confirmation must match if provided
* Dialog closes on success
* Node appears in table under selected group
* Success notification displayed

***

#### Operation 3.1: Add NIC Ports, IP & Interface Mapping

**Steps**:

1. In the Add Node or Edit Node dialog, click **Add NIC Port**
2. Enter NIC Port fields:
   * `name` (for example: `eth1`, `ib0`)
   * `card` (for example: `nic1`)
   * `networkType` (`ethernet`, `ib`, `bmc`)
   * `mac` (required, format `XX:XX:XX:XX:XX:XX`)
   * Optional: `formFactor`, `speed`
3. Click **Save** to create the NIC Port entry
4. Click **Add Interface Mapping**
5. Select interface type and binding:
   * `ethernet` or `ib`: bind one NIC Port
   * `bond`: select at least 2 NIC Ports
6. Confirm interface name:
   * Non-bond interface name is synchronized from selected NIC
   * Bond interface requires a custom interface name
7. Click **Save** to create the Interface Mapping
8. In the interface row, click **Add IP**
9. Enter IP fields:
   * `ipAddress` (required, IPv4)
   * `mask` (optional CIDR number `0-32`)
   * `gateway` (optional IPv4)
   * `dns` (optional IPv4)
10. Click **Save** to add the IP entry
11. Repeat for additional NICs/interfaces/IPs if needed, then click main **Save** on node dialog

**Expected Result**:

* `bmc` and `eth0` NIC Port defaults exist and cannot be removed
* `bmc` and `eth0` Interface Mapping defaults exist and cannot be removed
* Save button stays disabled until required network rules are satisfied
* Each required default interface (`bmc`, `eth0`) has valid binding and at least one IP address
* Bond interface requires at least 2 slave NICs before it is valid
* NIC Port cannot be deleted when currently bound by an interface
* Network config is saved into node payload as:

```json
{
   "networkConfig": {
      "nics": [
         {
            "name": "eth0",
            "card": "nic0",
            "networkType": "ethernet",
            "mac": "00:11:22:33:44:55"
         }
      ],
      "interfaces": [
         {
            "name": "eth0",
            "type": "ethernet",
            "slaves": [],
            "ipList": [
               {
                  "ip": "10.0.0.10",
                  "mask": 24,
                  "gw4": "10.0.0.1",
                  "dns": "8.8.8.8"
               }
            ]
         }
      ]
   }
}
```

***

![Import Nodes(No.1)](https://pub-f334ff01208c4e6195b80133ac6e6030.r2.dev/portal/nodeManagement/Node_Management_Import_CSV-1.png) ![Import Nodes(No.2)](https://pub-f334ff01208c4e6195b80133ac6e6030.r2.dev/portal/nodeManagement/Node_Management_Import_CSV-2.png)

#### Operation 4: Import Nodes via CSV

**Steps**:

1. Click "Import" button (No.1)
2. Select CSV file from file browser (No.2)
3. Review parsed node list in preview dialog
4. Click Save (No.3)

**Expected Result**:

* CSV file parsed automatically
* Preview shows: Node Group, Hostname, Model
* Warning indicator appears in footer
* Click Save to commit import
* All nodes created in batch
* Cancel button available to abort import

***

#### Operation 5: Edit Node Configuration

![Edit Nodes](https://pub-f334ff01208c4e6195b80133ac6e6030.r2.dev/portal/nodeManagement/Node_Management-Edit_Node-1.png)

**Steps**:

1. Click action menu (⋮) on target node row
2. Select "Edit"
3. Modify desired fields
4. Click Save

**Expected Result**:

* Dialog pre-populated with current values
* Hostname field disabled (cannot be changed)
* Password status shown (Configured/Not configured)
* Form validates changes
* Node updated in database
* Table refreshes with new values

***

#### Operation 6: Move Nodes to Different Group

![Move Nodes(No.1)](https://pub-f334ff01208c4e6195b80133ac6e6030.r2.dev/portal/nodeManagement/Node_Management_Move_1.png) ![Move Nodes(No.2)](https://pub-f334ff01208c4e6195b80133ac6e6030.r2.dev/portal/nodeManagement/Node_Management_Move_2.png)

**Steps**:

1. Select multiple nodes using checkboxes
2. Click "Modify Nodes" → "Move to Group"
3. Select target group from submenu
4. Click "Save" button to confirm action

**Expected Result**:

* "Move to Group" option enabled only when nodes selected
* Submenu lists all available groups
* Selected nodes relocated to target group
* Table reorganizes with new grouping
* Selection cleared after operation

***

#### Operation 7: Create New Node Group

![Add Group](https://pub-f334ff01208c4e6195b80133ac6e6030.r2.dev/portal/nodeManagement/Node_Management_Add_Group.png)

**Steps**:

1. Click "Modify Groups" → "Add Group"
2. Enter group name
3. Click Create

**Expected Result**:

* Input validates group name:
  * No special characters except underscore
  * Not a reserved keyword
* New group appears in system
* Group available in dropdowns and menus
* Success notification displayed

***

#### Operation 8: Delete Node Group

![Delete Group](https://pub-f334ff01208c4e6195b80133ac6e6030.r2.dev/portal/nodeManagement/Node_Management_Delete_Group.png)

**Steps**:

1. Click "Modify Groups" → "Delete Groups"
2. Click delete icon (🗑️) next to group(s) to remove
3. Click Save

**Expected Result**:

* Dialog shows all available groups
* Only empty groups can be deleted
* Groups with nodes cannot be deleted
* Deleted groups removed from system
* Dropdowns and menus updated

***

#### Operation 9: Export Node Data

![Export Nodes](https://pub-f334ff01208c4e6195b80133ac6e6030.r2.dev/portal/nodeManagement/Node_Management_Export_CSV.png)

**Steps**:

1. Click "Export" button
2. Enter filename
3. Click Export

**Expected Result**:

* CSV file generated with all node data
* File downloaded to browser's download folder
* Includes all columns (visible and hidden)
* Formatted for re-import compatibility

***

#### Operation 10: Delete Node

![Delete Nodes](https://pub-f334ff01208c4e6195b80133ac6e6030.r2.dev/portal/nodeManagement/Node_Management_Delete_Nodes.png)

**Steps**:

1. Click action menu (⋮) on target node
2. Select "Delete"
3. Confirm deletion

**Expected Result**:

* Confirmation dialog appears
* Node removed from database
* Table refreshes
* Node disappears from display
* Group count updates