Add 'Updating the boot loader on RHCOS nodes using bootupd' to update section

travier · travier · commit ab31fceeed52 · 2024-02-14T12:39:14.000+01:00
- Fix issues with the bootupd section: Correct terms, commands and details regarding how `bootupd` works. - Use a Butane config to generate the MachineConfig. - Moves the boot loader update content to a dedicated page in the update section and removes it from the installation pages. Fixes: #71172
diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml
@@ -695,6 +695,12 @@ Topics:
     File: migrating-to-multi-payload
   - Name: Updating hosted control planes
     File: updating-hosted-control-planes
+  - Name: Updating the boot loader on Red Hat Enterprise Linux CoreOS nodes using bootupd
+    File: updating-bootloader-rhcos
+    Distros: openshift-enterprise
+  - Name: Updating the boot loader on Fedora CoreOS nodes using bootupd
+    File: updating-bootloader-rhcos
+    Distros: openshift-origin
 - Name: Troubleshooting a cluster update
   Dir: troubleshooting_updates
   Distros: openshift-enterprise,openshift-origin
diff --git a/installing/installing_bare_metal/installing-bare-metal-network-customizations.adoc b/installing/installing_bare_metal/installing-bare-metal-network-customizations.adoc
@@ -160,8 +160,6 @@ include::modules/installation-user-infra-machines-static-network.adoc[leveloffse
 
 include::modules/rhcos-enabling-multipath.adoc[leveloffset=+2]
 
-include::modules/architecture-rhcos-updating-bootloader.adoc[leveloffset=+2]
-
 include::modules/installation-installing-bare-metal.adoc[leveloffset=+1]
 
 [role="_additional-resources"]
diff --git a/installing/installing_bare_metal/installing-bare-metal.adoc b/installing/installing_bare_metal/installing-bare-metal.adoc
@@ -193,8 +193,6 @@ include::modules/rhcos-enabling-multipath.adoc[leveloffset=+2]
 
 * See xref:../../installing/installing_bare_metal/installing-bare-metal.adoc#creating-machines-bare-metal_installing-bare-metal[Installing {op-system} and starting the {product-title} bootstrap process] for more information on using special `coreos.inst.*` arguments to direct the live installer.
 
-include::modules/architecture-rhcos-updating-bootloader.adoc[leveloffset=+2]
-
 include::modules/installation-installing-bare-metal.adoc[leveloffset=+1]
 
 [role="_additional-resources"]
diff --git a/installing/installing_bare_metal/installing-restricted-networks-bare-metal.adoc b/installing/installing_bare_metal/installing-restricted-networks-bare-metal.adoc
@@ -181,8 +181,6 @@ include::modules/installation-user-infra-machines-static-network.adoc[leveloffse
 
 include::modules/rhcos-enabling-multipath.adoc[leveloffset=+2]
 
-include::modules/architecture-rhcos-updating-bootloader.adoc[leveloffset=+2]
-
 include::modules/installation-installing-bare-metal.adoc[leveloffset=+1]
 
 [role="_additional-resources"]
diff --git a/installing/installing_platform_agnostic/installing-platform-agnostic.adoc b/installing/installing_platform_agnostic/installing-platform-agnostic.adoc
@@ -80,8 +80,6 @@ include::modules/installation-user-infra-machines-advanced.adoc[leveloffset=+2]
 
 include::modules/installation-user-infra-machines-static-network.adoc[leveloffset=+3]
 
-include::modules/architecture-rhcos-updating-bootloader.adoc[leveloffset=+2]
-
 include::modules/installation-installing-bare-metal.adoc[leveloffset=+1]
 
 include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1]
diff --git a/installing/installing_vmc/installing-restricted-networks-vmc-user-infra.adoc b/installing/installing_vmc/installing-restricted-networks-vmc-user-infra.adoc
@@ -113,8 +113,6 @@ include::modules/machine-vsphere-machines.adoc[leveloffset=+1]
 
 include::modules/installation-disk-partitioning.adoc[leveloffset=+1]
 
-include::modules/architecture-rhcos-updating-bootloader.adoc[leveloffset=+1]
-
 include::modules/installation-installing-bare-metal.adoc[leveloffset=+1]
 
 include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1]
