# Operating System Preparation

## Edge Node Infrastructure Blueprint

The Edge Node Infrastructure Blueprint creates a comprehensive edge computing platform that
enables hardware acceleration capabilities, such as GPU, NPU, and SR-IOV, for
modern applications. This cloud-native infrastructure allows containerized and cloud-native
applications to be deployed seamlessly on edge nodes.

- Build bootable installation artifacts.
- Prepare USB media for target node provisioning.
- Bring up core software components after the first boot.
- Validate platform readiness for cloud-native edge workloads.

The solution bridges the gap between edge hardware capabilities and application requirements,
providing a standardized platform for deploying latency-sensitive workloads, AI or machine
learning inference, IoT processing, and real-time applications at the network edge.

## Scope

- Developer system: Host machine used to generate installation artifacts.
- Target system: Edge machine used for application deployment.

## Phase 1: Build Artifacts on the Developer System

### 1. Prerequisites

Install and configure Docker Engine before starting the build.

- Docker installation: [Docker Engine on Ubuntu](https://docs.docker.com/engine/install/ubuntu/)
- Docker proxy setup: [Docker daemon proxy configuration](https://docs.docker.com/engine/daemon/proxy/)

If your environment uses a proxy, verify the following files:

- `~/.docker/config.json` (Docker CLI proxy settings)
- `/etc/systemd/system/docker.service.d/http-proxy.conf` (Docker service proxy settings)
- `/etc/docker/daemon.json` (Docker daemon proxy settings)

#### Go Toolchain

Go toolchain version 1.22 or later is required to build the Intel® CDI GPU specification generator, which is compiled and embedded into the HookOS image before the OS build starts.

```bash
# Install Go 1.22+ (example: 1.24.2)
wget https://go.dev/dl/go1.24.2.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.24.2.linux-amd64.tar.gz
export PATH=/usr/local/go/bin:$PATH  # add to ~/.bashrc to persist
go version  # should report go1.22 or later
```

> **Notes**:
>
> - Keep `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` consistent across all proxy configuration files.
> - Intel has verified the build flow on Ubuntu OS versions 22.04 and 24.04.


### 2. Build Bootable USB Artifacts

From the repository root, run one of the following build modes.

> **Note**: If your environment is behind a firewall, add proxy configuration to `infrastructure/micro-os/config`.

#### Option 1: Build from ISO

Build the Ubuntu image, including required tools or packages from an Ubuntu ISO:

```bash
make build MODE=image-from-iso ISO_URL=https://releases.ubuntu.com/24.04.4/ubuntu-24.04.4-desktop-amd64.iso
```

For additional image customization, see  `infrastructure/host-os/readme.md`.

#### Option 2: Build with Image from OS Image Composer

Generate an image using OS Image Composer. See
[`infrastructure/host-os/ict/README.md`](infrastructure/host-os/ict/README.md).

Use this mode when you already have an image generated by OS Image Composer.

```bash
make build MODE=image-from-tool ICT_IMG=/absolute/path/to/minimal-desktop-ubuntu-ptl-24.04.raw.gz
```

Supported OS Image Composer's image extensions:

- `.raw.gz`
- `.raw.img.gz`

Example:

```bash
make build MODE=image-from-tool ICT_IMG=/home/user/images/minimal-desktop-ubuntu-ptl-pv-24.04.raw.gz
```

This mode skips host image creation and packages the provided OS Image Composer's image into the USB artifacts.

Build output:

- `usb-installation-files.tar.gz` in `infrastructure/build-artifacts/out`

### Developer Incremental Build

To skip base image regeneration and reduce build time:

```bash
make build MODE=reuse-image
```

This reuses a prebuilt image. You can also copy an existing image manually to USB partition 5 if required.

For reusable OS Image Composer images, use `MODE=image-from-tool` with `ICT_IMG` instead of `MODE=reuse-image`.

## Phase 2: Prepare Bootable USB

### 1. Extract Installation Files on the Developer System

```bash
sudo tar -xzf usb-installation-files.tar.gz
```

Extracted files include:

- `usb-bootable-files.tar.gz`
- `config-file`
- `bootable-usb-prepare.sh`
- `ven-deployment.sh`

### 2. Configure and Prepare the USB Device

Required inputs:

- USB Device Path (usb): Target USB device identifier (for example, `/dev/sdX`). Use the `lsblk` command to locate the correct device.
- Bootable Package (`usb-bootable-files.tar.gz`): Compressed archive containing bootable system files.
- Configuration File (`config-file`): User-customizable settings that includes:
  - Proxy configurations
  - SSH public key (`id_rsa.pub`)
  - Additional system parameters

> **Note**: Proxy configuration is optional in unrestricted network environments.

Run the following command:

```bash
sudo ./bootable-usb-prepare.sh /dev/sdX usb-bootable-files.tar.gz config-file
```

For prebuilt image reuse:

```bash
sudo ./bootable-usb-prepare.sh /dev/sdX usb-bootable-files.tar.gz config-file image.raw.gz
```

After the USB preparation completes:

1. Safely disconnect the USB from the developer system.
2. Connect it to the target system.
3. Enter the BIOS boot menu and boot from USB.

### Access the Edge Node

After installation, log in using the credentials specified in the configuration file created during the Ubuntu desktop image preparation process.


## Phase 3: Post-Boot Bring-Up and Validation on Target System


Verify the Kubernetes cluster status:

```bash
# Kubernetes nodes and plugin pods
sudo kubectl get nodes
sudo kubectl get pods -A
```

Expected output:
Intel and Node Feature Discovery components are running, for example:

```text
intel-device-plugins     intel-gpu-plugin-xxxxx                  1/1   Running
intel-device-plugins     intel-npu-plugin-xxxxx                  1/1   Running
node-feature-discovery   nfd-master-xxxxx                        1/1   Running
node-feature-discovery   nfd-worker-xxxxx                        1/1   Running
kube-system              coredns-xxxxx                           1/1   Running
kube-system              metrics-server-xxxxx                    1/1   Running
```

Verify the SR-IOV status:

```bash
sudo cat /sys/kernel/debug/dri/0000:00:02.1/sriov_info
```

Expected output:

```text
supported: yes
enabled: yes
mode: SR-IOV VF
```

Verify the GPU and NPU driver bring-up:

```bash
sudo dmesg | grep xe
sudo dmesg | grep vpu
```

Verify the Docker enviroment:

```bash
docker info
docker ps
```

## Troubleshooting Checklist

- Docker build fails: Re-check the Docker daemon and CLI proxy settings, then restart the Docker daemon.
- USB preparation fails: Verify the device path and available USB capacity.
- `kubectl` issues: Confirm that the Kubernetes installation is completed and the node status is `Ready`.
- GPU or NPU not detected: Re-run the best-known configuration (BKC) installation and inspect `dmesg` for driver load failures.