The LXD cloud and Juju

List of supported clouds > LXD

This document describes details specific to using your existing LXD cloud with Juju.


Expand to view how to get a LXD cloud quickly on Ubuntu

Your Ubuntu likely comes with LXD preinstalled. Configure it as below. Juju will then recognize it as the localhost cloud.

lxd init --auto
lxc network set lxdbr0 ipv6.address none

See more: LXD

When using the LXD cloud with Juju, it is important to keep in mind that it is a (1) machine cloud and (2) not some other cloud.

See more: Cloud differences in Juju

As the differences related to (1) are already documented generically in our Tutorial, How-to guides, and Reference docs, here we record just those that follow from (2).


Expand to view some reasons to use a LXD cloud

The LXD cloud, especially when used locally, is great for:

- creating a repeatable deployment: Juju enables you to quickly iterate to construct the optimal deployment for your situation, then distribute that across your team

– local development: Juju’s localhost cloud can mirror the production ops environment (without incurring the costs involved with duplicating it)

- learning Juju: LXD is a lightweight tool for exploring Juju and how it operates

- rapid prototyping: LXD is great for when you’re creating a new charm and want to be able to quickly provision capacity and tear it down


Expand to find out why Docker wouldn't work

Juju expects to see an operating system-like environment, so a LXD system container fits the bill. Docker containers are laid out for a singular application process, with a self-contained filesystem rather than a base userspace image.


Juju points of variation Notes for the LXD cloud
setup (chronological order):
CLOUD
supported versions: Juju 2.9.x: LXD 5.0

Juju 3.x.x: LXD 5.x

requirements: TBA
definition: :information_source: Juju automatically defines a cloud of this type.
- name: localhost or user-defined
- type: lxd
- authentication types: [certificate, interactive]
- regions: [TO BE ADDED]
- cloud-specific model configuration keys: project (string)
The LXD project name to use for Juju’s resources.
CREDENTIAL
definition: local LXD cloud: If you are a Juju admin user: Already known to Juju. Run juju bootstrap, then juju credentials to confirm. (Pre-defined credential name in Juju: localhost.) Otherwise: Add manually as you would a remote.

clustered LXD cloud: In Juju, this counts as a remote cloud. You must add its definition to Juju explicitly.

remote LXD cloud: Requires the API endpoint URL for the remote LXD server.
> See more: LXD | How to add remote servers

If you want to use a YAML file:

(Pro tip: If you define a trust password, you can just use a trust-password key, and that will retrieve the certificates for you.)

credentials:
<user-defined cloud name>:
   <user-defined credential name>:
    auth-type: certificate
    client-key: |
     -----BEGIN RSA PRIVATE KEY---
     <content-of-rsa-private-key>
     -----END RSA PRIVATE KEY-----
    client-cert: |
     -----BEGIN CERTIFICATE-----
     <content-of-certificate>
     -----END CERTIFICATE-------
    server-cert: |
     -----BEGIN CERTIFICATE-----
     <content of certificate>
     -----END CERTIFICATE-------

CONTROLLER
notes on bootstrap:
other (alphabetical order:)
CONSTRAINT With LXD system containers, constraints are interpreted as resource maximums (as opposed to minimums).

There is a 1:1 correspondence between a Juju machine and a LXD container. Compare juju machines and lxc list.

conflicting: TBA
supported?
- allocate-public-ip :x:
- arch :white_check_mark:
Valid values: [host arch].
- container :x:
- cores :white_check_mark:
- cpu-power :x:
- image-id :x:
- instance-role :x:
- instance-type
- mem The maximum amount of memory that a machine/container will have.
- root-disk
- root-disk-source :white_check_mark:
root-disk-source is the LXD storage pool for the root disk. The default LXD storage pool is used if root-disk-source is not specified.
- spaces :x:
- tags :x:
- virt-type :x:
- zones :x:
PLACEMENT DIRECTIVE
<machine> TBA
subnet=... :x:
system-id=... :x:
zone=... :white_check_mark:
If there’s no ‘=’ delimiter, assume it’s a node name.
MACHINE
RESOURCE (cloud)

