diff --git a/CHANGELOG.md b/CHANGELOG.md index efb38a74..f0c7243b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -88,6 +88,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 test-it with test. #890 - realy reboot also without systemd +- Specify primary network device per-node rather than per-netdev +- refactored output `wwctl node/profile list` so that `-a` will only show all the + set values and `-A` will show all fields included the ones without a set value +- Added support for file systems, partitions and disks. Values for these objects can + be set with `wwctl profile/node set/add`. The format of this objects is inspired by + butane/ignition, but where butane/ignition uses lists for holding disks, partitions + and file systems, warewulf uses maps instead. For disks the map key is the underlying + block device, for partitions its the partition label and for file systems its the path + to the partitions (e.g. `/dev/disk/by-partlabel/scratch`). + Not all available options of butane/ignition are exposed to the commandline, but are + available via `wwctl node/profile edit`. +- Added the template function `{{ createIgnitionJson }}` which will create a json object + compatible with ignition. +- Container images need ignition and sgdisk installed in order to the disk management. +- Added boootup services based on ignition which will manage the disks, partitions and file + systems. The services are systemd services as sgdisk needs systemd in order to work + correctly. All service use the existence of `/warewulf/ignition.json` as perquisite so + that they can be place in the `wwinit` overlay and will only become active if disk management + is configured for this node. The service `ignition-disks-ww4.service` will partition and + format and create the file systems on the disks. For every a file system a systemd mount unit + file is create and will executed after the `ignition-disks-ww4.service` has finished. + Entries in `/etc/fstab` for every file system are created with the `noauto` option. ## [4.4.0] 2023-01-18 diff --git a/userdocs/contents/disks.rst b/userdocs/contents/disks.rst new file mode 100644 index 00000000..36152178 --- /dev/null +++ b/userdocs/contents/disks.rst @@ -0,0 +1,89 @@ +=============== +Disk Management +=============== + +Warewulf itself does not manage disks, partitions, or file systems +directly, but provides structures in the configuration for these +objects. At the moment warewulf supports `ignition` to create the +partitions and file systems. + +.. note:: + + It is not currently possible to manage the root file system with + Warewulf. + +Warewulf can be used, for example, to create `swap` partitions or +`/scratch` file systems. + +Storage objects +=============== + +The format of the storage objects is inspired by `butane/ignition`; +but, where `butane/ignition` uses lists for holding disks, partitions +and file systems, Warewulf uses maps instead. + +A node or profile can have several disks, where each disk is +identified by the path to its block device. Every disks holds a map to +its partitions and a `bool` switch to indicate if an existing +partition table should be overwritten if it does not matched the +desired configuration. + +Each partition is identified by its label. The partition number can be +omitted, but specifying it is recommended as `ignition` may fail +without it. Partition sizes should also be set (specified in MiB), +except of the last partition: if no size is given, the maximum +available size is used. Each partition has the switches `should_exist` +and `wipe_partition_entry` which control the partition creation +process. + +File systems are identified by their underlying block device, +preferably using the `/dev/by-partlabel` format. Except for a `swap` +partition, an absolute path for the mount point must be specified for +each file system. Depending on the container used, valid formats are +`btrfs`, `ext3`, `ext4`, and `xfs`. Each file system has the switch +`wipe_filesystem` to control whether an existing file system is wiped. + +Ignition Implementation +======================= + +The ignition implementation uses systemd services, as the underlying +`sgdisk` command relies on dbus notifications. All necessary services +are distributed by the `wwinit` overlay and depends on the existence +of the file `/warewulf/ignition.json`. This file is created by the +template function `{{ createIgnitionJson }}` only if the configuration +contains necessary specifications for disks, partitions, and file +systems. If the file `/warewulf/ignition.json` exists, the service +`ignition-disks-ww4.service` calls the ignition binary which takes +creates partitions and file systems. A systemd `.mount` unit is +created for each configured file system, which also creates the +necessary mount points in the root file system. These mount units are +required by the enabled `ww4-disks.target`. Entries in `/etc/fstab` +are created with the `no_auto` option so that file systems can be +easily mounted. + +Example +======= + +The following command will create a `/scratch` file system on the node +`n01` + +.. code-block:: shell + + wwctl node set n01 \ + --diskname /dev/vda --diskwipe \ + --partname scratch --partcreate \ + --fsname scratch --fsformat btrfs --fspath /scratch --fswipe + +As this is a single file system, the partition number can be omitted. + +A swap partition with 1Gig can be added with + +.. code-block:: shell + + wwctl node set n01 \ + --diskname /dev/vda \ + --partname swap --partsize=1024 --partnumber 1 \ + --fsname swap --fsformat swap --fspath swap + +which has the partition number `1` so that it will be added before the +`/scratch` partition. diff --git a/userdocs/index.rst b/userdocs/index.rst index 7b651a90..f18504d1 100644 --- a/userdocs/index.rst +++ b/userdocs/index.rst @@ -23,6 +23,7 @@ Welcome to the Warewulf User Guide! Warewulf Overlays Node Provisioning IPMI + Disk Management Security Templating