diff options
Diffstat (limited to 'doc/sphinx/Pacemaker_Explained/rules.rst')
| -rw-r--r-- | doc/sphinx/Pacemaker_Explained/rules.rst | 1021 |
1 files changed, 1021 insertions, 0 deletions
diff --git a/doc/sphinx/Pacemaker_Explained/rules.rst b/doc/sphinx/Pacemaker_Explained/rules.rst new file mode 100644 index 0000000..e9d85e0 --- /dev/null +++ b/doc/sphinx/Pacemaker_Explained/rules.rst @@ -0,0 +1,1021 @@ +.. index:: + single: rule + +.. _rules: + +Rules +----- + +Rules can be used to make your configuration more dynamic, allowing values to +change depending on the time or the value of a node attribute. Examples of +things rules are useful for: + +* Set a higher value for :ref:`resource-stickiness <resource-stickiness>` + during working hours, to minimize downtime, and a lower value on weekends, to + allow resources to move to their most preferred locations when people aren't + around to notice. + +* Automatically place the cluster into maintenance mode during a scheduled + maintenance window. + +* Assign certain nodes and resources to a particular department via custom + node attributes and meta-attributes, and add a single location constraint + that restricts the department's resources to run only on those nodes. + +Each constraint type or property set that supports rules may contain one or more +``rule`` elements specifying conditions under which the constraint or properties +take effect. Examples later in this chapter will make this clearer. + +.. index:: + pair: XML element; rule + +Rule Properties +############### + +.. table:: **Attributes of a rule Element** + :widths: 1 1 3 + + +-----------------+-------------+-------------------------------------------+ + | Attribute | Default | Description | + +=================+=============+===========================================+ + | id | | .. index:: | + | | | pair: rule; id | + | | | | + | | | A unique name for this element (required) | + +-----------------+-------------+-------------------------------------------+ + | role | ``Started`` | .. index:: | + | | | pair: rule; role | + | | | | + | | | The rule is in effect only when the | + | | | resource is in the specified role. | + | | | Allowed values are ``Started``, | + | | | ``Unpromoted``, and ``Promoted``. A rule | + | | | with a ``role`` of ``Promoted`` cannot | + | | | determine the initial location of a clone | + | | | instance and will only affect which of | + | | | the active instances will be promoted. | + +-----------------+-------------+-------------------------------------------+ + | score | | .. index:: | + | | | pair: rule; score | + | | | | + | | | If this rule is used in a location | + | | | constraint and evaluates to true, apply | + | | | this score to the constraint. Only one of | + | | | ``score`` and ``score-attribute`` may be | + | | | used. | + +-----------------+-------------+-------------------------------------------+ + | score-attribute | | .. index:: | + | | | pair: rule; score-attribute | + | | | | + | | | If this rule is used in a location | + | | | constraint and evaluates to true, use the | + | | | value of this node attribute as the score | + | | | to apply to the constraint. Only one of | + | | | ``score`` and ``score-attribute`` may be | + | | | used. | + +-----------------+-------------+-------------------------------------------+ + | boolean-op | ``and`` | .. index:: | + | | | pair: rule; boolean-op | + | | | | + | | | If this rule contains more than one | + | | | condition, a value of ``and`` specifies | + | | | that the rule evaluates to true only if | + | | | all conditions are true, and a value of | + | | | ``or`` specifies that the rule evaluates | + | | | to true if any condition is true. | + +-----------------+-------------+-------------------------------------------+ + +A ``rule`` element must contain one or more conditions. A condition may be an +``expression`` element, a ``date_expression`` element, or another ``rule`` element. + + +.. index:: + single: rule; node attribute expression + single: node attribute; rule expression + pair: XML element; expression + +.. _node_attribute_expressions: + +Node Attribute Expressions +########################## + +Expressions are rule conditions based on the values of node attributes. + +.. table:: **Attributes of an expression Element** + :class: longtable + :widths: 1 2 3 + + +--------------+---------------------------------+-------------------------------------------+ + | Attribute | Default | Description | + +==============+=================================+===========================================+ + | id | | .. index:: | + | | | pair: expression; id | + | | | | + | | | A unique name for this element (required) | + +--------------+---------------------------------+-------------------------------------------+ + | attribute | | .. index:: | + | | | pair: expression; attribute | + | | | | + | | | The node attribute to test (required) | + +--------------+---------------------------------+-------------------------------------------+ + | type | The default type for | .. index:: | + | | ``lt``, ``gt``, ``lte``, and | pair: expression; type | + | | ``gte`` operations is ``number``| | + | | if either value contains a | How the node attributes should be | + | | decimal point character, or | compared. Allowed values are ``string``, | + | | ``integer`` otherwise. The | ``integer`` *(since 2.0.5)*, ``number``, | + | | default type for all other | and ``version``. ``integer`` truncates | + | | operations is ``string``. If a | floating-point values if necessary before | + | | numeric parse fails for either | performing a 64-bit integer comparison. | + | | value, then the values are | ``number`` performs a double-precision | + | | compared as type ``string``. | floating-point comparison | + | | | *(32-bit integer before 2.0.5)*. | + +--------------+---------------------------------+-------------------------------------------+ + | operation | | .. index:: | + | | | pair: expression; operation | + | | | | + | | | The comparison to perform (required). | + | | | Allowed values: | + | | | | + | | | * ``lt:`` True if the node attribute value| + | | | is less than the comparison value | + | | | * ``gt:`` True if the node attribute value| + | | | is greater than the comparison value | + | | | * ``lte:`` True if the node attribute | + | | | value is less than or equal to the | + | | | comparison value | + | | | * ``gte:`` True if the node attribute | + | | | value is greater than or equal to the | + | | | comparison value | + | | | * ``eq:`` True if the node attribute value| + | | | is equal to the comparison value | + | | | * ``ne:`` True if the node attribute value| + | | | is not equal to the comparison value | + | | | * ``defined:`` True if the node has the | + | | | named attribute | + | | | * ``not_defined:`` True if the node does | + | | | not have the named attribute | + +--------------+---------------------------------+-------------------------------------------+ + | value | | .. index:: | + | | | pair: expression; value | + | | | | + | | | User-supplied value for comparison | + | | | (required for operations other than | + | | | ``defined`` and ``not_defined``) | + +--------------+---------------------------------+-------------------------------------------+ + | value-source | ``literal`` | .. index:: | + | | | pair: expression; value-source | + | | | | + | | | How the ``value`` is derived. Allowed | + | | | values: | + | | | | + | | | * ``literal``: ``value`` is a literal | + | | | string to compare against | + | | | * ``param``: ``value`` is the name of a | + | | | resource parameter to compare against | + | | | (only valid in location constraints) | + | | | * ``meta``: ``value`` is the name of a | + | | | resource meta-attribute to compare | + | | | against (only valid in location | + | | | constraints) | + +--------------+---------------------------------+-------------------------------------------+ + +.. _node-attribute-expressions-special: + +In addition to custom node attributes defined by the administrator, the cluster +defines special, built-in node attributes for each node that can also be used +in rule expressions. + +.. table:: **Built-in Node Attributes** + :widths: 1 4 + + +---------------+-----------------------------------------------------------+ + | Name | Value | + +===============+===========================================================+ + | #uname | :ref:`Node name <node_name>` | + +---------------+-----------------------------------------------------------+ + | #id | Node ID | + +---------------+-----------------------------------------------------------+ + | #kind | Node type. Possible values are ``cluster``, ``remote``, | + | | and ``container``. Kind is ``remote`` for Pacemaker Remote| + | | nodes created with the ``ocf:pacemaker:remote`` resource, | + | | and ``container`` for Pacemaker Remote guest nodes and | + | | bundle nodes | + +---------------+-----------------------------------------------------------+ + | #is_dc | ``true`` if this node is the cluster's Designated | + | | Controller (DC), ``false`` otherwise | + +---------------+-----------------------------------------------------------+ + | #cluster-name | The value of the ``cluster-name`` cluster property, if set| + +---------------+-----------------------------------------------------------+ + | #site-name | The value of the ``site-name`` node attribute, if set, | + | | otherwise identical to ``#cluster-name`` | + +---------------+-----------------------------------------------------------+ + | #role | The role the relevant promotable clone resource has on | + | | this node. Valid only within a rule for a location | + | | constraint for a promotable clone resource. | + +---------------+-----------------------------------------------------------+ + +.. Add_to_above_table_if_released: + + +---------------+-----------------------------------------------------------+ + | #ra-version | The installed version of the resource agent on the node, | + | | as defined by the ``version`` attribute of the | + | | ``resource-agent`` tag in the agent's metadata. Valid only| + | | within rules controlling resource options. This can be | + | | useful during rolling upgrades of a backward-incompatible | + | | resource agent. *(since x.x.x)* | + + +.. index:: + single: rule; date/time expression + pair: XML element; date_expression + +Date/Time Expressions +##################### + +Date/time expressions are rule conditions based (as the name suggests) on the +current date and time. + +A ``date_expression`` element may optionally contain a ``date_spec`` or +``duration`` element depending on the context. + +.. table:: **Attributes of a date_expression Element** + :widths: 1 4 + + +---------------+-----------------------------------------------------------+ + | Attribute | Description | + +===============+===========================================================+ + | id | .. index:: | + | | pair: id; date_expression | + | | | + | | A unique name for this element (required) | + +---------------+-----------------------------------------------------------+ + | start | .. index:: | + | | pair: start; date_expression | + | | | + | | A date/time conforming to the | + | | `ISO8601 <https://en.wikipedia.org/wiki/ISO_8601>`_ | + | | specification. May be used when ``operation`` is | + | | ``in_range`` (in which case at least one of ``start`` or | + | | ``end`` must be specified) or ``gt`` (in which case | + | | ``start`` is required). | + +---------------+-----------------------------------------------------------+ + | end | .. index:: | + | | pair: end; date_expression | + | | | + | | A date/time conforming to the | + | | `ISO8601 <https://en.wikipedia.org/wiki/ISO_8601>`_ | + | | specification. May be used when ``operation`` is | + | | ``in_range`` (in which case at least one of ``start`` or | + | | ``end`` must be specified) or ``lt`` (in which case | + | | ``end`` is required). | + +---------------+-----------------------------------------------------------+ + | operation | .. index:: | + | | pair: operation; date_expression | + | | | + | | Compares the current date/time with the start and/or end | + | | date, depending on the context. Allowed values: | + | | | + | | * ``gt:`` True if the current date/time is after ``start``| + | | * ``lt:`` True if the current date/time is before ``end`` | + | | * ``in_range:`` True if the current date/time is after | + | | ``start`` (if specified) and before either ``end`` (if | + | | specified) or ``start`` plus the value of the | + | | ``duration`` element (if one is contained in the | + | | ``date_expression``). If both ``end`` and ``duration`` | + | | are specified, ``duration`` is ignored. | + | | * ``date_spec:`` True if the current date/time matches | + | | the specification given in the contained ``date_spec`` | + | | element (described below) | + +---------------+-----------------------------------------------------------+ + + +.. note:: There is no ``eq``, ``neq``, ``gte``, or ``lte`` operation, since + they would be valid only for a single second. + + +.. index:: + single: date specification + pair: XML element; date_spec + +Date Specifications +___________________ + +A ``date_spec`` element is used to create a cron-like expression relating +to time. Each field can contain a single number or range. Any field not +supplied is ignored. + +.. table:: **Attributes of a date_spec Element** + :widths: 1 3 + + +---------------+-----------------------------------------------------------+ + | Attribute | Description | + +===============+===========================================================+ + | id | .. index:: | + | | pair: id; date_spec | + | | | + | | A unique name for this element (required) | + +---------------+-----------------------------------------------------------+ + | seconds | .. index:: | + | | pair: seconds; date_spec | + | | | + | | Allowed values: 0-59 | + +---------------+-----------------------------------------------------------+ + | minutes | .. index:: | + | | pair: minutes; date_spec | + | | | + | | Allowed values: 0-59 | + +---------------+-----------------------------------------------------------+ + | hours | .. index:: | + | | pair: hours; date_spec | + | | | + | | Allowed values: 0-23 (where 0 is midnight and 23 is | + | | 11 p.m.) | + +---------------+-----------------------------------------------------------+ + | monthdays | .. index:: | + | | pair: monthdays; date_spec | + | | | + | | Allowed values: 1-31 (depending on month and year) | + +---------------+-----------------------------------------------------------+ + | weekdays | .. index:: | + | | pair: weekdays; date_spec | + | | | + | | Allowed values: 1-7 (where 1 is Monday and 7 is Sunday) | + +---------------+-----------------------------------------------------------+ + | yeardays | .. index:: | + | | pair: yeardays; date_spec | + | | | + | | Allowed values: 1-366 (depending on the year) | + +---------------+-----------------------------------------------------------+ + | months | .. index:: | + | | pair: months; date_spec | + | | | + | | Allowed values: 1-12 | + +---------------+-----------------------------------------------------------+ + | weeks | .. index:: | + | | pair: weeks; date_spec | + | | | + | | Allowed values: 1-53 (depending on weekyear) | + +---------------+-----------------------------------------------------------+ + | years | .. index:: | + | | pair: years; date_spec | + | | | + | | Year according to the Gregorian calendar | + +---------------+-----------------------------------------------------------+ + | weekyears | .. index:: | + | | pair: weekyears; date_spec | + | | | + | | Year in which the week started; for example, 1 January | + | | 2005 can be specified in ISO 8601 as "2005-001 Ordinal", | + | | "2005-01-01 Gregorian" or "2004-W53-6 Weekly" and thus | + | | would match ``years="2005"`` or ``weekyears="2004"`` | + +---------------+-----------------------------------------------------------+ + | moon | .. index:: | + | | pair: moon; date_spec | + | | | + | | Allowed values are 0-7 (where 0 is the new moon and 4 is | + | | full moon). *(deprecated since 2.1.6)* | + +---------------+-----------------------------------------------------------+ + +For example, ``monthdays="1"`` matches the first day of every month, and +``hours="09-17"`` matches the hours between 9 a.m. and 5 p.m. (inclusive). + +At this time, multiple ranges (e.g. ``weekdays="1,2"`` or ``weekdays="1-2,5-6"``) +are not supported. + +.. note:: Pacemaker can calculate when evaluation of a ``date_expression`` with + an ``operation`` of ``gt``, ``lt``, or ``in_range`` will next change, + and schedule a cluster re-check for that time. However, it does not + do this for ``date_spec``. Instead, it evaluates the ``date_spec`` + whenever a cluster re-check naturally happens via a cluster event or + the ``cluster-recheck-interval`` cluster option. + + For example, if you have a ``date_spec`` enabling a resource from 9 + a.m. to 5 p.m., and ``cluster-recheck-interval`` has been set to 5 + minutes, then sometime between 9 a.m. and 9:05 a.m. the cluster would + notice that it needs to start the resource, and sometime between 5 + p.m. and 5:05 p.m. it would realize that it needs to stop the + resource. The timing of the actual start and stop actions will + further depend on factors such as any other actions the cluster may + need to perform first, and the load of the machine. + + +.. index:: + single: duration + pair: XML element; duration + +Durations +_________ + +A ``duration`` is used to calculate a value for ``end`` when one is not +supplied to ``in_range`` operations. It contains one or more attributes each +containing a single number. Any attribute not supplied is ignored. + +.. table:: **Attributes of a duration Element** + :widths: 1 3 + + +---------------+-----------------------------------------------------------+ + | Attribute | Description | + +===============+===========================================================+ + | id | .. index:: | + | | pair: id; duration | + | | | + | | A unique name for this element (required) | + +---------------+-----------------------------------------------------------+ + | seconds | .. index:: | + | | pair: seconds; duration | + | | | + | | This many seconds will be added to the total duration | + +---------------+-----------------------------------------------------------+ + | minutes | .. index:: | + | | pair: minutes; duration | + | | | + | | This many minutes will be added to the total duration | + +---------------+-----------------------------------------------------------+ + | hours | .. index:: | + | | pair: hours; duration | + | | | + | | This many hours will be added to the total duration | + +---------------+-----------------------------------------------------------+ + | days | .. index:: | + | | pair: days; duration | + | | | + | | This many days will be added to the total duration | + +---------------+-----------------------------------------------------------+ + | weeks | .. index:: | + | | pair: weeks; duration | + | | | + | | This many weeks will be added to the total duration | + +---------------+-----------------------------------------------------------+ + | months | .. index:: | + | | pair: months; duration | + | | | + | | This many months will be added to the total duration | + +---------------+-----------------------------------------------------------+ + | years | .. index:: | + | | pair: years; duration | + | | | + | | This many years will be added to the total duration | + +---------------+-----------------------------------------------------------+ + + +Example Time-Based Expressions +______________________________ + +A small sample of how time-based expressions can be used: + +.. topic:: True if now is any time in the year 2005 + + .. code-block:: xml + + <rule id="rule1" score="INFINITY"> + <date_expression id="date_expr1" start="2005-001" operation="in_range"> + <duration id="duration1" years="1"/> + </date_expression> + </rule> + + or equivalently: + + .. code-block:: xml + + <rule id="rule2" score="INFINITY"> + <date_expression id="date_expr2" operation="date_spec"> + <date_spec id="date_spec2" years="2005"/> + </date_expression> + </rule> + +.. topic:: 9 a.m. to 5 p.m. Monday through Friday + + .. code-block:: xml + + <rule id="rule3" score="INFINITY"> + <date_expression id="date_expr3" operation="date_spec"> + <date_spec id="date_spec3" hours="9-16" weekdays="1-5"/> + </date_expression> + </rule> + + Note that the ``16`` matches all the way through ``16:59:59``, because the + numeric value of the hour still matches. + +.. topic:: 9 a.m. to 6 p.m. Monday through Friday or anytime Saturday + + .. code-block:: xml + + <rule id="rule4" score="INFINITY" boolean-op="or"> + <date_expression id="date_expr4-1" operation="date_spec"> + <date_spec id="date_spec4-1" hours="9-16" weekdays="1-5"/> + </date_expression> + <date_expression id="date_expr4-2" operation="date_spec"> + <date_spec id="date_spec4-2" weekdays="6"/> + </date_expression> + </rule> + +.. topic:: 9 a.m. to 5 p.m. or 9 p.m. to 12 a.m. Monday through Friday + + .. code-block:: xml + + <rule id="rule5" score="INFINITY" boolean-op="and"> + <rule id="rule5-nested1" score="INFINITY" boolean-op="or"> + <date_expression id="date_expr5-1" operation="date_spec"> + <date_spec id="date_spec5-1" hours="9-16"/> + </date_expression> + <date_expression id="date_expr5-2" operation="date_spec"> + <date_spec id="date_spec5-2" hours="21-23"/> + </date_expression> + </rule> + <date_expression id="date_expr5-3" operation="date_spec"> + <date_spec id="date_spec5-3" weekdays="1-5"/> + </date_expression> + </rule> + +.. topic:: Mondays in March 2005 + + .. code-block:: xml + + <rule id="rule6" score="INFINITY" boolean-op="and"> + <date_expression id="date_expr6-1" operation="date_spec"> + <date_spec id="date_spec6" weekdays="1"/> + </date_expression> + <date_expression id="date_expr6-2" operation="in_range" + start="2005-03-01" end="2005-04-01"/> + </rule> + + .. note:: Because no time is specified with the above dates, 00:00:00 is + implied. This means that the range includes all of 2005-03-01 but + none of 2005-04-01. You may wish to write ``end`` as + ``"2005-03-31T23:59:59"`` to avoid confusion. + + +.. index:: + single: rule; resource expression + single: resource; rule expression + pair: XML element; rsc_expression + +Resource Expressions +#################### + +An ``rsc_expression`` *(since 2.0.5)* is a rule condition based on a resource +agent's properties. This rule is only valid within an ``rsc_defaults`` or +``op_defaults`` context. None of the matching attributes of ``class``, +``provider``, and ``type`` are required. If one is omitted, all values of that +attribute will match. For instance, omitting ``type`` means every type will +match. + +.. table:: **Attributes of a rsc_expression Element** + :widths: 1 3 + + +---------------+-----------------------------------------------------------+ + | Attribute | Description | + +===============+===========================================================+ + | id | .. index:: | + | | pair: id; rsc_expression | + | | | + | | A unique name for this element (required) | + +---------------+-----------------------------------------------------------+ + | class | .. index:: | + | | pair: class; rsc_expression | + | | | + | | The standard name to be matched against resource agents | + +---------------+-----------------------------------------------------------+ + | provider | .. index:: | + | | pair: provider; rsc_expression | + | | | + | | If given, the vendor to be matched against resource | + | | agents (only relevant when ``class`` is ``ocf``) | + +---------------+-----------------------------------------------------------+ + | type | .. index:: | + | | pair: type; rsc_expression | + | | | + | | The name of the resource agent to be matched | + +---------------+-----------------------------------------------------------+ + +Example Resource-Based Expressions +__________________________________ + +A small sample of how resource-based expressions can be used: + +.. topic:: True for all ``ocf:heartbeat:IPaddr2`` resources + + .. code-block:: xml + + <rule id="rule1" score="INFINITY"> + <rsc_expression id="rule_expr1" class="ocf" provider="heartbeat" type="IPaddr2"/> + </rule> + +.. topic:: Provider doesn't apply to non-OCF resources + + .. code-block:: xml + + <rule id="rule2" score="INFINITY"> + <rsc_expression id="rule_expr2" class="stonith" type="fence_xvm"/> + </rule> + + +.. index:: + single: rule; operation expression + single: operation; rule expression + pair: XML element; op_expression + +Operation Expressions +##################### + + +An ``op_expression`` *(since 2.0.5)* is a rule condition based on an action of +some resource agent. This rule is only valid within an ``op_defaults`` context. + +.. table:: **Attributes of an op_expression Element** + :widths: 1 3 + + +---------------+-----------------------------------------------------------+ + | Attribute | Description | + +===============+===========================================================+ + | id | .. index:: | + | | pair: id; op_expression | + | | | + | | A unique name for this element (required) | + +---------------+-----------------------------------------------------------+ + | name | .. index:: | + | | pair: name; op_expression | + | | | + | | The action name to match against. This can be any action | + | | supported by the resource agent; common values include | + | | ``monitor``, ``start``, and ``stop`` (required). | + +---------------+-----------------------------------------------------------+ + | interval | .. index:: | + | | pair: interval; op_expression | + | | | + | | The interval of the action to match against. If not given,| + | | only the name attribute will be used to match. | + +---------------+-----------------------------------------------------------+ + +Example Operation-Based Expressions +___________________________________ + +A small sample of how operation-based expressions can be used: + +.. topic:: True for all monitor actions + + .. code-block:: xml + + <rule id="rule1" score="INFINITY"> + <op_expression id="rule_expr1" name="monitor"/> + </rule> + +.. topic:: True for all monitor actions with a 10 second interval + + .. code-block:: xml + + <rule id="rule2" score="INFINITY"> + <op_expression id="rule_expr2" name="monitor" interval="10s"/> + </rule> + + +.. index:: + pair: location constraint; rule + +Using Rules to Determine Resource Location +########################################## + +A location constraint may contain one or more top-level rules. The cluster will +act as if there is a separate location constraint for each rule that evaluates +as true. + +Consider the following simple location constraint: + +.. topic:: Prevent resource ``webserver`` from running on node ``node3`` + + .. code-block:: xml + + <rsc_location id="ban-apache-on-node3" rsc="webserver" + score="-INFINITY" node="node3"/> + +The same constraint can be more verbosely written using a rule: + +.. topic:: Prevent resource ``webserver`` from running on node ``node3`` using a rule + + .. code-block:: xml + + <rsc_location id="ban-apache-on-node3" rsc="webserver"> + <rule id="ban-apache-rule" score="-INFINITY"> + <expression id="ban-apache-expr" attribute="#uname" + operation="eq" value="node3"/> + </rule> + </rsc_location> + +The advantage of using the expanded form is that one could add more expressions +(for example, limiting the constraint to certain days of the week), or activate +the constraint by some node attribute other than node name. + +Location Rules Based on Other Node Properties +_____________________________________________ + +The expanded form allows us to match on node properties other than its name. +If we rated each machine's CPU power such that the cluster had the following +nodes section: + +.. topic:: Sample node section with node attributes + + .. code-block:: xml + + <nodes> + <node id="uuid1" uname="c001n01" type="normal"> + <instance_attributes id="uuid1-custom_attrs"> + <nvpair id="uuid1-cpu_mips" name="cpu_mips" value="1234"/> + </instance_attributes> + </node> + <node id="uuid2" uname="c001n02" type="normal"> + <instance_attributes id="uuid2-custom_attrs"> + <nvpair id="uuid2-cpu_mips" name="cpu_mips" value="5678"/> + </instance_attributes> + </node> + </nodes> + +then we could prevent resources from running on underpowered machines with this +rule: + +.. topic:: Rule using a node attribute (to be used inside a location constraint) + + .. code-block:: xml + + <rule id="need-more-power-rule" score="-INFINITY"> + <expression id="need-more-power-expr" attribute="cpu_mips" + operation="lt" value="3000"/> + </rule> + +Using ``score-attribute`` Instead of ``score`` +______________________________________________ + +When using ``score-attribute`` instead of ``score``, each node matched by the +rule has its score adjusted differently, according to its value for the named +node attribute. Thus, in the previous example, if a rule inside a location +constraint for a resource used ``score-attribute="cpu_mips"``, ``c001n01`` +would have its preference to run the resource increased by ``1234`` whereas +``c001n02`` would have its preference increased by ``5678``. + + +.. _s-rsc-pattern-rules: + +Specifying location scores using pattern submatches +___________________________________________________ + +Location constraints may use ``rsc-pattern`` to apply the constraint to all +resources whose IDs match the given pattern (see :ref:`s-rsc-pattern`). The +pattern may contain up to 9 submatches in parentheses, whose values may be used +as ``%1`` through ``%9`` in a rule's ``score-attribute`` or a rule expression's +``attribute``. + +As an example, the following configuration (only relevant parts are shown) +gives the resources **server-httpd** and **ip-httpd** a preference of 100 on +**node1** and 50 on **node2**, and **ip-gateway** a preference of -100 on +**node1** and 200 on **node2**. + +.. topic:: Location constraint using submatches + + .. code-block:: xml + + <nodes> + <node id="1" uname="node1"> + <instance_attributes id="node1-attrs"> + <nvpair id="node1-prefer-httpd" name="prefer-httpd" value="100"/> + <nvpair id="node1-prefer-gateway" name="prefer-gateway" value="-100"/> + </instance_attributes> + </node> + <node id="2" uname="node2"> + <instance_attributes id="node2-attrs"> + <nvpair id="node2-prefer-httpd" name="prefer-httpd" value="50"/> + <nvpair id="node2-prefer-gateway" name="prefer-gateway" value="200"/> + </instance_attributes> + </node> + </nodes> + <resources> + <primitive id="server-httpd" class="ocf" provider="heartbeat" type="apache"/> + <primitive id="ip-httpd" class="ocf" provider="heartbeat" type="IPaddr2"/> + <primitive id="ip-gateway" class="ocf" provider="heartbeat" type="IPaddr2"/> + </resources> + <constraints> + <!-- The following constraint says that for any resource whose name + starts with "server-" or "ip-", that resource's preference for a + node is the value of the node attribute named "prefer-" followed + by the part of the resource name after "server-" or "ip-", + wherever such a node attribute is defined. + --> + <rsc_location id="location1" rsc-pattern="(server|ip)-(.*)"> + <rule id="location1-rule1" score-attribute="prefer-%2"> + <expression id="location1-rule1-expression1" attribute="prefer-%2" operation="defined"/> + </rule> + </rsc_location> + </constraints> + + +.. index:: + pair: cluster option; rule + pair: instance attribute; rule + pair: meta-attribute; rule + pair: resource defaults; rule + pair: operation defaults; rule + pair: node attribute; rule + +Using Rules to Define Options +############################# + +Rules may be used to control a variety of options: + +* :ref:`Cluster options <cluster_options>` (``cluster_property_set`` elements) +* :ref:`Node attributes <node_attributes>` (``instance_attributes`` or + ``utilization`` elements inside a ``node`` element) +* :ref:`Resource options <resource_options>` (``utilization``, + ``meta_attributes``, or ``instance_attributes`` elements inside a resource + definition element or ``op`` , ``rsc_defaults``, ``op_defaults``, or + ``template`` element) +* :ref:`Operation properties <operation_properties>` (``meta_attributes`` + elements inside an ``op`` or ``op_defaults`` element) + +.. note:: + + Attribute-based expressions for meta-attributes can only be used within + ``operations`` and ``op_defaults``. They will not work with resource + configuration or ``rsc_defaults``. Additionally, attribute-based + expressions cannot be used with cluster options. + +Using Rules to Control Resource Options +_______________________________________ + +Often some cluster nodes will be different from their peers. Sometimes, +these differences -- e.g. the location of a binary or the names of network +interfaces -- require resources to be configured differently depending +on the machine they're hosted on. + +By defining multiple ``instance_attributes`` objects for the resource and +adding a rule to each, we can easily handle these special cases. + +In the example below, ``mySpecialRsc`` will use eth1 and port 9999 when run on +``node1``, eth2 and port 8888 on ``node2`` and default to eth0 and port 9999 +for all other nodes. + +.. topic:: Defining different resource options based on the node name + + .. code-block:: xml + + <primitive id="mySpecialRsc" class="ocf" type="Special" provider="me"> + <instance_attributes id="special-node1" score="3"> + <rule id="node1-special-case" score="INFINITY" > + <expression id="node1-special-case-expr" attribute="#uname" + operation="eq" value="node1"/> + </rule> + <nvpair id="node1-interface" name="interface" value="eth1"/> + </instance_attributes> + <instance_attributes id="special-node2" score="2" > + <rule id="node2-special-case" score="INFINITY"> + <expression id="node2-special-case-expr" attribute="#uname" + operation="eq" value="node2"/> + </rule> + <nvpair id="node2-interface" name="interface" value="eth2"/> + <nvpair id="node2-port" name="port" value="8888"/> + </instance_attributes> + <instance_attributes id="defaults" score="1" > + <nvpair id="default-interface" name="interface" value="eth0"/> + <nvpair id="default-port" name="port" value="9999"/> + </instance_attributes> + </primitive> + +The order in which ``instance_attributes`` objects are evaluated is determined +by their score (highest to lowest). If not supplied, the score defaults to +zero. Objects with an equal score are processed in their listed order. If the +``instance_attributes`` object has no rule, or a ``rule`` that evaluates to +``true``, then for any parameter the resource does not yet have a value for, +the resource will use the parameter values defined by the ``instance_attributes``. + +For example, given the configuration above, if the resource is placed on +``node1``: + +* ``special-node1`` has the highest score (3) and so is evaluated first; its + rule evaluates to ``true``, so ``interface`` is set to ``eth1``. +* ``special-node2`` is evaluated next with score 2, but its rule evaluates to + ``false``, so it is ignored. +* ``defaults`` is evaluated last with score 1, and has no rule, so its values + are examined; ``interface`` is already defined, so the value here is not + used, but ``port`` is not yet defined, so ``port`` is set to ``9999``. + +Using Rules to Control Resource Defaults +________________________________________ + +Rules can be used for resource and operation defaults. The following example +illustrates how to set a different ``resource-stickiness`` value during and +outside work hours. This allows resources to automatically move back to their +most preferred hosts, but at a time that (in theory) does not interfere with +business activities. + +.. topic:: Change ``resource-stickiness`` during working hours + + .. code-block:: xml + + <rsc_defaults> + <meta_attributes id="core-hours" score="2"> + <rule id="core-hour-rule" score="0"> + <date_expression id="nine-to-five-Mon-to-Fri" operation="date_spec"> + <date_spec id="nine-to-five-Mon-to-Fri-spec" hours="9-16" weekdays="1-5"/> + </date_expression> + </rule> + <nvpair id="core-stickiness" name="resource-stickiness" value="INFINITY"/> + </meta_attributes> + <meta_attributes id="after-hours" score="1" > + <nvpair id="after-stickiness" name="resource-stickiness" value="0"/> + </meta_attributes> + </rsc_defaults> + +Rules may be used similarly in ``instance_attributes`` or ``utilization`` +blocks. + +Any single block may directly contain only a single rule, but that rule may +itself contain any number of rules. + +``rsc_expression`` and ``op_expression`` blocks may additionally be used to +set defaults on either a single resource or across an entire class of resources +with a single rule. ``rsc_expression`` may be used to select resource agents +within both ``rsc_defaults`` and ``op_defaults``, while ``op_expression`` may +only be used within ``op_defaults``. If multiple rules succeed for a given +resource agent, the last one specified will be the one that takes effect. As +with any other rule, boolean operations may be used to make more complicated +expressions. + +.. topic:: Default all IPaddr2 resources to stopped + + .. code-block:: xml + + <rsc_defaults> + <meta_attributes id="op-target-role"> + <rule id="op-target-role-rule" score="INFINITY"> + <rsc_expression id="op-target-role-expr" class="ocf" provider="heartbeat" + type="IPaddr2"/> + </rule> + <nvpair id="op-target-role-nvpair" name="target-role" value="Stopped"/> + </meta_attributes> + </rsc_defaults> + +.. topic:: Default all monitor action timeouts to 7 seconds + + .. code-block:: xml + + <op_defaults> + <meta_attributes id="op-monitor-defaults"> + <rule id="op-monitor-default-rule" score="INFINITY"> + <op_expression id="op-monitor-default-expr" name="monitor"/> + </rule> + <nvpair id="op-monitor-timeout" name="timeout" value="7s"/> + </meta_attributes> + </op_defaults> + +.. topic:: Default the timeout on all 10-second-interval monitor actions on ``IPaddr2`` resources to 8 seconds + + .. code-block:: xml + + <op_defaults> + <meta_attributes id="op-monitor-and"> + <rule id="op-monitor-and-rule" score="INFINITY"> + <rsc_expression id="op-monitor-and-rsc-expr" class="ocf" provider="heartbeat" + type="IPaddr2"/> + <op_expression id="op-monitor-and-op-expr" name="monitor" interval="10s"/> + </rule> + <nvpair id="op-monitor-and-timeout" name="timeout" value="8s"/> + </meta_attributes> + </op_defaults> + + +.. index:: + pair: rule; cluster option + +Using Rules to Control Cluster Options +______________________________________ + +Controlling cluster options is achieved in much the same manner as specifying +different resource options on different nodes. + +The following example illustrates how to set ``maintenance_mode`` during a +scheduled maintenance window. This will keep the cluster running but not +monitor, start, or stop resources during this time. + +.. topic:: Schedule a maintenance window for 9 to 11 p.m. CDT Sept. 20, 2019 + + .. code-block:: xml + + <crm_config> + <cluster_property_set id="cib-bootstrap-options"> + <nvpair id="bootstrap-stonith-enabled" name="stonith-enabled" value="1"/> + </cluster_property_set> + <cluster_property_set id="normal-set" score="10"> + <nvpair id="normal-maintenance-mode" name="maintenance-mode" value="false"/> + </cluster_property_set> + <cluster_property_set id="maintenance-window-set" score="1000"> + <nvpair id="maintenance-nvpair1" name="maintenance-mode" value="true"/> + <rule id="maintenance-rule1" score="INFINITY"> + <date_expression id="maintenance-date1" operation="in_range" + start="2019-09-20 21:00:00 -05:00" end="2019-09-20 23:00:00 -05:00"/> + </rule> + </cluster_property_set> + </crm_config> + +.. important:: The ``cluster_property_set`` with an ``id`` set to + "cib-bootstrap-options" will *always* have the highest priority, + regardless of any scores. Therefore, rules in another + ``cluster_property_set`` can never take effect for any + properties listed in the bootstrap set. |