|
|
|
|
|
About this guide
Bosch IoT Edge Services is constantly evolving in order to stay competitive and meet customer needs for innovative value-adding features delivered with the best possible quality. Customers that wish to take advantage of the latest product features, security updates and critical fixes must migrate their solutions to the latest product versions as they become available. It is of utmost importance for customers to be able to continuously migrate their solutions easily and without friction, therefore, migration-relevant information is included in this documentation. This guide provides general guidance for migrating edge solutions using Bosch IoT Edge Services from one product version to the next, including navigation throughout all migration-relevant documentation.
Guidance and consulting for migrating throughout several product versions at once are not covered by the standard migration guides but they can be provided on request. Guidance and consulting for deploying the migrated solution and recommendations on designing software update mechanisms are not covered by the standard migration guides can also be provided on request.
Preparing for migration
1. Check out the Release notes for the latest Bosch IoT Edge Services version
All changes that would require any adaptations in your solution are listed in the Release Notes, namely:
Generally, setup and configuration changes that require adaptations in your solution's image may be introduced in major or minor versions. Deprecation of APIs is possible in major or minor versions, however, removal of APIs is only possible in major versions. Deprecated APIs are maintained until removal allowing for a reasonable time for migration to alternative APIs.
2. Update your Bosch IoT Edge Services installation and Eclipse plug-ins
Before you start, you need to update your Bosch IoT Edge Services installation on your workstation. Then you need to update Bosch IoT Edge Services Eclipse plug-ins following the instructions in the Update guide.
Updating and building your solution
1. Update your solution's runtime image
You can update your solution's image descriptor by using the Image Builder as described in Configuring Image Content guides All replaced, removed or renamed bundles (jar name and symbolic name) and changes in system properties and configuration properties are marked in the Release notes including comparison tables where necessary. Further details for using the new setup and configuration are available in the Setup guides for all modules in Runtime.
2. Update your solution's logic to use the latest APIs
You need to adapt your solution's logic to the API changes that are introduced - generally, this means to migrate to new alternatives of deprecated or removed APIs. All replaced, removed and deprecated APIs and API elements are marked in the Release notes including links to further migration details where necessary. Further API migration and comparison details are available in the API Javadoc and in dedicated Migration guides for relevant modules in the Runtime.
As deprecated APIs are maintained for a certain period of time a more smooth two-phased migration can be implemented which does not include adaptation of your solution's logic to the alternative APIs. You can adapt your solution to the setup and configuration changes as first phase but adaptation to alternative new APIs can be planned as next phase before the APIs are removed
3. Build and validate your solution
You can use Image builder to build your updated runtime image which can now be deployed either on your workstation or on your target devices. After you have updated your solution you can test and validate the migration to make sure that everything is working as expected and there are no issues.
Migrating your data
1. Preserve your data
Before deploying the update on your target devices you need to make sure that all data that is persistently stored on the gateway is preserved during software update. Bosch IoT Edge Services offers backup and restore mechanism for preserving data stored by Bosch IoT Edge Services runtime bundles. The Backup Admin provides a way for persisting bundles data on configurable location (outside the OSGi cache) and allows users to backup their data (periodically or on request) and restore the data from previous backup.
All Bosch IoT Edge Services bundles that store user data persistently support backup and restore of data including automatic conversion between data versions during restore, thus, stored user data and configurations are not lost in case of data format changes. All solution-specific bundles which store data persistently should also provide backup and restore capabilities whenever the data they persist needs to be preserved across software updates - including conversions between data versions. Using Backup Admin is a preferred way of backing up and restoring data during a software update. Simply copying the "storage" folder of the existing runtime is not an appropriate solution, because it does not deal gracefully with bundle reordering, bundle name changes, deployment model changes, etc.