# Edge Node Infrastructure Blueprint — Get Started ## Related Guides | Topic | Guide | |---|---| | Host OS image generation from an Ubuntu ISO Image | [Ubuntu Desktop Raw Image Generation](https://github.com/open-edge-platform/edge-node-infrastructure-blueprint/blob/main/infrastructure/host-os/readme.md) | | **Advanced**: Build the host OS image with the Image Composer Tool | [Building an Ubuntu OS version 24.04 Image with Image Composer Tool](https://github.com/open-edge-platform/edge-node-infrastructure-blueprint/blob/main/infrastructure/host-os/ict/README.md) | | Exposing Intel GPU or NPU to containers via Container Device Interface (CDI) | [Intel CDI Usage Guide](./container-device-interface-guide.md) | | Writing and using AI agent skills for this blueprint | [AI Agent-Driven Development Strategy](https://github.com/open-edge-platform/edge-node-infrastructure-blueprint/blob/main/infrastructure/docs/agent-skills-guide.md) | ## 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. ```bash # 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 ```bash 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 1 (Recommended): Build from ISO Build the Ubuntu image, including the required tools and packages, from an Ubuntu ISO image file: ```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 the [Ubuntu Desktop Raw Image Generation guide](https://github.com/open-edge-platform/edge-node-infrastructure-blueprint/blob/main/infrastructure/host-os/readme.md). #### 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](https://github.com/open-edge-platform/edge-node-infrastructure-blueprint/blob/main/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: ```bash 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: ```bash 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: ```bash 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 ```bash 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: ```bash /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: ```bash sudo ./bootable-usb-prepare.sh /dev/sdX usb-bootable-files.tar.gz config-file ``` To reuse a prebuilt image: ```bash 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: ```bash # 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: ```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 SR-IOV status: ```bash sudo cat /sys/kernel/debug/dri/0000:00:02.1/sriov_info ``` Expected indicators: ```text supported: yes enabled: yes mode: SR-IOV VF ``` Verify GPU and NPU driver bring-up: ```bash sudo dmesg | grep xe sudo dmesg | grep vpu ``` For containers: ```bash docker info docker ps ``` For details on exposing Intel® GPU or NPU to containers via CDI, see the [Intel CDI Usage Guide](./container-device-interface-guide.md). ## 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 - Run repeatable workflows through natural language using the agent skills described in the [AI Agent-Driven Development Strategy](https://github.com/open-edge-platform/edge-node-infrastructure-blueprint/blob/main/infrastructure/docs/agent-skills-guide.md) section. - Expose Intel® accelerators to containerized workloads using the [Intel CDI Usage Guide](./container-device-interface-guide.md).