Merge pull request #98143 from dfitzmau/OSDOCS-15899

OSDOCS-15899: Added day-2 docs for making disruptive change to br-ex

Author: dfitzmau

installing/installing_bare_metal/bare-metal-postinstallation-configuration.adoc

@@ -8,7 +8,6 @@ toc::[]
 
 After successfully deploying a bare-metal cluster, consider the following postinstallation procedures.
 
-
 //About the cluster API
 include::modules/bare-metal-about-the-cluster-api.adoc[leveloffset=+1]
 
@@ -34,6 +33,9 @@ include::modules/creating-manifest-file-customized-br-ex-bridge.adoc[leveloffset
 
 * xref:../../installing/installing_bare_metal/bare-metal-expanding-the-cluster.adoc#bare-metal-expanding-the-cluster[Expanding the cluster]
 
+// Making disruptive changes to a customized br-ex bridge
+include::modules/making-disruptive-changes-br-ex-bridge.adoc[leveloffset=+1]
+
 // Services for a user-managed load balancer
 include::modules/nw-osp-services-external-load-balancer.adoc[leveloffset=+1]
 

modules/creating-manifest-file-customized-br-ex-bridge.adoc

@@ -170,7 +170,7 @@ spec:
 <2> Writes the encoded base64 information to the specified path.
 <3> For each node in your cluster, specify the hostname path to your node and the base-64 encoded Ignition configuration file data for the machine type. The `worker` role is the default role for nodes in your cluster. The `.yaml` extension does not work when specifying the short hostname, `hostname -s`, path for each node or all nodes in the `MachineConfig` manifest file.
 +
-Alternatively, if you have a single global configuration specified in an `/etc/nmstate/openshift/cluster.yml` configuration file that you want to apply to all nodes in your cluster, you do not need to specify the short hostname path for each node, such as `/etc/nmstate/openshift/<node_hostname>.yml`. For example:
+If you have a single global configuration specified in an `/etc/nmstate/openshift/cluster.yml` configuration file that you want to apply to all nodes in your cluster, you do not need to specify the short hostname path for each node, such as `/etc/nmstate/openshift/<node_hostname>.yml`. For example:
 +
 [source,yaml]
 ----

modules/making-disruptive-changes-br-ex-bridge.adoc

@@ -0,0 +1,122 @@
+// Module included in the following assemblies:
+//
+// * installing/installing_bare_metal/bare-metal-postinstallation-configuration.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="making-disruptive-changes-br-ex-bridge.adoc_{context}"]
+= Making disruptive changes to a customized br-ex bridge
+
+For certain situations, you might need to make disruptive changes to a `br-ex` bridge for planned maintenance or network configuration updates. A `br-ex` bridge is a gateway for all external network traffic from your workloads, so any change to the bridge might temporarily disconnect pods and virtual machines (VMs) from an external network.
+
+The following procedure uses an example to show making disruptive changes to a `br-ex` bridge that minimizes any impact to running cluster workloads. 
+
+For all the nodes in your cluster to receive the `br-ex` bridge changes, you must reboot your cluster. Editing the existing `MachineConfig` object does not force a reboot operation, so you must create an additional `MachineConfig` object to force a reboot operation for the cluster.
+
+[IMPORTANT]
+====
+Red Hat does not support changing IP addresses for nodes as a postintallation task.
+====
+
+.Prerequisites
+
+* You created a manifest object that includes a `br-ex` bridge. 
+* You deployed your cluster that has the configured `br-ex` bridge.
+
+.Procedure
+
+. Make changes to the NMState configuration file that you created during cluster installation for customizing your `br-ex` bridge network interface.
++
+[IMPORTANT]
+====
+Before you save the `MachineConfig` object, check the changed parameter values. If you enter wrong values and save the file, you cannot recover the file to its original state and this impacts networking functionality for your cluster. 
+====
+
+. Use the `base64` command to re-encode the contents of the NMState configuration by entering the following command:
++
+[source,terminal]
+----
+$ base64 -w0 <nmstate_configuration>.yml <1>
+----
+<1> Replace `<nmstate_configuration>` with the name of your NMState resource YAML file.
+
+. Update the `MachineConfig` manifest file that you created during cluster installation and re-define the customized `br-ex` bridge network interface. 
+
+. Apply the updates from the `MachineConfig` object to your cluster by entering the following command:
++
+[source,terminal]
+----
+$ oc apply -f <machine_config>.yml
+----
+
+. Create a bare `MachineConfig` object but do not make any configuration changes to the file.
++
+[source,yaml]
+----
+apiVersion: machineconfiguration.openshift.io/v1
+kind: MachineConfig
+metadata:
+  labels:
+    machineconfiguration.openshift.io/role: master
+  name: 10-force-reboot-master
+spec:
+  config:
+    ignition:
+      version: 3.2.0
+    storage:
+      files:
+      - contents:
+          source: data:text/plain;charset=utf-8;base64,
+        mode: 0644
+        overwrite: true
+        path: /etc/force-reboot
+---
+apiVersion: machineconfiguration.openshift.io/v1
+kind: MachineConfig
+metadata:
+  labels:
+    machineconfiguration.openshift.io/role: worker
+  name: 10-force-reboot-worker
+spec:
+  config:
+    ignition:
+      version: 3.2.0
+    storage:
+      files:
+      - contents:
+          source: data:text/plain;charset=utf-8;base64,
+        mode: 0644
+        overwrite: true
+        path: /etc/force-reboot
+# ...
+----
+
+. Start a reboot operation by applying the bare `MachineConfig` object configuration to your cluster by entering the following command:
++
+[source,terminal]
+----
+$ oc apply -f <bare_machine_config>.yml
+----
+
+. Check that each node in your cluster has the `Ready` status to indicate that they have finished rebooting by entering the following command: 
++
+[source,terminal]
+----
+$ oc get nodes
+----
+
+. Delete the bare `MachineConfig` object by entering the following command:
++
+[source,terminal]
+----
+$ oc delete machineconfig <machine_config_name>
+----
+
+.Verification
+
+* Use the `nmstatectl` tool to check the configuration for the `br-ex` bridge interface by running the following command. The tool checks a node that runs the `br-ex` bridge interface and not the location where you deployed the `MachineConfig` objects.
++
+[source,terminal]
+----
+$ sudo nmstatectl show br-ex
+----
+