PART 5. SUPPLEMENTARY DOCUMENTATION
Code Update Deployment

 

Code Update Deployment

·            Overview

·            ESF Updater

·            Comments on Updates

Code Update Deployment

 

Overview

The ESF software update mechanism uses the Configuration Manager (CM) as the basis to receive updates.  However, it can also be called directly by another bundle to kick off an update.  Software updates can be complex in how they are transferred to a unit, how they get deployed, and how they are validated.  While ESF can’t do all of this since there are so many variables, the CM is a tool that can eliminate the need to write an update tool from scratch.

 

The CM is very pervasive throughout ESF.  It also has many adapters for receiving Objects.  Since a File is an Object, it made sense to use the CM for the update mechanism as well.  The only difference is the ‘configuration’ is really a File that contains a software update.

 

Updates need to be carefully considered on a project by project basis.  This document will not cover all of the considerations that need to be made there.  We will simply cover what the com.esf.core.updater project does and how it works.

 

ESF Updater

The com.esf.core.updater.EsfUpdater implements the com.esf.core.configuration.service.IConfigurableComponentService.  In doing so, it can receive updates from the Cloud, the CM HTTP Servlet, the local filesystem, or any other yet to be conceived CM configuration provider.  This capability gives the Updater a lot of flexibility without having to write any code with regard to how this is done.

 

An update must be well formatted.  While the receiveConfig method receives a File Object, it must be a very specific File Object.  It must be a .zip file that contains one or more ‘star’ files and a ‘project_releases.txt’.  A star file is a ‘self-extracting tar file’.  It is essentially a script with binary data that when executed knows how to extract the contents of the file.  However, it also gives flexibility in that a pre and post script can be built into a single file.

 

The star file updates should be named

 

company_project_update-version.star

 

where “company” and “product” come from the /opt/jvm/esf/configuration/.esf/com.esf.core.system.manager/esf.props file.

 

The following is an example.

 

eurotech_helios-denali_update-1.0.1.star

 

The version number is then pulled out and compared with the current <product_version> tag held in the /etc/esf/release.xml file.  The version should always be in the form MAJOR.MINOR.SUBMINOR.

 

If the version is newer, the update can be copied to the local filesystem and then executed.  At this point, the star file is in full control of the system.  If it needs to, it can kill the VM, reboot the box, or do whatever it likes.  A lot of care must be taken in not deploying updates that can damage the box.

 

The “versions” file contains some metadata about the update.

 

The versions file should be named

 

project_releases.txt

 

The following is an example file (helios-denali_releases.txt).

 

1.0.1 867b9069ff0188d629c827165bbcc0b6    2511 eurotech_helios-denali_update-1.0.1.star

1.1.0 ab35012fcd058123950fcd23abaa1345    3503 eurotech_helios-denali_update-1.1.0.star

 

The project_releases.txt file contains the version number, the md5sum, the filesize, and the filename of each update.  The reason for this construct is that updates can be incremental, and it gives the updater a baseline to validate the star files against before applying them.  It is important to note that this does not force incremental updates.  The .star files can contain cumulative updates that include all of the previous updates in a single star file.  However, this is not recommended, in that rolling back becomes more complicated and the updates can grow very large in size over time.

 

Comments on Updates

As noted previously, this document doesn’t cover how to put the updates together.  Contact Eurotech for tools to help with the details of constructing .star files. 

 

However, the following are a few recommendations about creating updates:

·            Keep updates small and incremental.

·            Use the package manager whenever possible (rpm for WRL).

·            Test – Test – Test! before deploying to all units or to any remote units.

·            Make sure a rollback is possible if necessary.

·            Update metadata (i.e. updating /etc/esf/release.xml and the System Manager’s esf.props file) when needed.

·            Pay careful attention if updating the update mechanism so future updates remain possible.