Migrating Cumulocity IoT Edge 10.7 to 10.9

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

Important: You can have both the Edge 10.7 and the Edge 10.9 appliances on the same host machine. Ensure that the IP address of the Edge 10.9 appliance is different from the IP address of the Edge 10.7 appliance.

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

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.

Important: Before the data back up, ensure that there is sufficient disk space to save the back up in your Edge 10.7 appliance. The MongoDB backup requires the same amount of space as the database. For example, if the size of the database is 100 GB, the MongoDB backup also requires 100 GB of disk space. You would need an additional 100 GB of disk space to save the MongoDB backup in your Edge 10.7 appliance.

Run the following command to stop monitoring all processes:
```
monit unmonitor all
```
Stop the Karaf process by using the following command:
```
sudo service cumulocity-core-karaf stop
```

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

Note down the device ID of your Edge 10.7 appliance available at /usr/edge/properties/edge-agent/device-id.
Create a backup of the /etc/opcua directory.
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.

Important: Before copying the backup, ensure that there is sufficient disk space in your Edge 10.9 appliance. For example, in the Edge 10.9 appliance, if the size of the data disk is 75 GB and the size of the MongoDB backup is 100 GB, you must expand the size of the data disk to additional 100 GB before copying the MongoDB backup. For more information about disk size expansion, see Expanding the disk size.

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

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.

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"
  }
}

Download the web applications using the ID of the application by using the following command:

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.

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

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

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

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/

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

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

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

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.

Important: To enable the microservice hosting feature, the Management tenant user must have the “Tenant Manager” role. Use the 10.7 Management tenant admin credentials. By default, the credentials are sysadmin/sysadmin-pass.

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 Cumulocity IoT 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 for reference at:

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

Important: Software AG does not officially support these scripts. These scripts are only for your reference.

Using the scripts

In 10.7 appliance

Important: Before the data back up, ensure that there is sufficient disk space to save the backup in your Edge 10.7 appliance. The MongoDB backup requires the same amount of space as the database. For example, if the size of the database is 100 GB, the MongoDB backup also requires 100 GB of disk space. You would need additional 100 GB of disk space to save the MongoDB backup in your Edge 10.7 appliance.

Run the following command to stop monitoring all the processes:
```
monit unmonitor all
```
Stop the Karaf process by using the following command:
```
sudo service cumulocity-core-karaf stop
```
Copy the backup.sh script to your Edge 10.7 appliance.
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 at /tmp directory. The /tmp directory is located on the installation disk. If the installation disk has no space, the system could become unstable.

For example:
```
./backup.sh /home/admin/
```
The script creates a ZIP archive file with the migration data in the OUTPUT_DIRECTORY.
Move the ZIP archive with the migration data to your Edge 10.9 appliance.

In 10.9 appliance

Important: Before copying the backup, ensure that there is sufficient disk space in your Edge 10.9 appliance. For example, in the Edge 10.9 appliance, if the size of the data disk is 75 GB and the size of the MongoDB backup is 100 GB, you must expand the size of the data disk to additional 100 GB before copying the MongoDB backup. For more information about disk size expansion, see Expanding the disk size.

Log in as a root user.
Copy the restore.sh and restore_analytics.sh scripts to your Edge 10.9 appliance.
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.

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.

Important: To enable the microservice hosting feature, the Management tenant user must have the “Tenant Manager” role. Use the 10.7 Management tenant admin credentials. By default, the credentials are sysadmin/sysadmin-pass.

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