Skip to main content
Onboard a node when you want Edge Infrastructure Services to manage an edge device running EVE-OS. In the new UI, open Infrastructure > Fleet > Nodes, then select the contextual + create action in the lower-right corner. The same + pattern creates the resource for the page you are on. On the Nodes list, it starts node onboarding. Contextual plus create action in the lower-right corner of a list page. The onboarding page heading is Onboard Nodes.

​
Before You Start

Prepare the node and the platform objects it depends on. If you plan to deploy Applications from a datastore, make sure the node can reach that datastore from the deployment location.

​
Name and identity uniqueness

Edge Infrastructure Services rejects an onboarding request that reuses an identity it already knows. Check the following before you create the node:
  • The node Name must be unique within your enterprise, across all projects. If a node with the same name exists, the request fails with Entry already exists.
  • An onboarding key and serial number pair, or an onboarding certificate and serial number pair, can register only one node. If that pair is already registered to a node, the request fails with Duplicate Device configuration, already exists.
  • A device certificate can register only one node. If the certificate is already registered, the request fails with Duplicate Device Certificate, already exists.
  • Supply either an onboarding key or an onboarding certificate, not both.
The serial number by itself does not need to be unique. Only its combination with the onboarding key or certificate must be. If the matching node was off-boarded rather than deleted, the request does not fail. Edge Infrastructure Services re-onboards the node and reuses its previous identity. See Off-board a Node.

​
Choose an Onboarding Method

The onboarding gallery offers four paths.

​
Use Ask ZEIA

Ask ZEIA onboarding is not yet available. When available, this method will guide you through onboarding using ZEIA at the bottom of the console. Use Single-Use Installer, Onboarding Key, or Certificate in the meantime.

​
Use Single-Use Installer

Single-Use Installer onboarding is organized as a New Node flow with the subtitle Single-use installer onboarding. The installer image is generated for the specific node after you create it, so the device registers automatically on first boot without requiring a serial number or certificate. Choose this method when your environment does not support DHCP, when you need to provision an air-gapped node, or when you want to avoid writing manual JSON network configuration files. The installer contains a bootstrap configuration signed by Edge Infrastructure Services and can only be used once, making it more tamper-resistant than a hand-edited config file.
  1. Open Infrastructure > Fleet > Nodes.
  2. Select the contextual + create action.
  3. On Onboard Nodes, select Single-Use Installer.
  4. In General, enter Name, Title, and optional Description.
  5. In Assignment, select a Project. Optionally select a Hardware Model to pre-configure network ports and IO adapters.
  6. If you selected a hardware model, configure the Network and IO Adapters sections before continuing. If an adapter is bound to a network that uses static addressing, supply its IP details in the adapter row. See Configure Per-Adapter IP Addresses.
  7. Select Create Node.
  8. On the EVE-OS step, select Generate Installer for the appropriate architecture (AMD64 or ARM64).
  9. When the image is ready, download it and flash it to a USB drive using ZFlash. See Flash an EVE-OS Installer or Live Image.
  10. Boot the edge device from the USB drive. The node registers with Edge Infrastructure Services automatically on first boot.
  11. Select Done to return to Nodes.
After the device boots EVE-OS and reaches Edge Infrastructure Services, the node moves toward a registered or online state.

​
Use Onboarding Key

Onboarding Key requires the device serial number and an onboarding key UUID, which are sent with the registration request instead of a generated installer image.
  1. Open Infrastructure > Fleet > Nodes.
  2. Select the contextual + create action.
  3. On Onboard Nodes, select Onboarding Key.
  4. In General, enter Name, Title, and optional Description.
  5. In Assignment, select a Project. Optionally select a Hardware Model.
  6. Select Next to proceed to Registration.
  7. Enter the Serial Number and the Onboarding Key UUID. The Serial Number field accepts two kinds of serial:
    • Hardware serial: printed on the device label or available from the BIOS. You can enter this before EVE-OS is installed.
    • Soft serial: generated during EVE-OS installation. It is displayed when the install finishes and saved as a folder name in the INVENTORY partition of the install media.
    If you do not have a soft serial yet, expand Don’t have a soft serial number yet? below the field. The panel instructs you to install EVE-OS first, then return to this step to complete registration with the serial the installation reports.
  8. If you selected a hardware model, configure the Network and IO Adapters sections before continuing. If an adapter is bound to a network that uses static addressing, supply its IP details in the adapter row. See Configure Per-Adapter IP Addresses.
  9. Select Create Node.

