Using LXD as a cloud

LXD provides a fast, powerful, self-contained and largely configuration-free way to experiment with Juju. Using lightweight LXC containers as instances, even a moderately powerful laptop can create useful models, or serve as a development platform for your own charms.


Juju's support for LXD currently works only with Ubuntu 16.04 (Xenial).

Install LXD:

sudo apt install lxd
newgrp lxd

Alternate backing file-system

LXD can optionally use an alternative file-system for containers. We recommend using ZFS for the best experience. To use ZFS with LXD enter these commands:

sudo apt install zfsutils-linux
sudo mkdir /var/lib/zfs
sudo truncate -s 32G /var/lib/zfs/lxd.img
sudo zpool create lxd /var/lib/zfs/lxd.img
sudo lxd init --auto --storage-backend zfs --storage-pool lxd

Above we allocated 32GB of space to a sparse file. Consider using a fast block device if available.

Create a controller (bootstrap)

It is time to create the controller for LXD. Below, we call it 'lxd-xenial':

juju bootstrap lxd lxd-test

This will result in the controller being visible with the LXC client:

lxc list
|     NAME      |  STATE  |         IPV4          | IPV6 |    TYPE    | SNAPSHOTS |
| juju-669cb0-0 | RUNNING | (eth0) |      | PERSISTENT | 0         |

See more examples of Creating a controller.

Next steps

A controller is created with two models - the 'controller' model which should be reserved for Juju's operations, and a model named 'default' for deploying user workloads.

Additional information about LXD

LXD and images

LXD is image based: all LXD containers come from images and any LXD daemon instance (also called a "remote") can serve images. When LXD is installed a locally-running remote is provided (Unix domain socket) and the client is configured to talk to it (named 'local'). The client is also configured to talk to several other, non-local, ones (named 'ubuntu', 'ubuntu-daily', and 'images').

An image is identified by its fingerprint (SHA-256 hash), and can be tagged with multiple aliases. Juju looks for images with aliases in the format ubuntu-<codename>, for instance 'ubuntu-trusty' or 'ubuntu-xenial'.

For any image-related command, an image is specified by its alias or by its fingerprint. Both are shown in image lists. An image's filename is its full fingerprint while an image list displays its partial fingerprint. Either type of fingerprint can be used to refer to images.

Juju pulls official cloud images from the 'ubuntu' remote ( and creates the necessary alias. Any subsequent requests will be satisfied by the LXD cache (/var/lib/lxd/images). Cached images can be seen with lxc image list:

lxc image list after importing

Image cache expiration and image synchronization mechanisms are built-in.

Remote user credentials

When working with remote users on different machines (see [Creating users][users] for details on adding users, registering them and granting them permissions), LXD-hosted controllers need to generate a specific certificate credential which is shared with the remote machine.

To do this, first run juju autoload-credentials on the LXD host. This will generate output similar to the following:

Looking for cloud and credential information locally...

1. LXD credential "localhost" (new)
Select a credential to save by number, or type Q to quit:

Select the LXD credential (1 in the above example) and you will be asked for the name of a cloud to link to this credential. Enter 'localhost' to specify the local LXD deployment. When the prompt re-appears, type 'q' to quit. The new certificate credential will have been created.

To export this certificate credential to a file called localhost-credentials.yaml, type the following:

juju credentials localhost --format=yaml > localhost-credentials.yaml

The output file now needs to be moved to the machine and account that requires access to the local LXD deployment. With this file on the remote machine, the certificate credential can be imported with the following command:

juju add-credential localhost -f localhost-credentials.yaml

See Cloud credentials for more details on how credentials are used.


LXD itself logs to /var/log/lxd/lxd.log and Juju machines created via the LXD local provider log to /var/log/lxd/juju-{uuid}-machine-{#}. However, the standard way to view logs is with the juju debug-log command. See Viewing logs for more details.


Although not Juju-related, see lxc --help for more on LXD client usage and lxd --help for assistance with the daemon. See upstream documentation for how to configure the lxd daemon and containers .

For additional configuration of LXD controllers, please see the Controllers documentation.