Bug 1507548

The resource-discovery option is not supported in the "pcs constraint location <resource> prefers|avoids" command. To set the resource-discovery options, use the "pcs constraint location add" command.


According to documentation:
location <resource> prefers <node>[=<score>] [<node>[=<score>]]...
Create a location constraint on a resource to prefer the specified node with score (default score: INFINITY).

# pcs constraint location vg_svtlatat51clu_appvg_00 avoids node1 resource-discovery=never
This means: set score -INFINITY for node "node1", set score "never" for node "resource-discovery".

# pcs constraint location vg_svtlatat51clu_appvg_00 avoids node1 INFINITY resource-discovery=never
This means: set score -INFINITY for node "node1", set score -INFINITY for node "INFINITY", set score "never" for node "resource-discovery".

# pcs constraint location vg_svtlatat51clu_appvg_00 avoids node1 resource-discovery never
This means: set score -INFINITY for node "node1", set score -INFINITY for node "resource-discovery", set score -INFINITY for node "never".

Created constraints match the expectation and documentation.


Pcs does check for score validity as you can clearly see from the error messages:
Error: invalid score 'never', use integer or INFINITY or -INFINITY

Pcs cannot check for hostname validity, such a check would:
a) block a possibility to create a constraint for a node which is going to be added to a cluster later
b) break backward compatibility


I do not see any bug here.

The only thing to improve in pcs is make it not to create any constraint if the command as a whole is not valid. If that is of no concern I would close this as not a bug.

Thanks for clarification Tomas, that makes sense. I guess the content of table 7.1 in our docs followed by example command which utilizes prefer/avoid notation is source of confusion here:

https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html-single/high_availability_add-on_reference/#tb-locationconstraint-options-HAAR


So maybe the documentation needs tweaking to avoid assumption that prefer/avoid notation apply to setting resource-discovery parameter.

Moving to documentation to consider an improvement / clarification of the location constraints section.


How about splitting the chapter to three parts:

0. An introduction, which is basically the current first paragraph.

1. The simplest constraints:
* the easiest way to create a constraint - a resource prefers or avoids a node, optionally set score
* easy to do but does not support any advanced options
* pcs constraint location <rsc> avoids|prefers <node>[=<score>] [<node>[=<score>]]...
* '[<node>[=<score>]]' before ... indicates it is possible to create constraints for more nodes with the same resource in one command and that there is no place for other options
* From "Table 7.1. Location Constraint Options" use just the rsc, node and score options

2. Advanced location constraints:
* A bit more complicated command which allows to set more options
* pcs constraint location add <id> <rsc> <node> <score> [resource-discovery=<option>]
* Explain the resource-discovery option here.

3. Location constraints with rules:
* The most complicated and the most powerful way of creating location constraints
* pcs constraint location <rsc> rule ... (see pcs help for details)
* Seems to be already described in Chapter 11. Pacemaker Rules. However, it misses description of built-in node attributes (Table 8.3. Built-in node attributes in Pacemaker Explained) which I think are quite important - they for example allow to create a constraint which prefers full-stack nodes over remote nodes by using the #kind attribute (There was a question about this recently: https://github.com/ClusterLabs/pcs/issues/156#issuecomment-347464261 ).
* Looking at the Chapter 11 quickly, it seems to be a bit outdated as the location rule command has been improved in pcs and those improvements do not seem to be covered in the documentation. The last piece, "The expression can be one of the following:", is not correct any more, check pcs help.


Also the possibility of specifying resources in location constraints using regular expressions should be documented: bz1362493

This slipped through the cracks (I'm doing a post 7.5-GA assessment).  Moving this up in priority to address soon.

Tomas:

Thanks for the analyis and thought for how to fix/improve the documentation on location constraints. I think I have enough to get started here. The documentation here (and in chapter 11, the chapter on rules) has been here since 7.0 and was based at the time on what was in Pacemaker Explained.

Do you think I should leave in the information about "opt-in" and "opt-out" clusters, as is, in the first section (on "simple" contraints), or does that complicate things?

Steven

Steven,

The opt-in and opt-out cluster parts are definitely worth keeping. However, I would rather put them in the same level as simple constraints instead of making them a sub-chapter of it. The reason is, if they are included in the simple constraints part, it may lead people to thinking that the opt-in and opt-out only apply when simple constraints are used, which is not true. Using simple, advanced as well as rule constraints in opt-in and opt-out examples may help as well to realize it is a general principle and the form or type of constraints does not matter there.

Tomas

Link to table 8.3 noted in Comment 4:

https://clusterlabs.org/pacemaker/doc/en-US/Pacemaker/1.1/html/Pacemaker_Explained/_node_attribute_expressions.html

Just to keep this here -- the help display for score expression in a rule, as referenced in part 3 of comment 4, is as follows:

   rule add <constraint id> [id=<rule id>] [role=master|slave]
             [score=<score>|score-attribute=<attribute>] <expression>
        Add a rule to a constraint where the expression looks like one of
        the following:
          defined|not_defined <attribute>
          <attribute> lt|gt|lte|gte|eq|ne [string|integer|version] <value>
          date gt|lt <date>
          date in_range <date> to <date>
          date in_range <date> to duration <duration options>...
          date-spec <date spec options>...
          <expression> and|or <expression>
          ( <expression> )
        where duration options and date spec options are: hours, monthdays,
        weekdays, yeardays, months, weeks, years, weekyears, moon.
        If score is omitted it defaults to INFINITY. If id is omitted one is
        generated from the constraint id.

FORGET comment 9.  This is the command under discussion:


pcs constraint location <resource> rule [id=<rule id>] [resource-discovery=<option>]
             [role=master|slave] [constraint-id=<id>]
             [score=<score> | score-attribute=<attribute>] <expression>
        Creates a location rule on the specified resource where the expression
        looks like one of the following:
          defined|not_defined <attribute>
          <attribute> lt|gt|lte|gte|eq|ne [string|integer|version] <value>
          date gt|lt <date>
          date in_range <date> to <date>
          date in_range <date> to duration <duration options>...
          date-spec <date spec options>...
          <expression> and|or <expression>
          ( <expression> )
        where duration options and date spec options are: hours, monthdays,
        weekdays, yeardays, months, weeks, years, weekyears, moon.
        Resource may be either a resource id <resource_id> or %<resource_id> or
        resource%<resource_id>, or a resource name regular expression
        regexp%<resource_pattern>. If score is omitted it defaults to INFINITY.
        If id is omitted one is generated from the resource id. If
        resource-discovery is omitted it defaults to 'always'.

*** Bug 1129869 has been marked as a duplicate of this bug. ***

The updated section on location constraints is now on the Customer Portal:

https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html-single/high_availability_add-on_reference/index#s1-locationconstraints-HAAR

Updated document on Portal:

https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html-single/high_availability_add-on_reference/index#ch-resourceconstraints-HAAR