Updating Edge

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.

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 .

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

This section describes the steps to migrate from Edge 10.7 to Edge 10.9. If you are using a version earlier than Edge 10.7 and plan to upgrade to Edge 10.9, you must first upgrade to Edge 10.7.

Before you begin

• Import the Edge 10.9 appliance, see Configuring the Edge infrastructure for further information.
• Configure the network and complete the installation procedure on your Edge 10.9 appliance. For details see Installing Edge.

For information about upgrading from an earlier version to Edge 10.7, see:

• Operating Cumulocity IoT Edge > Upgrading on VMware ESX,
• Operating Cumulocity IoT Edge > Upgrading on VMware Workstation Player,
• Operating Cumulocity IoT Edge > Upgrading on Hyper-V

in the 10.7.0 Cumulocity IoT Edge guide.

To migrate from Edge 10.7 to 10.9:

• back up the data on Edge 10.7,
• move the backup to Edge 10.9,
• restore the data on Edge 10.9.

Creating a backup on Edge 10.7

In your Edge 10.7 setup, back up the data for each tenant and docker collection, and note down the device ID.

1. Run the following command to stop monitoring all processes:

   monit unmonitor all
   

2. Stop the Karaf process by using the following command:

   sudo service cumulocity-core-karaf stop
   

3. Create a backup of the MongoDB database by using the following commands:

   mongodump --db=management --out OUTPUT_DIRECTORY # OUTPUT_DIRECTORY specifies the location of the backup.
   mongodump --db=edge --out OUTPUT_DIRECTORY
   mongodump --db=docker --out OUTPUT_DIRECTORY # This only needs to be done if microservices are enabled on 10.7.
   

4. Note down the device ID of your Edge 10.7 appliance available at /usr/edge/properties/edge-agent/device-id.

5. Create a backup of the /etc/opcua directory.

6. Create a backup of the /var/lib/cumulocity-agent/credentials file.

Restoring the data on Edge 10.9

To restore the data, you must first copy the MongoDB backup from the Edge 10.7 appliance to your Edge 10.9 appliance.

Perform the following steps as a root user in your Edge 10.9 appliance.

1. Copy the backup folders from your Edge 10.7 appliance to the Edge 10.9 appliance using any file transfer tool such as WINSCP, SCP, or FTP.

   Copy the backup folders to /home/admin/migration_data/ in your Edge 10.9 appliance.

2. Backup the web applications in the Edge 10.9 appliance. To do this, first detect the IDs of the applications by using the following command:

   mongo management --quiet --eval 'db.cmdata.files.find({},{"_id":false, "metadata.id":true,"metadata.name":true})' | jq
   

   The command returns the name and ID of the application. For example:

   {
     "metadata": {
       "id": "112",
       "name": "cockpit.zip"
     }
   }
   {
     "metadata": {
       "id": "113",
       "name": "devicemanagement.zip"
     }
   }
   {
     "metadata": {
       "id": "114",
       "name": "administration.zip"
     }
   }
   {
     "metadata": {
       "id": "122",
       "name": "streaming-analytics-app.zip"
     }
   }
   

3. Download the web applications using the ID of the application by using the following commands:

   mkdir -p /tmp/apps/
   mongofiles -d management --prefix cmdata get  APP_ID -l /tmp/apps/APP_NAME.zip
   

   Here:

   • APP_ID refers to the ID of the application. For example, 112
   • APP_NAME refers to the name of the application. For example, devicemanagement.zip

   For example:

   mongofiles -d management --prefix cmdata get  112 -l /tmp/apps/cockpit.zip
   mongofiles -d management --prefix cmdata get  113 -l /tmp/apps/devicemanagement.zip
   mongofiles -d management --prefix cmdata get  114 -l /tmp/apps/administration.zip
   mongofiles -d management --prefix cmdata get  122 -l /tmp/apps/streaming-analytics-app.zip
   

   Important

   Create a backup of the streaming-analytics-app.zip file separately.

4. Install the RPM package by using the following command:

   rpm -ivh http://mirror.centos.org/centos/7/os/x86_64/Packages/zip-3.0-11.el7.x86_64.rpm
   

   If your Edge appliance is not connected to the internet, ensure that the RPM package is available locally and run the following command:

   rpm -ivh zip-3.0-11.el7.x86_64.rpm
   

5. Prepare the applications for deployment by using the following commands:

   Important

   Do not include the streaming-analytics-app.zip file in the ZIP package.

   UI_VERSION=1009.0.14 #The Edge appliance UI version number. Must be in the format xxxx.x.x
   cd /tmp/apps
   zip package-cumulocity-$UI_VERSION.zip cockpit.zip devicemanagement.zip administration.zip #Do not include the streaming-analytics-app.zip file.
   chown karaf:karaf package-cumulocity-$UI_VERSION.zip
   zip $UI_VERSION.zip package-cumulocity-$UI_VERSION.zip
   chown karaf:karaf $UI_VERSION.zip
   

6. Restore the device ID of the Edge 10.7 appliance by using the following commands:

   DEVICE_ID="DEVICE_ID_OF_EDGE_10.7"
   
   curl -v --header "Content-Type: application/json" --request POST --data
   '{"device_id":"'$DEVICE_ID'"}' 127.0.0.1:3032/configuration/edge-agent
   
   systemctl restart edge-agent
   

