How to form a cluster

When forming a LXD cluster, you start with a bootstrap server. This bootstrap server can be an existing LXD server or a newly installed one.

After initializing the bootstrap server, you can join additional servers to the cluster. See Cluster members for more information.

You can form the LXD cluster interactively by providing configuration information during the initialization process or by using preseed files that contain the full configuration.

To quickly and automatically set up a basic LXD cluster, you can use MicroCloud.

Configure the cluster interactively

To form your cluster, you must first run lxd init on the bootstrap server. After that, run it on the other servers that you want to join to the cluster.

When forming a cluster interactively, you answer the questions that lxd init prompts you with to configure the cluster.

Initialize the bootstrap server

To initialize the bootstrap server, run lxd init and answer the questions according to your desired configuration.

You can accept the default values for most questions, but make sure to answer the following questions accordingly:

Would you like to use LXD clustering?

Select yes.
What IP address or DNS name should be used to reach this server?

Make sure to use an IP or DNS address that other servers can reach.
Are you joining an existing cluster?

Select no.
Setup password authentication on the cluster?

Select no to use authentication tokens (recommended) or yes to use a trust password.

Expand to see a full example for lxd init on the bootstrap server

~$ lxd init

Would you like to use LXD clustering? (yes/no) [default=no]: yes What IP address or DNS name should be used to reach this server? [default=192.0.2.101]: Are you joining an existing cluster? (yes/no) [default=no]: no What member name should be used to identify this server in the cluster? [default=server1]: Setup password authentication on the cluster? (yes/no) [default=no]: no Do you want to configure a new local storage pool? (yes/no) [default=yes]: Name of the storage backend to use (btrfs, dir, lvm, zfs) [default=zfs]: Create a new ZFS pool? (yes/no) [default=yes]: Would you like to use an existing empty block device (e.g. a disk or partition)? (yes/no) [default=no]:

After the initialization process finishes, your first cluster member should be up and available on your network. You can check this with lxc cluster list.

Join additional servers

You can now join further servers to the cluster.

Note

The servers that you add should be newly installed LXD servers. If you are using existing servers, make sure to clear their contents before joining them, because any existing data on them will be lost.

To join a server to the cluster, run lxd init on the cluster. Joining an existing cluster requires root privileges, so make sure to run the command as root or with sudo.

Basically, the initialization process consists of the following steps:

Request to join an existing cluster.

Answer the first questions that lxd init asks accordingly:
- Would you like to use LXD clustering?
  
  Select yes.
- What IP address or DNS name should be used to reach this server?
  
  Make sure to use an IP or DNS address that other servers can reach.
- Are you joining an existing cluster?
  
  Select yes.
- Do you have a join token?
  
  Select yes if you configured the bootstrap server to use authentication tokens (recommended) or no if you configured it to use a trust password.
Authenticate with the cluster.

There are two alternative methods, depending on which authentication method you choose when configuring the bootstrap server.

Authentication tokens (recommended)Trust password

Generate a cluster join token for each new member.

To do so, run the following command on an existing cluster member (for example, the bootstrap server):
```
lxc cluster add <new\_member\_name>
```
This command returns a single-use join token that is valid for a configurable time (see cluster.join_token_expiry). Enter this token when lxd init prompts you for the join token.

The join token contains the addresses of the existing online members, as well as a single-use secret and the fingerprint of the cluster certificate. This reduces the amount of questions that you must answer during lxd init, because the join token can be used to answer these questions automatically.

If you configured your cluster to use a trust password, lxd init requires more information about the cluster before it can start the authorization process:
1. Specify a name for the new cluster member.
2. Provide the address of an existing cluster member (the bootstrap server or any other server you have already added).
3. Verify the fingerprint for the cluster.
4. If the fingerprint is correct, enter the trust password to authorize with the cluster.
Confirm that all local data for the server is lost when joining a cluster.
Configure server-specific settings (see Member configuration for more information).

You can accept the default values or specify custom values for each server.

Expand to see full examples for lxd init on additional servers

Authentication tokens (recommended)Trust password

~$ sudo lxd init

