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 that has decoded base64 information for your customized `br-ex` bridge network:
 +
 .Example of an NMState configuration for a customized `br-ex` bridge network
 [source,yaml]

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

@@ -0,0 +1,71 @@
+// 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 that has decoded base64 information for your customized `br-ex` bridge network.
+
+. Create a `MachineConfig` manifest file that has decoded base64 information and define a customized `br-ex` bridge network configuration in the file.
+
+. Use the `cat` command to base64-encode the contents of the `MachineConfig` manifest file:
++
+[source,terminal]
+----
+$ cat <machine_config>.yaml | base64 <1>
+----
+<1> Replace `<machine_config>` with the name of your NMState resource YAML 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.
+
+. 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
+----