Updating Edge

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 the Edge appliance using the GUI or the REST API.

Updating Edge using the GUI

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.

Important
For information about upgrading from an earlier version to Edge 10.18, refer to Migrating Edge 10.17 to 10.18.

To update Edge:

  1. Log in to the Management tenant.

  2. Switch to the Administration application using the application switcher at the right of the top bar icon.

  3. Click Edge > Update in the navigator.

  4. Click Update > Next.

  5. Upload the new Edge archive file and click Next.

  6. Click Update.

    While updating the Edge appliance with the microservice hosting feature enabled, the following notification may appear on the user interface:

    Could not get the details on the update status. Do refresh after some time to check if the update has completed.

    Refresh the page to check if the update has been completed by verifying the version number.

  7. Restart your Edge appliance.

Updating Edge using the REST APIs

To update Edge using the REST APIs, see POST /edge/update.

Migrating Edge 10.17 to 10.18

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 the 10.17.0 Cumulocity IoT Edge guide.

Backing Up Data and Configuration on Edge 10.17

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.

  1. 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:

    monit unmonitor all && \
systemctl stop installation-service opcua-mgmt-service opcua-device-gateway smartrule apama cumulocity-core-karaf mongod

  2. 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

  3. 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

  4. 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.
  1. Refer to Configuring the Edge infrastructure for detailed instructions on importing the Edge 10.18 appliance.
  2. 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:

  1. 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.

  2. Run the following commands to unmonitor and stop the relevant services:

    monit unmonitor all && \
systemctl stop installation-service opcua-mgmt-service opcua-device-gateway smartrule apama cumulocity-core-karaf mongod

  3. Cleanup the MongoDB data before replacing the backup data with the following command:

    rm -rf /opt/mongodb/*

  4. Untar the backup file using the following command:

    tar -xf /opt/edge-1017-backup.tar -C /

  5. Reboot the Edge appliance with the following command:

    reboot

  6. 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.

  7. 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.

  1. Follow the instructions in Configuring the time synchronization to synchronize the time settings.

  2. Refer to Configuring the Network for instructions on configuring the network settings.

  3. 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.

  4. 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:

    chown -R systemd-coredump:systemd-coredump /opt/mongodb/cdh-*

  5. For information about security configuration, refer to Configuring security.

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

  1. Install the Edge 10.18 appliance by following the instructions in Installing Edge 10.18

  2. 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.

  3. 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.

  4. After executing the script, reboot the Edge appliance using the following command:

    reboot

  5. 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.

  6. Follow the steps outlined in Updating Edge to finalize the data migration process.

  7. Refer to Configuring Edge 10.18 after data migration for instructions on configuring the new Edge appliance.