Would you like to use LXD clustering? (yes/no) [default=no]: yes``What IP address or DNS name should be used to reach this server? [default=192.0.2.102]:``Are you joining an existing cluster? (yes/no) [default=no]: yes``Do you have a join token? (yes/no/[token]) [default=no]: yes``Please provide join token: eyJzZXJ2ZXJfbmFtZSI6InJwaTAxIiwiZmluZ2VycHJpbnQiOiIyNjZjZmExZDk0ZDZiMjk2Nzk0YjU0YzJlYzdjOTMwNDA5ZjIzNjdmNmM1YjRhZWVjOGM0YjAxYTc2NjU0MjgxIiwiYWRkcmVzc2VzIjpbIjE3Mi4xNy4zMC4xODM6ODQ0MyJdLCJzZWNyZXQiOiJmZGI1OTgyNjgxNTQ2ZGQyNGE2ZGE0Mzg5MTUyOGM1ZGUxNWNmYmQ5M2M3OTU3ODNkNGI5OGU4MTQ4MWMzNmUwIn0=``All existing data is lost when joining a cluster, continue? (yes/no) [default=no] yes``Choose "size" property for storage pool "local":``Choose "source" property for storage pool "local":``Choose "zfs.pool_name" property for storage pool "local":``Would you like a YAML "lxd init" preseed to be printed? (yes/no) [default=no]:

~$ sudo lxd init

Would you like to use LXD clustering? (yes/no) [default=no]: yes``What IP address or DNS name should be used to reach this server? [default=192.0.2.102]:``Are you joining an existing cluster? (yes/no) [default=no]: yes``Do you have a join token? (yes/no/[token]) [default=no]: no``What member name should be used to identify this server in the cluster? [default=server2]:``IP address or FQDN of an existing cluster member (may include port): 192.0.2.101:8443``Cluster fingerprint: 2915dafdf5c159681a9086f732644fb70680533b0fb9005b8c6e9bca51533113``You can validate this fingerprint by running "lxc info" locally on an existing cluster member.``Is this the correct fingerprint? (yes/no/[fingerprint]) [default=no]: yes``Cluster trust password:``All existing data is lost when joining a cluster, continue? (yes/no) [default=no] yes``Choose "size" property for storage pool "local":``Choose "source" property for storage pool "local":``Choose "zfs.pool_name" property for storage pool "local":``Would you like a YAML "lxd init" preseed to be printed? (yes/no) [default=no]:

After the initialization process finishes, your server is added as a new cluster member. You can check this with lxc cluster list.

Configure the cluster through preseed files

To form your cluster, you must first run lxd init on the bootstrap server. After that, run it on the other servers that you want to join to the cluster.

Instead of answering the lxd init questions interactively, you can provide the required information through preseed files. You can feed a file to lxd init with the following command:

cat <preseed-file> | lxd init --preseed

You need a different preseed file for every server.

Initialize the bootstrap server

The required contents of the preseed file depend on whether you want to use authentication tokens (recommended) or a trust password for authentication.

Authentication tokens (recommended)Trust password

To enable clustering, the preseed file for the bootstrap server must contain the following fields:

config:
  core.https\_address: <IP\_address\_and\_port>
cluster:
  server\_name: <server\_name>
  enabled: true

Here is an example preseed file for the bootstrap server:

config:
  core.https\_address: 192.0.2.101:8443
  images.auto\_update\_interval: 15
storage\_pools:
- name: default
  driver: dir
- name: my-pool
  driver: zfs
networks:
- name: lxdbr0
  type: bridge
profiles:
- name: default
  devices:
    root:
      path: /
      pool: my-pool
      type: disk
    eth0:
      name: eth0
      nictype: bridged
      parent: lxdbr0
      type: nic
cluster:
  server\_name: server1
  enabled: true

To enable clustering, the preseed file for the bootstrap server must contain the following fields:

config:
  core.https\_address: <IP\_address\_and\_port>
  core.trust\_password: <trust\_password>
cluster:
  server\_name: <server\_name>
  enabled: true

Here is an example preseed file for the bootstrap server:

config:
  core.trust\_password: the\_password
  core.https\_address: 192.0.2.101:8443
  images.auto\_update\_interval: 15
storage\_pools:
- name: default
  driver: dir
- name: my-pool
  driver: zfs
networks:
- name: lxdbr0
  type: bridge
profiles:
- name: default
  devices:
    root:
      path: /
      pool: my-pool
      type: disk
    eth0:
      name: eth0
      nictype: bridged
      parent: lxdbr0
      type: nic
cluster:
  server\_name: server1
  enabled: true

See Preseed YAML file fields for the complete fields of the preseed YAML file.