Consistent naming, tagging, and the ability to add user-controlled tags to created instances.

:x:

Other notes

Simple bootstrap of a remote LXD server

From Juju 2.9.5, the easiest method for bootstrapping a remote LXD server is to add the remote to your local LXC config then bootstrap with juju.

On the remote server:

# ensure the LXD daemon is listening on an accessible IP
lxc config set core.https_address '[::]'
# give the LXD daemon a trust password so the client can register credentials
lxc config set core.trust_password mytrustpassword

On the bootstrapping client:

# add the remote LXD server to the local LXC config
lxc remote add myremote 11.22.33.44 --password mytrustpassword
# bootstrap juju using the remote name in LXC
juju bootstrap myremote

The bootstrapping client must be able to reach the remote LXD containers. This may require the setup of a bridge device with the hosts ethernet device.

Non-admin user credentials

See Credentials for more details on how Juju credentials are used to share a bootstrapped controller.

To share a LXD server with other users on the same machine or remotely, the best method is to use LXC remotes. See Simple bootstrap of a remote LXD server above.

Add resilience via LXD clustering

LXD clustering provides the ability for applications to be deployed in a high-availability manner. In a clustered LXD cloud, Juju will deploy units across its nodes. For more, see Using LXD clustering with Juju.

Use LXD profiles from a charm

LXD Profiles allows the definition of a configuration that can be applied to any instance. Juju can apply those profiles during the creation or modification of a LXD container. For more, see Using LXD profiles with Juju.

LXD 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.

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 (http://cloud-images.ubuntu.com) and creates the necessary alias. Any subsequent requests will be satisfied by the LXD cache (/var/lib/lxd/images).

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


Contributors: @barryprice , @danieleprocida , @hpidcock, @jameinel , @pedroleaoc , @pmatulis , @timClicks , @tmihoc

1 Like

This information is misleading since it is phrased that this command comes from the LXD host, which is not the case.

I would like to see link to a clear instruction on how to generate those LXD server side certificates and how to transfer it over to the juju client.

The command is: “juju autoload-credentials” and now-a-days with juju2.9, the output from that command is not like the one presented…

I’m not confident enough yet to give the full description on how to achieve it or I would have done it already. @pedroleaoc

Thanks, Erik. I will add this to the list of documents that require reviewing and ask someone from the team to check this info.

@erik-lonroth is the confusion between host and admin here?

Configure networking section was removed in a previous revision, but its (broken) link is still in the table of content.

1 Like

removed, thanks for letting us know

1 Like

These instructions look suspect:

newgrp lxd
sudo adduser $USER lxd

The first command is likely to fail if the second hasn’t already been run.

This is actually good, as the first command would also set the primary group to lxd for the spawned process, which will infect files that the user creates in that shell and all descendant processes. newgrp - is better.

Thanks

Can you please change the green :negative_squared_cross_mark: with a red one? It’s quite confusing for people seeing green color on both symbols: :negative_squared_cross_mark: and :white_check_mark: Also on the docs here juju.is

I think there’s a bug in the generated page here, specifically the YAML example for certificate-based credentials.

Above, and on the live page, you have:

credentials:
 <user-defined cloud name>:
   <user-defined credential name>:
    auth-type: certificate
    client-key:
     -----BEGIN RSA PRIVATE KEY---
     <content-of-rsa-private-key>
     -----END RSA PRIVATE KEY-----
    `client-cert:

It looks as if there ought to be more after that line, perhaps caused by the stray backtick - probably a placeholder for the certificate data, and perhaps a server-cert: section as well?

I’m trying to set up a credential for an LXD cluster using certificates (without a trust-password key), and getting parsing errors from the example given:

ERROR parsing credentials file: credentials.lxd-microcloud. lxd-microcloud: expected map, got nothing

It was a rendering issue. Thanks for noticing it and taking the time to point it out to us. I’ve fixed it now and also added you to the list of contributors on the bottom of the doc. Thanks again!

1 Like

BTW, since we pointed out client-cert: it was also clear that it was missing the YAML | to indicate that what followed was a multi line (ignore surrounding whitespace) string. I believe I fixed it correctly.

1 Like