Register Edge Nodes in Edge Orchestrator#

Edge Orchestrator supports the following registration methods:

  1. UI-assisted registration

  2. Bulk import of edge devices through the orch-cli

Note

When you use the LOC-A software, you must register the device there using one of the available methods. You do not need to register the device through Edge Orchestrator.

Register Using the User Interface#

To register your edge node(s) through the User Interface (UI), you must be a member of the Edge Manager Group. Then:

  1. Manual onboarding and provisioning.

  2. Automated onboarding and manual provisioning.

  3. Automated onboarding and provisioning.

  4. Automated onboarding and provisioning with single node cluster creation.

Note

The first two registration options with manual provisioning assumes that Near Zero Touch Provisioning (nZTP) has been disabled. To confirm if nZTP is disabled, verify that nZTP has been disabled in the provider configuration. For details on nZTP, see Near Zero Touch Provisioning.

Manual Onboarding and Provisioning#

  1. Go to the Infrastructure tab, click Hosts on the left menu. The Hosts page appears.

  2. On the Hosts page, click the Register Hosts option. The Register Hosts page appears:

    Register Host

  3. Enter in a user-friendly name in the Host Name field and either the serial number or UUID in the respective fields. At least one between the serial number or the UUID must be provided.

    Note

    The serial number and UUID are typically on a sticker on the device or in the device’s BIOS. Other vendors make this information available through the Base Management Controller (BMC).

  4. To select manual onboarding, deselect the Onboard Automatically field.

  5. Leave the Provision Automatically field deselected to enable manual provisioning.

  6. If multiple edge nodes are to be registered, you can add additional fields using the + option below the host table.

  7. Click Register Hosts to submit the edge node(s); a redirect will happen to the list of nodes with a successful notification:

    Registration successful

The Host will show Status as Unknown, waiting for the edge node to attempt to connect.

Once a connecting edge node reports a UUID or serial number that matches the registered information, the status will become Registered.

You can proceed to onboard the host by following the Onboard Host instructions.

To provision the host after it is onboarded, follow the Provision Host instructions.

Refer to Registered Host Mismatch for any issues in encountered during set up.

Automated Onboarding and Manual Provisioning#

  1. Go to the Infrastructure tab, click Hosts on the left menu. The Hosts page appears.

  2. On the Hosts page, click the Register Hosts option. The Register Hosts page appears.

    Register Host

  3. Enter in a user-friendly name in the Host Name field and either the serial number or UUID in their proper fields. You must provide either the serial number or the UUID.

    Note

    The serial number and UUID are typically on a sticker on the device or in the device’s BIOS. Other vendors make this information available through the Base Management Controller (BMC).

  4. Select Onboarding Automatically if appropriate for your usage. By selecting this field, the node will automatically go through the onboarding process when connected. By default, the option is enabled.

  5. Leave the Provision Automatically field deselected to enable manual provisioning.

  6. If multiple edge nodes are to be registered, you can add additional fields using the + option below the host table.

  7. Click Register Hosts to submit the edge node(s), a redirect will happen to the list of nodes with a successful notification.

    Registration successful

The host will show the Status as Unknown; waiting for the edge node to attempt to connect.

Once a connecting edge node reports a UUID or serial number that matches the registered information, the status will become Onboarded. It will then be automatically moved to the Onboarded tab of the Hosts page.

To provision the host after it is onboarded, follow the Provision Host instructions.

Automated Onboarding and Provisioning#

  1. Go to the Infrastructure tab, click Hosts on the left menu. The Hosts page appears.

  2. On the Hosts page, click the Register Hosts option. The Register Hosts page appears:

    Register Host Automatic Provisioning

  3. Enter in a user-friendly name in the Host Name field and either the serial number or UUID in the respective fields. You must provide either the serial number or the UUID.

    Note

    The serial number and UUID are typically on a sticker on the device or in the device’s BIOS. Other vendors make this information available through the Base Management Controller (BMC).

  4. Select Onboarding Automatically if appropriate for your usage. By selecting this field, the node will automatically go through the onboarding process when connected. By default, the option is enabled.

  5. Select Provision Automatically if appropriate for your usage. By selecting this field, the node will automatically go through the provisioning process when connected. By default, the option is disabled.

  6. If both Onboard Automatically and Provision Automatically are selected, the Create Single Node Cluster option becomes available and enabled by default. This will allow you to automatically create a Kubernetes cluster and attach it to this node.

    Register Host Automatic Cluster

    Note

    The Create Single Node Cluster option is only available when both automated onboarding and automated provisioning are enabled. This ensures the node is fully configured before before initiating cluster bootstrap. Note that the cluster may remain in the provisioning status until the host is completely onboarded and provisioned.

  7. If multiple edge nodes are to be registered, you can add additional fields by clicking the + option.

  8. Click Continue to configure the provisioning settings. This follows the Provision Host instructions.

  9. After completing and reviewing the provisioning settings, click Provision to submit the edge node(s), a redirect will happen to the list of nodes with a successful notification.

    Registration successful

