> 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/osprovisioning.md).

# OS Provisioning

| Name      | Last Modified |
| --------- | ------------- |
| AIDC Team | 2026/08/21    |

![OS Provisioning Feature](https://pub-f334ff01208c4e6195b80133ac6e6030.r2.dev/portal/osProvisioning/OS_Provisioning.png)

## Feature Goal

### Aim

The OS Provisioning feature provides a guided multi-step wizard for creating and editing OS deployment job templates. It enables users to:

* Define a deployment job with a name, description, and provisioning mode
* Select a target OS image (stateful disk-based or stateless live)
* Choose target nodes or node groups for the deployment
* Review the full configuration before saving and executing
* Immediately execute the job upon save (create or update)

## Feature Description

### 3.1 Location

* **Route**: `/OSProvisioning`
* **Navigation Path**:
  * Side Menu: `Deploy` → `OS Provisioning`
  * `Deploy` → `Job Management` → **Create Job** → **OS Deployment**
  * Or: `Job Management` → Edit (✏️) on an existing OS deployment job
* **Access Level**: Requires authenticated user with deployment job management permissions

### 3.2 Reference Feature

**Related Features**:

* **Job Management** (`/JobManagement`): Entry point for creating/editing OS deployment jobs; after saving, the user is redirected back here
* **Image Builder** (`/ImageBuilder`): Manage OS images; accessible via the **Manage OS Image** button in Step 1
* **Node Management** (`/NodeManagement`): Source of target nodes selectable in Step 2

**Dependencies**:

* Jobs API for creating and updating job records
* OS Images API for fetching available images filtered by provisioning mode
* IAC Tools API for stage/task scaffolding (`install-os` tool)
* Node Devices API for loading available nodes and groups

### 3.3 Operation Requirements

**Prerequisites**:

1. User must be authenticated and logged into the system
2. User must have deployment job management permissions
3. At least one OS image must be downloaded for the desired provisioning mode (stateful or stateless)
4. At least one node must exist in the system to be selectable in Step 2

**System Requirements**:

* Modern web browser (Chrome, Firefox, Edge, Safari)
* JavaScript enabled
* Network connection to the portal API

**Access Permissions**:

* Create or edit OS deployment jobs
* Execute jobs
* View nodes and OS images

### 3.4 Operation Flow

**Main Workflow (Create Mode)**:

1. **Enter Wizard**
   * User clicks **Create Job** → **OS Deployment** in Job Management
   * Wizard opens at Step 1 (Deployment Details) with a blank form
2. **Step 1 – Deployment Details**
   * User selects a provisioning mode: **Stateful** (disk-based, default) or **Stateless** (live image)
   * User enters a job **Name** (required)
   * User selects an **OS image** from the filtered dropdown (options change per mode)
   * User optionally enters a **Description**
   * User clicks **Next Step** (disabled until the form is valid)
3. **Step 2 – Node Selection**
   * System renders the node/group selector
   * User browses and selects individual nodes and/or node groups
   * User clicks **Confirm** (or **Back** to return to Step 1)
4. **Step 3 – Preview**
   * System displays a summary: Basic Information, Deployment Configuration, Group/Node Settings, and Target Nodes list
   * User searches target nodes by hostname (optional)
   * User clicks **Save and Execute** to create and immediately run the job
   * Or clicks **Back** to return to Step 2
5. **Save & Execute**
   * System calls `createJob` API → on success, calls `runJob` API
   * User is navigated to `/JobManagement`

**Edit Mode Differences**:

* Wizard pre-fills all form fields from existing job data (name, OS, description, provisioning mode, nodes, stages)
* **Save and Execute** calls `updateJob` API → then `runJob` API
* Navigates back to `/JobManagement` on success

**Cancel / Back Navigation**:

* **Cancel** (Step 1 footer) → navigates to `/JobManagement` immediately
* **Back** (Step 3 footer) → returns to Step 2

### 3.5 UI Review

![OS Provisioning UI](https://pub-f334ff01208c4e6195b80133ac6e6030.r2.dev/portal/osProvisioning/OS_Provisioning_UI_Interface.png)

The wizard is presented as a full-page form with a fixed footer bar containing step-specific action buttons.

#### Step 1 – Deployment Details

**Provisioning Mode Tabs** (top of page):

| Tab                              | Icon     | Description                                                 |
| -------------------------------- | -------- | ----------------------------------------------------------- |
| **Stateful Provisioning(No.1)**  | 💿 HDD   | Disk-based persistent OS installation; uses non-live images |
| **Stateless Provisioning(No.1)** | ☁️ Cloud | Live image deployment; uses live images                     |

**Form Fields**:

| Field                     | Type       | Required | Description                                                                                                        |
| ------------------------- | ---------- | -------- | ------------------------------------------------------------------------------------------------------------------ |
| **Name(No.2)**            | Text input | ✅        | Unique identifier for the deployment job                                                                           |
| **OS Selection(No.3)**    | Dropdown   | ✅        | Lists available OS images filtered by the active provisioning mode; formatted as `{distribution}-{version}-{arch}` |
| **Manage OS Image(No.4)** | Button     | —        | Opens Image Builder (`/ImageBuilder`) to download or manage OS images                                              |
| **Description(No.5)**     | Textarea   | —        | Optional free-text description of the job                                                                          |

**Supported Operating Systems**

AIDC currently supports automated deployment for the following operating systems and architectures:

| OS     | Version         | Architecture     |
| ------ | --------------- | ---------------- |
| RHEL   | 9.6 / 9.8       | x86\_64, aarch64 |
| Ubuntu | 24.04.4 / 26.04 | x86\_64, aarch64 |

{% hint style="info" %}
The **OS Selection** dropdown only lists images that have already been downloaded via **Manage OS Image** (Image Builder). If the OS/version/architecture you need isn't listed, download it there first.
{% endhint %}

**Footer**:

| Button              | Behaviour                                          |
| ------------------- | -------------------------------------------------- |
| **Cancel(No.6)**    | Exits the wizard and navigates to `/JobManagement` |
| **Next Step(No.6)** | Advances to Step 2; disabled when form is invalid  |

***

#### Step 2 – Node Selection

![OS Provisioning UI](https://pub-f334ff01208c4e6195b80133ac6e6030.r2.dev/portal/osProvisioning/OS_Provisioning_UI_Interface_2.png)

* Shows calculation of nodes by status(No.7)
* Rendered by `<app -nodes-select>` in `groups-and-nodes` mode(No.8), can filter nodes by keywords (name, IP, or group) or status
* Displays nodes grouped by node group; supports search and multi-select(No.9)
* Pre-selects previously chosen node IDs when in edit mode
* Footer is controlled by the `NodesSelectComponent` (Back / Confirm)(No.10)
* Rapidly preview the first 50 nodes selected for checking(No.11)

***

#### Step 3 – Preview

![OS Provisioning UI](https://pub-f334ff01208c4e6195b80133ac6e6030.r2.dev/portal/osProvisioning/OS_Provisioning_UI_Interface_3.png)

Four summary cards are displayed in a responsive grid:

| Card                                | Fields Shown                                                               |
| ----------------------------------- | -------------------------------------------------------------------------- |
| **Basic Information(No.12)**        | Name, Description                                                          |
| **Deployment Configuration(No.13)** | Provisioning Mode badge, Selected OS badge                                 |
| **Group / Node Settings(No.14)**    | Node Count, Group Count                                                    |
| **Target Nodes** (full-width)       | Searchable hostname list; shows all selected nodes as comma-separated text |

**Target Nodes Search**:

* Text input filters the hostname list in real time
* Show filtered nodes count on the right when searching specific hostname
* A **Clear** button appears when the search field is non-empty

**Footer(No.16)**:

| Button               | Behaviour                                                                                     |
| -------------------- | --------------------------------------------------------------------------------------------- |
| **Back**             | Returns to Step 2 (Node Selection)                                                            |
| **Save and Execute** | Saves the job and immediately runs it; disabled when form is invalid or a save is in progress |

### 3.6 Operation & Expected Result

#### Operation 1: Select Provisioning Mode

**Steps**:

1. Navigate to `/OSProvisioning` (or open an existing job for editing)
2. In Step 1, click the **Stateful Provisioning** or **Stateless Provisioning** tab

**Expected Result**:

* The active tab is highlighted
* The OS dropdown reloads with images appropriate fo r the selected mode (live images for Stateless; non-live for Stateful)
* The OS field value is cleared to prevent mismatched selection

***

#### Operation 2: Fill in Deployment Details

**Steps**:

1. Enter a value in the **Name** field (required)
2. Select an OS image from the **OS Selection** dropdown
3. Optionally enter a **Description**
4. Click **Next Step**

**Expected Result**:

* If Name or OS is missing, inline validation errors appear and **Next Step** remains disabled
* When the form is valid, **Next Step** becomes active and the wizard advances to Step 2

***

#### Operation 3: Navigate to Image Builder

**Steps**:

1. In Step 1, click **Manage OS Image**

**Expected Result**:

* The portal navigates to `/ImageBuilder`
* User can download or manage OS images, then return to restart the wizard

***

#### Operation 4: Select Target Nodes

**Steps**:

1. In Step 2, browse the node/group tree
2. Check individual nodes or entire groups
3. Click **Confirm** (handled by `NodesSelectComponent`)

**Expected Result**:

* Selected nodes are stored in the form
* Wizard advances to Step 3 (Preview)
* Node Count and Group Count in the preview reflect the selection

***

#### Operation 5: Search Target Nodes in Preview

**Steps**:

1. In Step 3, type a partial hostname into the **Search hostnames** input

**Expected Result**:

* The Target Nodes text block filters in real time to show only matching hostnames
* A **Clear** button appears; clicking it resets the filter and shows all nodes

***

#### Operation 6: Save and Execute (Create)

**Steps**:

1. Complete Steps 1–3 with valid data
2. Click **Save and Execute** in Step 3 footer

**Expected Result**:

* System calls `createJob` API with form data (name, description, nodes, groups, OS stage, tags: `["deployment"]`)
* On success, system immediately calls `runJob` API to start execution
* User is redirected to `/JobManagement`
* The new job appears in the job list with status **In Progress**

***

#### Operation 7: Save and Execute (Edit)

**Steps**:

1. Open an existing OS deployment job via the Edit (✏️) button in Job Management
2. Modify any field across Steps 1–3
3. Click **Save and Execute** in Step 3 footer

**Expected Result**:

* System calls `updateJob` API with the updated data
* On success, system calls `runJob` API to start a new execution
* User is redirected to `/JobManagement`
* The job list shows the updated job with a new execution entry

***

#### Operation 8: Cancel Creation

**Steps**:

1. Start the wizard (any step)
2. Click **Cancel** (available in Step 1 footer)

**Expected Result**:

* No job is created or modified
* User is navigated back to `/JobManagement`