diff --git a/docs/modeldescr/actions.rst b/docs/modeldescr/actions.rst index 715f1ce2..1a5ef27b 100644 --- a/docs/modeldescr/actions.rst +++ b/docs/modeldescr/actions.rst @@ -12,8 +12,8 @@ data to modules. The following rules are applied to an action: - - An action is a consumer of facts of an entity - - One action applies only to one fact, but it may statically refer facts from other entities + - An action is a consumer of claims of an entity + - One action applies only to one claim, but it may statically refer claims from other entities Synopsis -------- @@ -78,7 +78,7 @@ Below is the description of configuration sections: If actions processing the system in a serial fashion without knowing what it is even discovered, then how exactly the state is determined? - They are not. An entity anyway is checked through all defined states. If facts are matching for one particular state, + They are not. An entity anyway is checked through all defined states. If claims are matching for one particular state, it is concluded that the device is in this state. Another option is to pass an argument to a module of a state. So if a module is able to request a state, then it can match the return result accordingly. @@ -150,25 +150,25 @@ Given there are entities, such as ``syslogd``, ``systemd`` etc, one can bind an .. warning:: - The *minimal* data structure of a facts must be identical! + The *minimal* data structure of a claims must be identical! -In this example of two entities that have additional facts and one action that is checking +In this example of two entities that have additional claims and one action that is checking those processes. Module ``sys.proc`` receives a flag ``is-running`` which puts it to a -process checking mode, accepting ``process`` parameter of a currently processed fact. +process checking mode, accepting ``process`` parameter of a currently processed claim. In this case, ``sys.proc`` will accept ``/sbin/init`` and ``/usr/bin/syslogd`` file. -The fact ``discspace`` from ``my-special`` fact will be omitted. +The claim ``discspace`` from ``my-special`` claim will be omitted. .. code-block:: yaml entities: systemd: - facts: - my-fact: + claims: + my-claim: - default: path: /sbin/init syslogd: - facts: + claims: my-special: - default: path: /usr/bin/syslogd @@ -198,7 +198,7 @@ to the Shell expression as such: ``$MY_VAR``. a clear arguments without complex interpolations. In some rare cases one might create a comma-separated string, if that is very necessary: - ``myfact: "claim(foo),claim(bar)"``, however this is very discouraged practice and it is strongly + ``myclaim: "claim(foo),claim(bar)"``, however this is very discouraged practice and it is strongly recommended to change the module so it accepts a list of values instead of a comma-separated string. Another example, showing static data references. Consider the following configuration: @@ -209,7 +209,7 @@ Another example, showing static data references. Consider the following configur # An entity, describing a static configuration systemconf: descr: static system configuration - facts: + claims: default: - storage: type: SSD @@ -223,7 +223,7 @@ Another example, showing static data references. Consider the following configur syslogd-possible: # Description of the action that will be logged # The shorter, the better - description: Validate syslogd facts + description: Validate syslogd claims # Path to the module namespace. # Modules are located in $module_root and namespace @@ -238,7 +238,7 @@ Another example, showing static data references. Consider the following configur $: args: # Variable $(foo.bar) always refers to a full path from the document root. - - free-disk: "static(entities.syslogd.facts.storage.free)" - - free-mem: "static(entities.systemconf.facts.mem.free)" + - free-disk: "static(entities.syslogd.claims.storage.free)" + - free-mem: "static(entities.systemconf.claims.mem.free)" -In the example above, function ``static(....)`` can statically reach any defined value of a fact. +In the example above, function ``static(....)`` can statically reach any defined value of a claim. diff --git a/docs/modeldescr/constraints.rst b/docs/modeldescr/constraints.rst index 0f27c708..4de071bd 100644 --- a/docs/modeldescr/constraints.rst +++ b/docs/modeldescr/constraints.rst @@ -6,13 +6,13 @@ Constraints This document explains how constraints work and what they are for. Constraints are declarative logic carriers. They provide clear rules what to *consume* within -a specific fact. +a specific claim. .. important:: The following rules are applied to a constraint: - - It provides declarative logic for modules those are consuming a specific fact + - It provides declarative logic for modules those are consuming a specific claim - It operates on actions, using entities's data Synopsis @@ -110,7 +110,7 @@ Example entities: # NOTE: An id of an entity, referred by a constraint below addresses: - facts: + claims: $: - wifi: if: wlp0s20f3 diff --git a/docs/modeldescr/entities.rst b/docs/modeldescr/entities.rst index 01fbc04e..12bbd7fc 100644 --- a/docs/modeldescr/entities.rst +++ b/docs/modeldescr/entities.rst @@ -8,7 +8,7 @@ The element ``entitles`` is the basis of the model. It contains the entire inven of a system in a CMDB fashion. Each entity can be described in a specific manner, holding all the -necessary attributes, facts, claims and other data that must be +necessary attributes, claims and other data that must be understood by the corresponding consumers. Consumers are actions that call specific modules, and constraints that process them. @@ -17,14 +17,14 @@ call specific modules, and constraints that process them. Entities the the following rules: - An entity is independent of the specific architecture of a system - - An entity may contain only self-applied facts, describing only that particular entity. + - An entity may contain only self-applied claims, describing only that particular entity. - A single entity exists on its own and is unaware of other entities. - A compound entity exists only when all its parts are active. Synopsis -------- -Entitles describe facts and relations within the architecture. These expectations should +Entitles describe claims and relations within the architecture. These expectations should be aligned with constraints. Each entity has a **true** or **false** state. A "true" state is when all constraints and checks produce the expected result. @@ -32,7 +32,7 @@ all constraints and checks produce the expected result. Each entity is a map. A map starts with an "id" and then contains the necessary attributes. The current attributes of an "entity" are as follows: -1. ``facts`` *(required)* contains all data to be consumed by any module, check, or constraint, which must be true in the end. +1. ``claims`` *(required)* contains all data to be consumed by any module, check, or constraint, which must be true in the end. 2. ``consists`` *(optional)* It is only for collection entities (e.g., a network) and contains a list of other single entities that together form such a collection. This determines the operational state of the entity **itself**. 3. ``depends`` *(optional)* It is for defining which other entities are required for this entity to be functional. @@ -50,7 +50,7 @@ Here is the full entity description: : inherits: - - facts: + claims: :