OSDOCS-16201-RE: Documented migrating a br-ex interface to NMState

Author: dfitzmau

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

@@ -36,6 +36,16 @@ include::modules/creating-manifest-file-customized-br-ex-bridge.adoc[leveloffset
 // Making disruptive changes to a customized br-ex bridge
 include::modules/making-disruptive-changes-br-ex-bridge.adoc[leveloffset=+1]
 
+// Migrating a configured br-ex bridge to NMState
+include::modules/migrating-br-ex-bridge-nmstate.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../installing_bare_metal/ipi/ipi-install-installation-workflow.adoc#creating-manifest-file-customized-br-ex-bridge_ipi-install-installation-workflow[Installer-provisioned infrastructure: Creating a manifest object that includes a customized `br-ex` bridge]
+
+* xref:../../installing/installing_bare_metal/upi/installing-bare-metal.adoc#creating-manifest-file-customized-br-ex-bridge_installing-bare-metal[User-provisioned infrastructure: Creating a manifest object that includes a customized `br-ex` bridge]
+
 // 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

@@ -81,7 +81,7 @@ endif::postinstall-bare-metal[]
 .Procedure
 
 ifndef::postinstall-bare-metal[]
-. Create a NMState configuration file that has decoded base64 information for your customized `br-ex` bridge network:
+. Create an NMState configuration file and define a customized `br-ex` bridge network configuration in the file:
 +
 .Example of an NMState configuration for a customized `br-ex` bridge network
 [source,yaml]
@@ -182,6 +182,13 @@ If you have a single global configuration specified in an `/etc/nmstate/openshif
         path: /etc/nmstate/openshift/cluster.yml
 # ...
 ----
+
+. Apply the updates from the `MachineConfig` object to your cluster by entering the following command:
++
+[source,terminal]
+----
+$ oc apply -f <machine_config>.yml
+----
 endif::postinstall-bare-metal[]
 
 ifdef::postinstall-bare-metal[]

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

@@ -48,7 +48,7 @@ $ base64 -w0 <nmstate_configuration>.yml <1>
 $ oc apply -f <machine_config>.yml
 ----
 
-. Create a bare `MachineConfig` object but do not make any configuration changes to the file.
+. Create a bare `MachineConfig` object but do not make any configuration changes to the file:
 +
 [source,yaml]
 ----

modules/migrating-br-ex-bridge-nmstate.adoc

@@ -0,0 +1,116 @@
+// Module included in the following assemblies:
+//
+// * installing/installing_bare_metal/bare-metal-postinstallation-configuration.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="migrating-br-ex-bridge-nmstate_{context}"]
+= Migrating a configured br-ex bridge to NMState
+
+If you used the `configure-ovs.sh` shell script to set a `br-ex` bridge during cluster installation, you can migrate the `br-ex` bridge to NMState as a postinstallation task. NMState provides a declarative and idempotent way to handle configuring the `br-ex` bridge.
+
+[NOTE]
+====
+The initial steps in the procedure do not show example configurations. For detailed example configurations that would represent objects to create during cluster installation, see the "Creating a manifest object that includes a customized br-ex bridge" link in the _Additional resources_ section.
+====
+
+After you migrate your configured `br-ex` bridge to NMState, you cannot reverse the operation. This means that you cannot migrate back to the shell script version of the `br-ex` bridge.
+
+[IMPORTANT]
+====
+Misconfiguring any files that form part of the migration operation can cause disruptive changes to your cluster. Reverting these changes might not always be possible. 
+====
+
+.Prerequisties 
+
+* You used the `configure-ovs.sh` shell script to set a `br-ex` bridge for your cluster.
+
+.Procedure
+
+. Create an NMState configuration file for your customized `br-ex` bridge network. In a later step, the `MachineConfig` object saves the NMState configuration file in the `/etc/nmstate/openshift` directory path.
+
+. Use the `cat` command to base64-encode the contents of the NMState configuration file:
++
+[source,terminal]
+----
+$ cat <nmstate_configuration>.yaml | base64
+----
++
+--
+where:
+
+`<nmstate_configuration>`:: Specifies `<nmstate_configuration>` with the name of your NMState resource YAML file.
+--
+
+. Create a `MachineConfig` manifest file and define a customized `br-ex` bridge network configuration in the file. Additionally, ensure that you specify the path to the base64-encoded NMState configuration file so that the contents of this file get embedded in the `MachineConfig` manifest file.
+
+. 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
+----
+
+. 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
+----