diff --git a/doc/auto_storage.md b/doc/auto_storage.md index 46145433f5..686f109c5e 100644 --- a/doc/auto_storage.md +++ b/doc/auto_storage.md @@ -126,6 +126,7 @@ Partition encryption [Encryption] filesystem [] delete [] + deleteIfNeeded [] LogicalVolume search [] @@ -139,7 +140,7 @@ LogicalVolume encryption [Encryption] filesystem [] delete [] - + deleteIfNeeded [] Encryption reuse type @@ -255,6 +256,10 @@ into the following: - If the product does not specify a default volume, the behavior is still not defined (there are several reasonable options). +It is also possible to specify "current" as a size value for partitions and logical volumes that +already exist in the system. The usage of "current" and how it affects resizing the corresponding +devices is explained at a separate section below. + ### Under Discussion As explained, it should be possible to specify the sizes as "default", as a range or as a fixed @@ -264,10 +269,11 @@ represent a size. The following two possibilities are also under consideration. - `{ "gib": 40 }` - `{ "value": 40, "units": "gib" }` -Resizing is also an open topic. We may not be able to easily combine a resize operation with aspects -like ranges (min and max) or automatic sizes. We also need to define how to specify something like -"shink as much as needed to allocate the other partitions". See the section below about deleting and -shrinking. +## Partitions Needed for Booting + +Using a `boot` entry makes it possible to configure whether (and where, using an alias) Agama +should calculate and create the extra partitions needed for booting. If the device is not +specified, Agama will take the location of the root file system as a reference. ## Searching Existing Devices @@ -548,11 +554,6 @@ system (so the same conditions can be matched by a disk, a partition, an LVM dev } ``` -## Partitions Needed for Booting - -Using a `boot` entry makes it possible to configure whether (and where, using an alias) Agama -should calculate and create the extra partitions needed for booting. - ## Keeping an Existing File System or Encryption Layer The entries for both `encryption` and `filesystem` contain a flag `reuse` with a default value of @@ -564,29 +565,134 @@ or re-formatted. The storage proposal must make possible to define what to do with existing partitions and logical volumes. Even with existing MD RAIDs or LVM volume groups. -In order to provide the same capabilities than the Guided proposal (see below) it must be possible -to specify that a given partition (or LVM logical volume) must be: +A `search` section allows to match the definition of a partition or an LVM logical volume with one +(or several) devices existing in the system. In order to provide the same capabilities than the +Guided proposal (see below) it must be possible to specify that a given partition or volume must be: - Deleted if needed to make space for the newly defined devices - Deleted in all cases - Shrunk to the necessary size to make space for new devices - - Shrunk to a given size, maybe a range, in all cases (not really possible in the current Guided + - Shrunk or extended to a given size, maybe a range (not really possible in the current Guided Proposal) -It would be desirable to have the possibility of expressing some combinations of the above, like -"try to shrink it to make space but proceed to delete it if shrinking it is not enough". +It is even possible to express some combinations of the above, like "try to shrink it to make space +but proceed to delete it if shrinking it is not enough". + +Deletion can be achieved with the corresponding `delete` flag or the alternative `deleteIfNeeded`. +If any of those flags are active for a partition, it makes no sense to specify any other usage +(like declaring a file system on it). + +The following example deletes the partition with the label "root" in all cases and, if needed, keeps +deleting other partitions as needed to make space for the new partition of 30 GiB. + +```json +"storage": { + "drives": [ + { + "partitions": [ + { + "search": { + "condition": { "property": "fsLabel", "value": "root" } + }, + "delete": true + }, + { "search": {}, "deleteIfNeeded": true }, + { "size": "30 GiB" } + ] + } + ] +} +``` + +Often some partitions or logical volumes are shrunk only to make space for the declared devices. But +since resizing is not a destructive operation, it can also make sense to declare a given partition +must be resized (shrunk or extended) and then formatted and/or mounted. + +In any case, note that resizing a partition can be limited depending on its content, the filesystem +type, etc. + +Combining `search` and `resize` is enough to indicate Agama is expected to resize a given partition +if possible. The keyword "current" can be used eveywhere a size is expected and it is always +equivalent to the exact original size of the device. The simplest way to use "current" is to just +specify that the matched device should keep its original size. That's the default for searched (and +found) devices if `size` is completely omitted. + +```json +"storage": { + "drives": [ + { + "partitions": [ + { + "search": { + "condition": { "property": "fsLabel", "value": "reuse" } + }, + "size": "current" + } + ] + } + ] +} +``` + +Using "current" for the min and max values of a size allows to specify how a device could be resized +if possible. See the following examples with explanatory filesystem labels. -For partitions that are marked to be deleted (either mandatory or on demand), it makes no sense to -specify any other usage (like declaring a file system on it). But resizing a partition is more on -the grey area. Often some partitions or logical volumes are resized only to make space for the -declared devices. But since resizing is not a destructive operation it can also make sense to -declare a given partition must be resized and then formatted. +```json +"storage": { + "drives": [ + { + "partitions": [ + { + "search": { + "condition": { "property": "fsLabel", "value": "shrinkIfNeeded" } + }, + "size": { "min": 0, "max": "current" } + }, + { + "search": { + "condition": { "property": "fsLabel", "value": "resizeToFixedSize" } + }, + "size": "15 GiB" + }, + { + "search": { + "condition": { "property": "fsLabel", "value": "resizeByRange" } + }, + "size": { "min": "10 GiB", "max": "50 GiB" } + }, + { + "search": { + "condition": { "property": "fsLabel", "value": "growAsMuchAsPossible" } + }, + "size": { "min": "current" } + }, + ] + } + ] +} +``` + +Of course, when the size limits are specified as a combination of "current" and a fixed value, the +user must still make sure that the resulting min is not bigger than the resulting max. + +Both `deleteIfNeeded` and a size range can be combined to indicate that Agama should try to make +space first by shrinking the partitions and deleting them only if shrinking is not enough. -The exact syntax to specify all the possible actions is still under discussion. The current document -shows how a `delete` attribute could be used in combination with `search` to specify the devices to -delete. An alternative could be to have separate section for each device to specify how to delete -and/or shrink its partitions or logical volumes, instead of integrating that information into the -corresponding `partitions` or `logical_volumes` attributes. +```json +"storage": { + "drives": [ + { + "partitions": [ + { + "search": {}, + "size": { "min": 0, "max": "current" }, + "deleteIfNeeded": true + } + ] + } + ] +} +``` ## Using the Automatic Proposal