Adding upstream version 2.1.6.upstream/2.1.6

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 415 insertions, 0 deletions

diff --git a/doc/sphinx/Pacemaker_Explained/reusing-configuration.rst b/doc/sphinx/Pacemaker_Explained/reusing-configuration.rst
new file mode 100644
index 0000000..0f34f84
--- /dev/null
+++ b/doc/sphinx/Pacemaker_Explained/reusing-configuration.rst
@@ -0,0 +1,415 @@
+Reusing Parts of the Configuration
+----------------------------------
+
+Pacemaker provides multiple ways to simplify the configuration XML by reusing
+parts of it in multiple places.
+
+Besides simplifying the XML, this also allows you to manipulate multiple
+configuration elements with a single reference.
+
+Reusing Resource Definitions
+############################
+
+If you want to create lots of resources with similar configurations, defining a
+*resource template* simplifies the task. Once defined, it can be referenced in
+primitives or in certain types of constraints.
+
+Configuring Resources with Templates
+____________________________________
+
+The primitives referencing the template will inherit all meta-attributes,
+instance attributes, utilization attributes and operations defined
+in the template. And you can define specific attributes and operations for any
+of the primitives. If any of these are defined in both the template and the
+primitive, the values defined in the primitive will take precedence over the
+ones defined in the template.
+
+Hence, resource templates help to reduce the amount of configuration work.
+If any changes are needed, they can be done to the template definition and
+will take effect globally in all resource definitions referencing that
+template.
+
+Resource templates have a syntax similar to that of primitives.
+
+.. topic:: Resource template for a migratable Xen virtual machine
+
+   .. code-block:: xml
+
+      <template id="vm-template" class="ocf" provider="heartbeat" type="Xen">
+        <meta_attributes id="vm-template-meta_attributes">
+          <nvpair id="vm-template-meta_attributes-allow-migrate" name="allow-migrate" value="true"/>
+        </meta_attributes>
+        <utilization id="vm-template-utilization">
+          <nvpair id="vm-template-utilization-memory" name="memory" value="512"/>
+        </utilization>
+        <operations>
+          <op id="vm-template-monitor-15s" interval="15s" name="monitor" timeout="60s"/>
+          <op id="vm-template-start-0" interval="0" name="start" timeout="60s"/>
+        </operations>
+      </template>
+
+Once you define a resource template, you can use it in primitives by specifying the
+``template`` property.
+
+.. topic:: Xen primitive resource using a resource template
+
+   .. code-block:: xml
+
+      <primitive id="vm1" template="vm-template">
+        <instance_attributes id="vm1-instance_attributes">
+          <nvpair id="vm1-instance_attributes-name" name="name" value="vm1"/>
+          <nvpair id="vm1-instance_attributes-xmfile" name="xmfile" value="/etc/xen/shared-vm/vm1"/>
+        </instance_attributes>
+      </primitive>
+
+In the example above, the new primitive ``vm1`` will inherit everything from ``vm-template``. For
+example, the equivalent of the above two examples would be:
+
+.. topic:: Equivalent Xen primitive resource not using a resource template
+
+   .. code-block:: xml
+
+      <primitive id="vm1" class="ocf" provider="heartbeat" type="Xen">
+        <meta_attributes id="vm-template-meta_attributes">
+          <nvpair id="vm-template-meta_attributes-allow-migrate" name="allow-migrate" value="true"/>
+        </meta_attributes>
+        <utilization id="vm-template-utilization">
+          <nvpair id="vm-template-utilization-memory" name="memory" value="512"/>
+        </utilization>
+        <operations>
+          <op id="vm-template-monitor-15s" interval="15s" name="monitor" timeout="60s"/>
+          <op id="vm-template-start-0" interval="0" name="start" timeout="60s"/>
+        </operations>
+        <instance_attributes id="vm1-instance_attributes">
+          <nvpair id="vm1-instance_attributes-name" name="name" value="vm1"/>
+          <nvpair id="vm1-instance_attributes-xmfile" name="xmfile" value="/etc/xen/shared-vm/vm1"/>
+        </instance_attributes>
+      </primitive>
+
+If you want to overwrite some attributes or operations, add them to the
+particular primitive's definition.
+
+.. topic:: Xen resource overriding template values
+
+   .. code-block:: xml
+
+      <primitive id="vm2" template="vm-template">
+        <meta_attributes id="vm2-meta_attributes">
+          <nvpair id="vm2-meta_attributes-allow-migrate" name="allow-migrate" value="false"/>
+        </meta_attributes>
+        <utilization id="vm2-utilization">
+          <nvpair id="vm2-utilization-memory" name="memory" value="1024"/>
+        </utilization>
+        <instance_attributes id="vm2-instance_attributes">
+          <nvpair id="vm2-instance_attributes-name" name="name" value="vm2"/>
+          <nvpair id="vm2-instance_attributes-xmfile" name="xmfile" value="/etc/xen/shared-vm/vm2"/>
+        </instance_attributes>
+        <operations>
+          <op id="vm2-monitor-30s" interval="30s" name="monitor" timeout="120s"/>
+          <op id="vm2-stop-0" interval="0" name="stop" timeout="60s"/>
+        </operations>
+      </primitive>
+
+In the example above, the new primitive ``vm2`` has special attribute values.
+Its ``monitor`` operation has a longer ``timeout`` and ``interval``, and
+the primitive has an additional ``stop`` operation.
+
+To see the resulting definition of a resource, run:
+
+.. code-block:: none
+
+   # crm_resource --query-xml --resource vm2
+
+To see the raw definition of a resource in the CIB, run:
+
+.. code-block:: none
+
+   # crm_resource --query-xml-raw --resource vm2
+
+Using Templates in Constraints
+______________________________
+
+A resource template can be referenced in the following types of constraints:
+
+- ``order`` constraints (see :ref:`s-resource-ordering`)
+- ``colocation`` constraints (see :ref:`s-resource-colocation`)
+- ``rsc_ticket`` constraints (for multi-site clusters as described in :ref:`ticket-constraints`)
+
+Resource templates referenced in constraints stand for all primitives which are
+derived from that template. This means, the constraint applies to all primitive
+resources referencing the resource template. Referencing resource templates in
+constraints is an alternative to resource sets and can simplify the cluster
+configuration considerably.
+
+For example, given the example templates earlier in this chapter:
+
+.. code-block:: xml
+
+   <rsc_colocation id="vm-template-colo-base-rsc" rsc="vm-template" rsc-role="Started" with-rsc="base-rsc" score="INFINITY"/>
+
+would colocate all VMs with ``base-rsc`` and is the equivalent of the following constraint configuration:
+
+.. code-block:: xml
+
+   <rsc_colocation id="vm-colo-base-rsc" score="INFINITY">
+     <resource_set id="vm-colo-base-rsc-0" sequential="false" role="Started">
+       <resource_ref id="vm1"/>
+       <resource_ref id="vm2"/>
+     </resource_set>
+     <resource_set id="vm-colo-base-rsc-1">
+       <resource_ref id="base-rsc"/>
+     </resource_set>
+   </rsc_colocation>
+
+.. note::
+
+   In a colocation constraint, only one template may be referenced from either
+   ``rsc`` or ``with-rsc``; the other reference must be a regular resource.
+
+Using Templates in Resource Sets
+________________________________
+
+Resource templates can also be referenced in resource sets.
+
+For example, given the example templates earlier in this section, then:
+
+.. code-block:: xml
+
+   <rsc_order id="order1" score="INFINITY">
+     <resource_set id="order1-0">
+       <resource_ref id="base-rsc"/>
+       <resource_ref id="vm-template"/>
+       <resource_ref id="top-rsc"/>
+     </resource_set>
+   </rsc_order>
+
+is the equivalent of the following constraint using a sequential resource set:
+
+.. code-block:: xml
+
+   <rsc_order id="order1" score="INFINITY">
+     <resource_set id="order1-0">
+       <resource_ref id="base-rsc"/>
+       <resource_ref id="vm1"/>
+       <resource_ref id="vm2"/>
+       <resource_ref id="top-rsc"/>
+     </resource_set>
+   </rsc_order>
+
+Or, if the resources referencing the template can run in parallel, then:
+
+.. code-block:: xml
+
+   <rsc_order id="order2" score="INFINITY">
+     <resource_set id="order2-0">
+       <resource_ref id="base-rsc"/>
+     </resource_set>
+     <resource_set id="order2-1" sequential="false">
+       <resource_ref id="vm-template"/>
+     </resource_set>
+     <resource_set id="order2-2">
+       <resource_ref id="top-rsc"/>
+     </resource_set>
+   </rsc_order>
+
+is the equivalent of the following constraint configuration:
+
+.. code-block:: xml
+
+   <rsc_order id="order2" score="INFINITY">
+     <resource_set id="order2-0">
+       <resource_ref id="base-rsc"/>
+     </resource_set>
+     <resource_set id="order2-1" sequential="false">
+       <resource_ref id="vm1"/>
+       <resource_ref id="vm2"/>
+     </resource_set>
+     <resource_set id="order2-2">
+       <resource_ref id="top-rsc"/>
+     </resource_set>
+   </rsc_order>
+
+.. _s-reusing-config-elements:
+
+Reusing Rules, Options and Sets of Operations
+#############################################
+
+Sometimes a number of constraints need to use the same set of rules,
+and resources need to set the same options and parameters.  To
+simplify this situation, you can refer to an existing object using an
+``id-ref`` instead of an ``id``.
+
+So if for one resource you have
+
+.. code-block:: xml
+
+   <rsc_location id="WebServer-connectivity" rsc="Webserver">
+      <rule id="ping-prefer-rule" score-attribute="pingd" >
+       <expression id="ping-prefer" attribute="pingd" operation="defined"/>
+      </rule>
+   </rsc_location>
+
+Then instead of duplicating the rule for all your other resources, you can instead specify:
+
+.. topic:: **Referencing rules from other constraints**
+
+   .. code-block:: xml
+   
+      <rsc_location id="WebDB-connectivity" rsc="WebDB">
+         <rule id-ref="ping-prefer-rule"/>
+      </rsc_location>
+   
+.. important::
+
+   The cluster will insist that the ``rule`` exists somewhere.  Attempting
+   to add a reference to a non-existing rule will cause a validation
+   failure, as will attempting to remove a ``rule`` that is referenced
+   elsewhere.
+
+The same principle applies for ``meta_attributes`` and
+``instance_attributes`` as illustrated in the example below:
+
+.. topic:: Referencing attributes, options, and operations from other resources
+
+    .. code-block:: xml
+
+      <primitive id="mySpecialRsc" class="ocf" type="Special" provider="me">
+         <instance_attributes id="mySpecialRsc-attrs" score="1" >
+           <nvpair id="default-interface" name="interface" value="eth0"/>
+           <nvpair id="default-port" name="port" value="9999"/>
+         </instance_attributes>
+         <meta_attributes id="mySpecialRsc-options">
+           <nvpair id="failure-timeout" name="failure-timeout" value="5m"/>
+           <nvpair id="migration-threshold" name="migration-threshold" value="1"/>
+           <nvpair id="stickiness" name="resource-stickiness" value="0"/>
+         </meta_attributes>
+         <operations id="health-checks">
+           <op id="health-check" name="monitor" interval="60s"/>
+           <op id="health-check" name="monitor" interval="30min"/>
+         </operations>
+      </primitive>
+      <primitive id="myOtherlRsc" class="ocf" type="Other" provider="me">
+         <instance_attributes id-ref="mySpecialRsc-attrs"/>
+         <meta_attributes id-ref="mySpecialRsc-options"/>
+         <operations id-ref="health-checks"/>
+      </primitive>
+
+``id-ref`` can similarly be used with ``resource_set`` (in any constraint type),
+``nvpair``, and ``operations``.
+
+Tagging Configuration Elements
+##############################
+
+Pacemaker allows you to *tag* any configuration element that has an XML ID.
+
+The main purpose of tagging is to support higher-level user interface tools;
+Pacemaker itself only uses tags within constraints. Therefore, what you can
+do with tags mostly depends on the tools you use.
+
+Configuring Tags
+________________
+
+A tag is simply a named list of XML IDs.
+
+.. topic:: Tag referencing three resources
+
+   .. code-block:: xml
+
+      <tags>
+        <tag id="all-vms">
+          <obj_ref id="vm1"/>
+          <obj_ref id="vm2"/>
+          <obj_ref id="vm3"/>
+        </tag>
+      </tags>
+
+What you can do with this new tag depends on what your higher-level tools
+support. For example, a tool might allow you to enable or disable all of
+the tagged resources at once, or show the status of just the tagged
+resources.
+
+A single configuration element can be listed in any number of tags.
+
+Using Tags in Constraints and Resource Sets
+___________________________________________
+
+Pacemaker itself only uses tags in constraints. If you supply a tag name
+instead of a resource name in any constraint, the constraint will apply to
+all resources listed in that tag.
+
+.. topic:: Constraint using a tag
+
+   .. code-block:: xml
+
+      <rsc_order id="order1" first="storage" then="all-vms" kind="Mandatory" />
+
+In the example above, assuming the ``all-vms`` tag is defined as in the previous
+example, the constraint will behave the same as:
+
+.. topic:: Equivalent constraints without tags
+
+   .. code-block:: xml
+
+      <rsc_order id="order1-1" first="storage" then="vm1" kind="Mandatory" />
+      <rsc_order id="order1-2" first="storage" then="vm2" kind="Mandatory" />
+      <rsc_order id="order1-3" first="storage" then="vm3" kind="Mandatory" />
+
+A tag may be used directly in the constraint, or indirectly by being
+listed in a :ref:`resource set <s-resource-sets>` used in the constraint.
+When used in a resource set, an expanded tag will honor the set's
+``sequential`` property.
+
+Filtering With Tags
+___________________
+
+The ``crm_mon`` tool can be used to display lots of information about the
+state of the cluster.  On large or complicated clusters, this can include
+a lot of information, which makes it difficult to find the one thing you
+are interested in.  The ``--resource=`` and ``--node=`` command line
+options can be used to filter results.  In their most basic usage, these
+options take a single resource or node name.  However, they can also
+be supplied with a tag name to display several objects at once.
+
+For instance, given the following CIB section:
+
+.. code-block:: xml
+
+   <resources>
+     <primitive class="stonith" id="Fencing" type="fence_xvm"/>
+     <primitive class="ocf" id="dummy" provider="pacemaker" type="Dummy"/>
+     <group id="inactive-group">
+       <primitive class="ocf" id="inactive-dummy-1" provider="pacemaker" type="Dummy"/>
+       <primitive class="ocf" id="inactive-dummy-2" provider="pacemaker" type="Dummy"/>
+     </group>
+     <clone id="inactive-clone">
+       <primitive id="inactive-dhcpd" class="lsb" type="dhcpd"/>
+     </clone>
+   </resources>
+   <tags>
+     <tag id="inactive-rscs">
+       <obj_ref id="inactive-group"/>
+       <obj_ref id="inactive-clone"/>
+     </tag>
+   </tags>
+
+The following would be output for ``crm_mon --resource=inactive-rscs -r``:
+
+.. code-block:: none
+
+   Cluster Summary:
+     * Stack: corosync
+     * Current DC: cluster02 (version 2.0.4-1.e97f9675f.git.el7-e97f9675f) - partition with quorum
+     * Last updated: Tue Oct 20 16:09:01 2020
+     * Last change:  Tue May  5 12:04:36 2020 by hacluster via crmd on cluster01
+     * 5 nodes configured
+     * 27 resource instances configured (4 DISABLED)
+
+   Node List:
+     * Online: [ cluster01 cluster02 ]
+
+   Full List of Resources:
+     * Clone Set: inactive-clone [inactive-dhcpd] (disabled):
+       * Stopped (disabled): [ cluster01 cluster02 ]
+     * Resource Group: inactive-group (disabled):
+       * inactive-dummy-1  (ocf::pacemaker:Dummy):  Stopped (disabled)
+       * inactive-dummy-2  (ocf::pacemaker:Dummy):  Stopped (disabled)