Use the client

This page covers operations that can be applied to the Juju client, the software that is used to manage Juju, whether as an admin user or as a regular user.

A juju client has been designed to be backward compatible and can talk to older or newer existing controllers if the controller and the client are on the same major version (2.x and 3.x). Performing simple commands can be achieved without upgrading the client. It is always recommended to be up-to-date with the client and controller where possible.

The following topics are covered:

  • Client prerequisites
  • Client directory
  • Client backups
  • Client upgrades

See the Concepts page for a full definition of the client.

Client prerequisites

The Juju client expects that the running client OS is up to date with security updates.
If the client OS is Ubuntu then installing distro-info via apt is advised. distro-info provides the client updated supported Ubuntu releases that Juju doesn’t know about when released, but can be run against.

Client directory

The Juju client directory is located, on Ubuntu, at ~/.local/share/juju.

Aside from things like a credentials YAML file, which you are presumably able to recreate, this directory contains unique files such as Juju’s SSH keys, which are necessary to be able to connect to a Juju machine. This location may also be home to resources needed by charms or models.

On Microsoft Windows, the directory is in a different place (usually C:\Users\{username}\AppData\Roaming\Juju).

Client backups

A backup of the client enables one to regain management control of one’s controllers and associated cloud environments.

This section will cover the following topics:

  • Creating a backup
  • Restoring from a backup

Data backups can also be made of the Juju controller. See the Controller backups page for guidance.

Creating a backup

Making a copy of the client directory is sufficient for backing up the client. This is normally done with backup software that compresses the data into a single file (archive). On a Linux/Ubuntu system, the tar program is a common choice:

cd ~
tar -cpzf juju-client-$(date "+%Y%m%d-%H%M%S").tar.gz .local/share/juju 

For Microsoft Windows any native Windows backup tool will do.

The above invocation embeds a timestamp in the generated archive’s filename, which is useful for knowing when a backup was made. You may, of course, call it what you wish.

The archive should normally be transferred to another system (or at the very least to a different physical drive) for safe-keeping.

Whoever has access to a client backup will have access to its associated environments. Appropriate steps should be taken to protect it (e.g. encryption).

Restoring from a backup

Restoring your client settings is a simple matter of extracting the backup created earlier. For Ubuntu:

cd ~
tar -xzf juju-yymmdd-hhmmss.tar.gz 

This command will extract the contents of the archive and overwrite any existing files in the Juju directory. Make sure that this is what you want.

Client upgrades

Ensure you’ve created a backup of your ./local/share/juju before starting the upgrade process for the client.

If the juju client was installed via snap, the updates to the client should be handled automatically. You can see the latest version of the installed snap by calling snap info juju.

$ snap info juju
name:      juju
summary:   A model-driven operator lifecycle manager
publisher: Canonical✓
license:   unset
refresh-date: 6 days ago, at 05:14 BST
  latest/stable:    2.9.4              2021-06-08 (16423) 99MB classic
  latest/candidate: 2.9.5              2021-06-17 (16559) 99MB classic
  latest/beta:      ↑
  latest/edge:      3.0-beta1-6f9ca9d  2021-06-14 (16531) 85MB classic
  2.9/stable:       2.9.4              2021-06-08 (16423) 99MB classic
  2.9/candidate:    2.9.5              2021-06-17 (16559) 99MB classic
  2.9/beta:         ↑
  2.9/edge:         2.9.5-2fe7a0f      2021-06-17 (16555) 99MB classic
  2.8/stable:       2.8.11             2021-06-10 (16475) 74MB classic
  2.8/candidate:    ↑
  2.8/beta:         ↑
  2.8/edge:         2.8.12-98e51af     2021-06-17 (16563) 74MB classic
  2.7/stable:       2.7.8              2020-07-22 (13563) 77MB classic
  2.7/candidate:    ↑
  2.7/beta:         ↑
  2.7/edge:         2.7.9+2.7-46f947e  2020-07-22 (13578) 82MB classic
  2.6/stable:       2.6.10             2019-10-30  (9484) 69MB classic
  2.6/candidate:    ↑
  2.6/beta:         ↑
  2.6/edge:         2.6.11+2.6-b96e122 2020-01-22 (10408) 75MB classic
  2.5/stable:       2.5.8              2019-06-27  (8361) 67MB classic
  2.5/candidate:    ↑
  2.5/beta:         ↑
  2.5/edge:         2.5.9+2.5-36af233  2019-07-24  (8546) 73MB classic
  2.4/stable:       2.4.7              2019-05-23  (6012) 58MB classic
  2.4/candidate:    ↑
  2.4/beta:         ↑
  2.4/edge:         ↑
  2.3/stable:       2.3.9              2018-09-19  (5267) 55MB classic
  2.3/candidate:    ↑
  2.3/beta:         ↑
  2.3/edge:         2.3.10+2.3-41313d1 2019-03-25  (7080) 55MB classic
installed:          2.8.11                        (16475) 74MB classic

If a new release has been released and the juju snap hasn’t been refreshed, you can manually trigger this with sudo snap refresh juju.

Moving from one channel to another can be done using the --channel argument.

sudo snap refresh --channel=latest juju

For more installation information and what versions are available, see Reference: Installing Juju.

Models can also be upgraded. See the Upgrading models page for guidance.