Using LXD with Juju - advanced

This page is dedicated to more advanced topics related to using LXD with Juju. The main page is Using LXD with Juju.

The topics presented here are:

  • LXD clustering
  • Adding a remote LXD cloud
  • Charms and LXD profiles

LXD clustering

LXD clustering (lxd v.3 and greater) allows for distributed computing to the extent that Juju units end up on different cluster nodes (LXD hosts) by default. It also offers high availability so that the cluster remains functional as long as more than half of the nodes are up. A downed node will lead to its hosted containers becoming unavailable.

In terms of adding a LXD cloud, Juju is indifferent as to whether it is clustered or not. Juju connects to a single LXD host and, when prompted for connection information, you will need to decide which host that is. It should be noted that if this host becomes unavailable Juju will lose connection to the entire cluster.

Important: Each cluster node must have a network bridge that is connected to LXD. This is to allow the client to communicate with the Juju machines (containers).

Clustering is configured by running lxd init on each LXD host (a minimum of three is recommended). The first host that does so will initialise the cluster and any subsequent node will join the cluster. When joining, sudo is required.

Once the cluster is set up a controller can be created and will end up randomly on one of the nodes. Since v.2.5.0, however, specific cluster nodes can be targeted. See Deploying to specific machines for how to do this.

Warning: The cluster-creation process will remove any existing containers. In a Juju context, this implies that you must initialise the cluster before creating a controller.

See the upstream documentation on Clustering.

Adding a remote LXD cloud

The traditional way of using LXD with Juju is by having both the Juju client and the LXD daemon local to each other. However, since v.2.5.0 Juju supports connecting to a remote LXD daemon. Doing so does not require LXD to be installed alongside the Juju client.

Use the add-cloud command in interactive mode to add a LXD cloud to Juju's list of clouds. You will need to supply the name you wish to call your cloud and the unique LXD API endpoint.

For the manual method of adding a LXD cloud, see below section Manually adding a remote LXD cloud.

juju add-cloud

Example user session:

Cloud Types


Select cloud type: lxd

Enter a name for your lxd cloud: lxd-remote

Enter the API endpoint url for the remote LXD server:                                                                                                   
Auth Types

Enter region [default]: 

Enter the API endpoint url for the region [use cloud api url]: 

Enter another region? (y/N): n

Cloud "lxd-remote" successfully added

You will need to add credentials for this cloud (`juju add-credential lxd-remote`)
before creating a controller (`juju bootstrap lxd-remote`).

Important: The remote LXD server needs to be available over the network and is specified with lxd init on the remote host. Networking is enabled automatically when clustering is chosen.

Now confirm the successful addition of the cloud:

juju clouds

Here is a partial output:

Cloud        Regions  Default          Type        Description
lxd-remote         1  default          lxd         LXD Container Hypervisor

Manually adding a remote LXD cloud

Alternatively, the remote LXD cloud can be added manually to Juju (see Adding clouds manually for background information).

The manual method necessitates the use of a YAML-formatted configuration file. Here is an example:

    type: lxd
    auth-types: [certificate]

We've called the cloud 'lxd-remote-manual'. The endpoint is based on the HTTPS protocoal, port 8443, and the IP address of the remote LXD host.

To add cloud 'lxd-remote-manual', assuming the configuration file is lxd-cloud.yaml in the current directory, we would run:

juju add-cloud lxd-remote-manual lxd-cloud.yaml

Adding credentials

As opposed to a local LXD cloud, in a remote context, credentials need to be added prior to creating a controller (see Credentials for background information).

Use the add-credential command to add credentials to the new cloud:

juju add-credential lxd-remote
Enter credential name: lxd-remote-creds

Auth Types

Select auth type [interactive]: 

Enter trust-password: *******

Loaded client cert/key from "/home/ubuntu/.local/share/juju/lxd"
Uploaded certificate to LXD server.

Credential "lxd-remote-creds" added locally for cloud "lxd-remote".

We've called the new credential 'lxd-remote-creds'. When prompted for 'trust-password', enter the password that was set up with lxd init on the remote LXD host.

Note: If the 'certificate' authentication type is chosen in place of 'interactive' the server and client certificates and the client key will need to be gathered manually. You will be prompted for the paths to the three files containing the data.

Manually adding LXD credentials

Like adding a cloud manually, a YAML file is needed to manually add credentials. Here is an example:

      auth-type: interactive
      trust-password: ubuntu

Here, we've named the credential as we did when using the interactive method: 'lxd-remote-creds'. The trust password is set as 'ubuntu'.

To add credentials for cloud 'lxd-remote', assuming the configuration file is lxd-cloud-creds.yaml in the current directory, we would run:

juju add-credential lxd-remote -f lxd-cloud-creds.yaml

Next steps

Now that the cloud and credentials have been added the next step is to create a controller. See Creating a controller on the main LXD page.

Charms and LXD profiles

Juju (v.2.5.0) allows charms to include a LXD profile. The profile will be applied to a LXD container that the charm is deployed into. The following functionality is built in:

  • A validity check is performed on the profile(s) during the deployment of the charm. This is based on a hardcoded list of allowed items, everything else being denied. The --force option can be used to bypass this check but this is not recommended. The list is:

  • Profiles are upgraded during the upgrade of the charm (juju upgrade-charm).
  • Profiles are displayed at the machine level by using either the show-machine command or the status --format=yaml command. Below is an example of the kind of information that can be obtained from either of these two commands:
          environment.http_proxy: ""
          linux.kernel_modules: openvswitch,nbd,ip_tables,ip6_tables
          security.nesting: "true"
          security.privileged: "true"
        description: lxd profile for testing, black list items grouped commented out
            source: /dev/loop0
            type: unix-block
            productid: 51da
            type: usb
            vendorid: 0fce
            path: /dev/net/tun
            type: unix-char

See the LXD documentation to learn about the valid profile configuration options.