Edge Node Infrastructure Blueprint — Get Started#

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#

Go Toolchain#

You will need Go programming language version 1.22 or later to build the Intel CDI GPU specification generator, which is compiled and embedded into the HookOS image before the OS build starts.

# Install Go programming language version 1.22 or later, for example, version 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 Go programming language version 1.22 or later

Notes:

  • Keep the HTTP_PROXY, HTTPS_PROXY, and NO_PROXY values consistent across all proxy configuration files.

  • Intel has verified the build flow on Ubuntu OS versions 22.04 and 24.04.

2. Clone the Repository#

git clone https://github.com/open-edge-platform/edge-node-infrastructure-blueprint.git
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 2 (Advanced): Build with Image Composer Tool Image#

This path is intended for advanced users who need fine-grained control over disk layout, package repositories, and image composition. Most users can start with Option 1.

See Build an Ubuntu OS Version 24.04 Image with Image Composer Tool 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)

    • 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 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 config-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 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 GPU and NPU driver bring-up:

sudo dmesg | grep xe
sudo dmesg | grep vpu

For containers:

docker info
docker ps

For details on exposing Intel® GPU or NPU to containers via CDI, see the Intel CDI Usage Guide.

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.

  • CDI GPU generator is not built because of the wrong Go programming language version: The build runs under sudo, which may find a different Go programming language version. Verify with sudo go version and symlink the correct the binary path to /usr/local/bin/go if needed.

Next Steps#