From fdb1b41cf759304b87c0ead001971030c5e20bd9 Mon Sep 17 00:00:00 2001
From: Tahlia Richardson <3069029+tahliar@users.noreply.github.com>
Date: Thu, 15 Aug 2024 15:50:47 +1000
Subject: [PATCH] Improve the DRBD workflow to be easier to follow

jsc#DOCTEAM-976
---
 xml/ha_drbd.xml | 140 +++++++++++++++++++++++++++++-------------------
 1 file changed, 86 insertions(+), 54 deletions(-)

diff --git a/xml/ha_drbd.xml b/xml/ha_drbd.xml
index 5111712a..7c144ba4 100644
--- a/xml/ha_drbd.xml
+++ b/xml/ha_drbd.xml
@@ -166,7 +166,7 @@ NAME       SIZELIMIT OFFSET AUTOCLEAR RO BACK-FILE
   </para>
  </sect1>
  <sect1 xml:id="sec-ha-drbd-configure">
-  <title>Setting up DRBD service</title>
+  <title>Setting up the DRBD service</title>
   <note>
    <title>Adjustments needed</title>
    <para>
@@ -179,15 +179,57 @@ NAME       SIZELIMIT OFFSET AUTOCLEAR RO BACK-FILE
   </note>
 
   <para>
-   The following sections assumes you have two nodes, &node1;
-   and &node2;, and that they should use the TCP port <literal>7788</literal>.
+   The following sections assume that the cluster nodes use the TCP port <literal>7788</literal>.
    Make sure this port is open in your firewall.
   </para>
 
-  <procedure>
-    <step>
-      <para>Prepare your system:</para>
-      <substeps>
+  <orderedlist>
+    <title>Procedure overview</title>
+    <para>
+      To set up DRBD, perform the following procedures:
+    </para>
+    <listitem>
+      <para>
+        <xref linkend="sec-ha-drbd-prepare"/>
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+         Configure DRBD using one of the following methods:
+      </para>
+      <itemizedlist>
+        <listitem>
+          <para>
+            <xref linkend="sec-ha-drbd-configure-manually"/>
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            <xref linkend="sec-ha-drbd-configure-yast"/>
+          </para>
+        </listitem>
+      </itemizedlist>
+    </listitem>
+    <listitem>
+      <para>
+        <xref linkend="sec-ha-drbd-configure-init"/>
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        <xref linkend="sec-ha-drbd-configure-cluster-resource"/>
+      </para>
+    </listitem>
+  </orderedlist>
+
+  <sect2 xml:id="sec-ha-drbd-prepare">
+    <title>Preparing your system to use DRBD</title>
+    <para>
+      Before you start configuring DRBD, you might need to perform some or
+      all of the following steps:
+    </para>
+    <procedure xml:id="pro-drbd-prepare">
+      <title>Preparing your system to use DRBD</title>
         <step>
           <para>Make sure the block devices in your Linux nodes are ready
             and partitioned (if needed).</para>
@@ -208,49 +250,13 @@ NAME       SIZELIMIT OFFSET AUTOCLEAR RO BACK-FILE
             <screen>&prompt.root;<command>crm maintenance on</command></screen>
             <para> If you skip this step when your cluster already uses
               DRBD, a syntax error in the live configuration leads
-              to a service shutdown. </para>
-            <para>As an alternative, you can also use
-                <command>drbdadm</command>
-              <option>-c <replaceable>FILE</replaceable></option> to
-              test a configuration file.</para>
+              to a service shutdown.
+              Alternatively, you can also use
+              <command>drbdadm -c <replaceable>FILE</replaceable></command>
+              to test a configuration file.</para>
           </step>
-      </substeps>
-    </step>
-    <step>
-      <para>Configure DRBD by choosing your method:</para>
-      <itemizedlist>
-        <listitem>
-          <para><xref linkend="sec-ha-drbd-configure-manually"/></para>
-        </listitem>
-        <listitem>
-          <para><xref linkend="sec-ha-drbd-configure-yast"/></para>
-        </listitem>
-      </itemizedlist>
-    </step>
-    <step>
-      <para>
-        If you have configured &csync; (which should be the default), the
-        DRBD configuration files are already included in the list of files that
-        need to be synchronized. To synchronize them, run the following command:
-      </para>
-      <screen>&prompt.root;<command>csync2 -xv</command></screen>
-      <para>
-        If you do not have &csync; (or do not want to use it), copy the DRBD
-        configuration files manually to the other node:
-      </para>
-      <screen>&prompt.root;<command>scp /etc/drbd.conf &node2;:/etc/</command>
-&prompt.root;<command>scp /etc/drbd.d/* &node2;:/etc/drbd.d/</command></screen>
-    </step>
-    <step>
-      <para>Perform the initial synchronization (see <xref linkend="sec-ha-drbd-configure-init"/>).</para>
-    </step>
-    <step>
-      <para>
-        Reset the cluster's maintenance mode flag:
-      </para>
-      <screen>&prompt.root;<command>crm maintenance off</command></screen>
-    </step>
-  </procedure>
+    </procedure>
+  </sect2>
 
   <sect2 xml:id="sec-ha-drbd-configure-manually">
     <title>Configuring DRBD manually</title>
@@ -425,8 +431,16 @@ NAME       SIZELIMIT OFFSET AUTOCLEAR RO BACK-FILE
       </para>
       <screen>&prompt.root;<command>drbdadm dump all</command></screen>
      </step>
-    <step>
-      <para>Continue with <xref linkend="sec-ha-drbd-configure-init"/>.</para>
+     <step>
+      <para>
+        Copy the DRBD configuration files to all nodes:
+      </para>
+      <screen>&prompt.root;<command>csync2 -xv</command></screen>
+      <para>
+        By default, the DRBD configuration file <filename>/etc/drbd.conf</filename>
+        and the directory <filename>/etc/drbd.d/</filename> are already included in the list
+        of files that &csync; synchronizes.
+      </para>
     </step>
   </procedure>
   </sect2>
@@ -592,13 +606,21 @@ NAME       SIZELIMIT OFFSET AUTOCLEAR RO BACK-FILE
    <step>
      <para>Save your changes with <guimenu>Finish</guimenu>.</para>
    </step>
-    <step>
-      <para>Continue with <xref linkend="sec-ha-drbd-configure-init"/>.</para>
+   <step>
+      <para>
+        Copy the DRBD configuration files to all nodes:
+      </para>
+      <screen>&prompt.root;<command>csync2 -xv</command></screen>
+      <para>
+        By default, the DRBD configuration file <filename>/etc/drbd.conf</filename>
+        and the directory <filename>/etc/drbd.d/</filename> are already included in the list
+        of files that &csync; synchronizes.
+      </para>
     </step>
   </procedure>
   </sect2>
   <sect2 xml:id="sec-ha-drbd-configure-init">
-    <title>Initializing and formatting DRBD resource</title>
+    <title>Initializing and formatting DRBD resources</title>
     <para>After you have prepared your system and configured DRBD,
       initialize your disk for the first time:
     </para>
@@ -698,7 +720,17 @@ r0 role:Primary
      </para>
 <screen>&prompt.crm.conf;<command>commit</command></screen>
     </step>
+    <step>
+      <para>
+        Exit the interactive shell:
+      </para>
+<screen>&prompt.crm.conf;<command>quit</command></screen>
+    </step>
    </procedure>
+   <para>
+     If you put the cluster in maintenance mode before configuring DRBD, you can now move
+     it back to normal operation with <command>crm maintenance off</command>.
+   </para>
   </sect2>
  </sect1>