​
Use Certificate

Certificate onboarding registers the node using its hardware identity certificate. Upload or paste the certificate in PEM format during the Registration step.
  1. Open Infrastructure > Fleet > Nodes.
  2. Select the contextual + create action.
  3. On Onboard Nodes, select Certificate.
  4. In General, enter Name, Title, and optional Description.
  5. In Assignment, select a Project. Optionally select a Hardware Model.
  6. Select Next to proceed to Registration.
  7. Upload or paste the device hardware identity certificate in PEM format.
  8. If you selected a hardware model, configure the Network and IO Adapters sections before continuing. If an adapter is bound to a network that uses static addressing, supply its IP details in the adapter row. See Configure Per-Adapter IP Addresses.
  9. Select Create Node.

​
Configure Per-Adapter IP Addresses

The Network section lists the adapters defined by the selected hardware model. Each adapter row binds a network from the node’s project. Most networks (DHCP Client, None) need nothing else, but the two static addressing modes require IP details per adapter. The wizard blocks the Network step until every required field is complete, because Edge Infrastructure Services rejects node creation when an adapter bound to a static network has no IP address. The same fields appear in all onboarding methods that include the Network section (Single-Use Installer, Onboarding Key, and Certificate).

​
Static IP Networks

When an adapter is bound to a network whose IP Address Config is Static IP, the row shows a required Static IP Address field. The network object already defines the subnet, gateway, and DNS. The adapter supplies only its own address.
  • Enter a bare IPv4 or IPv6 address without a prefix length (for example, 192.168.1.10, not 192.168.1.10/24).
  • The address must fall within the network’s subnet so the port has working connectivity.

​
Static IP - Adapter Specific networks

When an adapter is bound to a network whose IP Address Config is Static IP - Adapter Specific, the network defines no IP details of its own. The adapter carries its own network configuration. The row shows two required fields inline:
  • Kind: The IP addressing stack (Dual-stack, IPv4 preferred, Dual-stack, IPv6 preferred, IPv4 Only, or IPv6 Only). The value is pre-filled from the bound network.
  • Static IP Address: The fixed address for this port, as a bare IPv4 or IPv6 address without a prefix length.
Select Network settings in the row to open a modal with the optional per-adapter settings: All fields in the modal are optional. If an optional value fails validation, the row shows how many settings need attention until you correct them.
When you apply a static network to several selected adapter rows at once, the wizard expands each affected row so you can enter the required address for every adapter. Each adapter needs its own address; the bulk action does not copy IP values between rows.
To create a Static IP - Adapter Specific network ahead of onboarding, see Create a Network.

​
Verify the Result

After creating the node:
  • Return to Infrastructure > Fleet > Nodes.
  • Confirm the node appears in the list.
  • Confirm the node is assigned to the expected project.
  • Open the node detail page and check status, admin state, and EVE-OS information.
  • If the node is not online yet, confirm the device has booted EVE-OS and can reach Edge Infrastructure Services.
After onboarding, EVE-OS disables keyboard, VGA, and console access by default as a security measure. If you need physical local access to the node (for example, to use the Local UI or open a debug shell) re-enable these after onboarding by pushing the following configuration items from Edge Infrastructure Services:
See Manage Nodes with EVE-OS Local UI for details.
Consider enabling last-resort SSH access while the node is connected and healthy. Last-resort SSH is an emergency break-glass method for reaching a node when EdgeView and standard SSH are both unavailable. Because it is enabled by pushing a config through Edge Infrastructure Services, it cannot be turned on after the node goes dark. Enable it proactively on production nodes, then disable it when it is no longer needed.
See Enable Last Resort for the full procedure.

​
Next Steps