Installing Cumulocity IoT Edge
This section describes how to install Cumulocity IoT Edge.
This section describes how to install Cumulocity IoT Edge.
Item | Details |
---|---|
Hypervisor | - VMWare ESXi 6.5 and 6.7 - VMware Workstation Player 16.x - Hyper-V on Microsoft Windows 10 Enterprise, version 1809. The supported VM configuration version is 9.0. 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. |
Edge appliance image | To be downloaded from the Software AG Empower Portal, based on the target hypervisor. For VMware (ESXi and Workstation Player), download all the 4 files: - CumulocityIoTEdge-Appliance-version-VMware-disk1.vmdk - CumulocityIoTEdge-Appliance-version-VMware-disk2.vmdk - CumulocityIoTEdge-Appliance-version-VMware.mf - CumulocityIoTEdge-Appliance-version-VMware.ovf For Hyper-V, download the ZIP file: - CumulocityIoTEdge-Appliance-version-HyperV.zip The fixes for Cumulocity IoT Edge: - CumulocityIoTEdge-version.tar.gz |
Cumulocity IoT Edge license file | To request the license file for Cumulocity IoT Edge, please contact the logistics team for your region: - North and South America: LogisSrvus@softwareagusa.com - All Other Regions: LogisticsServiceCenterGER@softwareag.com In the email, you must include - your company name, under which the license has been bought - the domain name (for example, myedge.domain.com), where Cumulocity IoT Edge will be reachable For more information, see Domain name validation for Edge license key generation. |
SSL key and SSL certificate | Optional. Use your internal or an external CA (Certification Authority) to generate these files. These files must not be password-protected. Info: Ensure that the .crt and .key files are in PEM format and the .key file is not encrypted. |
DNS entry | The DNS (Domain Name System) is used to resolve human readable host names like www.cumulocity.com to machine readable IP addresses like 192.198.1.10. If you want to connect to Edge appliance within your LAN, the DNS entry has to be added for the domain name (URL under which Cumulocity IoT Edge can be reached) with the IP address of the host. |
Edge cloud remote access | To connect and manage one (or multiple) Edge appliances to your Cumulocity IoT cloud tenant, you need an active Cumulocity IoT Standard tenant with the Data Broker and Cloud Remote Access extensions. Info: The Edge cloud remote access is an optional feature in Cumulocity IoT Edge. |
To procure the Cumulocity IoT Edge license file, you must provide the right domain name to the Software AG’s logistics team for Edge license key generation.
When you provide the domain name, consider the following points:
The domain name does not need to be a Fully Qualified Domain Name (FQDN). For example, to access the Edge appliance with the domain name myown.iot.com, request the Edge license for myown.iot.com or iot.com (without the subdomain myown).
If you exclude the subdomain from the domain name in the Edge license, you must possess a wildcard SSL certificate which can be used with multiple subdomains (myown or others) of the domain (iot.com).
For example, if you provide iot.com as the domain name, you must possess an SSL certificate for .iot.com.
If you have an Internationalized Domain Name (IDN), then you must provide the translated ASCII equivalent domain name.
For example, if your domain name is myown.iöt.com (for example, containing ö), then you must use myown.xn–it-fka.com.
Also, provide the same translated ASCII equivalent domain name as the tenant domain name during the Edge installation process.
Info: An Internationalized Domain Name (IDN) is an internet domain name that contains at least one label, in whole or in part, in a language-specific script or alphabet, such as Arabic, Chinese, Cyrillic, Devanagari, Hebrew or the Latin alphabet-based characters with diacritics or ligatures, such as French. The internationalization of domain names is a technical solution to translate names written in language-native scripts into an ASCII text representation that is compatible with the Domain Name System. See Wikipedia.
Ensure that you adhere to the following domain name validation rules:
The following network ports must be reachable from the local network:
If Cumulocity IoT Edge should communicate with the cloud, the following ports of www.cumulocity.com (or another instance) need to be available:
There is no internet connection required during installation. Internet connection during runtime is optional, and only used if this is configured in the Data Broker.
The following ports need to be enabled by default in order to accept traffic from users and devices on the internet (also see Setting up port forwarding:
Source IP | Source Port | Destination IP | Destination Port | Service |
---|---|---|---|---|
any | any | Edge appliance IP | TCP/443 | HTTPS |
any | any | Edge appliance IP | TCP/1883 | MQTT |
any | any | Edge appliance IP | TCP/8883 | MQTT/TLS |
Depending on additional integrations more ports must be opened.
The core node must be able to connect to the internet. Ports required to outside are:
Service | Port |
---|---|
HTTPS | 443 |
Depending on the installed integrations (email, SMS, etc.) different ports might have to be opened in order to make these services available to the Cumulocity IoT platform. The descriptions of these ports are delivered with the corresponding integrations.
Depending on the DNS and NTP setup it might be the case that DNS (UDP/53) and NTP (UDP/123) connections to the internet must be possible from all hosts.
The virtual machine has the following minimum hardware requirements:
Hardware | Configuration |
---|---|
Disk space | 100 GB |
CPU | Intel x86 |
Number of CPU cores | 2 - without microservice 4 - with microservice |
RAM | 6 GB - without microservice 8 GB - with microservice |
Network Interface Controller (NIC) | 1 |
These are the minimum system requirements to enable the microservice hosting feature. If the microservice requires additional system resources, you must configure the system requirements accordingly in addition to minimum system requirements. For example, if the microservice requires 2 CPU cores and 4 GB of RAM, then the VM must have 6 CPU cores (4 cores for VM + 2 cores for microservice) and 12 GB of RAM (8 GB for VM + 4 GB for microservice).
Info: This does not cover host operating system hardware requirements. The host operating system resource requirements must be sized independently and should be over and above the resource allocated to the virtual machines.
To install Cumulocity IoT Edge using the user interface:
Info: The network configuration blue screen does not appear post installation. After the installation, you must use the Administration application or the REST API to configure the network.
Configure the network for your Edge appliance, see the sample screenshot.
Press Enter to save the network configuration.
Note down the URL to perform the installation. In the screenshot above, the URL is https://192.168.66.10/apps/installation/
.
Open the URL in a browser to start the installation process.
Read the prerequisites and ensure that you have the domain name, SSL certificate and key associated with your domain name, and the license file.
Click Start Installation.
Create an administrator account for the guest operating system below Guest OS admin.
Provide a password for the root user of the guest operating system below Guest OS root, and click Next.
Important: Do not use the root credentials to perform any task. The root credentials must be used only when asked by Software AG support personnel. Using it otherwise might void the appliance support.
Create an administrator account to access the Cumulocity IoT Edge tenant and the Cumulocity IoT Edge Management tenant, and click Next.
Provide a fully qualified domain name below Domain name.
For example, “myown.iot.com”. Here, you must have the Cumulocity IoT Edge license for the domain name iot.com or myown.iot.com.
The domain name must adhere to all the domain name validation rules as described in Domain name validation.
Provide the Cumulocity IoT Edge license file associated with your domain name below Licence file.
Provide the SSL certificate file and the SSL certificate key file.
If you do not have an SSL certificate, select Generate self-signed certificate to generate one.
Click Install.
During the installation, the certificates are updated in the Edge appliance. If these certificates are not accepted by your browser, the browser does not get the progress of the installation. In such case, you must refresh the browser and follow the browser instructions for more details. The installation takes some time to complete. After the installation is complete, the “Cumulocity IoT Edge installation is now complete” message appears.
Info: If you still see the installation in progress, refresh the browser.
Next, click Open Cumulocity IoT Edge.
Important: In case you need to reset the password, you must configure the “reset password” template and email server settings to receive the password reset email. For more information, see Configuring password reset and Configuring email server in the User guide.
Cumulocity IoT Edge supports REST APIs to perform the tasks like installation, configuration, updating the Edge appliance, and so on. For more information about working with REST APIs, see REST APIs for Edge.
To install Cumulocity IoT Edge using the REST APIs, use the following endpoints:
To check the status of the installation, use the following endpoints:
The Cumulocity IoT Edge appliance is accessible using the domain name configured as part of the installation.
There are two ways to configure the accessibility with the domain names:
Info: The first option is always preferable so that the Edge appliance is accessible over LAN.
On Linux machines, add the following entry to /etc/hosts:
<IP address> <domain_name>
Use the IP address provided during the network configuration. For example, the default value for Hyper-V is 192.168.66.10.
On Windows machines, add the same entry to C:\Windows\System32\drivers\etc\hosts.
Ping the <domain_name> to verify it.
[admin@iot-edge-server ~]$ ping <domain_name>
If the ping is successful, the DNS resolution is working properly.
Using <domain_name>, the Edge appliance can be connected from the host operating system (operating system which is hosting the Edge appliance). If you want to connect the Edge appliance within your LAN, which is outside of the host operating system, you need to do following:
Enter the URL in the browser:
https://<domain_name>
The Edge appliance login screen appears. Log in with your credentials created during the installation.