From 5f98f1b3ac0a1e38ed8c621953552873fb46d7c6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Julian=20Peliz=C3=A4us?= Date: Thu, 13 Aug 2026 17:34:16 +0200 Subject: [PATCH 1/4] doc/reference/preseed: Move reference yaml file MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Julian Pelizäus --- doc/{how-to => reference}/preseed.yaml | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename doc/{how-to => reference}/preseed.yaml (100%) diff --git a/doc/how-to/preseed.yaml b/doc/reference/preseed.yaml similarity index 100% rename from doc/how-to/preseed.yaml rename to doc/reference/preseed.yaml From 348c99a94ff9e9371e63b47664f580eca1d8b76c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Julian=20Peliz=C3=A4us?= Date: Thu, 13 Aug 2026 17:35:36 +0200 Subject: [PATCH 2/4] doc/reference: Add preseed reference page MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Julian Pelizäus --- doc/reference/index.md | 11 +++++ doc/reference/preseed.md | 100 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 111 insertions(+) create mode 100644 doc/reference/preseed.md diff --git a/doc/reference/index.md b/doc/reference/index.md index 917dcbb09..aa37deef6 100644 --- a/doc/reference/index.md +++ b/doc/reference/index.md @@ -31,6 +31,17 @@ Consult this command reference to work with MicroCloud through the CLI. /reference/commands ``` + +## Preseed + +Consult this preseed reference for a detailed explanation of the various configuration options. + +```{toctree} +:maxdepth: 1 + +/reference/preseed +``` + ## Requirements and releases ```{toctree} diff --git a/doc/reference/preseed.md b/doc/reference/preseed.md new file mode 100644 index 000000000..78a35d9b5 --- /dev/null +++ b/doc/reference/preseed.md @@ -0,0 +1,100 @@ +(ref-preseed)= +# Preseed configuration options + +MicroCloud preseed allows the unattended (non-interactive) deployment of a cluster using a pre-configured file. +See below for detailed descriptions of the main building blocks of the file, followed by a {ref}`full configuration example ` file. + +(ref-preseed-filters)= +## Storage disk filters + +Explicitly setting the storage disks per system under `systems.[*].storage` is optional. +Use filters if the exact disk paths are unknown when crafting the preseed file. +This also makes the preseed file generic enough to be usable across various MicroCloud deployments. + +Filters allow MicroCloud to make a selection from a list of all disks available on the systems. +These filters correspond to the YAML field names of the disk resources returned from LXD's `/1.0/resources` endpoint. + +The following table lists all of the available filters: + +```{table} +:align: left + +| Filter | Example | +| ------------------ | ------------------------------------------- | +| `id` | `nvme0n1` | +| `device` | `259:0` | +| `model` | `` | +| `type` | `nvme` | +| `read_only` | `false` | +| `mounted` | `false` | +| `size` | `1024209543168` (size of the disk in bytes) | +| `removable` | `false` | +| `wwn` | `eui.00xxxxxxxxxxxxxx` | +| `numa_node` | `0` | +| `device_path` | `pci-0000:04:00.0-nvme-1` | +| `block_size` | `512` | +| `firmware_version` | `4L2XXXXX` | +| `rpm` | `0` | +| `serial` | `S7XKXXXXXXXXXX` | +| `device_id` | `nvme-eui.00xxxxxxxxxxxxxx` | +| `pci_address` | `0000:04:00.0` | +| `used_by` | `bcache` | +``` + +When using the `size` filter, its value can be compared against a user-defined number using byte suffixes in either units of 1000 or 1024: + +`B`, `kB`, `MB`, `GB`, `TB`, `EB`, `KiB`, `MiB`, `GiB`, `TiB`, `PiB`, `EiB` + +### Filter operands + +All filters can use the following operands to compare against defined values: + +`&&`, `||`, `<`, `>`, `<=`, `>=`, `==`, `!=`, `!` + +Furthermore the following restrictions apply: + +* Filters are checked in order of appearance +* String values must not be in quotes unless the string contains a space +* Single quotes are fine, but double quotes must be escaped + + +Multiple filters can be added to a single section: + +```yaml +storage: + ceph: + - find: + - find: +``` + +### Limit filtered disks + +In addition to finding disks by filter, the minimum and maximum number of disks can also be specified. +For this, the `find_min` and `find_max` settings can be added to the relevant section: + +```yaml +storage: + ceph: + - find: + find_min: 1 + find_max: 2 +``` + +The example above will make sure that the filters select at least one, but not more than two, disks for remote (Ceph) storage. + +```{note} +For local storage there can only ever be one disk per system. +If the filters return more than one disk, only one of them will be used. + +For remote storage the filters apply for all disks across all systems. +``` + +(ref-preseed-full-configuration-example)= +## Full configuration example + +The preseed YAML file must use the following syntax: + +```{literalinclude} preseed.yaml +:language: YAML +:emphasize-lines: 1-4,7-10,13-14,17-19,22,25-27,30-35,63-66,72,79-88 +``` From 465a871e98f7a6b14102b33ad8494cebc74dd9d5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Julian=20Peliz=C3=A4us?= Date: Thu, 13 Aug 2026 17:35:00 +0200 Subject: [PATCH 3/4] doc/how-to: Refer to preseed reference MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Julian Pelizäus --- doc/how-to/initialize.md | 8 +------- doc/how-to/member_add.md | 8 +------- 2 files changed, 2 insertions(+), 14 deletions(-) diff --git a/doc/how-to/initialize.md b/doc/how-to/initialize.md index 10a58e94f..3569bb3ff 100644 --- a/doc/how-to/initialize.md +++ b/doc/how-to/initialize.md @@ -182,13 +182,7 @@ If you want to automate the initialization process, you can provide a preseed co cat | microcloud preseed Make sure to distribute and run the same preseed configuration on all systems that should be part of the MicroCloud. - -The preseed YAML file must use the following syntax: - -```{literalinclude} preseed.yaml -:language: YAML -:emphasize-lines: 1-4,7-10,13-14,17-19,22,25-27,30-35,63-66,72,79-87 -``` +See the {ref}`full reference ` for possible configuration options or the minimal example below. ### Minimal preseed using multicast discovery diff --git a/doc/how-to/member_add.md b/doc/how-to/member_add.md index 50532ed36..56b8c2225 100644 --- a/doc/how-to/member_add.md +++ b/doc/how-to/member_add.md @@ -31,13 +31,7 @@ In the list of systems, include only the new machine and set either `initiator` that is already part of the MicroCloud. Distribute and run the same preseed configuration on both the machine being added, and the cluster member used for the `initiator` or `initiator_address`. - -The preseed YAML file must use the following syntax: - -```{literalinclude} preseed.yaml -:language: YAML -:emphasize-lines: 1-4,7-10,13-14,17-19,22,25-27,30-35,63-66,72,79-88 -``` +See the {ref}`full reference ` for possible configuration options or the minimal example below. ### Minimal preseed using multicast discovery From 6ccd3d71314f7728c26a5b0d46e610a8c926c2b0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Julian=20Peliz=C3=A4us?= Date: Thu, 13 Aug 2026 17:35:58 +0200 Subject: [PATCH 4/4] doc/how-to/initialize: Add preseed filter how-to MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Julian Pelizäus --- doc/how-to/initialize.md | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/doc/how-to/initialize.md b/doc/how-to/initialize.md index 3569bb3ff..408a86870 100644 --- a/doc/how-to/initialize.md +++ b/doc/how-to/initialize.md @@ -233,6 +233,40 @@ ovn: If you initialized MicroCloud without local storage _and_ with CephFS storage, continue to the section below to complete your initialization. ``` +### Use storage disk filters + +You may not know the exact disk paths used for local and remote storage when crafting the preseed file. +In such cases, you can add disk filters for local and remote storage configuration. +By using those filters, you can narrow down the list of available disks to the ones eligible based on the given rules. + +For example you might want to use all disks for local storage which are of type `nvme` and use a model description ``: + +```yaml +storage: + local: + - find: type == nvme && model == "" +``` + +As another example, you can filter for remote (Ceph) storage disks with size greater than 1TiB and model description ``, and ensure there are at least six disks (maximum eight) selected across all members: + +```yaml +storage: + ceph: + - find: size > 1TiB && model == "" + find_min: 6 + find_max: 8 +``` + +See the {ref}`list of filters ` for a full reference. + +```{admonition} Finding the right filters +:class: note +If you want to see the actual filter values for your system(s) for further refinement of the preseed file, you can run `lxc query /1.0/resources | jq .storage.disks` on any of the MicroCloud members prior to initialization. + +The response will show all the disks available to MicroCloud on this member. +Repeat the command on every member for a full list of disks across the cluster. +``` + (howto-initialize-images-backups)= ## Configure `backups_volume` and `images_volume`