Page MenuHomeClusterLabs Projects

Improve terminology for clarity
Open, WishlistPublic

Assigned To
None
Authored By
kgaillot
Mon, Mar 18, 5:01 PM
Tags
  • Restricted Project
  • Restricted Project
  • Restricted Project
Referenced Files
None
Subscribers

Description

Pacemaker uses a lot of jargon, some of it poorly defined. More consistent and natural language would be easier for users and developers, especially new ones.

Problems

Attribute, option, parameter, property, and setting are often used interchangeably. Then we have instance attributes, meta-attributes, utilization attributes, node attributes, and XML attributes, which are mostly unrelated despite using the same term. All of these except XML attributes use the obscurely named nvpair element for individual values. We have historically used set to indicate a single XML element (instance_attributes, meta_attributes, etc.) containing a collection of nvpair elements (and optionally rules), but this can be confused with resource sets and set as a verb.

Similarly, we tend to use action, command, op, operation, request, and task somewhat interchangeably.

Acronyms (like CIB, CRM, DC, and STONITH) tend to be confusing for beginners. It's not essential to eliminate these entirely (hello XML), but more natural phrasing (such as fencing instead of stonith) should be used when available.

When we come up with a good system, we can update the code and documentation, and update the schema to accept either the old or new names (later using an XSL transform at a major or minor version bump to ensure the new names are always used). We can create subtasks for specific changes so it can be done in reasonable pieces.

Definite changes

  • Use metadata (no hyphen, to follow the dictionary spelling) instead of meta-data, except when referring to the OCF-defined action name
  • Use primitive instead of native
  • Use primary instead of lh, and dependent instead of rh, when referring to constraints
  • Use assign instead of allocate for associating resources with nodes
  • Use score instead of weight
  • Use self-fencing instead of suicide (T279)
  • Continue to use message for IPC and CPG messages (sometimes divided into requests and replies)

Likely changes still open to discussion

  • Use agent parameters or parameters instead of instance attributes (so we have resource agent parameters or resource parameters, alert agent parameters or alert parameters, etc.; note that this is consistent with the OCF standard's usage)
  • Use options for Pacemaker-defined settings, so we have cluster options, resource options, alert options, etc.). This would replace meta-attributes as a generic term, and would cover both meta_attributes blocks ad XML attributes in the CIB. Note that we allow users to set custom meta-attributes (see T813), so we need a separate name for those.
  • Use action instead of task, operation, or op to refer to a generic action name (start, stop, etc.), for consistency with the OCF standard
  • Use standard instead of class for resource agents, except when referring to a literal setting name

Other possibilities for discussion

  • Replace nvpair with something more natural (maybe setting, property, or variable) as a generic reference for an option, agent parameter, node attribute, or utilization attribute. Alternatively, we could use separate elements for option, parameter, etc.
  • Maybe replace set with something more distinctive (such as collection or block) for a grouping of nvpairs
  • Maybe replace attribute for node and utilization attributes (maybe following the nvpair replacement), so attribute refers solely to XML attributes
  • Use operation (or maybe task) instead of action or op to refer to a specific instance of an action executed for a particular resource and node

CIB syntax

Here is a hypothetical example of what CIB syntax changes might look like (see also T814):

<cib ...>                       | <cib ...>
  <configuration>               |   <configuration>
    <crm_config>                |     <cluster>
      <cluster_property_set>    |       <options>
        <nvpair ... />          |         <setting ... />
      </cluster_property_set>   |       </options>
    </crm_config>               |     </cluster>
    <nodes>                     |     <nodes>
      ...                       |       ...
    </nodes>                    |     </nodes>
    <resources>                 |     <resources>
      <primitive ...>           |       <resource ...>
        <meta_attributes>       |         <options>
          <nvpair ... />        |           <setting ... />
        </meta_attributes>      |         </options>
        <instance_attributes>   |         <agent_parameters>
          <nvpair ... />        |           <setting ... />
        </instance_attributes>  |         </agent_parameters>
      </primitive>              |       </resource>
    </resources>                |     </resources>
  </configuration>              |   </configuration>
    ...                         |   ...
</cib>                        | </cib>

Related Objects

StatusAssignedTask
OpenNone
OpenNone
OpenNone

Event Timeline

kgaillot triaged this task as Wishlist priority.Mon, Mar 18, 5:01 PM
kgaillot created this task.
kgaillot created this object with edit policy "Restricted Project (Project)".
kgaillot added subtasks: Restricted Maniphest Task, Restricted Maniphest Task, Restricted Maniphest Task, Restricted Maniphest Task, Restricted Maniphest Task.
kgaillot updated the task description. (Show Details)
kgaillot added a parent task: Restricted Maniphest Task.