Basic client usage - tutorial
The goal of this tutorial is to give new Juju operators a solid introduction to the command line client. In so doing, several important concepts are introduced. It also discusses the use of command prefixes and aliases. Further reading suggestions are included at the end.
Prerequisites
The following prerequisites are assumed as a starting point for this tutorial:
- You're using Ubuntu 18.04 LTS (Bionic).
- Juju (stable snap channel) is installed. See the Installing Juju page.
- You have chosen a backing cloud and have created a controller for it. Refer to the Clouds page to get started with a cloud and controller.
This guide uses LXD (v.3.9) as a backing cloud due to its accessibility and
low resource usage. Choose a local LXD cloud if you're not sure what to use
(see Using LXD with Juju).
Command prefixes and aliases
As you gain more experience with the client, you will discover a common set of
command prefixes: add-, create-, destroy-, get-, list-, remove-,
set-, and show-.
Generally their meanings are self-evident but some require explanation. A good
example of this are the destroy- and remove- prefixes, such as in the
commands destroy-model and remove-user. These two prefixes differ in terms
of severity. Basically, destroy- indicates a destructive action that is
difficult to reverse whereas remove- does not.
There is a kill- prefix but it is reserved for a single command:
kill-controller. The latter differs from destroy-controller in that it has
the ability to terminate the controller machine directly via the cloud
provider, without cleaning up any machines that may be running in workload
models.
The list- prefix can often be omitted as there is usually a corresponding
command alias available. For instance, clouds can be used instead of
list-clouds. The list of aliases can be obtained in this way:
juju help commands | grep Alias
The show- prefix is used to drill down into an object to reveal details. It
is akin to the verb "describe".
Fundamental commands
Juju makes available to the operator a wide variety of commands. In this section, we'll cover the basic ones.
Listing initial information
List the controller:
juju controllers
This will return a list of all the controllers known to your Juju client. Below, we have a controller named 'lxd':
Controller Model User Access Cloud/Region Models Machines HA Version lxd* default admin superuser localhost/localhost 2 1 none 2.5.0
A newly-created controller has two models: The 'controller' model, which should be used only for internal Juju management, and a 'default' model, which is ready for actual use.
Confirm the above by listing all the models in the currently active controller:
juju models
Our example's output:
Controller: lxd Model Cloud/Region Status Machines Access Last connection controller localhost/localhost available 1 admin just now default* localhost/localhost available 2 admin 2019-02-02
To see the currently active controller, model, and user:
juju whoami
Our example:
Controller: lxd Model: default User: admin
Deploying an application
Applications are contained within models and are installed via charms. By default, charms are downloaded from the online Charm Store during deployment.
To deploy a charm, such as 'redis', in the currently active model:
juju deploy redis
This results in an identically-named application ("redis") to be installed on a newly-created machine within the backing cloud. You can assign a custom name to the application by specifying that name as an argument:
juju deploy redis datastore
Adding a model
To create a model, named 'alpha', in the currently active controller:
juju add-model alpha
By default, when a model is created the currently active model becomes the new model.
Changing models
To manually change to a different model, say the original 'default' model:
juju switch default
Adding a machine
To request that two machines be created that are devoid of an application:
juju add-machine -m alpha -n 2
Here we've used the -m option to explicitly select a model (i.e. we don't
want the currently active model, which at this time is 'default').
Listing machines
To change context to model 'alpha' and then list the model's machines:
juju switch alpha juju machines
Our example:
Machine State DNS Inst id Series AZ Message 0 started 10.243.67.116 juju-ded876-0 bionic Running 1 started 10.243.67.53 juju-ded876-1 bionic Running
Deploying to a LXD container
To deploy 'apache2' to a new LXD container on existing machine '0':
juju deploy apache2 --to lxd:0
It's not necessary to explicitly target an existing machine in order to deploy a charm upon on. To deploy 'mongodb' on the second available machine ('1'):
juju deploy mongodb
Scaling up an application
To scale out the 'apache2' application by creating another instantiation (unit) of it on a new machine:
juju add-unit apache2
Like the add-machine command, the -n option is available if multiple units
are desired.
Viewing the model status
The status command is one that you'll use often. It gives live information
for a given model.
juju status
Our example currently shows:
Model Controller Cloud/Region Version SLA Timestamp alpha lxd localhost/localhost 2.5.0 unsupported 21:28:33Z App Version Status Scale Charm Store Rev OS Notes apache2 unknown 2 apache2 jujucharms 26 ubuntu mongodb 3.6.3 active 1 mongodb jujucharms 52 ubuntu Unit Workload Agent Machine Public address Ports Message apache2/0* unknown idle 0/lxd/0 10.72.88.191 apache2/1 unknown idle 2 10.243.67.141 mongodb/0* active idle 1 10.243.67.53 27017/tcp,27019/tcp,27021/tcp,28017/tcp Unit is ready Machine State DNS Inst id Series AZ Message 0 started 10.243.67.116 juju-ded876-0 bionic Running 0/lxd/0 started 10.72.88.191 juju-ded876-0-lxd-0 bionic Container started 1 started 10.243.67.53 juju-ded876-1 bionic Running 2 started 10.243.67.141 juju-ded876-2 bionic Running
The output is broken up into four sections.
The top section mentions basic information such as the names of the current model and controller ('alpha' and 'lxd' respectively), followed by the cloud name ('localhost'), what version of Juju the model is running, whether Juju is being used in a third-party context (see Managed solutions), and finally, the timestamp of the current controller.
The App section contains information at the application level. It is closely related to the providence of an application's charm. The 'Scale' tells us how many units exist for an application while the 'Rev' column shows the charm's revision number.
The Unit section contains information at the unit level. It lists them, along with information that is passed back from the unit agent. The type of data available is is very charm-specific. For instance, the 'unknown' workload message for the apache2 units is not necessarily a bad thing. It's just that the associated charm was not written to give something more insightful.
The Machine section contains information at the machine level. It lists machines by their ID (e.g. '0/lxd/0' or just '1'). The 'Inst id' is the instance id of the machine that gets passed to the cloud provider as the instance name.
Notice how the machines command output is a subset of the status command
output.
Inspecting the logs
Juju logs are inspected on a per-model basis using a specific utility.
To view (tail) the logs of the 'alpha' model:
juju debug-log -m alpha
There are a number of ways to configure the behaviour of the debug-log
command.
Connecting to a machine via SSH
The system user who created the controller (bootstrap command) will
automatically have SSH access to all machines in the original two default
models ('controller' and 'default') and any models they create afterwards.
To connect to a machine simply refer to the machine ID (from the machines
command). Here we connect to machine '1' in the current model:
juju ssh 1
This command will always get you to the controller machine:
juju ssh -m controller 0
Removing an application
To remove the 'apache2' application, including all units, along with associated machines (provided they are not hosting another application's units).
juju remove-application apache2
Removing a unit
To remove just a single unit, such as 'apache2/1':
juju remove-unit apache2/1
Like the remove-application command, this command will also remove the
machine if it is now devoid of units.
Removing a machine
To remove the machine whose ID is '1':
juju remove-machine 1
As a safety precaution, a machine cannot be removed if it is hosting a unit.
Either remove all of its units first or, as a last resort, use the --force
option.
Destroying a model
Destroying a model is a quick way to remove all applications and machines within that model. Begin anew with the creation of a new one.
To destroy the model called 'alpha':
juju destroy-model alpha
Destroying a controller
When a controller is destroyed, all its models, applications, and machines are as well.
To destroy the controller called 'lxd':
juju destroy-controller lxd
Next steps
Based on the material covered in this tutorial, we suggest the following for further reading: