How to manage a machine

See also: Machine

This document demonstrates how to manage machines.


Add a machine

See also: juju add-machine

To add a new machine to a model, run the add-machine command, as below. juju will start a new machine by requesting one from the cloud provider.

juju add-machine

The command also provides many options. By using them you can customize many things. For example, you can provision multiple machines, specify the Ubuntu series to be installed on them, choose to deploy on a lxd container inside a machine, apply various constraints to the machine (e.g., storage, spaces, …) to override more general defaults (e.g., at the model level), etc.

Machines provisioned via add-machine can be used for an initial deployment (deploy ) or a scale-out deployment (add-unit).

List all machines

See also: juju machines

To see a list of all the available machines, use the machines command:

juju machines

The output should be similar to the one below:

Machine  State    Address         Inst id        Base          AZ  Message
0        started  juju-552e37-0  ubuntu@22.04      Running
1        started   juju-552e37-1  ubuntu@22.04      Running

Show details about a machine

See also: juju show-machine

To see details about a machine, use the show-machine command followed by the machine ID. For example:

juju show-machine 0

This should output something similar to:

model: localhost-model
      current: started
      since: 27 Oct 2022 09:37:17+02:00
      version: 3.0.0
    hostname: juju-552e37-0
    instance-id: juju-552e37-0
      current: running
      message: Running
      since: 27 Oct 2022 09:36:10+02:00
      current: applied
      since: 27 Oct 2022 09:36:07+02:00
      name: ubuntu
      channel: "22.04"
        mac-address: 00:16:3e:cc:f2:16
        space: alpha
        is-up: true
    constraints: arch=amd64
    hardware: arch=amd64 cores=0 mem=0M

Show the status of a machine

See also: juju status

To see the status of a machine, use the status command:

juju status

This will report the status of the model, its applications, its units, and also its machines. For example:

Model            Controller            Cloud/Region         Version  SLA          Timestamp
localhost-model  localhost-controller  localhost/localhost  3.0.0    unsupported  13:51:33+02:00

App       Version  Status   Scale  Charm     Channel  Rev  Exposed  Message
influxdb           waiting    0/1  influxdb  stable    24  no       waiting for machine

Unit        Workload  Agent       Machine  Public address  Ports  Message
influxdb/0  waiting   allocating  2                               waiting for machine

Machine  State    Address  Inst id  Base          AZ  Message
2        pending           pending  ubuntu@20.04      Retrieving image: rootfs: 4% (10.87MB/s)

Execute a command inside a machine

See also: juju exec (before juju v.3.0, juju run)

To run a command in a machine, use the exec command followed by the target machine(s) (--all, --machine, --application or --unit) and the commands you want to run. For example:

# Run the 'echo' command in the machine corresponding to unit 0 of the 'ubuntu' application:
juju exec --unit ubuntu/0 echo "hi"

# Run the 'echo' command in all the machines corresponding to the 'ubuntu' application:
 juju exec --application ubuntu echo "hi"

The exec command can take many other flags, allowing you to specify an output file, run the commands sequentially (since juju v.3.0, the default is to run them in parallel), etc.

Access a machine via SSH

There are two ways you can connect to a Juju machine: via juju ssh or via a standard SSH client. The former is more secure as it allows access solely from a Juju user with admin model access.

Use the juju ssh command

See also: juju ssh

First, make sure you have admin access to the model and your public SSH key has been added to the model.

If you are the model creator, your public SSH key is already known to juju and you already have admin access for the model. If you are not the model creator, see How to manage users and User access levels for how to gain admin access to a model and How to manage SSH keys for how to add your SSH key to the model.

Then, to initiate an SSH session or execute a command on a Juju machine (or container), use the juju ssh command followed by the target machine (or container). This target can be specified using a machine (or container) ID or using the ID of the unit that it hosts. Both can be retrieved from the output of juju status. For example, below we ssh into machine 0 and inside of it run echo hello:

