The Software Update Manager (SUM) provides ability to update a system. It could be used to perform major or minor updates. The main difference of major and minor updates is whether the update RPM contains the entire ISO contents or not. The SUM framework can be used to perform live update or an offline update (i.e., utilitizing a separate partition). It relies on Plugin Manager & Plugins to drive or replay any required configuration. The SUM architecture & workflow can be found in the following sections.
Table of Contents
At a high-level, the SUM architecture is as shown below.
- User/consumer gets the location of the staging area, and uploads the update package into staging area.
SUM doesn't provide an upload API. The update package must be uploaded into the staging area by the consuming application/product (using appropriate authentication).
- Once the update package is in staging area, it must be first added it into SUM software repository. Adding it into SUM software repository also validates the update package for version compatibility with system. Once it's made available in SUM software repository, it could be listed, installed and/or deleted.
- User/consumer can start the installation and monitor it's status to see if it's ready for reboot.
- Once the system is ready for reboot, user/consumer can run prereboot operations like set-boot & reboot in to updated version immediately (or choose to do it later).
- When user/consumer reboots to updated version, the update will proceed with any post-reboot update actions, and update the status appropriately towards the end of the update operation.
NOTE: SUM is designed to update system locally. The rolling updates in case of cluster, should be handled by the orchestration layer.
This section details out the design of the SUM Update Framework.
The SUM Framework uses Plugin Manager (PM) to perform several of it's actions, and defines the types of plugins to perform following user actions: install, reboot, rollback and commit in the below sections. The framework also defines certain variables to enable plugins to access following paths:
| Environment Variable | Description |
|---|---|
${PM_LIBRARY} |
Plugins library path. |
${VXAPP_UPGRADE_ROOT} |
Alternate root volume path for doing offline updates. |
| Types | File extensions | Examples |
|---|---|---|
| Pre-install update actions | .preinstall |
- Bind mount required file systems inside update volume before installing RPM/ISO, to share configuration that could be used during install step. One could have say mountfs.preinstall plugin to perform the same action. - Check whether application is stopped. |
| Install update actions | .install |
VUF install could be used with appropriate arguments to perform either live or offline update. |
| Types | File extensions | Examples |
|---|---|---|
| Pre-reboot config, replay or validations | .prereboot |
Copy config or keys (say ssh-keys) from current root to upgrade volume |
| Post-reboot config, replay or validations | .postreboot |
Load any container images into docker registery. |
NOTE: If an action can be performed before the reboot, then it is recommended to do it in the
.prerebootplugin rather than a.postrebootplugin, so that if there are any failures, it can be caught before reboot which helps in avoiding downtime for customers.
| Types | File extensions | Examples |
|---|---|---|
| Prechecks before starting rollback | .rollback-precheck |
- Check whether node is updated. - Check whether instances are stopped. |
| Pre rollback actions | .prerollback |
- Set Grub to boot to old version in case of using offline update approach. - Revert snapshot. |
| Rollback actions | .rollback |
- Remove new version container images. |
| Types | File extensions | Examples |
|---|---|---|
| Precheck before starting commit | .commit-precheck |
- To check if all nodes in the cluster are updated. - Check for applications are stopped if cluster upgrade action requires them to be stopped. |
| Commit actions and cleanup any remnants | .commit |
- Remove previous version container images. - Perform one time actions that could not be run earlier in install step as they do not support rollback. Examples: - cluster or storage (disk/fs) protocol upgrade. |
NOTE: The rollback plugins are expected to be re-runnable. In case rollback fails, rollback plugins could be executed through Plugin Manager (PM).
The update plugins must be deployed into a plugin folder under plugins library path i.e., ${PM_LIBRARY}/<plugin-folder>/.
To access this path in plugins, one must use environment variable ${PM_LIBRARY} to access the plugins library location.
An update RPM should be SUM format compliant in order for one to successfully install the update. In order to generate such an RPM, one should use SUM SDK. For more details about SDK, refer to SUM SDK.
A example usage of the framework can be found here: sample-update.
The following sub-sections detail out the software update manager command tool usage. The default values of some of the optional parameters are as follows:
repo:"/system/software/repository/"output_format:"yaml"
$ ${sum_binary} repo add -filepath=${software_staging_area}/${software_name}
[ -repo=${software_repo} ]$ ${sum_binary} repo list
[ -repo=${software_repo} ]
[ -type=${software_type} ]
[ -filename=${software_name} ]$ ${sum_binary} repo remove
-type=${software_type}
-filename=${software_name}
[ -repo=${software_repo} ]
[ -output-file=${output_file} ]
[ -output-format=${output_format} ]$ ${sum_binary} install
-filename=${software_name}
-type=${software_type}
[ -repo=${software_repo} ]$ ${sum_binary} commit
-filename=${software_name}
-type=${software_type}
[ -repo=${software_repo} ]
[ -output-file=${output_file} ]
[ -output-format=${output_format} ]$ ${sum_binary} rollback
-filename=${software_name}
-type=${software_type}
[ -repo=${software_repo} ]
[ -output-file=${output_file} ]
[ -output-format=${output_format} ]