Bug 1926260: Use Butane to create config for separate /var partition

bgilbert · bgilbert · commit 91a063ef8d16 · 2021-10-26T17:48:09.000-04:00
Users were customizing the example config and failing to rename the mount unit to match the new mountpoint, causing the mount to fail. Preprocess the config with Butane and have it automatically generate the mount unit so we don't need to explicitly define the unit at all. In the process, revert and redo commit 897ae24. The original commit has a few issues: - It adds a long Prerequisites section which almost entirely duplicates the config in the Procedure section, with the lines in a different order, solely to add the pquota mount option. This doesn't narratively make sense as a prerequisite. - It references mounting filesystems via /etc/fstab, which we don't generally document or recommend. - It references adding rootflags=pquota if container storage is kept on the root filesystem, in order to mount the root filesystem with the prjquota option. This a) isn't relevant to adding a /var mountpoint and b) is the default. - It removes the note about configs encoding a dependency on the device node name for the disk containing additional partitions, which is still the case at present. We do need the prjquota option for container storage, but we can document that fact much more concisely.
diff --git a/modules/installation-disk-partitioning-upi-templates.adoc b/modules/installation-disk-partitioning-upi-templates.adoc
@@ -29,58 +29,13 @@ It is recommended that disk partitioning for {product-title} be left to the inst
 
 Storing the contents of a `/var` directory separately makes it easier to grow storage for those areas as needed and reinstall {product-title} at a later date and keep that data intact. With this method, you will not have to pull all your containers again, nor will you have to copy massive log files when you update systems.
 
-Because `/var` must be in place before a fresh installation of {op-system-first}, the following procedure sets up the separate `/var` partition by creating a machine config that is inserted during the `openshift-install` preparation phases of an {product-title} installation.
+Because `/var` must be in place before a fresh installation of {op-system-first}, the following procedure sets up the separate `/var` partition by creating a machine config manifest that is inserted during the `openshift-install` preparation phases of an {product-title} installation.
 
 [IMPORTANT]
 ====
 If you follow the steps to create a separate `/var` partition in this procedure, it is not necessary to create the Kubernetes manifest and Ignition config files again as described later in this section.
 ====
 
-.Prerequisites
-
-* If container storage is on the root partition, ensure that this root partition is mounted with the `pquota` option by including `rootflags=pquota` in the GRUB command line.
-
-* If the container storage is on a partition that is mounted by `/etc/fstab`, ensure that the following mount option is included in the `/etc/fstab` file:
-+
-[source,terminal]
-----
-/dev/sdb1      /var           xfs defaults,pquota 0 0
-----
-
-* If the container storage is on a partition that is mounted by `systemd`, ensure that the `MachineConfig` object includes the following mount option as in this example:
-+
-[source,yaml]
-----
-spec:
-  config:
-    ignition:
-      version: 3.2.0
-    storage:
-      disks:
-        - device: /dev/sdb
-          partitions:
-            - label: var
-              sizeMiB: 240000
-              startMiB: 0
-      filesystems:
-        - device: /dev/disk/by-partlabel/var
-          format: xfs
-          path: /var
-    systemd:
-      units:
-        - contents: |
-            [Unit]
-            Before=local-fs.target
-            [Mount]
-            Where=/var
-            What=/dev/disk/by-partlabel/var
-            Options=defaults,pquota
-            [Install]
-            WantedBy=local-fs.target
-          enabled: true
-          name: var.mount
-----
-
 .Procedure
 
 . Create a directory to hold the {product-title} installation files:
@@ -125,48 +80,47 @@ $ ls $HOME/clusterconfig/openshift/
 ...
 ----
 
-. Create a `MachineConfig` object and add it to a file in the `openshift` directory. For example, name the file `98-var-partition.yaml`, change the disk device name to the name of the storage device on the `worker` systems, and set the storage size as appropriate. This attaches storage to a separate `/var` directory.
-
+. Create a Butane config that configures the additional partition. For example, name the file `$HOME/clusterconfig/98-var-partition.bu`, change the disk device name to the name of the storage device on the `worker` systems, and set the storage size as appropriate. This example places the `/var` directory on a separate partition:
 +
 [source,yaml]
 ----
