diff options
Diffstat (limited to '')
| -rw-r--r-- | doc/sphinx/Pacemaker_Explained/rules.rst | 1293 |
1 files changed, 745 insertions, 548 deletions
diff --git a/doc/sphinx/Pacemaker_Explained/rules.rst b/doc/sphinx/Pacemaker_Explained/rules.rst index e9d85e0..13134da 100644 --- a/doc/sphinx/Pacemaker_Explained/rules.rst +++ b/doc/sphinx/Pacemaker_Explained/rules.rst @@ -6,226 +6,103 @@ 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: +Rules make a configuration more dynamic, allowing values to depend on +conditions such as time of day or the value of a node attribute. For example, +rules can: * Set a higher value for :ref:`resource-stickiness <resource-stickiness>` - during working hours, to minimize downtime, and a lower value on weekends, to + 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. + around * Automatically place the cluster into maintenance mode during a scheduled - maintenance window. + 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. +* Restrict a particular department's resources to run on certain nodes, as + determined by custom resource meta-attributes and node attributes .. 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. + pair: rule; XML element + pair: rule; options +Rule Options +############ -.. index:: - single: rule; node attribute expression - single: node attribute; rule expression - pair: XML element; expression +Each context that supports rules may contain a single ``rule`` element. -.. _node_attribute_expressions: +.. list-table:: **Attributes of a rule Element** + :class: longtable + :widths: 2 2 2 5 + :header-rows: 1 + + * - Name + - Type + - Default + - Description + + * - .. _rule_id: + + .. index:: + pair: rule; id + + id + - :ref:`id <id>` + - + - A unique name for this element (required) + * - .. _boolean_op: + + .. index:: + pair: rule; boolean-op + + boolean-op + - :ref:`enumeration <enumeration>` + - ``and`` + - How to combine conditions if this rule contains more than one. Allowed + values: + + * ``and``: the rule is satisfied only if all conditions are satisfied + * ``or``: the rule is satisfied if any condition is satisfied + +.. _rule_conditions: -Node Attribute Expressions -########################## +.. index:: + single: rule; conditions + single: rule; contexts -Expressions are rule conditions based on the values of node attributes. +Rule Conditions and Contexts +############################ -.. 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) | - +--------------+---------------------------------+-------------------------------------------+ +A ``rule`` element must contain one or more conditions. A condition is any of +the following, which will be described in more detail later: -.. _node-attribute-expressions-special: +* a :ref:`date/time expression <date_expression>` +* a :ref:`node attribute expression <node_attribute_expressions>` +* a :ref:`resource type expression <rsc_expression>` +* an :ref:`operation type expression <op_expression>` +* another ``rule`` (allowing for complex combinations of conditions) -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. +Each type of condition is allowed only in certain contexts. Although any given +context may contain only one ``rule`` element, that element may contain any +number of conditions, including other ``rule`` elements. -.. table:: **Built-in Node Attributes** - :widths: 1 4 +Rules may be used in the following contexts, which also will be described in +more detail later: - +---------------+-----------------------------------------------------------+ - | 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)* | +* a :ref:`location constraint <location_rule>` +* a :ref:`cluster_property_set <cluster_options>` element (within the + ``crm_config`` element) +* an :ref:`instance_attributes <option_rule>` element (within an ``alert``, + ``bundle``, ``clone``, ``group``, ``node``, ``op``, ``primitive``, + ``recipient``, or ``template`` element) +* a :ref:`meta_attributes <option_rule>` element (within an ``alert``, + ``bundle``, ``clone``, ``group``, ``op``, ``op_defaults``, ``primitive``, + ``recipient``, ``rsc_defaults``, or ``template`` element) +* a :ref:`utilization <option_rule>` element (within a ``node``, ``primitive``, + or ``template`` element) +.. _date_expression: + .. index:: single: rule; date/time expression pair: XML element; date_expression @@ -233,66 +110,77 @@ in rule expressions. Date/Time Expressions ##################### -Date/time expressions are rule conditions based (as the name suggests) on the -current date and time. +The ``date_expression`` element configures a rule condition based on the +current date and time. It is allowed in rules in any context. -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. +It may contain a ``date_spec`` or ``duration`` element depending on the +``operation`` as described below. +.. list-table:: **Attributes of a date_expression Element** + :class: longtable + :widths: 1 1 1 4 + :header-rows: 1 + + * - Name + - Type + - Default + - Description + * - .. _date_expression_id: + + .. index:: + pair: date_expression; id + + id + - :ref:`id <id>` + - + - A unique name for this element (required) + * - .. _date_expression_start: + + .. index:: + pair: date_expression; start + + start + - :ref:`ISO 8601 <iso8601>` + - + - The beginning of the desired time range. Meaningful with an + ``operation`` of ``in_range`` or ``gt``. + * - .. _date_expression_end: + + .. index:: + pair: date_expression; end + + end + - :ref:`ISO 8601 <iso8601>` + - + - The end of the desired time range. Meaningful with an ``operation`` of + ``in_range`` or ``lt``. + * - .. _date_expression_operation: + + .. index:: + pair: date_expression; operation + + operation + - :ref:`enumeration <enumeration>` + - ``in_range`` + - Specifies how to compare the current date/time against a desired time + range. Allowed values: + + * ``gt:`` The expression is satisfied if the current date/time is after + ``start`` (which is required) + * ``lt:`` The expression is satisfied if the current date/time is before + ``end`` (which is required) + * ``in_range:`` The expression is satisfied if the current date/time is + greater than or equal to ``start`` (if specified) and less than or + equal to either ``end`` (if specified) or ``start`` plus the value of + the :ref:`duration <duration_element>` element (if one is contained in + the ``date_expression``). At least one of ``start`` or ``end`` must be + specified. If both ``end`` and ``duration`` are specified, + ``duration`` is ignored. + * ``date_spec:`` The expression is satisfied if the current date/time + matches the specification given in the contained + :ref:`date_spec <date_spec>` element (which is required) + +.. _date_spec: .. index:: single: date specification @@ -301,87 +189,142 @@ A ``date_expression`` element may optionally contain a ``date_spec`` or 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. +A ``date_spec`` element is used within a ``date_expression`` to specify a +combination of dates and times that satisfy the expression. + +.. list-table:: **Attributes of a date_spec Element** + :class: longtable + :widths: 1 1 1 4 + :header-rows: 1 + + * - Name + - Type + - Default + - Description + * - .. _date_spec_id: + + .. index:: + pair: date_spec; id + + id + - :ref:`id <id>` + - + - A unique name for this element (required) + * - .. _date_spec_seconds: + + .. index:: + pair: date_spec; seconds + + seconds + - :ref:`range <range>` + - + - If this is set, the expression is satisfied only if the current time's + second is within this range. Allowed integers: 0 to 59. + * - .. _date_spec_minutes: + + .. index:: + pair: date_spec; minutes + + minutes + - :ref:`range <range>` + - + - If this is set, the expression is satisfied only if the current time's + minute is within this range. Allowed integers: 0 to 59. + * - .. _date_spec_hours: + + .. index:: + pair: date_spec; hours + + hours + - :ref:`range <range>` + - + - If this is set, the expression is satisfied only if the current time's + hour is within this range. Allowed integers: 0 to 23 where 0 is midnight + and 23 is 11 p.m. + * - .. _date_spec_monthdays: + + .. index:: + pair: date_spec; monthdays + + monthdays + - :ref:`range <range>` + - + - If this is set, the expression is satisfied only if the current date's + day of the month is in this range. Allowed integers: 1 to 31. + * - .. _date_spec_weekdays: + + .. index:: + pair: date_spec; weekdays + + weekdays + - :ref:`range <range>` + - + - If this is set, the expression is satisfied only if the current date's + ordinal day of the week is in this range. Allowed integers: 1-7 (where 1 + is Monday and 7 is Sunday). + * - .. _date_spec_yeardays: + + .. index:: + pair: date_spec; yeardays + + yeardays + - :ref:`range <range>` + - + - If this is set, the expression is satisfied only if the current date's + ordinal day of the year is in this range. Allowed integers: 1-366. + * - .. _date_spec_months: + + .. index:: + pair: date_spec; months + + months + - :ref:`range <range>` + - + - If this is set, the expression is satisfied only if the current date's + month is in this range. Allowed integers: 1-12 where 1 is January and 12 + is December. + * - .. _date_spec_weeks: + + .. index:: + pair: date_spec; weeks + + weeks + - :ref:`range <range>` + - + - If this is set, the expression is satisfied only if the current date's + ordinal week of the year is in this range. Allowed integers: 1-53. + * - .. _date_spec_years: + + .. index:: + pair: date_spec; years + + years + - :ref:`range <range>` + - + - If this is set, the expression is satisfied only if the current date's + year according to the Gregorian calendar is in this range. + * - .. _date_spec_weekyears: + + .. index:: + pair: date_spec; weekyears + + weekyears + - :ref:`range <range>` + - + - If this is set, the expression is satisfied only if the current date's + year in which the week started (according to the ISO 8601 standard) is + in this range. + * - .. _date_spec_moon: + + .. index:: + pair: date_spec; moon + + moon + - :ref:`range <range>` + - + - If this is set, the expression is satisfied only if the current date's + phase of the moon is in this range. Allowed values are 0 to 7 where 0 is + the new moon and 4 is the full moon. *(deprecated since 2.1.6)* .. note:: Pacemaker can calculate when evaluation of a ``date_expression`` with an ``operation`` of ``gt``, ``lt``, or ``in_range`` will next change, @@ -400,6 +343,8 @@ are not supported. need to perform first, and the load of the machine. +.. _duration_element: + .. index:: single: duration pair: XML element; duration @@ -407,64 +352,97 @@ are not supported. 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 +A ``duration`` element is used within a ``date_expression`` to calculate an +ending value for ``in_range`` operations when ``end`` is not supplied. + +.. list-table:: **Attributes of a duration Element** + :class: longtable + :widths: 1 1 1 4 + :header-rows: 1 + + * - Name + - Type + - Default + - Description + * - .. _duration_id: + + .. index:: + pair: duration; id + + id + - :ref:`id <id>` + - + - A unique name for this element (required) + * - .. _duration_seconds: + + .. index:: + pair: duration; seconds + + seconds + - :ref:`integer <integer>` + - 0 + - Number of seconds to add to the total duration + * - .. _duration_minutes: + + .. index:: + pair: duration; minutes + + minutes + - :ref:`integer <integer>` + - 0 + - Number of minutes to add to the total duration + * - .. _duration_hours: + + .. index:: + pair: duration; hours + + hours + - :ref:`integer <integer>` + - 0 + - Number of hours to add to the total duration + * - .. _duration_days: + + .. index:: + pair: duration; days + + days + - :ref:`integer <integer>` + - 0 + - Number of days to add to the total duration + * - .. _duration_weeks: + + .. index:: + pair: duration; weeks + + weeks + - :ref:`integer <integer>` + - 0 + - Number of weeks to add to the total duration + * - .. _duration_months: + + .. index:: + pair: duration; months + + months + - :ref:`integer <integer>` + - 0 + - Number of months to add to the total duration + * - .. _duration_years: + + .. index:: + pair: duration; years + + years + - :ref:`integer <integer>` + - 0 + - Number of years to add to the total duration + + +Example Date/Time Expressions +_____________________________ + + +.. topic:: Satisfied if the current year is 2005 .. code-block:: xml @@ -497,7 +475,7 @@ A small sample of how time-based expressions can be used: 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 +.. topic:: 9 a.m. to 6 p.m. Monday through Friday, or anytime Saturday .. code-block:: xml @@ -538,63 +516,227 @@ A small sample of how time-based expressions can be used: </date_expression> <date_expression id="date_expr6-2" operation="in_range" start="2005-03-01" end="2005-04-01"/> + </date_expression> </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. + only the first second of 2005-04-01. You may wish to write ``end`` + as ``"2005-03-31T23:59:59"`` to avoid confusion. .. index:: + single: rule; node attribute expression + single: node attribute; rule expression + pair: XML element; expression + +.. _node_attribute_expressions: + +Node Attribute Expressions +########################## + +The ``expression`` element configures a rule condition based on the value of a +node attribute. It is allowed in rules in location constraints and in +``instance_attributes`` elements within ``bundle``, ``clone``, ``group``, +``op``, ``primitive``, and ``template`` elements. + +.. list-table:: **Attributes of an expression Element** + :class: longtable + :widths: 1 1 3 5 + :header-rows: 1 + + * - Name + - Type + - Default + - Description + + * - .. _expression_id: + + .. index:: + pair: expression; id + + id + - :ref:`id <id>` + - + - A unique name for this element (required) + * - .. _expression_attribute: + + .. index:: + pair: expression; attribute + + attribute + - :ref:`text <text>` + - + - Name of the node attribute to test (required) + * - .. _expression_operation: + + .. index:: + pair: expression; operation + + operation + - :ref:`enumeration <enumeration>` + - + - The comparison to perform (required). Allowed values: + + * ``defined:`` The expression is satisfied if the node has the named + attribute + * ``not_defined:`` The expression is satisfied if the node does not have + the named attribute + * ``lt:`` The expression is satisfied if the node attribute value is + less than the reference value + * ``gt:`` The expression is satisfied if the node attribute value is + greater than the reference value + * ``lte:`` The expression is satisfied if the node attribute value is + less than or equal to the reference value + * ``gte:`` The expression is satisfied if the node attribute value is + greater than or equal to the reference value + * ``eq:`` The expression is satisfied if the node attribute value is + equal to the reference value + * ``ne:`` The expression is satisfied if the node attribute value is not + equal to the reference value + * - .. _expression_type: + + .. index:: + pair: expression; type + + type + - :ref:`enumeration <enumeration>` + - The default type for ``lt``, ``gt``, ``lte``, and ``gte`` operations is + ``number`` if either value contains a decimal point character, or + ``integer`` otherwise. The default type for all other operations is + ``string``. If a numeric parse fails for either value, then the values + are compared as type ``string``. + - How to interpret values. Allowed values are ``string``, ``integer`` + *(since 2.0.5)*, ``number``, and ``version``. ``integer`` truncates + floating-point values if necessary before performing a 64-bit integer + comparison. ``number`` performs a double-precision floating-point + comparison *(32-bit integer before 2.0.5)*. + * - .. _expression_value: + + .. index:: + pair: expression; value + + value + - :ref:`text <text>` + - + - Reference value to compare node attribute against (used only with, and + required for, operations other than ``defined`` and ``not_defined``) + * - .. _expression_value_source: + + .. index:: + pair: expression; value-source + + value-source + - :ref:`enumeration <enumeration>` + - ``literal`` + - How the reference value is obtained. Allowed values: + + * ``literal``: ``value`` contains the literal reference value to compare + * ``param``: ``value`` contains the name of a resource parameter to + compare (valid only in the context of a location constraint) + * ``meta``: ``value`` is the name of a resource meta-attribute to + compare (valid only in the context of a location constraint) + +.. _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. + +.. list-table:: **Built-in Node Attributes** + :class: longtable + :widths: 1 4 + :header-rows: 1 + + * - Name + - Description + * - #uname + - :ref:`Node name <node_name>` + * - #id + - Node ID + * - #kind + - Node type (``cluster`` for cluster nodes, ``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`` + + +.. _rsc_expression: + +.. 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 -__________________________________ +Resource Type Expressions +######################### + +The ``rsc_expression`` element *(since 2.0.5)* configures a rule condition +based on the agent used for a resource. It is allowed in rules in a +``meta_attributes`` element within a ``rsc_defaults`` or ``op_defaults`` +element. + +.. list-table:: **Attributes of a rsc_expression Element** + :class: longtable + :widths: 1 1 1 4 + :header-rows: 1 + + * - Name + - Type + - Default + - Description + * - .. _rsc_expression_id: + + .. index:: + pair: rsc_expression; id + + id + - :ref:`id <id>` + - + - A unique name for this element (required) + * - .. _rsc_expression_class: + + .. index:: + pair: rsc_expression; class + + class + - :ref:`text <text>` + - + - If this is set, the expression is satisfied only if the resource's agent + standard matches this value + * - .. _rsc_expression_provider: + + .. index:: + pair: rsc_expression; provider + + provider + - :ref:`text <text>` + - + - If this is set, the expression is satisfied only if the resource's agent + provider matches this value + * - .. _rsc_expression_type: + + .. index:: + pair: rsc_expression; type -A small sample of how resource-based expressions can be used: + type + - :ref:`text <text>` + - + - If this is set, the expression is satisfied only if the resource's agent + type matches this value -.. topic:: True for all ``ocf:heartbeat:IPaddr2`` resources + +Example Resource Type Expressions +_________________________________ + +.. topic:: Satisfied for ``ocf:heartbeat:IPaddr2`` resources .. code-block:: xml @@ -602,7 +744,7 @@ A small sample of how resource-based expressions can be used: <rsc_expression id="rule_expr1" class="ocf" provider="heartbeat" type="IPaddr2"/> </rule> -.. topic:: Provider doesn't apply to non-OCF resources +.. topic:: Satisfied for ``stonith:fence_xvm`` resources .. code-block:: xml @@ -611,49 +753,64 @@ A small sample of how resource-based expressions can be used: </rule> +.. _op_expression: + .. index:: single: rule; operation expression single: operation; rule expression pair: XML element; op_expression -Operation Expressions -##################### +Operation Type Expressions +########################## + +The ``op_expression`` element *(since 2.0.5)* configures a rule condition based +on a resource operation name and interval. It is allowed in rules in a +``meta_attributes`` element within an ``op_defaults`` element. + +.. list-table:: **Attributes of an op_expression Element** + :class: longtable + :widths: 1 1 1 4 + :header-rows: 1 + + * - Name + - Type + - Default + - Description + * - .. _op_expression_id: + + .. index:: + pair: op_expression; id + + id + - :ref:`id <id>` + - + - A unique name for this element (required) + * - .. _op_expression_name: + + .. index:: + pair: op_expression; name + + name + - :ref:`text <text>` + - + - The expression is satisfied only if the operation's name matches this + value (required) + * - .. _op_expression_interval: + + .. index:: + pair: op_expression; interval + interval + - :ref:`duration <duration>` + - + - If this is set, the expression is satisfied only if the operation's + interval matches this value -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 + +Example Operation Type Expressions +__________________________________ + +.. topic:: Expression is satisfied for all monitor actions .. code-block:: xml @@ -661,7 +818,7 @@ A small sample of how operation-based expressions can be used: <op_expression id="rule_expr1" name="monitor"/> </rule> -.. topic:: True for all monitor actions with a 10 second interval +.. topic:: Expression is satisfied for all monitor actions with a 10-second interval .. code-block:: xml @@ -670,15 +827,68 @@ A small sample of how operation-based expressions can be used: </rule> +.. _location_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. +If a :ref:`location constraint <location-constraint>` contains a rule, the +cluster will apply the constraint to all nodes where the rule is satisfied. +This acts as if identical location constraints without rules were defined for +each of the nodes. + +In the context of a location constraint, ``rule`` elements may take additional +attributes. These have an effect only when set for the constraint's top-level +``rule``; they are ignored if set on a subrule. + +.. list-table:: **Extra Attributes of a rule Element in a Location Constraint** + :class: longtable + :widths: 2 2 1 5 + :header-rows: 1 + + * - Name + - Type + - Default + - Description + + * - .. _rule_role: + + .. index:: + pair: rule; role + + role + - :ref:`enumeration <enumeration>` + - ``Started`` + - If this is set in the constraint's top-level rule, the constraint acts + as if ``role`` were set to this in the ``rsc_location`` element. + + * - .. _rule_score: + + .. index:: + pair: rule; score + + score + - :ref:`score <score>` + - + - If this is set in the constraint's top-level rule, the constraint acts + as if ``score`` were set to this in the ``rsc_location`` element. + Only one of ``score`` and ``score-attribute`` may be set. + + * - .. _rule_score_attribute: + + .. index:: + pair: rule; score-attribute + + score-attribute + - :ref:`text <text>` + - + - If this is set in the constraint's top-level rule, the constraint acts + as if ``score`` were set to the value of this node attribute on each + node where the rule is satisfied. Only one of ``score`` and + ``score-attribute`` may be set. Consider the following simple location constraint: @@ -689,7 +899,7 @@ Consider the following simple location constraint: <rsc_location id="ban-apache-on-node3" rsc="webserver" score="-INFINITY" node="node3"/> -The same constraint can be more verbosely written using a rule: +The same constraint can be written more verbosely using a rule: .. topic:: Prevent resource ``webserver`` from running on node ``node3`` using a rule @@ -703,15 +913,14 @@ The same constraint can be more verbosely written using a 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. +(for example, limiting the constraint to certain days of the week). 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: +The expanded form allows us to match node attributes other than its name. As an +example, consider this configuration of custom node attributes specifying each +node's CPU capacity: .. topic:: Sample node section with node attributes @@ -730,8 +939,7 @@ nodes section: </node> </nodes> -then we could prevent resources from running on underpowered machines with this -rule: +We can use a rule to prevent a resource from running on underpowered machines: .. topic:: Rule using a node attribute (to be used inside a location constraint) @@ -746,11 +954,13 @@ 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``. +rule has its score adjusted according to its value for the named node +attribute. + +In the previous example, if the location constraint rule used +``score-attribute="cpu_mips"`` instead of ``score="-INFINITY"``, node +``c001n01`` would have its preference to run the resource increased by 1234 +whereas node ``c001n02`` would have its preference increased by 5678. .. _s-rsc-pattern-rules: @@ -758,16 +968,15 @@ would have its preference to run the resource increased by ``1234`` whereas 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``. +Location constraints may use :ref:`rsc-pattern <s-rsc-pattern>` to apply the +constraint to all resources whose IDs match the given pattern. The pattern may +contain up to 9 submatches in parentheses, whose values may be used as ``%1`` +through ``%9`` in a ``rule`` element's ``score-attribute`` or an ``expression`` +element'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**. +For example, the following configuration excerpt 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 @@ -807,6 +1016,8 @@ gives the resources **server-httpd** and **ip-httpd** a preference of 100 on </constraints> +.. _option_rule: + .. index:: pair: cluster option; rule pair: instance attribute; rule @@ -820,37 +1031,34 @@ 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 +* :ref:`Cluster options <cluster_options>` (as ``cluster_property_set`` + elements) +* :ref:`Node attributes <node_attributes>` (as ``instance_attributes`` or ``utilization`` elements inside a ``node`` element) -* :ref:`Resource options <resource_options>` (``utilization``, +* :ref:`Resource options <resource_options>` (as ``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`` +* :ref:`Operation options <operation_properties>` (as ``meta_attributes`` elements inside an ``op`` or ``op_defaults`` element) +* :ref:`Alert options <alerts>` (as ``instance_attributes`` or + ``meta_attributes`` elements inside an ``alert`` or ``recipient`` 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 +these differences (for example, 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 +By defining multiple ``instance_attributes`` elements 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. +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 @@ -878,20 +1086,20 @@ for all other nodes. </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``. +Multiple ``instance_attributes`` elements are evaluated from highest score to +lowest. If not supplied, the score defaults to zero. Objects with equal scores +are processed in their listed order. If an ``instance_attributes`` object has +no rule or a satisfied ``rule``, then for any parameter the resource does not +yet have a value for, the resource will use the value 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. + rule is satisfied, so ``interface`` is set to ``eth1``. +* ``special-node2`` is evaluated next with score 2, but its rule is not + satisfied, 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``. @@ -899,11 +1107,12 @@ For example, given the configuration above, if the resource is placed on 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. +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 @@ -923,20 +1132,8 @@ business activities. </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. +``rsc_expression`` is valid within both ``rsc_defaults`` and ``op_defaults``; +``op_expression`` is valid only within ``op_defaults``. .. topic:: Default all IPaddr2 resources to stopped |