diff --git a/doc/how-to/initialize.md b/doc/how-to/initialize.md index 10a58e94f..408a86870 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 @@ -239,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` 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 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 +``` 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