The Kura upgrade process was designed to minimize the upgrade file size to make remote installations easier. In order to do this, the upgrade script will reuse files from the currently installed Kura version whenever possible. The Kura upgrader will support upgrades between sequential releases of Kura regardless of whether the upgrade is a patch (ex: 2.0.6 -> 2.0.7) or a major/minor upgrade (ex: 2.0.6 -> 2.1.0 if 2.1.0 release is the first release after 2.0.6). See the Kura versioning page for more info on versioning.
The Kura upgrade will be created as a script which can be run directly, and also as a deployment package which could be installed remotely. This deployment package will contain:
- The JAR files that have changed since the last release
- System files that have changed since the last release
- The upgrade script(s)
- An implementation of the OSGI ResourceProcessor (similar to the diagnostic bundle customizer)
- Everything but the customizer will be packaged in self-extractable .sh script (e.g. a star file). The customizer only needs to execute the .sh script as a daemon detaching it from the Java process.
For each release, a catalog will be generated of all the files in the release and their versions. For bundles, the bundle version will be used, and for other files the md5 hash will be computed. The diff between the previous and the new version will be computed by comparing this list.
Before upgrading the installer will check the currently installed version on the target by reading the kura.version value in the kura.properties file and reject the upgrade if the target release does not match.
It might also be helpful for the discussion to classify the resources in the installer (bundles, system files, etc contained in the installer). For example if a resource has been removed from the latest release it should also be deleted on the target (it's stale).
The general flow for an upgrade is:
- The upgrade deployment package can be installed via device management UI (Denali), EDC console, APIs, or OSGI console
- The bundle from the deployment package will start and initiate the upgrade script(s) to run as a background process
- Alternatively, the upgrade script can be uploaded and run directly on the device
- The upgrade script will stop Kura and monit
- There is danger here for open hardware that is using monit for other monitoring.
- The upgrade script will create a copy of the old version (e.g. /opt/eclipse/kura_0.2.0) into a new directory (e.g. /opt/eclipse/kura_0.2.1) using hard links to save on disk space, and to allow the old version to be deleted once the new version is confirmed to be running correctly.
- Real copies will be made of certain files so that changes to them will not affect the multiple installations. These include: kura/kura_custom.properties, kura/dpa.properties, and data/kuranet.conf
- Files that are no longer needed or that have changed since the last version will be removed from the new directory. Then the new (and/or updated) files will be extracted into the new directory.
- Potential Issues:
- Resource limitations (ex: running out of disk space)
- Potential Issues:
- The /opt/eclipse/kura symlink will be updated to point to the new directory.
- The device will be rebooted.
- Open items:
- Is there a way to start from original install directory if there is a failure in startup?
Creating the Upgrade Package
Finding the diff
For each release, a catalog will be generated of all associated files (bundles, config files, etc.) for that release. For each updatable file, a version would be included - this could be the bundle version, or just an md5sum for non-versioned files.
Finding the diff between two releases would then involve comparing this list between the two versions. This diff would identify which files are to be removed (this would include files that were in the old version but not the new, as well as any files that have changed), which files to keep (unchanged between the two versions), and which to add.
The upgrade script would create a directory for the new version by copying (creating a hard link of) all the files from the previous version. Next it would delete all files that are in the list to remove. Then it would extract all the files included in the upgrade into the new directory. Lastly, the /opt/eclipse/kura symlink will be updated to point to the new directory and the device rebooted. At this point, the old /opt/eclipse/kura_x.x.x directory could be deleted.
The ResourceProcessor Implementation
The ResoureceProcessor implementation should be structured similar to the one used in the diagnostic bundle. Its function, however, should be much simpler; its only job will be to start the upgrade script as a background job.