openshift · mburke5678 · Jun 22, 2026
diff --git a/machine_configuration/machine-configs-configure.adoc b/machine_configuration/machine-configs-configure.adoc
@@ -7,13 +7,13 @@ include::_attributes/common-attributes.adoc[]
 toc::[]
 
 [role="_abstract"]
-You can use the tasks in this section to create `MachineConfig` objects that modify files, systemd unit files, and other operating system features running on {product-title} nodes. This allows you to perform such tasks such as disabling chronyd, adding kernel arguments, enabling multipathing, and adding {op-system} extensions.
+You can create `MachineConfig` objects that modify files, systemd unit files, and other operating system features running on {product-title} nodes. By using `MachineConfig` objects, you can perform tasks such as disabling chronyd, adding kernel arguments, enabling multipathing, and adding {op-system} extensions.
 
-For more ideas on working with machine configs, see content related to link:https://access.redhat.com/solutions/3868301[updating] SSH authorized keys, xref:../security/container_security/security-container-signature.adoc#security-container-signature[verifying image signatures], link:https://access.redhat.com/solutions/4727321[enabling SCTP], and link:https://access.redhat.com/solutions/5170251[configuring iSCSI initiatornames] for {product-title}.
+For more ideas on working with machine configs, see "How to update ssh keys after installation in OpenShift 4?", "Container image signatures", "Enabling SCTP in Openshift Container Platform 4", and "How to provide custom iSCSI initiatornames for nodes" in the _Additional resources_ section.
 
-{product-title} supports link:https://coreos.github.io/ignition/configuration-v3_5/[Ignition specification version 3.5]. You should base all new machine configs you create going forward on Ignition specification version 3.5. If you are upgrading your {product-title} cluster, any existing machine configs with a previous Ignition specification will be translated automatically to specification version 3.5.
+{product-title} supports Ignition specification version 3.5. For more information, see "Ignition specification version 3.5" in  the _Additional resources_ section. You should base all new machine configs you create going forward on Ignition specification version 3.5. If you are upgrading your {product-title} cluster, any existing machine configs with a previous Ignition specification will be translated automatically to specification version 3.5.
 
-There might be situations where the configuration on a node does not fully match what the currently-applied machine config specifies. This state is called _configuration drift_. The Machine Config Daemon (MCD) regularly checks the nodes for configuration drift. If the MCD detects configuration drift, the MCO marks the node `degraded` until an administrator corrects the node configuration. A degraded node is online and operational, but, it cannot be updated. For more information on configuration drift, see xref:../machine_configuration/index.adoc#machine-config-drift-detection_machine-config-overview[Understanding configuration drift detection].
+There might be situations where the configuration on a node does not fully match what the currently-applied machine config specifies. This state is called _configuration drift_. The Machine Config Daemon (MCD) regularly checks the nodes for configuration drift. If the MCD detects configuration drift, the MCO marks the node `degraded` until an administrator corrects the node configuration. A degraded node is online and operational, but, it cannot be updated. For more information on configuration drift, see "Understanding configuration drift detection" in the _Additional resources_ section.
 
 [TIP]
 ====
@@ -44,6 +44,12 @@ include::modules/machine-config-install-time-configs.adoc[leveloffset=+1]
 [id="additional-resources_{context}"]
 == Additional resources
 
+* link:https://access.redhat.com/solutions/3868301[How to update ssh keys after installation in OpenShift 4? (Red{nbsp}Hat Knowledgebase article)]
+* xref:../security/container_security/security-container-signature.adoc#security-container-signature[Container image signatures]
+* link:https://access.redhat.com/solutions/4727321[Enabling SCTP in {product-title} 4 (Red{nbsp}Hat Knowledgebase article)]
+* link:https://access.redhat.com/solutions/5170251[How to provide custom iSCSI initiatornames for nodes in {product-title} 4.x]
+* link:https://coreos.github.io/ignition/configuration-v3_5/[Ignition specification version 3.5]
+* xref:../machine_configuration/index.adoc#machine-config-drift-detection_machine-config-overview[Understanding configuration drift detection]
 * xref:../installing/install_config/installing-customizing.adoc#installation-special-config-butane_installing-customizing[Creating machine configs with Butane]
 * xref:../installing/installing_bare_metal/upi/installing-bare-metal.adoc#rhcos-enabling-multipath_installing-bare-metal[Enabling multipathing with kernel arguments on RHCOS]
 * xref:../installing/install_config/installing-customizing.adoc#installation-special-config-butane_installing-customizing[Creating machine configs with Butane]