diff --git a/installing/installing_vmc/installing-vmc-network-customizations-user-infra.adoc b/installing/installing_vmc/installing-vmc-network-customizations-user-infra.adoc
@@ -102,8 +102,6 @@ include::modules/machine-vsphere-machines.adoc[leveloffset=+1]
 
 include::modules/installation-disk-partitioning.adoc[leveloffset=+1]
 
-include::modules/architecture-rhcos-updating-bootloader.adoc[leveloffset=+1]
-
 include::modules/installation-installing-bare-metal.adoc[leveloffset=+1]
 
 include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1]
diff --git a/installing/installing_vmc/installing-vmc-user-infra.adoc b/installing/installing_vmc/installing-vmc-user-infra.adoc
@@ -103,8 +103,6 @@ include::modules/machine-vsphere-machines.adoc[leveloffset=+1]
 
 include::modules/installation-disk-partitioning.adoc[leveloffset=+1]
 
-include::modules/architecture-rhcos-updating-bootloader.adoc[leveloffset=+1]
-
 include::modules/cli-installing-cli.adoc[leveloffset=+1]
 
 include::modules/installation-installing-bare-metal.adoc[leveloffset=+1]
diff --git a/installing/installing_vsphere/upi/installing-restricted-networks-vsphere.adoc b/installing/installing_vsphere/upi/installing-restricted-networks-vsphere.adoc
@@ -86,8 +86,6 @@ include::modules/machine-vsphere-machines.adoc[leveloffset=+1]
 
 include::modules/installation-disk-partitioning.adoc[leveloffset=+1]
 
-include::modules/architecture-rhcos-updating-bootloader.adoc[leveloffset=+1]
-
 include::modules/installation-installing-bare-metal.adoc[leveloffset=+1]
 
 include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1]
diff --git a/installing/installing_vsphere/upi/installing-vsphere-network-customizations.adoc b/installing/installing_vsphere/upi/installing-vsphere-network-customizations.adoc
@@ -75,8 +75,6 @@ include::modules/machine-vsphere-machines.adoc[leveloffset=+1]
 
 include::modules/installation-disk-partitioning.adoc[leveloffset=+1]
 
-include::modules/architecture-rhcos-updating-bootloader.adoc[leveloffset=+1]
-
 include::modules/installation-installing-bare-metal.adoc[leveloffset=+1]
 
 include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1]
diff --git a/installing/installing_vsphere/upi/installing-vsphere.adoc b/installing/installing_vsphere/upi/installing-vsphere.adoc
@@ -72,8 +72,6 @@ include::modules/machine-vsphere-machines.adoc[leveloffset=+1]
 
 include::modules/installation-disk-partitioning.adoc[leveloffset=+1]
 
-include::modules/architecture-rhcos-updating-bootloader.adoc[leveloffset=+1]
-
 include::modules/installation-installing-bare-metal.adoc[leveloffset=+1]
 
 include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1]