-apiVersion: machineconfiguration.openshift.io/v1
-kind: MachineConfig
+variant: openshift
+version: 4.9.0
 metadata:
   labels:
     machineconfiguration.openshift.io/role: worker
   name: 98-var-partition
-spec:
-  config:
-    ignition:
-      version: 3.2.0
-    storage:
-      disks:
-      - device: /dev/<device_name> <1>
-        partitions:
-        - sizeMiB: <partition_size>
-          startMiB: <partition_start_offset> <2>
-          label: var
-      filesystems:
-        - path: /var
-          device: /dev/disk/by-partlabel/var
-          format: xfs
-    systemd:
-      units:
-        - name: var.mount
-          enabled: true
-          contents: |
-            [Unit]
-            Before=local-fs.target
-            [Mount]
-            Where=/var
-            What=/dev/disk/by-partlabel/var
-            [Install]
-            WantedBy=local-fs.target
+storage:
+  disks:
+  - device: /dev/<device_name> <1>
+    partitions:
+    - label: var
+      start_mib: <partition_start_offset> <2>
+      size_mib: <partition_size> <3>
+  filesystems:
+    - device: /dev/disk/by-partlabel/var
+      path: /var
+      format: xfs
+      mount_options: [defaults, prjquota] <4>
+      with_mount_unit: true
 ----
 +
 <1> The storage device name of the disk that you want to partition.
 <2> When adding a data partition to the boot disk, a minimum value of 25000 MiB (Mebibytes) is recommended. The root file system is automatically resized to fill all available space up to the specified offset. If no value is specified, or if the specified value is smaller than the recommended minimum, the resulting root file system will be too small, and future reinstalls of {op-system} might overwrite the beginning of the data partition.
+<3> The size of the data partition in mebibytes.
+<4> The `prjquota` mount option must be enabled for filesystems used for container storage.
++
+[NOTE]
+====
+When creating a separate `/var` partition, you cannot use different instance types for worker nodes, if the different instance types do not have the same device name.
+====
+
+. Create a manifest from the Butane config and save it to the `clusterconfig/openshift` directory. For example, run the following command:
++
+[source,terminal]
+----
+$ butane $HOME/clusterconfig/98-var-partition.bu -o $HOME/clusterconfig/openshift/98-var-partition.yaml
+----
 
 . Run `openshift-install` again to create Ignition configs from a set of files in the `manifest` and `openshift` subdirectories:
 +
diff --git a/modules/installation-disk-partitioning.adoc b/modules/installation-disk-partitioning.adoc
@@ -45,54 +45,9 @@ Storing the contents of a `/var` directory separately makes it easier to grow st
 
 Because `/var` must be in place before a fresh installation of
 {op-system-first}, the following procedure sets up the separate `/var` partition
-by creating a machine config that is inserted during the `openshift-install`
+by creating a machine config manifest that is inserted during the `openshift-install`
 preparation phases of an {product-title} installation.
 
-.Prerequisites
-
-* If container storage is on the root partition, ensure that this root partition is mounted with the `pquota` option by including `rootflags=pquota` in the GRUB command line.
-
-* If the container storage is on a partition that is mounted by `/etc/fstab`, ensure that the following mount option is included in the `/etc/fstab` file:
-+
-[source,terminal]
-----
-/dev/sdb1      /var           xfs defaults,pquota 0 0
-----
-
-* If the container storage is on a partition that is mounted by `systemd`, ensure that the `MachineConfig` object includes the following mount option as in this example:
-+
-[source,yaml]
-----
-spec:
-  config:
-    ignition:
-      version: 3.2.0
-    storage:
-      disks:
-        - device: /dev/sdb
-          partitions:
-            - label: var
-              sizeMiB: 240000
-              startMiB: 0
-      filesystems:
-        - device: /dev/disk/by-partlabel/var
-          format: xfs
-          path: /var
-    systemd:
-      units:
-        - contents: |
-            [Unit]
-            Before=local-fs.target
-            [Mount]
-            Where=/var
-            What=/dev/disk/by-partlabel/var
-            Options=defaults,pquota
-            [Install]
-            WantedBy=local-fs.target
-          enabled: true
-          name: var.mount
-----
-
 .Procedure
 
 . Create a directory to hold the {product-title} installation files:
