Configuring the Edge infrastructure

This document describes how to set up the hypervisor infrastructure for Cumulocity IoT Edge.

Important: Ensure that you keep the virtualization platform updated and free from vulnerabilities by following the security advisories provided by the vendors of the hypervisor.

Example setup for VMware ESXi

Setting up ESXi

To set up an ESXi virtual machine, follow these steps:

  1. Click Create/Register VM to open a window to select the creation type.

  2. Under Select creation type, select Deploy a virtual machine from OVA or OVF template and click Next.

  3. In the next window, provide a name for the VM, e.g. EDGE-server, and drag and drop the required files (ovf, vmdk1, vmdk2) and click Next.

  4. Under Select storage, select the datastore where the VM will reside and click Next.

  5. Under Deployment options, select options like thin/thick provisioning and click Next.

  6. Review the machine settings and click Finish to complete the setup.

A VM with the provided name (for example, “EDGE-server”) should now show up in the Virtual Machines section. Notifications will appear accordingly in the Recent tasks pane.

VM hardware configuration

Next, perform the Edge appliance installation. See, Installing Cumulocity IoT Edge.

Example setup for VMware Workstation Player

Setting up for VMware

To set up the Edge appliance in VMware Workstation Player, follow the steps below.

Info: The following steps show a reference example. Refer to the VMware documentation for the exact setup. The final configuration also depends on the end user setup.

  1. In VMware, navigate to Player > File > Open to import the Edge appliance.

  2. Navigate to the folder where the Edge appliance files are located, select the OVF file and click Open.

  3. Change the Edge appliance name if required and click Import. You can also change the storage path of the Edge appliance here.

    Important: On VMware Workstation, you must use UTC on your host machine. If you choose not to use UTC, you may have time sync issues. Set rtc.diffFromUTC=0 in the .vmx file to avoid the time sync issues.

  4. Start the Edge appliance by clicking Play virtual machine.

Next, perform the Edge appliance installation. See, Installing Cumulocity IoT Edge.

Setting up for vmnetcfg utility

You can use the VMware vmnetcfg utility to get the necessary details like the subnet mask and gateway IP required to configure the network.

The following example illustrates the network configuration on a Windows platform. For instructions on Linux platform, see VMware Knowledge Base.

  1. Download the correct version of the vmnetcfg utility. It can also be extracted from the VMware Workstation Pro installer.

  2. Save the vmnetcfg binary file (vmnetcfg.exe) in the VMware Workstation Player installation directory. In a Windows environment, this is usually C:\Program Files (x86)\VMware\VMware Player.

  3. Open the file with the appropriate rights.

  4. Select “NAT” as external connection.

  5. Click NAT settings to open the NAT Settings window.

  6. Note down the gateway IP address and close the NAT settings window.

  7. Click DHCP Settings to open the DHCP Settings window.

  8. In the fields Starting IP address and Ending IP address, change the IP range from 3 to 254, i.e. if your gateway IP is 192.168.117.2, set the IP range from 192.168.117.3 to 192.168.117.254.

  9. Click OK to save your settings.

Port forwarding on a VMware platform

To perform port forwarding on a VMware platform, follow the steps below.

Important: The IP addresses used in the screenshots are sample IP addresses, for the purpose of example only. The IP addresses may vary in your set up.

  1. Run the vmnetcfg.exe utility as an administrator.

  2. Select the NAT adapter and click NAT Settings.

  3. Click Add to add the port forwarding rules. Enter the port forwarding rules for HTTPS, MQTT and MQTT over SSL protocols as described in the table below:

    Info: Ensure that the Virtual machine IP address is the same as the IP address that you have configured for the Edge appliance.

    Host Port Type VM IP Address VM Port Description
    443 TCP 192.168.117.10 443 HTTPS
    1883 TCP 192.168.117.10 1883 MQTT
    8883 TCP 192.168.117.10 8883 MQTT over SSL

    Click OK in the Map Incoming Port window after entering the port forwarding rules for each port.

  4. Click OK in the NAT Settings window.

  5. Click Apply > OK.

Example setup for Hyper-V

To set up Hyper-V, you must first enable Hyper-V on your system, and create Network Address Translation (NAT) adapter. For enabling Hyper-V, see the Microsoft documentation.

Creating a NAT adapter

You can create a NAT adapter using two ways:

Info: Run all the commands in Windows PowerShell with administrative privileges.

Creating a NAT adapter using default settings

Info: You must use the default adapter name NATSwitchForEdge and the default IP address 192.168.66.1.

  1. Open Windows PowerShell with administrative privileges.
  2. Create a new NAT adapter.
PS C:\WINDOWS\system32> New-VMSwitch -SwitchName "NATSwitchForEdge" -SwitchType Internal
  1. Verify that the new NAT adapter is created.
PS C:\WINDOWS\system32> Get-NetAdapter

Note down the ifIndex of the adapter. The ifIndex in the above screenshot is 31. The ifIndex may vary in your system and the same ifIndex should be used in the next step.

  1. Assign an IP address for the adapter.
PS C:\WINDOWS\system32> New-NetIPAddress -IPAddress 192.168.66.1 -PrefixLength 24 -InterfaceIndex 31
  1. Create a NAT rule.
PS C:\WINDOWS\system32> New-NetNat -Name NATSwitchForEDGE -InternalIPInterfaceAddressPrefix 192.168.66.0/24

Creating a NAT adapter using user-defined settings

You can define the adapter name and configure the IP address for your Edge appliance. In this example, the adapter name is EdgeAdapter1 and the IP address is 10.20.30.40.

Info: The following steps show a reference example. The final configuration also depends on the end user setup.

  1. Open Windows PowerShell with administrative privileges.
  2. Create a new NAT adapter.
PS C:\WINDOWS\system32> New-VMSwitch -SwitchName "EdgeAdapter1" -SwitchType Internal
  1. Verify that the new NAT adapter is created.
PS C:\WINDOWS\system32> Get-NetAdapter

Note down the ifIndex of the adapter. The ifIndex may vary in your system and the same ifIndex should be used in the next step.

  1. Assign an IP address for the adapter.
PS C:\WINDOWS\system32> New-NetIPAddress -IPAddress 10.20.30.40 -PrefixLength 24 -InterfaceIndex 71
  1. Create a NAT rule.
PS C:\WINDOWS\system32> New-NetNat -Name EdgeNATRule1 -InternalIPInterfaceAddressPrefix 10.20.30.0/24

Setting up the Edge appliance in Hyper-V

After creating a NAT adapter, you must import the Edge appliance image into Hyper-V.

  1. In Hyper-V Manager, go to Action > Import Virtual Machine.

  2. In the Before You Begin wizard, click Next.

  3. Provide the location of the Edge appliance image and click Next.

  4. Select the Edge appliance and click Next.

  5. In the Choose Import Type wizard, select Register the virtual machine in-place (use the existing unique ID) and click Next.

  6. If you have used the default NAT adapter name, skip this step and proceed with step 7.
    If you have used a different NAT adapter name, you will see the following screen:
    Select the adapter from the Connection drop down list and click Next.

  7. Click Finish. The Edge appliance image appears in the Hyper-V Manager.

  8. Right-click the Edge appliance image and click Connect.

Info: By default, the NTP servers are configured to Europe NTP servers. You can configure the NTP server as per your requirements.