Document MCO drain behavior

Author: Michael Burke

machine_configuration/index.adoc

@@ -23,12 +23,22 @@ Previously, NetworkManager stored new network configurations to `/etc/sysconfig/
 
 include::modules/understanding-machine-config-operator.adoc[leveloffset=+1]
 
+[role="_additional-resources"]
 .Additional resources
 
 * xref:../networking/openshift_sdn/about-openshift-sdn.adoc#about-openshift-sdn[About the OpenShift SDN network plugin]
 
 include::modules/machine-config-overview.adoc[leveloffset=+1]
 
+include::modules/machine-config-node-drain.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../machine_configuration/index.adoc#about-machine-config-operator_machine-config-overview[About the Machine Config Operator]
+* xref:../machine_configuration/machine-config-node-disruption.adoc#machine-configs-configure[Using node disruption policies to minimize disruption from machine config changes]
+* xref:../support/troubleshooting/troubleshooting-operator-issues.adoc#troubleshooting-disabling-autoreboot-mco_troubleshooting-operator-issues[Disabling the Machine Config Operator from automatically rebooting]
+
 include::modules/machine-config-drift-detection.adoc[leveloffset=+1]
 
 include::modules/checking-mco-status.adoc[leveloffset=+1]

modules/machine-config-node-drain.adoc

@@ -0,0 +1,32 @@
+// Module included in the following assemblies:
+//
+// * machine-configuration/index.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="machine-config-node-drain_{context}"]
+= Understanding the Machine Config Operator node drain behavior
+
+When you use a machine config to change a system feature, such as adding new config files, modifying systemd units or kernel arguments, or updating SSH keys, the Machine Config Operator (MCO) applies those changes and ensures that each node is in the desired configuration state.
+
+After you make the changes, the MCO generates a new rendered machine config. In the majority of cases, when applying the new rendered machine config, the Operator performs the following steps on each affected node until all of the affected nodes have the updated configuration:
+
+. Cordon. The MCO marks the node as not schedulable for additional workloads.
+. Drain. The MCO terminates all running workloads on the node, causing the workloads to be rescheduled onto other nodes.
+. Apply. The MCO writes the new configuration to the nodes as needed.
+. Reboot. The MCO restarts the node.
+. Uncordon. The MCO marks the node as schedulable for workloads.
+
+Throughout this process, the MCO maintains the required number of pods based on the `MaxUnavailable` value set in the machine config pool.
+
+If the MCO drains pods on the master node, note the following conditions:
+
+* In {sno} clusters, the MCO skips the drain operation.
+
+* The MCO does not drain static pods in order to prevent interference with services, such as etcd.
+
+[NOTE]
+====
+In certain cases the nodes are not drained. For more information, see "About the Machine Config Operator."
+====
+
+There are ways to mitigate the disruption caused by drain and reboot cycles by using node disruption policies or disabling control plane reboots. For more information, see "Understanding node restart behaviors after machine config changes" and "Disabling the Machine Config Operator from automatically rebooting."