diff --git a/modules/cnf-disable-chronyd.adoc b/modules/cnf-disable-chronyd.adoc
@@ -6,6 +6,7 @@
 [id="cnf-disable-chronyd_{context}"]
 = Disabling the chrony time service
 
+[role="_abstract"]
 You can disable the chrony time service (`chronyd`) for nodes with a specific role by using a `MachineConfig` custom resource (CR).
 
 .Prerequisites
@@ -25,7 +26,7 @@ apiVersion: machineconfiguration.openshift.io/v1
 kind: MachineConfig
 metadata:
   labels:
-    machineconfiguration.openshift.io/role: <node_role> <1>
+    machineconfiguration.openshift.io/role: <node_role>
   name: disable-chronyd
 spec:
   config:
@@ -62,7 +63,9 @@ spec:
             Wants=NetworkManager-wait-online.service crio-wipe.service
             Wants=rpc-statd.service
 ----
-<1> Node role where you want to disable `chronyd`, for example, `master`.
+where:
+
+`metadata.labels`:: Specifies the node role where you want to disable `chronyd`, for example, `master`.
 
 .. Create the `MachineConfig` CR by running the following command:
 +

diff --git a/modules/core-user-password.adoc b/modules/core-user-password.adoc
@@ -6,9 +6,10 @@
 [id="core-user-password_{context}"]
 = Changing the core user password for node access
 
-By default, {op-system-first} creates a user named `core` on the nodes in your cluster. You can use the `core` user to access the node through a cloud provider serial console or a bare metal baseboard controller manager (BMC). This can be helpful, for example, if a node is down and you cannot access that node by using SSH or the `oc debug node` command. However, by default, there is no password for this user, so you cannot log in without creating one.
+[role="_abstract"]
+You can use the default `core` user to access a node through a cloud provider serial console or a bare metal baseboard controller manager (BMC) if a node is down and you cannot access that node by using SSH or the `oc debug node` command.
 
-You can create a password for the `core` user by using a machine config. The Machine Config Operator (MCO) assigns the password and injects the password into the `/etc/shadow` file, allowing you to log in with the `core` user. The MCO does not examine the password hash. As such, the MCO cannot report if there is a problem with the password.
+By default, {op-system-first} creates a user named `core` on the nodes in your cluster. However, there is no password for this user. As such, you cannot log in with this user without creating a password by using a machine config. The Machine Config Operator (MCO) assigns the password and injects the password into the `/etc/shadow` file, allowing you to log in with the `core` user. The MCO does not examine the password hash. As such, the MCO cannot report if there is a problem with the password.
 
 [NOTE]
 ====
@@ -48,11 +49,13 @@ spec:
       version: 3.5.0
     passwd:
       users:
-      - name: core <1>
-        passwordHash: <password> <2>
+      - name: core
+        passwordHash: <password>
 ----
-<1> This must be `core`.
-<2> The hashed password to use with the `core` account.
+where:
+
+`spec.config.passwd.users.name`:: Specifies the user name. This must be `core`.
+`spec.config.passwd.users.passwordHash`:: Specifies the hashed password to use with the `core` account.
 
 . Create the machine config by running the following command:
 +

