From dfd9c3168da25ad39de6e9569a92eac686dc6d72 Mon Sep 17 00:00:00 2001 From: Niv Oppenhaim Date: Tue, 8 Aug 2017 06:57:55 +0000 Subject: [PATCH] Documentation for template configuration Change-Id: Ic9fff2af0cc32b0d640c37808a3b74feee607d57 --- doc/source/contributor/configuration.rst | 1 + doc/source/contributor/template-config.rst | 37 ++++++++++++++++++ .../contributor/vitrage-template-format.rst | 38 +++++++++++++++++-- 3 files changed, 72 insertions(+), 4 deletions(-) create mode 100644 doc/source/contributor/template-config.rst diff --git a/doc/source/contributor/configuration.rst b/doc/source/contributor/configuration.rst index 118803085..6bb7ddfd8 100644 --- a/doc/source/contributor/configuration.rst +++ b/doc/source/contributor/configuration.rst @@ -12,6 +12,7 @@ General alarm-severity-config profiler-config keycloak-config + template-config ../configuration/index diff --git a/doc/source/contributor/template-config.rst b/doc/source/contributor/template-config.rst new file mode 100644 index 000000000..a6c676094 --- /dev/null +++ b/doc/source/contributor/template-config.rst @@ -0,0 +1,37 @@ +================================ +Template Directory Configuration +================================ + +Overview +-------- +Vitrage uses configuration files called ``templates``, to express rules +regarding raising deduced alarms, setting deduced states, and detecting/setting +RCA links. + +Configuration +------------- +The templates, definition templates and entity equivalence directories should be defined in the +Vitrage configuration file, **/etc/vitrage/vitrage.conf** under the ``[evaluator]`` section. + + ++-------------------+------------------------------------------------------------------+--------------------------------------+ +| Name | Description | Default Value | ++===================+==================================================================+======================================+ +| templates_dir | A path for the templates used by the evaluator | /etc/vitrage/templates | ++-------------------+------------------------------------------------------------------+--------------------------------------+ +| def_templates_dir | A path for the definition template files used by the evaluator. | /etc/vitrage/templates/def_templates | +| | These are template files that contain only definitions and | | +| | can be included and used in regular template files to create | | +| | scenarios. | | ++-------------------+------------------------------------------------------------------+--------------------------------------+ +|equivalences_dir | A path for for entity equivalences used by the evaluator. | /etc/vitrage/templates/equivalences | ++-------------------+------------------------------------------------------------------+--------------------------------------+ + +.. code:: yaml + + + [evaluator] + + templates_dir = /etc/vitrage/templates + def_templates_dir = /etc/vitrage/templates/def_templates + equivalences_dir = /etc/vitrage/templates/equivalences diff --git a/doc/source/contributor/vitrage-template-format.rst b/doc/source/contributor/vitrage-template-format.rst index e853dacea..96b7144d9 100644 --- a/doc/source/contributor/vitrage-template-format.rst +++ b/doc/source/contributor/vitrage-template-format.rst @@ -4,7 +4,7 @@ Vitrage Templates Format & Usage Overview ======== -In Vitrage we use configuration files, called "templates", to express rules +In Vitrage we use configuration files, called ``templates``, to express rules regarding raising deduced alarms, setting deduced states, and detecting/setting RCA links. This page describes the format of the Vitrage templates, with some examples and @@ -13,7 +13,7 @@ templates is presented. Template Structure ================== -The template is written in YAML language, with the following structure. +The template is written in YAML language, with the following structure: :: metadata: @@ -26,6 +26,9 @@ The template is written in YAML language, with the following structure. relationships: - relationship: ... - relationship: ... + includes: + - name: + - name: ... scenarios: - scenario: condition: @@ -33,16 +36,43 @@ The template is written in YAML language, with the following structure. - action: ... -The template is divided into three main sections: +The template is divided into four main sections: - *metadata:* Contains the template name, and brief description of what the template does (optional) -- *definitions:* This section contains the atomic definitions referenced later on, for entities and relationships +- *definitions:* This section is **mandatory** unless an include section is specified in the template (see below). + This section contains the atomic definitions referenced later on, for entities and relationships. + - *entities –* describes the resources and alarms which are relevant to the template scenario (conceptually, corresponds to a vertex in the entity graph) - *relationships –* the relationships between the entities (conceptually, corresponds to an edge in the entity graph) +- *includes:* This section is optional. If included, it must contain a list of names of definition templates as they appear in the metadata section of said templates. + If only definitions from included definition templates are used to create scenarios within the template, then the *definitions* section is **optional**. - *scenarios:* A list of if-then scenarios to consider. Each scenario is comprised of: - *condition –* the condition to be met. This condition will be phrased referencing the entities and relationships previously defined. - *action(s) –* a list of actions to execute when the condition is met. +Definition Template Structure +----------------------------- +These are separate files, which contain only definitions and can be included under the includes section in regular templates. The definition templates are written in YAML +language, with the following structure: + + :: + + metadata: + name: + description: + definitions: + entities: + - entity: ... + - entity: ... + relationships: + - relationship: ... + - relationship: ... + +A definition template is in same format as a regular template - +except it **does not** contain a scenarios or an includes section. Once included in a +template, the definition template's entities and relationships can be used within the template +they are included to create scenarios. + Condition Format ---------------- The condition which needs to be met will be phrased using the entities and