Major Version Upgrades

Registered by Mark Ramm on 2013-05-01

[GOAL]
Allow environments to be upgraded across incompatible versions of juju.
[RATIONALE]
Users will be volubly unhappy if they have to destroy their environments to take advantage of new features.

Blueprint information

Status:
Complete
Approver:
Mark Ramm
Priority:
Undefined
Drafter:
William Reade
Direction:
Needs approval
Assignee:
None
Definition:
Obsolete
Series goal:
None
Implementation:
Unknown
Milestone target:
None
Completed by
Katherine Cox-Buday on 2015-06-11

Related branches

Sprints

Whiteboard

[USER STORIES]

Benny administers an environment with a few hundred machines running juju 1.10; he wants to use [some new feature] available only in juju 2.0. He installs juju 2.0 locally, and finds that certain commands fail with a complaint that the environment is running an older version of juju. He then runs `juju upgrade-juju`, and observes the following.

* CLI and GUI commands fail with a helpful message explaining that an upgrade is in progress.
* the progress of the upgrade is communicated over both the CLI (via juju status) and the GUI (automatically)
* all his services continue to run without interruption
* once the upgrade is complete, the CLI and GUI start working correctly in all respects.

[ASSUMPTIONS]

We can safely suspend management of units/machines for the duration of a major version upgrade.

We won't need to support major version downgrades.

We can maintain a backward-compatible public API, so the GUI can continue to work unimpeded across upgrades.

Safe major version upgrades depend on API everywhere.

[RISKS]

Failure to implement this will fatally constrain our ability to add new features to juju.

To have safe upgrades without api everywhere, we can't change the schema.

[IN SCOPE]

Mongodb schema and config changes.

Local agent data and config changes.

[OUT OF SCOPE]

Upgrades of mongodb itself.

Maintaining HA during an upgrade (surely important long-term; but, depends on HA, which will probably land later than this).

[USER ACCEPTANCE]
[RELEASE NOTE/BLOG]

(?)

Work Items

Work items:
Write the facility to allow schema migration during an upgrade size 4: TODO
Change upgrade process so the state servers are done first size 8: TODO
Non-HA upgrade shuts down API, upgrades schema, restarts process size 4: TODO
HA upgrade step one (two mongodb servers, all api servers enter read-only mode) size 2: TODO
HA upgrade step two (take remaining mongodb and one API out of the loop and upgrade those) size 4: TODO
HA upgrade step three (mongo magic for mongo dbs, restart API servers pointing at upgraded mongo) size 4: TODO

Dependency tree

* Blueprints in grey have been implemented.

This blueprint contains Public information 
Everyone can see this information.