The Host will show Status as Unknown, waiting for the edge node to attempt to connect.

Once a connecting edge node reports a UUID or serial number that matches the registered information, the node is onboarded and provisioning starts. It will then be automatically moved to the Provisioned tab of the Hosts page.

Orch-CLI - Bulk Import Edge Devices#

The orch-cli tool facilitates registration of a set of hardware devices as edge nodes through a comma-separated value (CSV) file:

  1. orch-cli supports the creation of an empty template, and/or tests the validity of a given CSV file for it to be used during creation the host resources.

  2. orch-cli facilitates the import of the edge nodes present in a CSV file to the Edge Orchestrator.

Download Tools#

The tool orch-cli is publicly available for release in Open Container Initiative* (OCI*) compliant registries. Intel recommends using the oras client to interact with it. Ensure that you have oras available on your system or follow the instructions in the public documentation to install it.

Download the tool as follows:

The tool is made available in the public AWS* Elastic Container Registry. It can be pulled without any credentials using commands like below:

oras pull registry-rs.edgeorchestration.intel.com/edge-orch/files/orch-cli:3.1

The package will be an archive which needs to be unpacked to access the binary.

For more information about the orch-cli tool and how to use it to create and view other Edge Orchestrator resources, refer to the: Orch CLI User Guide

Login to the Edge Orchestrator#

Go to the directory where the downloaded orch-cli tool resides (for example, ~), to run the login command. The username must be provided as and argument followed by –keycloak flag pointing to the Keycloak service of the Edge Orchestrator. This is followed by the password prompt:

cd ~
chmod +x orch-cli

orch-cli login <USER> --keycloak https://keycloak.<CLUSTER_FQDN>/realms/master
Enter Password:

Generate a .csv File#

This section guides through the creation of a formatted .csv file with all the entries. This is optional if you already have a correct .csv file.

Go to the directory where the downloaded orch-cli tool resides (for example, ~), to run it:

./orch-cli create host  --api-endpoint <CLUSTER_FQDN>  --project <PROJECT_NAME>  --generate-csv=<FILENAME>.csv

Now, you can populate the .csv file by appending details of systems. Do not change the first line Serial,UUID,OSProfile,Site,Secure,RemoteUser,Metadata,AMTEnable,CloudInitMeta,K8sEnable,K8sClusterTemplate,K8sConfig,Error - do not fill because that is the expected format. The Serial, UUID, OSProfile and Site columns must be filled, with the serial number and UUID of the edge node(s) you want to register as well as the OSProfile name/resource ID, and the site resource ID. The other columns are optional - for more information seek help with -h flag. The following is an example:

Serial,UUID,OSProfile,Site,Secure,RemoteUser,Metadata,AMTEnable,CloudInitMeta,K8sEnable,K8sClusterTemplate,K8sConfig,Error - do not fill
2500JF3,4c4c4544-2046-5310-8052-cac04f515233,"Edge Microvisor Toolkit 3.0.20250808",site-b05caf24
ICW814D,4c4c4544-4046-5310-8052-cac04f515233,"ubuntu-22.04-lts-generic",site-b05caf24
FW908CX,4c4c4544-0946-5310-8052-cac04f515233,"Edge Microvisor Toolkit 3.0.20250717",site-a053abcd

Check the CSV File#

You can now validate the CSV file that you have created yourself or through generation by attempting a dry run deployment. .. code-block:: bash

./orch-cli create host –api-endpoint <CLUSTER_FQDN> –project <PROJECT_NAME> –import-from-csv <FILENAME>.csv –dry-run

orch-cli#

This section shows how to use a CSV file to import a series of devices as edge nodes, the utility provides a set of override flags that can be used to globally override the arguments throughout the CSV file:

 Flags:
-a, --amt                                Override the AMT feature configuration provided in CSV file for all hosts
-j, --cloud-init string                  Override the cloud init metadata provided in CSV file for all hosts
-f, --cluster-config string              Override the cluster configuration provided in CSV file for all hosts
-c, --cluster-deploy string              Override the cluster deployment flag provided in CSV file for all hosts
-t, --cluster-template string            Override the cluster template provided in CSV file for all hosts
-d, --dry-run                            Verify the validity of input CSV file
-g, --generate-csv string[="test.csv"]   Generates a template CSV file for host import
-h, --help                               help for host
-i, --import-from-csv string             CSV file containing information about to be provisioned hosts
-m, --metadata string                    Override the metadata provided in CSV file for all hosts
-o, --os-profile string                  Override the OSProfile provided in CSV file for all hosts
-r, --remote-user string                 Override the metadata provided in CSV file for all hosts
-x, --secure string                      Override the security feature configuration provided in CSV file for all hosts
-s, --site string                        Override the site provided in CSV file for all hosts

