Juju 3.0 breaks a significant amount of documentation by renaming high-usage commands including run, upgrade-charm, add-relation, run-action

[Trent Lloyd]

Juju 3.0 was released over the weekend to latest/stable. It seems latest/stable has since been reverted to 2.9 again however many internal and customer machines have already updated and don't roll back automatically.

Several high-usage commands has been renamed or removed that are in *significant* amounts of documentation.

To my observation there was no deprecation warning about this in the previous versions and the old commands now error out with no helpful message. This is going to be hugely impactful to customers and automated/scripted testing environments.

It seems at least some of these changes have been in planning for 12-24 months since at least 2.8:
https://discourse.charmhub.io/t/juju-actions-opt-in-to-new-behaviour-from-juju-2-8/2255

However many others seem to have been done at the last minute in the last couple of weeks before the release:
https://github.com/juju/juju/pull/13876

Given the amount of user-facing documentation referencing these commands it seems like a better deprecation policy is needed and we a serious reconsideration on these changes for 3.0 is required. There were also some unanswerred comments along these lines in both of the linked PRs.

For some commands you could have a compatible old command as the old command no longer eixsts, however, the "juju run"/"juju exec" switch and "juju run-action"/"juju run" switch are problematic.

I also note that you now get errors and the "Did you mean:" output does not actually inform you of the new command, e.g.:

$ juju run-action -h
ERROR juju: "run-action" is not a juju command. See "juju --help".

Did you mean:
 show-action

The main ones I have so far observed:

= juju run =

Renamed to 'juju exec'.

A lot of documentation uses 'juju run --unit/u' or 'juju run --application/-a' for various tasks.

In my ~/src/charms with 182 repos of primarily Openstack charms: 80 mentions.

Likely many more in KBs, other repos, automation scripts, etc.

= juju run-action =

Renamed to 'juju run'

280 mentions in my ~/src/charms

= juju add-relation =

Renamed to 'juju relate'

486 mentions in my ~/src/charms

= juju upgrade-charm =

Renamed to 'juju refresh'

33 mentions in my ~/src/charms

= juju bootstrap --no-gui =

Least important one honestly but this switch was removed and was used in a lot of automated testing deployments to speed up bootstrap. So noted here.

References:
https://github.com/juju/juju/pull/13876
https://github.com/juju/juju/pull/13907
https://github.com/juju/juju/commit/a7c7b05decde2e3ce9fe90f9cc287f49cbec1e32

[Trent Lloyd (lathiat)]

To revert to the 2.9 CLI, the following command will force-downgrade back to the current 'latest/stable' (2.9.35 right now):
sudo snap refresh juju --classic

Alternatively you can specifically switch to the 2.9/stable channel but note this won't upgrade your CLI automatically in future (that may be a plus or minus):
sudo snap refresh juju --channel=2.9/stable --classic

[Trent Lloyd (lathiat)]

Although latest/stable was switched back to 2.9.35, it will not auto-refresh/auto-rollback all of the installs that automatically upgraded (which seems to be all of them tracking latest/stable) because juju v3 had strict confinement and v2 has classic confinement.

Switching from strict to classic confinement requires manual intervention, additionally, "snap refresh" will claim that all snaps are up-to-date when they are actually not. I have previously documented this issue in snapd Bug #1811063

You do see the following error in syslog but it is the only indication:
syslog:Oct 24 22:20:51 skc snapd[23851]: snapstate.go:1581: cannot update "juju": snap "juju" requires classic confinement

root@skc:~# snap refresh
All snaps up to date.

root@skc:~# snap list juju
Name Version Rev Tracking Publisher Notes
juju 3.0.0 21122 latest/stable canonical✓ -

root@skc:~# snap refresh juju
error: This revision of snap "juju" was published using classic confinement and thus may perform
       arbitrary system changes outside of the security sandbox that snaps are usually confined to,
       which may put your system at risk.

       If you understand and want to proceed repeat the command including --classic.

To rollback you specificlaly need to run:
snap refresh juju --classic

[Trent Lloyd (lathiat)]

I discussed the command changes with the Juju team last week. The feedback was:

"juju relate(add-relation)", "juju refresh(upgrade-charm)" and "juju exec(run)" are in both 2.9 & 3. So we should all switch to using those commands in most cases even for 2.9 so it's applicable to both.

New juju run (run-action) does not exist directly in juju v2 however can be enabled with a feature flag env variable:
JUJU_FEATURES=actions-v2 juju run …

So you can still write a command that is runnable on both v2.9 and 3.0 although a little awkward. It's CLI only so can just be done on a per-cmd basis.

More info on the actions-v2 part - it was noted that this flag changes the behaviour of actions generally so worth reading the info: https://discourse.charmhub.io/t/juju-actions-opt-in-to-new-behaviour-from-juju-2-8/2255