7. Restore the MongoDB collections from the Edge 10.7 appliance by using the following command:

   mongorestore --drop --db TENANT_NAME PATH_TO_BACKED_UP_COLLECTION
   

   Here:

   • PATH_TO_BACKED_UP_COLLECTION refers to the location of the 10.7 backup folders in your Edge 10.9 appliance.

   For example:

   mongorestore --drop --db edge /home/admin/migration_data/edge/
   mongorestore --drop --db management /home/admin/migration_data/management/
   mongorestore --drop --db docker /home/admin/migration_data/docker/
   

8. Restore the web applications of the Edge 10.9 appliance by using the following command:

   chown -R karaf:karaf /webapps/
   chown nginx:karaf /webapps
   cp -a /tmp/apps/$UI_VERSION.zip /webapps/2Install/
   

   Wait for Karaf to install the applications. After the installation is complete, the $UI_VERSION.zip.installed file appears at /webapps/2Install.

9. Copy the /etc/opcua directory from the Edge 10.7 appliance to the same location on the Edge 10.9 appliance.

10. Copy the /var/lib/cumulocity-agent/credentials file from the Edge 10.7 appliance to the same location on the Edge 10.9 appliance.

11. Restart the services by using the following commands:

    systemctl restart cumulocity-agent
    systemctl restart nginx
    systemctl restart cumulocity-core-karaf
    monit restart opcua_device_gateway_proc
    monit restart opcua_mgmt_service_proc
    

12. Restore the Streaming Analytics application by following these steps:

    • Log in to the Management tenant using the 10.7 Management tenant admin credentials. By default, the credentials are sysadmin/sysadmin-pass.

    • Upload the streaming-analytics-app.zip file as a web application.

    • Subscribe the Streaming Analytics application to the “Edge” tenant.

      Important

      To subscribe the application, the Management tenant user must have the “Tenant Manager” role.

    • Delete the Apama Analytics Builder and Apama EPL Apps applications.

    • Log in to the “edge” tenant and verify the Streaming Analytics application.

Restoring the Streaming Analytics application completes the migration procedure. Note that the tenants from the Edge 10.9 installation are removed after the successful migration. You are now be able to log in using the Edge 10.7 user credentials.

Next, configure the Edge 10.9 appliance. For example, if you enabled microservices and configured NTP in the Edge 10.7 appliance, you must enable microservices and configure NTP in the Edge 10.9 appliance.

If enabling the microservice hosting feature fails, it may be due to a Kubernetes limitation. After resolving the issue, delete the kube-registry pod and wait for it to be recreated.

For more information about configuring the Edge 10.9 appliance, see Configuring Edge.

Sample scripts to automate the migration

Software AG provides the backup.sh and restore.sh scripts for your reference. You may customize these scripts for your requirements and automate the migration process. These scripts are available at:

• backup.sh
• restore.sh - you must run the restore.sh script as a root user.
• restore_analytics.sh - restores the Streaming Analytics application.

Using the scripts

In 10.7 appliance

1. Run the following command to stop monitoring all the processes:

   monit unmonitor all
   

2. Stop the Karaf process by using the following command:

   sudo service cumulocity-core-karaf stop
   

3. Copy the backup.sh script to your Edge 10.7 appliance.

4. Run the backup.sh as a root user.

   You can also run the script with the parameters:

   • OUTPUT_DIRECTORY: (optional) path to save the backup archive on the same file system.
   • ARCHIVE_PATH: (optional) path to save the backup archive on an external file system.
   Info

   If you do not specify any parameter, the backup archive is saved to the /tmp directory. The /tmp directory is located on the installation disk. If the installation disk has no space, the system can become unstable.

   For example:

   ./backup.sh /home/admin/
   

   The script creates a ZIP archive file with the migration data in the OUTPUT_DIRECTORY.

5. Move the ZIP archive with the migration data to your Edge 10.9 appliance.

In 10.9 appliance

1. Log in as a root user.

2. Copy the restore.sh and restore_analytics.sh scripts to your Edge 10.9 appliance.

3. Run the restore.sh script with the parameters:

   • ARCHIVE_PATH: path to the ZIP with 10.7 migration data.
   • EXTRACTED_PATH: path to the folder with extracted migration data. It can also be an external drive.

   For example:

   ./restore.sh migration_data.tgz /home/admin/migration_data
   

   The restore.sh script fails if your Edge appliance is not connected to the internet. In such cases, ensure that the RPM package is available locally, and replace the command rpm -ivh http://mirror.centos.org/centos/7/os/x86_64/Packages/zip-3.0-11.el7.x86_64.rpm with rpm -ivh zip-3.0-11.el7.x86_64.rpm in the restore.sh script.

4. Run the restore_analytics.sh script. This script restores the Streaming Analytics application.

   ./restore_analytics.sh USERNAME PASSWORD /tmp/streaming-analytics-app.zip
   

   Here:

   • USERNAME and PASSWORD refers to the Management tenant user credentials.

   Running the restore_analytics.sh script completes the migration process.

Next, you must configure the Edge 10.9 appliance. For example, if you had enabled microservices and configured NTP in the Edge 10.7 appliance, you must enable microservices and configure NTP in the Edge 10.9 appliance.

If enabling the microservice hosting feature fails, it may be due to a Kubernetes limitation. After resolving the issue, delete the kube-registry pod and wait for it to be recreated.

For more information about configuring the Edge 10.9 appliance, see Configuring Edge.