Edge Node Infrastructure Blueprint

Introduction

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

This repository helps you:

• Build bootable installation artifacts.
• Prepare USB media for target node provisioning.
• Bring up core software components after 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 and machine learning inference, IoT processing, and real-time applications at the network edge.

Scope

• Developer system: The host machine used to generate installation artifacts.
• Target system: The edge machine used for application deployment.

Phase 1: Build Artifacts on the Developer System

1. Prerequisites

Docker Setup

For Windows Subsystem for Linux (WSL), follow the steps in the windows-wsl-guide.

Docker Engine is required because the build workflow uses Docker images and containers.

Install Docker Engine for your Linux distribution using the official Docker documentation:

• Linux install overview: https://docs.docker.com/engine/install/
• Debian: https://docs.docker.com/engine/install/debian/
• Ubuntu: https://docs.docker.com/engine/install/ubuntu/
• RHEL: https://docs.docker.com/engine/install/rhel/
• Fedora: https://docs.docker.com/engine/install/fedora/

Configure Docker for non-root usage and service startup after installation:

• https://docs.docker.com/engine/install/linux-postinstall/

If you are behind a proxy, configure Docker daemon proxy settings:

• https://docs.docker.com/config/daemon/systemd/

Install Make on the Development System

Install GNU Make on your development system:

# Ubuntu/Debian
sudo apt-get install make

# RHEL/Fedora
sudo dnf install make

Important Notes

• Keep HTTP_PROXY, HTTPS_PROXY, and NO_PROXY consistent across all proxy configuration files.
• Build flow has been verified on Ubuntu 22.04 and 24.04.

2. Clone the Repository

git clone https://github.com/open-edge-platform/edge-node-infrastructure-blueprint.git -b main
cd edge-node-infrastructure-blueprint

3. Build Bootable USB Artifacts

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

Note:If your development environment is behind a firewall, add proxy configuration to the proxy.env file in the edge-node-infrastructure-blueprint directory. To skip the proxy settings, pass skip-proxy=true to the make command.

Option 1: Build from a Standard 24.04 Minimal desktop image

Build the Ubuntu image, including the required tools and packages, from an Ubuntu minimal desktop image:

Note: Default credentials are user/user. For production, replace the SHA-512 hash in infrastructure/host-os/Dockerfile with your new password using:

openssl passwd -6 'your-new-password'  # or mkpasswd --method=sha-512 'your-new-password'

make build

Or explicitly specify the standard mode:

make build MODE=standard-image

Option 2: Build with Image Composer Tool Image

See infrastructure/host-os/ict/README.md to generate an image using Image Composer Tool.

Use the image-from-tool mode when you already have an image generated by Image Composer Tool. This mode skips host image creation and packages the provided Image Composer Tool image into the USB artifacts:

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

The following are the supported Image Composer Tool image extensions:

• .raw.gz
• .raw.img.gz

Example:

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

Build output:

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

Developer Incremental Build

Use the reuse-image mode to skip base image regeneration and reduce build time:

make build MODE=reuse-image

This reuses a prebuilt image. You can also manually copy an existing image to USB partition 5 when required by your process.

For reusable ICT images, use MODE=image-from-tool with ICT_IMG instead of MODE=reuse-image.

Phase 2: Prepare Bootable USB

4. Extract Installation Files on the Developer System

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

The extracted files include:

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

5. Configure and Prepare the USB Device

Required inputs:

• USB Device Path (usb): The target USB device identifier (for example, /dev/sdX). Use the lsblk command to locate the correct device.
• Bootable Package (usb-bootable-files.tar.gz): The compressed archive containing bootable system files.
• Configuration File (config-file): User-customizable settings that include the following:
  • Proxy configurations
  • SSH public key (id_rsa.pub)
  • Workload orchestration preference (host_type)
  • Single Root I/O Virtualization (SRIOV) toggle
  • Additional system parameters
  • Installation Mode (Attended or Unattended)

Installation Mode Details

Installation mode is optional and defaults to the Unattended Mode, which means a fully automated installation without user interaction. If you require interactive debugging, set installation_mode=true in the config-file to enable the Attended Mode with prompts for user input during the boot process.

If installation fails or you need to troubleshoot, run the installer in interactive debug mode on the Alpine OS terminal:

/usr/local/bin/os-install.sh -i

This launches the installer in interactive debug mode for troubleshooting and manual configuration.

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

To reuse a prebuilt image:

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 the USB.

Access the Edge Node

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

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

For the Kubernetes cluster:

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

Expected healthy output includes the running Intel and Node Feature Discovery components, 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 indicators:

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

Verify the GPU and NPU driver bring-up:

sudo dmesg | grep xe
sudo dmesg | grep vpu

For containers:

docker info
docker ps

Troubleshooting Checklist

• Docker build fails: Recheck 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 has 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.