Merge pull request #559 from ajeddeloh/partition-docs

docs: improve partitioning docs clarity

doc/configuration-v2_3-experimental.md

@@ -28,16 +28,15 @@ The Ignition configuration is a JSON document conforming to the following specif
   * **_disks_** (list of objects): the list of disks to be configured and their options.
     * **device** (string): the absolute path to the device. Devices are typically referenced by the `/dev/disk/by-*` symlinks.
     * **_wipeTable_** (boolean): whether or not the partition tables shall be wiped. When true, the partition tables are erased before any further manipulation. Otherwise, the existing entries are left intact.
-    * **disallowUnspecifiedPartitions** (boolean): whether or not to fail if a disk has partitions not described by Ignition. Has no effect if "wipeTable" is true.
     * **_partitions_** (list of objects): the list of partitions and their configuration for this particular disk.
       * **_label_** (string): the PARTLABEL for the partition.
       * **_number_** (integer): the partition number, which dictates it's position in the partition table (one-indexed). If zero, use the next available partition slot.
       * **_size_** (integer): the size of the partition (in device logical sectors, 512 or 4096 bytes). If zero, the partition will be made as large as possible.
       * **_start_** (integer): the start of the partition (in device logical sectors). If zero, the partition will be positioned at the start of the largest block available.
       * **_typeGuid_** (string): the GPT [partition type GUID][part-types]. If omitted, the default will be 0FC63DAF-8483-4772-8E79-3D69D8477DE4 (Linux filesystem data).
       * **_guid_** (string): the GPT unique partition GUID.
-      * **_wipePartitionEntry_** (boolean) whether or not Ignition is allowed to wipe an existing partition entry for this partition number.
-      * **_shouldExist_** (boolean) whether or not a partition `number` should exist. If ommited, it defaults to true. If false, `number` must be specified and non-zero and `label`, `start`, `size`, `guid`, and `typeGuid` must all be omitted.
+      * **_wipePartitionEntry_** (boolean) if true, Ignition will clobber an existing partition if it does not match the config. If false (default), Ignition will fail instead.
+      * **_shouldExist_** (boolean) whether or not the partition with the specified `number` should exist. If omitted, it defaults to true. If false Ignition will either delete the specified partition or fail, depending on `wipePartitionEntry`. If false `number` must be specified and non-zero and `label`, `start`, `size`, `guid`, and `typeGuid` must all be omitted.
   * **_raid_** (list of objects): the list of RAID arrays to be configured.
     * **name** (string): the name to use for the resulting md device.
     * **level** (string): the redundancy level of the array (e.g. linear, raid1, raid5, etc.).

doc/operator-notes.md

@@ -67,7 +67,7 @@ If tooling is being used to generate Ignition configs, the tooling _should_ gene
 
 The `wipePartitionEntry` and `shouldExist` flags control what Ignition will do when it encounters an existing partition. `wipePartitionEntry` specifies whether Ignition is permitted to delete partition entries in the partition table.  `shouldExist` specifies whether a partition with that number should exist or not (it is invalid to specify a partition should not exist and specify its attributes, such as `size` or `label`).
 
-The following table shows the possible combinations of whether or not a partition with the specified number is present, `shouldExist`, and `wipePartitionEntry`, and the action Ignition will take
+The following table shows the possible combinations of whether or not a partition with the specified number is present, `shouldExist`, and `wipePartitionEntry`, and the action Ignition will take:
 
 | Partition present | shouldExist | wipePartitionEntry | Action Ignition takes
 | ----------------- | ----------- | ------------------ | ---------------------
@@ -81,20 +81,20 @@ The following table shows the possible combinations of whether or not a partitio
 | true              | true        | true               | Check if existing partition matches the specified one, delete existing partition and create specified partition if it does not match
 
 ### Partition Matching
-A partition matches if all of the specified attributes (`label`, `start`, `size`, `uuid`, and `typeGuid`) are the same. Specifying `uuid` or `typeGuid` as an empty string is the same as not specifying them. When 0 is specified for start or size, Ignition checks if the existing partition's start / size match what they would be if all of the partitions specified were to be deleted (if allowed by wipPartitionEntry), then recreated if `shouldExist` is true.
+A partition matches if all of the specified attributes (`label`, `start`, `size`, `uuid`, and `typeGuid`) are the same. Specifying `uuid` or `typeGuid` as an empty string is the same as not specifying them. When 0 is specified for start or size, Ignition checks if the existing partition's start / size match what they would be if all of the partitions specified were to be deleted (if allowed by wipePartitionEntry), then recreated if `shouldExist` is true.
 
 ### Partition number 0
 Specifying `number` as 0 will use the next available partition number. Partition number 0 is disallowed on disks with partitions that specify `shouldExist` as false. If `number` is not specified it will be treated as 0.
 
 ### Partition start 0
-Specifying `start` as 0 will use the starting sector of the largest available block. It will *not* use the first available block large enough.
+Specifying `start` as 0 will use the starting sector of the largest available block. This is not necessarily the first available block large enough.
 
 ### Unspecified partition start
-If `start` is not specified and a partition with the same number exists, it will use the value of the existing partition, unless wipePartitionEntry is set.
-If `start` is not specified and there is no existing partition, or wipePartitionEntry is set, `start` act as if it were set to 0 and use the starting sector of the largest available block.
+If `start` is not specified and a partition with the same number exists, Ignition will use the start of the existing partition, unless wipePartitionEntry is set.
+If `start` is not specified and there is no existing partition, or wipePartitionEntry is set, Ignition will use the starting sector of the largest block, as if `start` were set to 0.
 
 ### Partition size 0
-Specifying `size` as 0 means the partition should span to the end of the largest available block. It will *not* use the size of first available block.
+Specifying `size` as 0 means the partition should span to the end of the largest available block. If the starting sector is not within the largest available block, Ignition will fail.
 
 ### Unspecified partition size
 If `size` is not specified and a partition with the same number exists, it will use the value of the existing partition, unless wipePartitionEntry is set.