From d978525e17c69dfa7717284a2313a0f2773fd40f Mon Sep 17 00:00:00 2001 From: Madhu Kanoor Date: Thu, 14 Sep 2023 09:44:01 -0400 Subject: [PATCH] docs: convert the ruleset attributes to table format (#580) --- docs/rulebooks.rst | 52 +++++++++++++++++++++++++++++++++------------- docs/rules.rst | 10 +++++---- docs/sources.rst | 2 +- 3 files changed, 44 insertions(+), 20 deletions(-) diff --git a/docs/rulebooks.rst b/docs/rulebooks.rst index a28e847a..30fb4277 100644 --- a/docs/rulebooks.rst +++ b/docs/rulebooks.rst @@ -12,14 +12,35 @@ Rulesets -------- A ruleset has the following properties: -* name -* hosts similar to Ansible playbook -* gather_facts: boolean -* default_events_ttl: time to keep the partially matched events around (default is 2 hours) -* match_multiple_rules: should multiple rules be triggered for an event(default is false) -* execution_strategy: How actions should be executed, sequential|parallel (default: sequential). For sequential strategy we wait for each action to finish before we kick off the next action. -* sources: A list of sources -* rules: a list of rules +.. list-table:: + :widths: 25 150 10 + :header-rows: 1 + + * - Name + - Description + - Required + * - name + - The name to identify the ruleset. Each ruleset must have an unique name across the rulebook. + - Yes + * - sources + - The list of one or more sources that will generate events for ansible-rulebook. See :doc:`sources` + - Yes + * - rules + - The list of one or more rule. See :doc:`rules` + - Yes + * - hosts + - Similar to hosts in an Ansible playbook + - Yes + * - gather_facts + - Collect artifacts from hosts at startup to be used in rules (default: false) + - No + * - default_events_ttl + - time to keep the partially matched events around (default: 2 hours) + - No + * - execution_strategy + - Action execution, sequential or parallel (default: sequential). For sequential + strategy we wait for the each action to finish before firing of the next action. + - No | A ruleset **should** have a unique name within the rulebook, each ruleset runs | as a separate session in the Rules engine. The events and facts are kept separate @@ -27,7 +48,7 @@ A ruleset has the following properties: | to itself or other rulesets in the rulebook. | The default_events_ttl takes time in the following format -| default_events_ttl : nnn seconds|minutes|hours|days +| default_events_ttl : **nnn seconds|minutes|hours|days** | e.g. default_events_ttl : 3 hours | If the rule set doesn't define this attribute the default events ttl that is | enforced by the rule engine is 2 hours @@ -61,12 +82,13 @@ A ruleset has the following properties: action: debug: -| A ruleset **must** contain one or more sources, it allows you to pass configuration -| parameters into the source plugin. The Source plugin can also be configured with -| event filters which allow you to transform the data before passing it to the Rules -| engine. The filters can also be used to limit the data that gets passed to the Rules -| engine. The source plugin is started by the **ansible-rulebook** and runs in the -| background putting events into the queue to be passed onto the Rules engine. +| A ruleset **must** contain one or more source plugins, the configuration parameters +| can be specified after the source plugin type. The source plugin +| can also be configured with event filters which allow you to transform the +| data before passing it to the rules engine. The filters can also be used to +| limit the data that gets passed to the rules engine. The source plugin is +| started by the **ansible-rulebook** and runs in the background putting events +| into the queue to be passed onto the rules engine. | When the source plugin ends we automatically generate a shutdown event and the ruleset | terminates which terminates **ansible-rulebook**. diff --git a/docs/rules.rst b/docs/rules.rst index f95c7fc7..0509e2d5 100644 --- a/docs/rules.rst +++ b/docs/rules.rst @@ -2,12 +2,14 @@ Rules ===== -| Rules is a list of rules. Event driven automation uses rules to determine if an action or -| actions should be taken when an event is received. +| The rules node in a rulebook contains a list of rules. Event driven automation uses rules +| to determine if an action or actions should be executed when an event is received. | The rule decides to run an action or actions by evaluating the condition(s) -| that is defined by the rulebook author. +| that is defined by the rulebook author. When writing the conditions for a rule you have +| to be aware of the attributes in the event payload from different sources defined in the +| ruleset. -A rule comprises: +A rule comprises of: .. list-table:: diff --git a/docs/sources.rst b/docs/sources.rst index 6d163b8d..27f4e63b 100644 --- a/docs/sources.rst +++ b/docs/sources.rst @@ -174,7 +174,7 @@ string or a list of host names. As the plugin have full access to an unbounded queue that is consumed by ansible-rulebbok we carefully recommend to use always the method ``asyncio.Queue.put`` to put events as it's a non-blocking call. To give free cpu cycles to the event loop to process the events, we recommend to use ``asyncio.sleep(0)`` -inmediately after the ``put`` method. +immediately after the ``put`` method. .. note:: ansible-rulebook is intended to be a long running process and react to events over the time.