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.

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.

# 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:

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.

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

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:

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:

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#

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:

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

For prebuilt image reuse:

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:

# 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:

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:

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

Expected output:

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

Verify the GPU and NPU driver bring-up:

sudo dmesg | grep xe
sudo dmesg | grep vpu

Verify the Docker enviroment:

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.