CSV file fields: The fields OSProfile, Site, Secure, RemoteUser, CloudInitMeta, and Metadata are used for provisioning configuration of the Edge Node. The fields accept both name and resource IDs, with an exception of site which only accepts resource IDs. The Secure field is a boolean value that can be set to true or false. The Metadata field is a key-value pair separated by an = sign, and multiple key-value pairs are separated by an & sign. The AMTEnable enables the AMT feature in supported edge nodes and is by default a boolean value of false. The K8sEnable enables the auto creation of single node K3s cluster and is by default a boolean false. When enabled additional configuration must be provided via K8sClusterTemplate which expects the template name and version in format <name>:<version>, and optional config K8sConfig in format role:<roles>;name:<name>;labels:<name=value>&<name2=value2>

  1. Do the following before running the create host command with the orch-cli:

    1. Complete the CSV file with the provisioning details for the edge nodes you want to register. OSProfile and Site are a mandatory fields without which provisioning configuration cannot be completed. Also, be aware that the OSProfile and Secure fields are related. If Secure is set to true, the OSProfile must support it. If left blank, Secure defaults to false. The values in other fields are validated before consumption though an empty string is allowed for all of them. If a column is not filled in but followed but value in other column it should be left blank followed by nex column ie. value,,value2. The following is an example:

      Serial,UUID,OSProfile,Site,Secure,RemoteUser,Metadata,AMTEnable,CloudInitMeta,K8sEnable,K8sClusterTemplate,K8sConfig,Error - do not fill
2500JF3,4c4c4544-2046-5310-8052-cac04f515233,os-7d650dd1,site-08c1e377,true,localaccount-9dfb57cb,key1=value1&key2=value2,,custom-config
ICW814D,4c4c4544-4046-5310-8052-cac04f515233,ubuntu-22.04-lts-generic,site-08c1e377,true,myuser-key,key1=value1&key2=value2,
FW908CX,4c4c4544-0946-5310-8052-cac04f515233,os-7d650dd1,site-08c1e377,true,myuser-key,key1=value1&key2=value2,,,true,baseline:v1.0.0,role:all;name:mycluster;labels:sample-label=samplevalue&sample-label2=samplevalue2

    2. Authenticate with Edge Orchestrator before importing hosts.

      1. Interactive shell - The default way to authenticate with Edge Orchestrator is to log in by providing username as first argument and using an interactive prompt The prompt will ask for password. Upon login the JWT access token will be cached on the system, it expires after one hour, after this time user needs to logout and log in again:

        cd ~
chmod +x orch-cli

orch-cli login <USER> --keycloak https://keycloak.<CLUSTER_FQDN>/realms/master
Enter Password:

      2. Password argument - Alternatively the password can be provided as a second command line argument - the recommended way is to use prompt based login above. When using this method, be cautious as the password may be exposed in the command line history. If using this method exporting the password as an environment variable is recommended.

        cd ~
chmod +x orch-cli

orch-cli login <USER> <PASSWORD> --keycloak https://keycloak.<CLUSTER_FQDN>/realms/master

  2. Run the bulk import tool. Go to the directory where you have downloaded the file (e.g. ~). The URL in the command is a mandatory argument that points the tool towards the Edge Orchestrator where the devices will be registered. Replace test.csv with your CSV filename, and CLUSTER_FQDN with the name of the domain used during installation, and the PROJECT_NAME with an actual project created in the Edge Orchestrator for a given user:

    cd ~
chmod +x orch-cli
./orch-cli create host  --api-endpoint <CLUSTER_FQDN>  --project <PROJECT_NAME>  --import-from-csv test.csv

  3. The orch-cli validates the input file again, similar to the dry-run tool, and generates an error report if validation fails. If validation passes, the bulk import tool proceeds to the registration phase. For each host registration that succeeds, expect output similar to the following at the console:

    ✔ Host Serial number : 2500JF3  UUID : 4c4c4544-2046-5310-8052-cac04f515233 registered. Name : host-a835ac40
✔ Host Serial number : ICW814D  UUID : 4c4c4544-4046-5310-8052-cac04f515233 registered. Name : host-17f57696
✔ Host Serial number : FW908CX  UUID : 4c4c4544-0946-5310-8052-cac04f515233 registered. Name : host-7bd98ae8
CSV import successful

  4. If there are errors during registration, a new CSV file with the name import_error_timestamp_filename is generated with each failed line having a corresponding error message.

Example of invocation and failure:

./orch-cli create host  --api-endpoint <CLUSTER_FQDN>  --project <PROJECT_NAME>  --import-from-csv test.csv
Importing hosts from file: test.csv to server: https://api.CLUSTER_FQDN
Onboarding is enabled
Checking CSV file: test.csv
Generating error file: import_error_2025-08-15T18:28:44+05:30_test.csv
error: Failed to import all hosts


$ cat import_error_2025-08-15T18\:28\:44+05\:30_test.csv
Serial,UUID,OSProfile,Site,Secure,RemoteUser,Metadata,AMTEnable,CloudInitMeta,K8sEnable,K8sClusterTemplate,K8sConfig,Error - do not fill
FW908CX,4c4c4544-0946-5310-8052-cac04f515233,os-7d650dd1,site-abcd1234,true,myuser-key,key1=value1&key2=value2,Host already registered