@@ -117,50 +72,47 @@ $ ls $HOME/clusterconfig/openshift/
 ...
 ----
 
-. Create a `MachineConfig` object and add it to a file in the `openshift` directory.
-For example, name the file `98-var-partition.yaml`, change the disk device name to the name of the storage device on the `worker` systems, and set the storage size as appropriate. This attaches storage to a separate `/var`
-directory.
-
+. Create a Butane config that configures the additional partition. For example, name the file `$HOME/clusterconfig/98-var-partition.bu`, change the disk device name to the name of the storage device on the `worker` systems, and set the storage size as appropriate. This example places the `/var` directory on a separate partition:
 +
 [source,yaml]
 ----
-apiVersion: machineconfiguration.openshift.io/v1
-kind: MachineConfig
+variant: openshift
+version: 4.9.0
 metadata:
   labels:
     machineconfiguration.openshift.io/role: worker
   name: 98-var-partition
-spec:
-  config:
-    ignition:
-      version: 3.2.0
-    storage:
-      disks:
-      - device: /dev/<device_name> <1>
-        partitions:
-        - sizeMiB: <partition_size>
-          startMiB: <partition_start_offset> <2>
-          label: var
-      filesystems:
-        - path: /var
-          device: /dev/disk/by-partlabel/var
-          format: xfs
-    systemd:
-      units:
-        - name: var.mount
-          enabled: true
-          contents: |
-            [Unit]
-            Before=local-fs.target
-            [Mount]
-            Where=/var
-            What=/dev/disk/by-partlabel/var
-            [Install]
-            WantedBy=local-fs.target
+storage:
+  disks:
+  - device: /dev/<device_name> <1>
+    partitions:
+    - label: var
+      start_mib: <partition_start_offset> <2>
+      size_mib: <partition_size> <3>
+  filesystems:
+    - device: /dev/disk/by-partlabel/var
+      path: /var
+      format: xfs
+      mount_options: [defaults, prjquota] <4>
+      with_mount_unit: true
 ----
 +
 <1> The storage device name of the disk that you want to partition.
 <2> When adding a data partition to the boot disk, a minimum value of 25000 mebibytes is recommended. The root file system is automatically resized to fill all available space up to the specified offset. If no value is specified, or if the specified value is smaller than the recommended minimum, the resulting root file system will be too small, and future reinstalls of {op-system} might overwrite the beginning of the data partition.
+<3> The size of the data partition in mebibytes.
+<4> The `prjquota` mount option must be enabled for filesystems used for container storage.
++
+[NOTE]
+====
+When creating a separate `/var` partition, you cannot use different instance types for worker nodes, if the different instance types do not have the same device name.
+====
+
+. Create a manifest from the Butane config and save it to the `clusterconfig/openshift` directory. For example, run the following command:
++
+[source,terminal]
+----
+$ butane $HOME/clusterconfig/98-var-partition.bu -o $HOME/clusterconfig/openshift/98-var-partition.yaml
+----
 
 . Run `openshift-install` again to create Ignition configs from a set of files in the `manifest` and `openshift` subdirectories:
 +
diff --git a/modules/installation-user-infra-machines-advanced.adoc b/modules/installation-user-infra-machines-advanced.adoc
@@ -104,7 +104,7 @@ Storing the contents of a `/var` directory separately makes it easier to grow st
 
 The use of a separate partition for the `/var` directory or a subdirectory of `/var` also prevents data growth in the partitioned directory from filling up the root file system.
 
