Install EVE-OS onto ESXi

Introduction

Run EVE-OS as one or more virtual machines on VMware ESXi to operate multiple independent nodes on a single physical host. Any instance of EVE running on a hypervisor as “virtual EVE” or a “virtual node” is referred to as virtual EVE (vEVE). A virtual instance of EVE-OS functions identically to a physical one, with two minor differences:

IOMMU functionality can only be accessed by one virtual node at a time on a given host.
Virtualization adds some overhead, which may affect performance-sensitive applications.

This procedure assumes familiarity with ESXi. For ESXi-specific operations not covered here, refer to VMware’s official documentation.

Prerequisites

EVE-OS version 9.4.0 or later.
ESXi server 7.0 Update 3 or later.
PowerShell/PowerCLI (recommended for the onboarding step).

Add VM Hardware to Your Enterprise

Log in to ZCLI. See Get Started With ZCLI for authentication steps.
Create a hardware.json file for an ESXi VM on your local machine. See the Hardware Models guide for file format details.
List your Docker containers.

docker ps

Observe the output from the previous command. Copy the ID of your ZCLI container, shown in the first column of the output. For example:

4fbeb231cb3b   zededa/zcli:9.4.0   "/bin/bash --rcfile ..."   3 minutes ago   Up 3 minutes   compassionate_blackburn

Copy your hardware.json into the ZCLI container’s root directory.

docker cp PATH_TO_hardware.json DOCKER_CONTAINER_ID:/root

Create a brand in Edge Infrastructure Services called VMware.

zcli brand create VMware --title=VMware

Create a hardware model called 7.0u3guest using your hardware.json file.

zcli model create 7.0u3guest --title=7.0u3guest --brand=VMware --hardware-details=/root/hardware.json

Get an EVE-OS ISO

Pull the EVE-OS ISO for your target version from Docker Hub. The following example uses version 9.4.0 for AMD64.

docker pull lfedge/eve:9.4.0-kvm-amd64

Upload the ISO to a ZEDEDA Cloud datastore or your vSphere library. You will point to it when creating the VM.

Configure a Network Port Group on ESXi

Create a new port group with the following security settings set to Accept:

Promiscuous mode
MAC address changes
Forged transmits

ESXi port group security settings showing Promiscuous mode, MAC address changes, and Forged transmits all set to Accept

Create the Virtual Machine

Complete the following sub-sections in order to create the vEVE VM.

Create a new VM

Select Guest OS family and Guest OS version

ESXi Guest OS family and version selection showing Linux guest type

VM storage

Select a datastore to host the vEVE VM.

CPU settings

Enable the following options in the CPU section: Hardware virtualization, IOMMU, and Performance counters.

Network settings

Assign the port group created in the previous section.

CD-ROM settings

Select the EVE-OS ISO (created in the previous section) for the guest installation.

VM options

Ensure Enable UEFI secure boot is not selected.

Get the Hardware Serial Number (macOS)

When onboarding a vEVE node, you need its hardware serial number derived from the VM UUID. The following procedure uses brew and is written for macOS. For other platforms, use the equivalent PowerShell installation method.

Install PowerShell.

brew install --cask powershell

Install PowerCLI. Enter y at the prompt.

PS /Users/USERNAME Install-Module -Name VMware.PowerCLI -Scope CurrentUser

Configure PowerShell to ignore invalid certificates (if applicable). Enter y at the prompt.

PS /Users/USERNAME Set-PowerCLIConfiguration -InvalidCertificateAction Ignore

Connect to the ESXi or vSphere server. Enter your credentials at the prompt.

PS /Users/USERNAME connect-viserver -server ESXI_OR_VSPHERE_ADDRESS

Get the vEVE VM UUID.

PS /Users/USERNAME $s = (Get-VM VM_NAME | %{(Get-View $_.Id).config.uuid}).Replace("-","")

Verify that the UUID was saved correctly.

PS /Users/USERNAME echo $s

The output looks like: 564ded02f75268f111428e7cece8db81

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 += " "}
}
PS /Users/USERNAME $Uuid.TrimEnd()

Save the output. It looks like:

VMware-56 4d f2 69 73 8c b3 72-5e 27 cf 93 40 26 6e f6

Onboard the Node Using ZCLI

Use the following PowerShell script to onboard a single vEVE node. Replace ONBOARDING_KEY with the node’s onboarding key before running.

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

To run the script:

Log in to ZCLI. See Get Started With ZCLI for authentication steps.
Save the script as onboardveve.ps1.
Run the script, replacing the placeholder values with your environment details.

./onboardveve.ps1 -viserver VCENTER_OR_ESXI_IP -vmname VM_NAME -model 7.0u3guest -project PROJECT_NAME

Start Here

Infrastructure Services Overview

Core infrastructure

Build

Applications and delivery

Edge Kubernetes

Operations

Monitor

Administration and Security

Troubleshooting

Partnerships

Introduction

Prerequisites

Add VM Hardware to Your Enterprise

Get an EVE-OS ISO

Configure a Network Port Group on ESXi

Create the Virtual Machine

Create a new VM

Select Guest OS family and Guest OS version

VM storage

CPU settings

Network settings

CD-ROM settings

VM options

Get the Hardware Serial Number (macOS)

Onboard the Node Using ZCLI

Next Steps

Onboard Nodes

Get Started with ZCLI

​Introduction

​Prerequisites

​Add VM Hardware to Your Enterprise

​Get an EVE-OS ISO

​Configure a Network Port Group on ESXi

​Create the Virtual Machine

​Create a new VM

​Select Guest OS family and Guest OS version

​VM storage

​CPU settings

​Network settings

​CD-ROM settings

​VM options

​Get the Hardware Serial Number (macOS)

​Onboard the Node Using ZCLI

​Next Steps

Onboard Nodes

Get Started with ZCLI

Introduction

Prerequisites

Add VM Hardware to Your Enterprise

Get an EVE-OS ISO

Configure a Network Port Group on ESXi

Create the Virtual Machine

Create a new VM

Select Guest OS family and Guest OS version

VM storage

CPU settings

Network settings

CD-ROM settings

VM options

Get the Hardware Serial Number (macOS)

Onboard the Node Using ZCLI

Next Steps