juju ssh 0 echo hello 

By passing further arguments and options, you can also run this on behalf of a different qualified user (other than the current user) or pass a private SSH key instead.

Use the OpenSHH ssh command

See also: OpenSSH

First, make sure you’ve added a public SSH key for your user to the target model.

If you are the model creator, your public SSH key is already known to juju and you already have admin access for the model. If you are not the model creator, see How to manage users and User access levels for how to gain admin access to a model and How to manage SSH keys for how to add your SSH key to the model.

Alternatively, for direct access using a standard SSH client, it is also possible to add the key to an individual machine using standard methods (manually copying a key to the authorized_keys file or by way of a command such as ssh-import-id in the case of Ubuntu).

Then, to connect to a machine via the OpenSSH client, use the OpenSSH ssh command followed by <user account>@<machine IP address>, where the default user account added to a Juju machine, to which public SSH keys added by add-ssa-key or import-ssh-key, is ubuntu. For example, for a machine with an IP address of, do the following:

ssh ubuntu@

Copy files securely between machines

See also: juju scp

The scp command copies files securely to and from machines.

Options specific to scp must be preceded by double dashes: --.


Copy 2 files from two MySQL units to the local backup/ directory, passing -v to scp as an extra argument:

juju scp -- -v mysql/0:/path/file1 mysql/1:/path/file2 backup/

Recursively copy the directory /var/log/mongodb/ on the first MongoDB server to the local directory remote-logs:

juju scp -- -r mongodb/0:/var/log/mongodb/ remote-logs/

Copy a local file to the second apache2 unit in the model “testing”. Note that the -m here is a Juju argument so the characters -- are not used:

juju scp -m testing foo.txt apache2/1:

Juju cannot transfer files between two remote units because it uses public key authentication exclusively and the native (OpenSSH) scp command disables agent forwarding by default. Either the destination or the source must be local (to the Juju client).

Retry provisioning for a failed machine

See also: juju retry-provisioning


Upgrade the Ubuntu series of a machine

See also: Upgrading things, juju upgrade-machine (before juju v.3.0, upgrade-series)

First, tell juju to take the machine out of circulation, in preparation for an upgrade. You can do this by running the upgrade-machine command followed by the machine ID, the subcommand prepare, and the name of the series to upgrade to. For example, the code below tells juju to prepare machine 3 for an upgrade to bionic.

Once the prepare command has been issued, there is no way to cancel or abort the process. Once you commit to prepare you must complete the process or you will end up with an unusable machine!

juju upgrade-machine 3 prepare bionic

This has multiple effects:

  1. The machine is no longer available for charm deployments or for hosting new containers.
  2. Juju prepares the machine for the upcoming OS upgrade. All units on the machine are taken into account.

Second, perform the upgrade. This is done manually. On an Ubuntu-based machine, you can do this by logging in to the machine via SSH and executing the do-release-upgrade command:

juju ssh 0
$ do-release-upgrade

Make sure to reserve some time for maintenance, in case any issues arise.

Third, inform Juju that the machine has been successfully upgraded by running the upgrade-machine command with the complete subcommand.

juju upgrade-machine 5 complete

Done! The upgraded machine is again available for charm deployments.

Remove a machine

See also: juju remove-machine, Removing things reference

To remove a machine, use the remove-machine command followed by the machine ID. For example:

juju remove-machine 3

It is not possible to remove a machine that is currently hosting either a unit or a container. Either remove all of its units (or containers) first or, as a last resort, use the --force option.

In some situations, even with the --force option, the machine on the backing cloud may be left alive. Examples of this include the Manual cloud or if harvest provisioning mode is not set (see provisioner-harvest-mode). In addition to those situations, if the client has lost connectivity with the backing cloud, any backing cloud, then the machine may not be destroyed, even if the machine’s record has been removed from the Juju database and the client is no longer aware of it.

By using various options, you can also customize various other things.

Last updated 2 months ago.