-The following procedure sets up a separate `/var` partition by adding a `MachineConfig` object that is wrapped into the Ignition config file for a node type during the preparation phase of an installation.
+The following procedure sets up a separate `/var` partition by adding a machine config manifest that is wrapped into the Ignition config file for a node type during the preparation phase of an installation.
 
 .Procedure
 
@@ -115,57 +115,48 @@ The following procedure sets up a separate `/var` partition by adding a `Machine
 $ openshift-install create manifests --dir=<installation_directory>
 ----
 
-. Create a `MachineConfig` object and add it to a file in the `./<installation_directory>/openshift` directory.
-For example, name the file `98-var-partition.yaml`,
-change the disk device name to the name of the storage device on the compute nodes,
-and set the storage size as appropriate. This example mounts the `/var` directory on a separate partition:
-
+. Create a Butane config that configures the additional partition. For example, name the file `$HOME/clusterconfig/98-var-partition.bu`, change the disk device name to the name of the storage device on the `worker` systems, and set the storage size as appropriate. This example places the `/var` directory on a separate partition:
 +
 [source,yaml]
 ----
-apiVersion: machineconfiguration.openshift.io/v1
-kind: MachineConfig
+variant: openshift
+version: 4.9.0
 metadata:
   labels:
     machineconfiguration.openshift.io/role: worker
   name: 98-var-partition
-spec:
-  config:
-    ignition:
-      version: 3.2.0
-    storage:
-      disks:
-      - device: /dev/<device_name> <1>
-        partitions:
-        - sizeMiB: <partition_size> <2>
-          startMiB: <partition_start_offset> <3>
-          label: var
-      filesystems:
-        - path: /var
-          device: /dev/disk/by-partlabel/var
-          format: xfs
-    systemd:
-      units:
-        - name: var.mount
-          enabled: true
-          contents: |
-            [Unit]
-            Before=local-fs.target
-            [Mount]
-            Where=/var
-            What=/dev/disk/by-partlabel/var
-            [Install]
-            WantedBy=local-fs.target
+storage:
+  disks:
+  - device: /dev/<device_name> <1>
+    partitions:
+    - label: var
+      start_mib: <partition_start_offset> <2>
+      size_mib: <partition_size> <3>
+  filesystems:
+    - device: /dev/disk/by-partlabel/var
+      path: /var
+      format: xfs
+      mount_options: [defaults, prjquota] <4>
+      with_mount_unit: true
 ----
 +
 <1> The storage device name of the disk that you want to partition.
-<2> The size of the data partition in mebibytes.
-<3> When adding a data partition to the boot disk, a minimum offset value of 25000 mebibytes is recommended. The root file system is automatically resized to fill all available space up to the specified offset. If no offset value is specified, or if the specified value is smaller than the recommended minimum, the resulting root file system will be too small, and future reinstalls of {op-system} might overwrite the beginning of the data partition.
+<2> When adding a data partition to the boot disk, a minimum offset value of 25000 mebibytes is recommended. The root file system is automatically resized to fill all available space up to the specified offset. If no offset value is specified, or if the specified value is smaller than the recommended minimum, the resulting root file system will be too small, and future reinstalls of {op-system} might overwrite the beginning of the data partition.
+<3> The size of the data partition in mebibytes.
+<4> The `prjquota` mount option must be enabled for filesystems used for container storage.
 +
 [NOTE]
 ====
 When creating a separate `/var` partition, you cannot use different instance types for compute nodes, if the different instance types do not have the same device name.
 ====
+
+. Create a manifest from the Butane config and save it to the `clusterconfig/openshift` directory. For example, run the following command:
++
+[source,terminal]
+----
+$ butane $HOME/clusterconfig/98-var-partition.bu -o $HOME/clusterconfig/openshift/98-var-partition.yaml
+----
+
 . Create the Ignition config files:
 +
 [source,terminal]