Join additional servers

The required contents of the preseed files depend on whether you configured the bootstrap server to use authentication tokens (recommended) or a trust password for authentication.

The preseed files for new cluster members require only a cluster section with data and configuration values that are specific to the joining server.

Authentication tokens (recommended)Trust password

The preseed file for additional servers must include the following fields:

cluster:
  enabled: true
  server\_address: <IP\_address\_of\_server>
  cluster\_token: <join\_token>
 
Here is an example preseed file for a new cluster member:
 
cluster:
  enabled: true
  server\_address: 192.0.2.102:8443
  cluster\_token: eyJzZXJ2ZXJfbmFtZSI6Im5vZGUyIiwiZmluZ2VycHJpbnQiOiJjZjlmNmVhMWIzYjhiNjgxNzQ1YTY1NTY2YjM3ZGUwOTUzNjRmM2MxMDAwMGNjZWQyOTk5NDU5YzY2MGIxNWQ4IiwiYWRkcmVzc2VzIjpbIjE3Mi4xNy4zMC4xODM6ODQ0MyJdLCJzZWNyZXQiOiIxNGJmY2EzMDhkOTNhY2E3MGJmYThkMzE0NWM4NWY3YmE0ZmU1YmYyNmJiNDhmMmUwNzhhOGZhMDczZDc0YTFiIn0=
  member\_config:
  - entity: storage-pool
    name: default
    key: source
    value: ""
  - entity: storage-pool
    name: my-pool
    key: source
    value: ""
  - entity: storage-pool
    name: my-pool
    key: driver
    value: "zfs"
 
The preseed file for additional servers must include the following fields:
 
cluster:
  server\_name: <server\_name>
  enabled: true
  cluster\_address: <IP\_address\_of\_bootstrap\_server>
  server\_address: <IP\_address\_of\_server>
  cluster\_password: <trust\_password>
  cluster\_certificate: <certificate> \# use this or cluster\_certificate\_path
  cluster\_certificate\_path: <path\_to-certificate\_file> \# use this or cluster\_certificate

To create a YAML-compatible entry for the cluster_certificate key, run one the following commands on the bootstrap server:

When using the snap: sed ':a;N;$!ba;s/\n/\n\n/g' /var/snap/lxd/common/lxd/cluster.crt
Otherwise: sed ':a;N;$!ba;s/\n/\n\n/g' /var/lib/lxd/cluster.crt

Alternatively, copy the cluster.crt file from the bootstrap server to the server that you want to join and specify its path in the cluster_certificate_path key.

Here is an example preseed file for a new cluster member:

cluster:
  server\_name: server2
  enabled: true
  server\_address: 192.0.2.102:8443
  cluster\_address: 192.0.2.101:8443
  cluster\_certificate: "-----BEGIN CERTIFICATE-----
 
opyQ1VRpAg2sV2C4W8irbNqeUsTeZZxhLqp4vNOXXBBrSqUCdPu1JXADV0kavg1l
 
2sXYoMobyV3K+RaJgsr1OiHjacGiGCQT3YyNGGY/n5zgT/8xI0Dquvja0bNkaf6f
 
...
 
-----END CERTIFICATE-----
"
  cluster\_password: the\_password
  member\_config:
  - entity: storage-pool
    name: default
    key: source
    value: ""
  - entity: storage-pool
    name: my-pool
    key: source
    value: ""
  - entity: storage-pool
    name: my-pool
    key: driver
    value: "zfs"

See Preseed YAML file fields for the complete fields of the preseed YAML file.

Use MicroCloud

▶ Watch on YouTube (opens in a new tab)

Instead of setting up your LXD cluster manually, you can use MicroCloud (opens in a new tab) to get a fully highly available LXD cluster with OVN and with Ceph storage up and running.

To install the required snaps, run the following command:

snap install lxd microceph microovn microcloud

Then start the bootstrapping process with the following command:

microcloud init

If you want to set up a multi-machine MicroCloud, run the following command on all the other machines:

microcloud join

Following the CLI prompts, a working MicroCloud will be ready within minutes.

When the initialization is complete, you'll have an OVN cluster, a Ceph cluster and a LXD cluster, and LXD itself will have been configured with both networking and storage suitable for use in a cluster.

See the MicroCloud documentation (opens in a new tab) for more information.

How to configure Auth0 as login method for the LXD UI and CLI How to work with different projects