rPath Appliance Platform Agent:UpdateTroves Plugin

From rPath Wiki

The rPath Appliance Platform Agent (rAPA) includes an UpdateTroves plugin which is enabled by default. The plugin provides the Updates page in the rAPA web interface. The UpdateTroves plugin allows a rAPA user to check for updates, schedule checks for updates, and apply available updates.

Using the UpdateTroves Plugin Interface

See the Updates page in the Appliance Administration pages for information on how to use the UpdateTroves plugin in the web interface.

Appliance Developer Notes

rPath Appliance Platform Updates web interface

By default, a rAPA update is a special kind of Conary update performed on the top-level Conary group that defines the appliance (such as group-example). Note that this custom behavior is different than that of conary update or conary updateall at a command prompt.

Include Extended Information About Updates

Appliance developers can provide Appliance Platform users with extended information about the updates, including the differences between current and pending software versions. Developers must enable a configuration directive that displays a hyperlink on the "update" text when updates are available for the appliance. When the user clicks the "Update" text, the Appliance Platform shows additional update details provided by a web service.

The rPath Appliance Platform attempts to access a web service at the URL specified by the updateTroves.rootUrl Appliance Platform configuration directive. When it accesses the web service using HTTP GET requests, the URL is modified by appending a question mark (?) and a set of variables which correspond to naming and version information for the software comprising your appliance. The following table shows the list of variables that can be passed:

The following is an example query from the Appliance Platform to the web service, showing the modified URL: http://updates.example.com?og="group-dist";ov="1.0.5-0.3-2";ng="group-dist";nv="1.0.6-0.1-1"

The variables used in the the Appliance Platform HTTP GET query correspond to data which is stored in a database for use by the web service. The following table is an example table structure:

The Details field should contain a list of all changes from the previous GroupId. Thus, you can join all of the Details for all of the GroupIds between the old group name and version and the new group name and version.

To display the additional update information, enable the configuration in the Appliance. As described in rPath Appliance Platform Agent:Configuration, include the appropriate directives in /etc/raa/custom.cfg. The following two configuration directives require attention:

• Set updateTroves.migrate to True. This corresponds to your appliance using the migrate method of updating software as described here.
• Set updateTroves.rootUrl to your custom Appliance Platform configuration file and specify the update details web service URL. For example, an entry in /etc/raa/custom.cfg resembling the following would instruct the rPath Appliance Platform Agent to access the web service at updates.example.com for update details:
  updateTroves.rootUrl = "http://updates.example.com"

Configure Number of Kernels to Keep During Updates

Appliance developers can configure the number of kernels the system will keep after an update through the UpdateTroves plugin. From the web interface, users cannot see this configuration or override it.

The corresponding updatetroves.kernelNumber configuration directive is found in the UpdateTroves configuration file /etc/raa/plugins.d/updatetroves.cfg. Its value is 2 by default:

updatetroves.kernelNumber = 2

Use /etc/raa/custom.cfg to change this value for an appliance. Select a value as follows:

• Use 0 (zero) to allow Conary's configuration to determine what actions should be taken; by default, Conary will keep all kernels pinned so that no older kernels are removed after updates to the kernel trove
• Using 1 will give the same results as 2, preventing the removal of a "last known good" kernel to which the appliance can boot
• Use an integer of 2 or greater to keep that number of kernels pinned after updates to the kernel trove; this is inclusive of the currently running kernel, so the default 2 implies that the appliance can update to the newest kernel and keep that plus one other "backup" kernel for a total of two kernels

Migrate Tab Configuration

Migrations inside the update plugin are disabled by default. The Migrate tab may be enabled by including the following in custom.cfg:

[/updatetroves]
default is updatetroves.migrate.hide = True

ISVs may want to leave the migrate tab hidden but still perform a migration. Accessing the following URL will allow migrations to occur without enabling or disabling the migrate tab inside the configuration file.:

https://hostname:8003/updatetroves/UpdateTroves/migrate

• substitute hostname for your appliances FQDN