Kura Upgrade Process - markcullen/kura_Windows GitHub Wiki

Table of Contents Packaging Logical Flow Creating the Upgrade Package Finding the diff Upgrade Script(s) The ResourceProcessor Implementation Versioning

The Kura upgrade will be created as a deployment package. 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.

Upgrades will be allowed between sequential releases of Kura regardless if 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). For each release, a list 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
• 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.
• 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)
• 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?

For each release, a list 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. Non-updatable files (for example, the default network config in the build might change, but we probably wouldn't want to change the user's config) could also be listed but without a version/md5sum.

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 with 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 ResoureceProcessor implementation should be structured similar to the one used in the diagnostic bundle. The function, however, should be much simpler. Its only job will be to start the upgrade script as a background job.

Kura should begin versioning bundles consistent with OSGI Semantic Versioning. For Kura, each manifest file will have the 'Bundle-version', each 'Export-Package', and each 'Import-Package' initialized to '0.2.0'. Each developer will be responsible for updating the major, minor, and micro version numbers consistent with the provider/consumer model outlined in the above OSGI document.