diff --git a/modules/architecture-rhcos-updating-bootloader.adoc b/modules/architecture-rhcos-updating-bootloader.adoc
diff --git a/updating/updating_a_cluster/updating-bootloader-rhcos.adoc b/updating/updating_a_cluster/updating-bootloader-rhcos.adoc
@@ -0,0 +1,138 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="updating-bootloader-rhcos"]
+= Updating the boot loader on {op-system} nodes using bootupd
+include::_attributes/common-attributes.adoc[]
+:context: updating-booloader-rhcos
+
+toc::[]
+
+To update the boot loader on {op-system} nodes using `bootupd`, you must either run the `bootupctl update` command on {op-system} machines manually or provide a machine config with a `systemd` unit.
+
+Unlike `grubby` or other boot loader tools, `bootupd` does not manage kernel space configuration such as passing kernel arguments.
+To configure kernel arguments, see xref:../../nodes/nodes/nodes-nodes-managing.adoc#nodes-nodes-kernel-arguments_nodes-nodes-managing[Adding kernel arguments to nodes].
+
+[NOTE]
+====
+You can use `bootupd` to update the boot loader to protect against the BootHole vulnerability.
+====
+
+== Updating the boot loader manually
+
+You can manually inspect the status of the system and update the boot loader by using the `bootupctl` command-line tool.
+
+. Inspect the system status:
++
+[source,terminal]
+----
+# bootupctl status
+----
++
+.Example output for `x86_64`
+[source,terminal]
+----
+Component EFI
+  Installed: grub2-efi-x64-1:2.04-31.el8_4.1.x86_64,shim-x64-15-8.el8_1.x86_64
+  Update: At latest version
+----
+ifndef::openshift-origin[]
++
+.Example output for `aarch64`
+[source,terminal]
+----
+Component EFI
+  Installed: grub2-efi-aa64-1:2.02-99.el8_4.1.aarch64,shim-aa64-15.4-2.el8_1.aarch64
+  Update: At latest version
+----
+endif::openshift-origin[]
+
+[start=2]
+. {product-title} clusters initially installed on version 4.4 and older require an explicit adoption phase.
++
+If the system status is `Adoptable`, perform the adoption:
++
+[source,terminal]
+----
+# bootupctl adopt-and-update
+----
++
+.Example output
+[source,terminal]
+----
+Updated: grub2-efi-x64-1:2.04-31.el8_4.1.x86_64,shim-x64-15-8.el8_1.x86_64
+----
+
+. If an update is available, apply the update so that the changes take effect on the next reboot:
++
+[source,terminal]
+----
+# bootupctl update
+----
++
+.Example output
+[source,terminal]
+----
+Updated: grub2-efi-x64-1:2.04-31.el8_4.1.x86_64,shim-x64-15-8.el8_1.x86_64
+----
+
+== Updating the bootloader automatically via a machine config
+
+Another way to automatically update the boot loader with `bootupd` is to create a systemd service unit that will update the boot loader as needed on every boot.
+This unit will run the `bootupctl update` command during the boot process and will be installed on the nodes via a machine config.
+
+[NOTE]
+====
+This configuration is not enabled by default as unexpected interruptions of the update operation may lead to unbootable nodes.
+If you enable this configuration, make sure to avoid interrupting nodes during the boot process while the bootloader update is in progress.
+The boot loader update operation generally completes quickly thus the risk is low.
+====
+
+. Create a Butane config file, `99-worker-bootupctl-update.bu`, including the contents of the `bootupctl-update.service` systemd unit.
++
+[NOTE]
+====
+See "Creating machine configs with Butane" for information about Butane.
+====
++
+.Example output
+[source,yaml,subs="attributes+"]
+----
+variant: openshift
+version: {product-version}.0
+metadata:
+  name: 99-worker-chrony <1>
+  labels:
+    machineconfiguration.openshift.io/role: worker <1>
+systemd:
+  units:
+  - name: bootupctl-update.service
+    enabled: true
+    contents: |
+      [Unit]
+      Description=Bootupd automatic update
+
+      [Service]
+      ExecStart=/usr/bin/bootupctl update
+      RemainAfterExit=yes
+
+      [Install]
+      WantedBy=multi-user.target
+----
+<1> On control plane nodes, substitute `master` for `worker` in both of these locations.
+
+. Use Butane to generate a `MachineConfig` object file, `99-worker-bootupctl-update.yaml`, containing the configuration to be delivered to the nodes:
++
+[source,terminal]
+----
+$ butane 99-worker-bootupctl-update.bu -o 99-worker-bootupctl-update.yaml
+----
+
+. Apply the configurations in one of two ways:
++
+* If the cluster is not running yet, after you generate manifest files, add the `MachineConfig` object file to the `<installation_directory>/openshift` directory, and then continue to create the cluster.
++
+* If the cluster is already running, apply the file:
++
+[source,terminal]
+----
+$ oc apply -f ./99-worker-bootupctl-update.yaml
+----
