Install EVE-OS onto ESXi

Updated

This guide describes how to install EVE-OS onto ESXi, a type 1 hypervisor from VMware. Using ESXi, you can install multiple instances of EVE onto a single machine, thus enabling you to run multiple edge nodes on that machine.

We refer to any instance of EVE running on a hypervisor as “virtual EVE” (vEVE) or a “virtual node”. We use this terminology for clarity. There isn’t anything fundamentally different between a virtual instance of EVE and a non-virtual instance. There are, however, a couple minor differences worth noting:

  • An edge device’s IOMMU functionality can only be accessed by one of its virtual edge nodes at a time.
  • Virtualization always comes with some overhead, which may adversely impact performance-sensitive edge apps.

If you are starting this process from scratch, complete the following sections in order. In the final section, you'll find a script that you can use to onboard your edge nodes.

Note that this guide does not extensively describe how to use ESXi. For those details, refer to VMware's official documentation.

Prerequisites and recommendations

Ensure that you have the following installed before proceeding.

  • EVE-OS version 9.4.0 or later
  • ESXi server 7.0 (test with 7.0 update3) or later

We recommend that you also install Powershell/PowerCLI. You don’t need to, but the following procedures assume that you have it.

Add VM hardware to your enterprise

  1. Log in to the ZCLI
  2. Create a hardware.json file for an ESXi VM on your local machine. For information about the hardware.json file, see our guide to Hardware models.
  3. List your docker containers. 
    docker ps
  4. Observe the output from the previous command. Copy the ID of your ZCLI container, bolded in the following example output. 
    4fbeb231cb3b   zededa/zcli:9.4.0   "/bin/bash --rcfile ..."   3 minutes ago   Up3 minutes   compassionate_blackburn
  5. Copy your hardware.json file into your ZCLI container’s root directory. 
    docker cp PATH_TO_hardware.json_FILE DOCKER_CONTAINER_ID:/root
  6. Create a brand in ZEDEDA Cloud called VMware. (Used to manage models.) 
    zcli brand create VMware --title=VMware
  7. Create a model in ZEDEDA Cloud called 7.0u3guest using the hardware.json file created above. (Ensures that your hardware is know by ZEDEDA Cloud when you are ready to onboard.) 
    zcli model create 7.0u3guest --title=7.0u3guest--brand=VMware --hardware-details=/root/hardware.json

Get an EVE-OS ISO

Pull your preferred EVE version's ISO from Docker Hub. The following command will give you an ISO for EVE version 9.4.0, compatible with 64 bit AMD processors.

docker pull lfedge/eve:9.4.0-kvm-amd64

When you have your ISO, upload it to a ZEDEDA Cloud datastore or to your vSphere library. You'll point to your ISO later in this guide.

Configure a network portgroup on ESXi

Create a new portgroup with the following security settings set to "Accept":

  • Promiscuous mode
  • MAC address changes
  • Forged transmits

EVE guest setup

The following subsections describe and show how to create a new VM for a virtual instance of EVE. Complete them in order.

Create a new VM

Select Guest OS family and Guest OS version

VM storage

Select a datastore that will contain the vEVE VM.

CPU settings

Ensure that the following options in the CPU section are enabled:

  • Hardware virtualization
  • IOMMU
  • Performance counters

Network settings

CDROM settings

Select the ISO (which you created in a previous procedure) for the installation of the guest.

VM options

Ensure that "Enable UEFI secure boot" is not selected.

 

Get hardware serial number using powershell (Mac)

When you onboard a node, you’ll need its hardware serial number. The following procedure will give you the UUID of your vEVE VM formatted as a hardware serial number.

  1. Install PowerShell. 
    brew install --cask powershell
  2. Install PowerCLI. 
    PS /Users/USER_NAME Install-Module -Name VMware.PowerCLI -Scope CurrentUser
  3. Enter "y" at the prompt triggered by the previous command.
  4. Configure your PowerShell to ignore an invalid certificate. 
    PS /Users/USER_NAME Set-PowerCLIConfiguration -InvalidCertificateAction Ignore
  5. Enter "y" at the prompt triggered by the previous command.
  6. Connect to the viserver. 
    PS /Users/USER_NAME connect-viserver -server ESXI_OR_VSPHERE_ADDRESS
  7. Enter your credentials to esxi or vsphere at the prompt triggered by the previous command.
  8. Get the vEVE VM UUID. 
    PS /Users/USER_NAME $s = (Get-VM VM_NAME | %{(Get-View $_.Id).config.uuid}).Replace("-","")
  9. Verify that the previous command successfully saved the UUID. 
    PS /Users/USER_NAME echo $s
  10. Observe the output from the previous command. 
    564ded02f75268f111428e7cece8db81
  11. Paste the following code into your powershell CLI to format the UUID as a hardware serial number. 
    $Uuid = "VMware-"

    for ($i = 0; $i -lt $s.Length; $i += 2)
    {
         $Uuid += ("{0:x2}" -f [byte]("0x" + $s.Substring($i,2)))
         if ($Uuid.Length -eq 30) {$Uuid += "-"} else {$Uuid += " "}
    }
  12. Print the formatted hardware serial number. 
    PS /Users/USER_NAME $Uuid.TrimEnd()
  13. Save the output from the previous command. 
    VMware-56 4d f2 69 73 8c b3 72-5e 27 cf 93 40 26 6e f6

Onboard a node using the ZCLI

The following script will onboard a single edge node and create a network instance for it. Before you run it, replace ONBOARDING_KEY with the onboarding key of the node that you want to onboard.

param($viserver,$vmname,$model,$project)
$onboardingkey="ONBOARDING_KEY"

if($global:defaultviserver -eq $null) {
  connect-viserver -server $viserver
}

$s = (Get-VM $vmname | %{(Get-View $_.Id).config.uuid}).Replace("-","")

$Uuid = "VMware-"

for ($i = 0; $i -lt $s.Length; $i += 2) {
  $Uuid += ("{0:x2}" -f [byte]("0x" + $s.Substring($i, 2)))
  if ($Uuid.Length -eq 30) {$Uuid += "-"} else {$Uuid += " "}
}

$serialnumber=$Uuid.TrimEnd()
$containerid=docker ps | grep -i 'zededa/zcli | awk '{print $1}'

docker exec -t $containerid zcli edge-node create $vmname /
--onboarding-key=$onboardingkey --serial=$serialnumber --model=$model /
--project=$project --network=eth0:management:defaultIPv4-net Start-Sleep -Seconds 2

docker exec -t $containerid zcli network-instance create defaultLocal-$vmname /
--edge-node=$vmname --kind=local --ip-type=v4 --default --port=Uplink

docker exec -t $containerid zcli edge-node activate $vmname

Run the script

  1. Log in to the ZCLI
  2. Copy the previous onboarding script into a file named onboardveve.ps1
  3. Run the script. Note the following example's PLACEHOLDER_VALUES.
    PS /Users/user/Documents/powershell ./onboardveve.ps1 -viserver VCENTER_OR_ESXI_SERVER_IP_FDQN -vmname VM_NAME -model 7.0u3guest -project ZEDEDA_CLOUD_PROJECT_NAME
Was this article helpful?
1 out of 1 found this helpful