Formula Upgrades

Upgrading a formula

A formula can be upgraded via the command line using the following syntax:

$ ensemble upgrade-formula <service-name>

In the case of a local formula the sytax would be:

$ ensemble upgrade-formula --repository=principia <service-name>

This will examine the named service, determine its formula, and check the formula’s originating repository for a newer version of the formula. If a newer formula version is found, it will be uploaded to the ensemble environment, and downloaded to all the running units of the service. The unit agent will switch over to executing hooks from the new formula, after executing the upgrade-formula hook.

Formula upgrade support

A formula author can add formula specific support for upgrades by providing an additional hook that can customize its upgrade behavior.

The hook upgrade-formula is executed with the new formula version in place on the unit. Ensemble guarantees this hook will be the first executed hook from the new formula.

The hook is intended to allow the formula to process any upgrade concerns it may have with regard to upgrading databases, software, etc before its new version of hooks are executed.

After the upgrade-formula hook is executed, new hooks of the formula will be utilized to respond to any system changes.


The upgrade-formula hook will likely need access to a new cli-api to access all relations of the unit, in addition to the standard hook api commands like relation-list, relation-get, relation-set, to perform per unit relation upgrades.

The new hook-cli api name is open, but possible suggestions are unit-relations or query-relations and would list all the relations a unit is a member of.

Most server services have multiple instances of a named relation. Else name iteration of the formula defined relations would suffice. It’s an open question on how these effectively anonymous instances of a named relation would be addressed.

The existing relation-* cli would also need to be extended to take a relation parameter, or documented usage of environment variables when doing relation iteration during upgrades.


The upgrade cli updates the service with its new unit, and sets an upgrade flag on each of its units. The unit agent then processes the upgrade using the workflow machinery to execute hooks and track upgrades across service units.

A unit whose upgrade-formula hook fails will be left running but won’t process any additional hooks. The hooks will continue to be queued for execution.

The upgrade cli command is responsible for

  • Finding the named service.
  • Determining its formula.
  • Determining if a newer version of the formula exists in the origin repository.
  • Uploading the new version of the formula to the environment’s machine provider storage.
  • Updating the service state with a reference to the new formula.
  • Marking the associated unit states as needing an upgrade.

As far as determining newer versions, the cli will assume the same formula name with the max version number that is greater than the installed to be an upgrade.

The unit agent is responsible for

  • Watching the unit state for upgrade changes.
  • Clearing the upgrade setting on the unit state.
  • Downloading the new formula version.
  • Stopping hook execution, hooks will continue to queue while the execution is stopped.
  • Extracting the formula into the unit container.
  • Updating the unit formula reference.
  • Running the upgrade workflow transition which will run the upgrade-formula hook, and restart normal hook execution.

Only the formula directory within a unit container/directory is replaced on upgrade, any existing peristent data within the unit container is maintained.

Project Versions

Table Of Contents

Previous topic


Next topic

EC2 provider configuration

This Page