Upgrading a juju model before the controller gives unhelpful error message

[Sandor Zeestraten]

While trying to upgrade a Juju controller from 2.0.0 to 2.0.1, I ran into an unhelpful error message (see below) because I was running upgrade-juju from a model different from the controller model.

I realize now that you need to switch to the controller model first, do the upgrade there, then switch back to any other model that you wish to upgrade, however that is not really intuitive.

This should also really be clarified better in the docs on https://jujucharms.com/docs/2.0/models-upgrade

### Steps to reproduce
# Bootstrap a controller with version 2.0.0
$ juju bootstrap lxd --agent-version=2.0.0

# Try to upgrade model/controller to 2.0.1
$ juju upgrade-juju --agent-version=2.0.1

# Results in the following unhelpful message
ERROR a hosted model cannot have a higher version than the server model: 2.0.1 > 2.0.0

[Anastasia (anastasia-macmood)]

Doc issue: https://github.com/juju/docs/issues/1519

[Tim Penhey (thumper)]

I think when run against hosted models the following behavior should happen:

* if the model version is the same as the controller version write:

$model is already the same version as the controller model.
Hosted models cannot be a later version than the controller.

* if a version was specified, and is greater than the controller version, we write the error:

ERROR hosted models cannot be a later version than the controller

* if no version is specified, and the model is less than the controller version, the hosted model is upgraded to the controller version.

[Anastasia (anastasia-macmood)]

Case 1 and 3 is already catered for and messages around these cases seem clear.

For 2, the error comes from a version check at the time when we are trying to set hosted model's agent binary version in state. I'll re-word to a modified version of your suggestion:

ERROR: hosted models cannot be a later version than the controller: 2.0.1 > 2.0.0

However, I think that the major source of confusion is not so much the phrasing of the error message but the fact the user did not upgrade a controller first.

Maybe we need to say:

hosted models cannot be a later version than the controller: 2.0.1 > 2.0.0. Upgrade 'controller' model first.

[Anastasia (anastasia-macmood)]

And looking at the reproduction steps closer, the fact that we have silently switched the user to a newly created 'default' model (which is unrelated to 'controller' model), is what throws people off. Maybe we should also add a very clear message to the output of bootstrap command that states that the user has been switched?

[Anastasia (anastasia-macmood)]

PR to re-phrase error message against 2.3: https://github.com/juju/juju/pull/8436

[Anastasia (anastasia-macmood)]

So for 2.3 series, since we are in minor releases, we can and have modified the error message to be slightly better.

For 2.4, we'll have a slightly different approach that I'll continue working on that will introduce a series of pre-checks. These will be run before an upgrade (or a dry-run) to specifically check versions (and other necessary bits in the future) and abort upgrade early before we hit internal errors.

[Anastasia (anastasia-macmood)]

Another bit for 2.4+ - we need to be a bit clearer about what we are actually upgrading. We want to avoid user confusion around upgrading model vs upgrading the controller. As part of this exercise, I've added an alias for 'upgrade-juju' - 'upgrade-model' since this is what we are actually doing here. PR: https://github.com/juju/juju/pull/8440

[Anastasia (anastasia-macmood)]

Re-phrased error message forward-ported to 2.4 as part of a larger commit - https://github.com/juju/juju/pull/8436

[Anastasia (anastasia-macmood)]

Comment # 8 should have referred to https://github.com/juju/juju/pull/8445 instead.

[Anastasia (anastasia-macmood)]

From a duplicate bug # 1763188, the message suggestion is a lot clearer:

    ERROR this model (2.3.5) cannot have a higher version than the controller model (2.3.3)

I'll change the message.

[Anastasia (anastasia-macmood)]

PR against 2.3: https://github.com/juju/juju/pull/8584

With this PR, users will get

model (2.3.5) cannot be upgraded to a later version than the controller (2.3.3): upgrade 'controller' model first

when trying to upgrade their model, say to 2.3.5, on the controller with 2.3.3.

[Anastasia (anastasia-macmood)]

Actually, after re-reading the message, I think this makes better sense:

model cannot be upgraded to 2.3.5 while the controller is 2.3.3: upgrade 'controller' model first

So changed the proposal to reflect this thinking.

[John A Meinel (jameinel)]

https://github.com/juju/juju/pull/8606 merge into 2.4

[Anastasia (anastasia-macmood)]

MArking as Fix Released as it did go into 2.4 branch according to comment # 13.