diff --git a/modules/installation-special-config-chrony.adoc b/modules/installation-special-config-chrony.adoc
@@ -27,6 +27,12 @@ set the time server and related settings used by the chrony time service (`chron
 by modifying the contents of the `chrony.conf` file and passing those contents
 to your nodes as a machine config.
 
+For more information on chrony best practices, see the following resources:
+
+* https://access.redhat.com/solutions/3073261[Configuring chrony]
+* https://access.redhat.com/solutions/778603[Best practices for NTP]
+* https://docs.redhat.com/en/documentation/red_hat_ceph_storage/8/html-single/troubleshooting_guide/basic-chrony-NTP-troubleshooting_diag#basic-chrony-NTP-troubleshooting_diag[Basic chrony NTP troubleshooting]
+
 .Procedure
 
 . Create a Butane config including the contents of the `chrony.conf` file. For example, to configure chrony on worker nodes, create a `99-worker-chrony.bu` file.
@@ -90,12 +96,6 @@ $ butane 99-worker-chrony.bu -o 99-worker-chrony.yaml
 $ oc apply -f ./99-worker-chrony.yaml
 ----
 
-For more information on chrony best practices, see the following resources:
-
-* https://access.redhat.com/solutions/3073261[Configuring chrony]
-* https://access.redhat.com/solutions/778603[Best practices for NTP]
-* https://docs.redhat.com/en/documentation/red_hat_ceph_storage/8/html-single/troubleshooting_guide/basic-chrony-NTP-troubleshooting_diag#basic-chrony-NTP-troubleshooting_diag[Basic chrony NTP troubleshooting]
-
 
 ifeval::["{context}" == "installing-restricted-networks-bare-metal"]
 :!restricted:

diff --git a/modules/machineconfig-modify-journald.adoc b/modules/machineconfig-modify-journald.adoc
@@ -6,7 +6,8 @@
 [id="machineconfig-modify-journald_{context}"]
 = Configuring journald settings
 
-If you need to configure settings for the `journald` service on {product-title} nodes, you can do that by modifying the appropriate configuration file and passing the file to the appropriate pool of nodes as a machine config.
+[role="_abstract"]
+To configure settings for the `journald` service on {product-title} nodes, you can modify the appropriate configuration file and pass the file to the appropriate pool of nodes as a machine config.
 
 This procedure describes how to modify `journald` rate limiting settings in the `/etc/systemd/journald.conf` file and apply them to worker nodes. See the `journald.conf` man page for information on how to use that file.
 

diff --git a/modules/rhcos-add-extensions.adoc b/modules/rhcos-add-extensions.adoc
@@ -7,9 +7,10 @@
 
 = Adding extensions to {op-system}
 
-{op-system} is a minimal container-oriented RHEL operating system, designed to provide a common set of capabilities to {product-title} clusters across all platforms. Although adding software packages to {op-system} systems is generally discouraged, the MCO provides an `extensions` feature you can use to add a minimal set of features to {op-system} nodes.
+[role="_abstract"]
+You can add software packages to {op-system} systems by using extension packages to add a minimal set of features to specific nodes.
 
-Currently, the following extensions are available:
+{op-system} is a minimal container-oriented RHEL operating system, designed to provide a common set of capabilities to {product-title} clusters across all platforms. Although adding software packages to RHCOS systems is generally discouraged, you can add any of the following extensions to extend {op-system}:
 
 * **usbguard**: The `usbguard` extension protects {op-system} systems from attacks by intrusive USB devices. For more information, see link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html-single/security_hardening/index#usbguard_protecting-systems-against-intrusive-usb-devices[USBGuard] for details.
 
@@ -70,7 +71,6 @@ $ oc get machineconfig 80-worker-extensions
 ----
 +
 .Example output
-+
 [source,terminal]
 ----
 NAME                 GENERATEDBYCONTROLLER IGNITIONVERSION AGE
@@ -85,7 +85,6 @@ $ oc get machineconfigpool
 ----
 +
 .Example output
-+
 [source,terminal]
 ----
 NAME   CONFIG             UPDATED UPDATING DEGRADED MACHINECOUNT READYMACHINECOUNT UPDATEDMACHINECOUNT DEGRADEDMACHINECOUNT AGE
@@ -101,7 +100,6 @@ $ oc get node | grep worker
 ----
 +
 .Example output
-+
 [source,terminal]
 ----
 NAME                                        STATUS  ROLES    AGE   VERSION
@@ -114,7 +112,6 @@ $ oc debug node/ip-10-0-169-2.us-east-2.compute.internal
 ----
 +
 .Example output
-+
 [source,terminal]
 ----
 ...

diff --git a/modules/rhcos-enabling-multipath-day-2.adoc b/modules/rhcos-enabling-multipath-day-2.adoc
@@ -6,13 +6,14 @@
 [id="rhcos-enabling-multipath-day-2_{context}"]
 = Enabling multipathing with kernel arguments on {op-system}
 
+[role="_abstract"]
+You can achieve higher host availability by enabling multipathing on the primary disk, which allows stronger resilience to hardware failure, by using a `MachineConfig` object.
+
 [IMPORTANT]
 ====
 Enabling multipathing during installation is supported and recommended for nodes provisioned in {product-title}. In setups where any I/O to non-optimized paths results in I/O system errors, you must enable multipathing at installation time. For more information about enabling multipathing during installation time, see "Enabling multipathing post installation" in the _Installing on bare metal_ documentation.
 ====
 
-{op-system-first} supports multipathing on the primary disk, allowing stronger resilience to hardware failure to achieve higher host availability. Postinstallation support is available by activating multipathing via the machine config.
-
 [IMPORTANT]
 ====
 On {ibm-z-name} and {ibm-linuxone-name}, you can enable multipathing only if you configured your cluster for it during installation. For more information, see "Installing {op-system} and starting the {product-title} bootstrap process" in _Installing a cluster with z/VM on {ibm-z-name} and {ibm-linuxone-name}_.

diff --git a/modules/rhcos-load-firmware-blobs.adoc b/modules/rhcos-load-firmware-blobs.adoc
@@ -6,7 +6,10 @@
 [id="rhcos-load-firmware-blobs_{context}"]
 = Loading custom firmware blobs in the machine config manifest
 
-Because the default location for firmware blobs in `/usr/lib` is read-only, you can locate a custom firmware blob by updating the search path. This enables you to load local firmware blobs in the machine config manifest when the blobs are not managed by {op-system}.
+[role="_abstract"]
+You can load local firmware blobs that are not managed by {op-system} into the machine config manifest by updating the search path.
+
+By default, the location for firmware blobs in `/usr/lib` is read-only.
 
 .Procedure
 
@@ -28,19 +31,20 @@ metadata:
   name: 98-worker-firmware-blob
 storage:
   files:
-  - path: /var/lib/firmware/<package_name> <1>
+  - path: /var/lib/firmware/<package_name>
     contents:
-      local: <package_name> <2>
-    mode: 0644 <3>
+      local: <package_name>
+    mode: 0644
 openshift:
   kernel_arguments:
-    - 'firmware_class.path=/var/lib/firmware' <4>
+    - 'firmware_class.path=/var/lib/firmware'
 ----
-+
-<1> Sets the path on the node where the firmware package is copied to.
-<2> Specifies a file with contents that are read from a local file directory on the system running Butane. The path of the local file is relative to a `files-dir` directory, which must be specified by using the `--files-dir` option with Butane in the following step.
-<3> Sets the permissions for the file on the {op-system} node. It is recommended to set `0644` permissions.
-<4> The `firmware_class.path` parameter customizes the kernel search path of where to look for the custom firmware blob that was copied from your local workstation onto the root file system of the node. This example uses `/var/lib/firmware` as the customized path.
+where:
+
+`storage.files.path`:: Specifies the path on the node where the firmware package is copied to.
+`storage.files.contents.local`:: Specifies a file with contents that are read from a local file directory on the system running Butane. The path of the local file is relative to a `files-dir` directory, which must be specified by using the `--files-dir` option with Butane in the following step.
+`storage.files.mode`:: Specifies the permissions for the file on the {op-system} node. It is recommended to set `0644` permissions.
+`openshift.kernel_arguments`:: Specifies the kernel search path of where to look for the custom firmware blob that was copied from your local workstation onto the root file system of the node. This example uses `/var/lib/firmware` as the customized path.
 
 . Run Butane to generate a `MachineConfig` object file that uses a copy of the firmware blob on your local workstation named `98-worker-firmware-blob.yaml`. The firmware blob contains the configuration to be delivered to the nodes. The following example uses the `--files-dir` option to specify the directory on your workstation where the local file or files are located:
 +