This section describes how to update Cumulocity IoT Edge using the GUI and the REST API. An update refers to applying a patch/fix to an existing Cumulocity IoT Edge installation or updating your Edge appliance to a higher version.
Keeping your Edge appliance updated ensures that the Edge appliance is running the latest version with new features and enhancements, and helps in improving the security vulnerabilities and performance of the Edge appliance.
You can update Edge or apply fixes to your existing installation using the Administration application in the Management tenant.
Download the Edge archive file Cumulocity IoT Edge (version) Update from the Software AG Empower Portal.
When you update your Edge appliance, the update also applies operating system patches and fixes for security vulnerabilities. Software AG recommends you to create a backup of your existing Edge installation before performing any update.
The following section outlines the procedure for migrating from Edge 10.17 to 10.18. Since Edge 10.18 is based on the Rocky Linux operating system, the upgrade process entails a side-by-side installation accompanied by data migration.
Important
If you are using a version earlier than Edge 10.17 and plan to migrate to Edge 10.18, you must first update your Edge to version 10.17.
If you are using a version prior to Edge 10.13, you must first update your Edge to version 10.13 before upgrading to 10.17.
For information about upgrading from an earlier version to Edge 10.17, see:
In your Edge 10.17 appliance, back up the MongoDB data, Edge, Cumulocity Agent, and OPC UA configurations.
Important
Before attempting the backup, ensure that there is sufficient disk space to save the backup in your Edge 10.17 appliance.
Perform the following steps as a root user on your Edge 10.17 appliance.
Run the following commands to unmonitor all services and stop the opcua-mgmt-service, opcua-device-gateway, smartrule, apama, cumulocity-core-karaf and mongod services:
If you have installed Cumulocity IoT DataHub in the Edge 10.17 appliance, run the following commands to stop the cdh-console, cdh-master and cdh-executor services:
service cdh-console stop && \
service cdh-master stop && \
service cdh-executor stop
Back up the MongoDB data, data lake contents from the DataHub if present, Edge, Cumulocity Agent, and OPC UA configurations using the following command to create the /opt/edge-1017-backup.tar file:
tar -zcf /opt/edge-1017-backup.tar /opt/softwareag /opt/mongodb /var/lib/cumulocity-agent /usr/edge /opt/opcua
After creating the /opt/edge-1017-backup.tar file, copy it to a network drive or storage location that is accessible from the Edge 10.18 appliance you will create in the next step. Once the backup file is safely stored, shut down the Edge 10.17 appliance to prevent any further changes to the system during the migration process. This step is optional and if not performed, you need to copy it directly into the Edge 10.18 appliance once it is created.
Installing Edge 10.18
Install the Edge appliance 10.18 following the instructions below.
Important
If you have both the Edge 10.17 and Edge 10.18 appliances on the same host machine, ensure that the IP addresses of both appliances are different.
Follow the installation procedure on your Edge 10.18 appliance, ensuring to configure the network settings appropriately. For detailed steps, refer to Installing Edge.
Migrating Backup Data to Edge 10.18
After installing and configuring the Edge 10.18 appliance, proceed to migrate the data and configurations backed up from Edge 10.17 to the new appliance.
Perform the following steps as a root user on your Edge 10.18 appliance:
Transfer the backup file /opt/edge-1017-backup.tar from the Edge 10.17 appliance to your Edge 10.18 appliance.
Important
Before copying the backup, ensure that there is sufficient disk space available on your Edge 10.18 appliance. For example, if the size of the data disk in the Edge 10.18 appliance is 75 GB and the size of the backup file is 100 GB, you must expand the size of the data disk by an additional 125 GB (total 200 GB, of which 100 GB used by the backup tar file) before copying the backup. For instructions on expanding disk size, refer to Expanding the disk size.
Run the following commands to unmonitor and stop the relevant services:
Cleanup the MongoDB data before replacing the backup data with the following command:
rm -rf /opt/mongodb/*
Untar the backup file using the following command:
tar -xf /opt/edge-1017-backup.tar -C /
Reboot the Edge appliance with the following command:
reboot
Once the Edge appliance restarts, verify its health by following the instructions in the Health check section. Ensure that the monit summary command returns status OK for all services and processes as described in Using Monit section.
Follow the steps outlined in Updating Edge to finalize the data migration process.
Configuring Edge 10.18 after data migration
After migrating data to Edge 10.18, proceed to configure the appliance to the same level as Edge 10.17.
If you have enabled the microservice hosting feature in the Edge 10.17 appliance, follow the instructions in Enabling the microservice hosting feature to enable the same in Edge 10.18.
If you have installed Cumulocity IoT DataHub in the Edge 10.17 appliance, follow the instructions in Setting up Cumulocity IoT DataHub Edge to install the same in Edge 10.18. Before you proceed with installing Cumulocity IoT DataHub, change the ownership of the data lake folders using the following command:
For detailed guidance on configuring the Edge 10.18 appliance, consult Configuring Edge.
Sample script to automate the data migration
Software AG provides the edge-1017-to-1018-data-migration.sh script as a reference for automating the data migration process. You can customize this script according to your requirements. Click here to download the script.
Important
Software AG does not officially support this migration script. It is provided for reference purposes only.
Using the script
Install the Edge 10.18 appliance by following the instructions in Installing Edge 10.18
Download the edge-1017-to-1018-data-migration.sh script and copy it to your Edge 10.18 appliance. This script migrates the necessary data including data lake contents from the DataHub.
Execute the edge-1017-to-1018-data-migration.sh script as a root user. Provide the IP address and root user password for the Edge 10.17 appliance when prompted. Note that you need to enable root login over SSH on the Edge 10.17 appliance for the script to work properly.
After executing the script, reboot the Edge appliance using the following command:
reboot
Once the Edge appliance restarts, verify its health by following the instructions in the Health check section. Ensure that the monit summary command returns status OK for all services and processes as described in Using Monit section.
Follow the steps outlined in Updating Edge to finalize the data migration process.