Add more information about how clones are promoted (#459)

* Add more information about how clones are promoted

bsc#1253010
jsc#DOCTEAM-2014

* Updated revision date

* Update from tech review

Author: tahliar

xml/book_administration.xml

@@ -76,7 +76,7 @@
   <info xmlns:d="http://docbook.org/ns/docbook">
    <revhistory xml:id="rh-admin-config">
     <revision>
-     <date>2021-06-22</date>
+     <date>2025-11-27</date>
      <revdescription>
       <para/>
      </revdescription>

xml/ha_configuring_resources.xml

@@ -24,7 +24,7 @@
   </dm:docmanager>
  <revhistory xml:id="rh-sec-ha-config-basics-resources">
    <revision>
-     <date>2024-01-15</date>
+     <date>2025-11-27</date>
      <revdescription>
        <para/>
      </revdescription>
@@ -769,8 +769,8 @@
      <term>Promotable clones (multi-state resources)</term>
      <listitem>
       <para>
-       Active instances of these resources are divided into two states,
-       active and passive. These are also sometimes called primary and
+       Active instances of these resources are divided into two states:
+       promoted and unpromoted. These are also sometimes called primary and
        secondary. Promotable clones can be either
        anonymous or globally unique. For more information, see
        <xref linkend="sec-ha-config-basics-resources-advanced-masters"/>.
@@ -885,16 +885,37 @@
    <title>Creating promotable clones (multi-state resources)</title>
    <para>
     Promotable clones (formerly known as multi-state resources) are a
-    specialization of clones. They allow the
-    instances to be in one of two operating modes (primary or
+    specialization of clones. They allow the instances to be in one of two
+    operating modes: promoted or unpromoted (also known as primary or
     secondary). Promotable clones must contain
     exactly one group or one regular resource.
    </para>
+   <para>
+    &pace; determines which instance of the clone to promote using one of the following
+    methods (or a combination of both):
+   </para>
+   <itemizedlist>
+     <listitem>
+       <para>
+         If a resource agent supports promotable clones, it might automatically set
+         <emphasis>promotion scores</emphasis> based on its own preference for which
+         instance to promote.
+       </para>
+     </listitem>
+     <listitem>
+       <para>
+         You can manually set promotion rules or preferences by creating
+         <emphasis>location</emphasis> or <emphasis>colocation</emphasis> constraints.
+       </para>
+     </listitem>
+   </itemizedlist>
+   <para>
+    For more information, see <link xlink:href="https://clusterlabs.org/projects/pacemaker/doc/3.0/Pacemaker_Explained/html/collective.html#determining-which-instance-is-promoted"/>.
+   </para>
    <para>
     When configuring resource monitoring or constraints, promotable
-    clones have different requirements than simple resources. For
-    details, see &paceex;. The version for Pacemaker 1.1 is available from
-    <link xlink:href="http://www.clusterlabs.org/pacemaker/doc/"/>.
+    clones have different requirements than simple resources. For more information, see
+    <link xlink:href="https://clusterlabs.org/projects/pacemaker/doc/3.0/Pacemaker_Explained/html/collective.html#clone-constraints"/>.
    </para>
    <para>
     You can create promotable clones using either &hawk2; or &crmsh;.