Upgrade a Charm

A charm can be changed at runtime with the upgrade-charm command. By default,
it changes to the latest available version of the same charm; if --revision
is specified, it changes to that revision of the same charm; and if --switch
is specified it changes to any arbitrary charm, inferred from the argument in
the same way as in juju deploy.

For a charm to replace another, though, there is a minimum standard of
compatibility, which applies regardless of the particular change. That is:

a subordinate charm must be replaced by a subordinate charm, and a principal
charm must be replaced by a principal charm.

every runtime relation used by the application must exist in both charms.

charm relations that are defined, but not in use at runtime, may be removed
freely.

in particular, it's not possible to remove a peer relation by upgrading,
because peer relations are always in use.

No other factor is used in determining compatibility: configuration settings in
particular are converted completely naively, such that any settings from the
original charm that share a name and type are preserved; any incompatible
settings are removed; and any new settings take defaults as though freshly
deployed. Settings may be added or updated by specifying the --config flag,
pointing to a YAML-encoded application config file (see
Application configuration for general information on
configuring a charm). It is important to read the documentation for the charm's
new version, not only to learn about new settings but especially to find out
about any new settings that require values.

When an application has been upgraded but a particular unit has not, the unit
will continue to see the configuration settings from before conversion; these
settings will not be affected by subsequent changes to the application's
settings.

Forced charm upgrades

Juju defines the upgrade-charm hook
for resolving differences between versions of the same charm. No notice is given
of charm upgrades; a charm upgrade may run at any time the unit is started, and
the only opportunity for resolution that exists occurs after the change has
taken place.

This is quite a tight restriction, but nonetheless valuable, so long as you can
guarantee it will run. However, it's important to understand that the upgrade-
charm accepts a --force-units flag: a forced charm upgrade will upgrade even
units that are currently in an error state, at
the cost of skipping the upgrade-charm hook for those units.

This is useful for charm authors who want to push a new version of a failed
hook (they can upgrade-charm --force-units and then resolved to run it
immediately without otherwise disturbing the system); but it's potentially
dangerous if abused. We recommend that use of the feature be restricted to charm
authors while developing their own charms, and that it's not sensible to devote
serious effort to recovering from inappropriately forced upgrades.

Charm upgrade errors

These will only occur as a result of conflicts between the contents of the charm
directory written at runtime, and should never be seen by a user; users
certainly cannot be expected to understand the structure of your charm well
enough to solve the conflicts sanely.

When you're writing a new version of a charm, you should always test upgrading
it from (at least) the previous version, to ensure these errors don't slip out
into the wild.

You can completely avoid these errors by never writing to the charm directory;
and you can also avoid them by rigorously delineating the parts of your charm
directory that you write to at runtime, and ensuring you never add a file to the
raw charm that could conflict with the runtime state.

If you're writing your hooks in Python, you should be doubly aware of this: if
you don't configure Python to suppress bytecode caching, it will write .pyc
files next to your Python files at runtime, and effectively prevent you from
rearranging those directories in future. This is not an unreasonable burden to
bear, but it's important to know you're taking it on.

If you encounter a charm upgrade error, you can run git status in the charm
directory to see what the problem is, and use the knowledge thus gleaned to fix
the charm and try to upgrade again.