From 1dc094a59317a755e6ef75ed2449d5203a208f65 Mon Sep 17 00:00:00 2001
From: "Q.hongtao" <qihongtao@inspur.com>
Date: Tue, 28 Apr 2020 09:19:51 +0800
Subject: [PATCH] Update doc: Using version 3 to update
 not_operator_support.rst

Now part of the document is version 2 syntax, and part of it is version 3.
So the document needs to be updated to Syntax 3 to replace Syntax 2.

Implements: blueprint doc-upgrade
Change-Id: Ic0d312922e4e5e34038ab4fc8d22999d679626eb
---
 .../contributor/not_operator_support.rst      | 279 ++++++---------
 .../contributor/not_operator_support_v2.rst   | 325 ++++++++++++++++++
 doc/source/index.rst                          |   1 +
 3 files changed, 423 insertions(+), 182 deletions(-)
 create mode 100644 doc/source/contributor/not_operator_support_v2.rst

diff --git a/doc/source/contributor/not_operator_support.rst b/doc/source/contributor/not_operator_support.rst
index 4b1477ab8..acf797636 100644
--- a/doc/source/contributor/not_operator_support.rst
+++ b/doc/source/contributor/not_operator_support.rst
@@ -9,6 +9,14 @@ The Templates language supports the "or" and "and" operators at the moment.
 Many scenarios can't be described by using only those two operators and thus
 we would like to add support for "not" operator as well.
 
+*Note:* This document refers to Vitrage templates version 3.
+
+For previous versions, see:
+
+Version_2_
+
+.. _Version_2: https://docs.openstack.org/vitrage/latest/contributor/not_operator_support_v2.html
+
 
 Template Structure
 ==================
@@ -16,24 +24,26 @@ The template is written in YAML language, with the following structure.
 ::
 
   metadata:
-    version: <template version>
+    version: 3
     name: <unique template identifier>
+    type: standard
     description: <what this template does>
-  definitions:
-    entities:
-        - entity: ...
-        - entity: ...
-    relationships:
-        - relationship: ...
-        - relationship: ...
+  entities:
+    example_host:
+     type: nova.host
+     name: compute-0-0
+    example_instance:
+     type: nova.instance
+    example_alarm:
+     type: zabbix
+     name: memory threshold crossed
   scenarios:
-      - scenario:
-          condition: <if statement true do the action>
-          actions:
-              - action: ...
+    - condition: <if statement true do the actions>
+      actions:
+        ...
 
 
-All the sections are in use as described in the "vitrage-template-format.rst" file.
+All the sections are in use as described in the "vitrage-templates.rst" file.
 But in the condition section it will be possible to write the "not" operator in addition to the "and" and "or" operators.
 The "not" operator can be used only before a relationship expression.
 
@@ -74,44 +84,25 @@ There exists an instance on Host but there is no Alarm on the instance.
  ::
 
     metadata:
-        version: 2
+        version: 3
         name: no_alarm_on_instance_that_contained_in_host
         description: when host contains vm that has no alarm on it, show implications on the host
-    definitions:
-        entities:
-            - entity:
-                category: ALARM
-                name: instance_mem_performance_problem
-                template_id: instance_alarm # some string
-            - entity:
-                category: RESOURCE
-                type: nova.host
-                template_id: host
-            - entity:
-                category: RESOURCE
-                type: nova.instance
-                template_id: instance
-        relationships:
-            - relationship:
-                source: instance_alarm
-                target: instance
-                relationship_type: on
-                template_id : alarm_on_instance
-            - relationship:
-                source: host
-                target: instance
-                relationship_type: contains
-                template_id : host_contains_instance
+    entities:
+        instance_alarm:
+            category: ALARM
+            name: instance_mem_performance_problem
+        host:
+            category: RESOURCE
+            type: nova.host
+        instance:
+            category: RESOURCE
+            type: nova.instance
     scenarios:
-        - scenario:
-            condition: host_contains_instance and not alarm_on_instance
-            actions:
-                - action:
-                   action_type: set_state
-                   properties:
-                      state: available
-                   action_target:
-                      target: host
+        - condition: host [contains] instance AND NOT instance_alarm [on] instance
+          actions:
+               - set_state:
+                   state: available
+                   target: instance
 
 
 Use Case 2:
@@ -128,39 +119,25 @@ There exists a host with no alarm.
  ::
 
     metadata:
-        version: 2
+        version: 3
         name: no_alarm_on_host
         description: when there is no alarm on the host, show implications on the host
-    definitions:
-        entities:
-            - entity:
-                category: ALARM
-                name: host_high_mem_load
-                template_id: host_alarm # some string
-            - entity:
-                category: RESOURCE
-                type: nova.host
-                template_id: host
-            - entity:
-                category: RESOURCE
-                type: nova.instance
-                template_id: instance
-        relationships:
-            - relationship:
-                source: host_alarm  # source and target from entities section
-                target: host
-                relationship_type: on
-                template_id : alarm_on_host
+    entities:
+        host_alarm:
+            category: ALARM
+            name: host_high_mem_load
+        host:
+            category: RESOURCE
+            type: nova.host
+        instance:
+            category: RESOURCE
+            type: nova.instance
     scenarios:
-        - scenario:
-            condition: not alarm_on_host
-            actions:
-                - action:
-                   action_type: set_state
-                   properties:
-                      state: available
-                   action_target:
-                      target: instance
+        - condition:  not instance_alarm [on] instance
+          actions:
+               - set_state:
+                   state: available
+                   target: instance
 
 
 Use Case 3:
@@ -190,69 +167,32 @@ There is no edge between the Vm and the Port.
  ::
 
     metadata:
-        version: 2
+        version: 3
         name: no_connection_between_vm_and_port
         description: when there is no edge between the port and the vm, show implications on the instances
-    definitions:
-        entities:
-            - entity:
-                category: RESOURCE
-                type: nova.host
-                template_id: host
-            - entity:
-                category: RESOURCE
-                type: nova.instance
-                template_id: instance
-            - entity:
-                category: RESOURCE
-                type: switch
-                template_id: switch
-            - entity:
-                category: RESOURCE
-                type: neutron.network
-                template_id: network
-            - entity:
-                category: RESOURCE
-                type: neutron.port
-                template_id: port
-        relationships:
-            - relationship:
-                source: host
-                target: instance
-                relationship_type: contains
-                template_id : host_contains_instance
-            - relationship:
-                source: switch
-                target: host
-                relationship_type: connected
-                template_id : host_connected_switch
-            - relationship:
-                source: switch
-                target: network
-                relationship_type: has
-                template_id : switch_has_network
-            - relationship:
-                source: port
-                target: network
-                relationship_type: attached
-                template_id : port_attached_network
-            - relationship:
-                source: instance
-                target: port
-                relationship_type: connected
-                template_id : vm_connected_port
+    entities:
+        host:
+            category: RESOURCE
+            type: nova.host
+        instance:
+            category: RESOURCE
+            type: nova.instance
+        switch:
+            category: RESOURCE
+            type: switch
+        network:
+            category: RESOURCE
+            type: neutron.network
+        port:
+            category: RESOURCE
+            type: neutron.port
     scenarios:
-        - scenario:
-            condition: host_contains_instance and host_connected_switch and switch_has_network and port_attached_network and not vm_connected_port
-            actions:
-                - action:
-                   action_type: raise_alarm
-                   properties:
-                      alarm_name: instance_mem_performance_problem
-                      severity: warning
-                   action_target:
-                      target: instance
-
+        - condition:  host [contains] instance AND switch [connected] host AND switch [has] network AND port [attached] network AND NOT instance [connected] port
+          actions:
+               - raise_alarm:
+                   target: instance
+                   alarm_name: instance_mem_performance_problem
+                   severity: WARNING
 
 
 Unsupported Use Cases
@@ -276,50 +216,25 @@ In the subgraphs above, we had only one vertex which was not connected to the ma
  ::
 
     metadata:
-        version: 2
+        version: 3
         name: host_contains_vm_with_no_edge_to_stack_that_has_alarm_on_it
         description: when host contains vm without and edge to a stack that has no alarms, show implications on the instances
-    definitions:
-        entities:
-            - entity:
-                category: RESOURCE
-                type: nova.host
-                template_id: host
-            - entity:
-                category: RESOURCE
-                type: nova.instance
-                template_id: instance
-            - entity:
-                category: RESOURCE
-                type: heat.stack
-                template_id: stack
-            - entity:
-                category: ALARM
-                name: stack_high_mem_load
-                template_id: stack_alarm
-        relationships:
-            - relationship:
-                source: host
-                target: instance
-                relationship_type: contains
-                template_id : host_contains_instance
-            - relationship:
-                source: stack_alarm
-                target: stack
-                relationship_type: on
-                template_id : alarm_on_stack
-            - relationship:
-                source: instance
-                target: stack
-                relationship_type: attached
-                template_id : instance_attached_stack
+    entities:
+        host:
+            category: RESOURCE
+            type: nova.host
+        instance:
+            category: RESOURCE
+            type: nova.instance
+        stack:
+            category: RESOURCE
+            type: heat.stack
+        stack_alarm:
+            category: ALARM
+            name: stack_high_mem_load
     scenarios:
-        - scenario:
-            condition: host_contains_instance and alarm_on_stack and not instance_attached_stack
-            actions:
-                - action:
-                   action_type: set_state
-                   properties:
-                      state: available
-                   action_target:
-                      target: instance
+        - condition:  host [contains] instance AND stack_alarm [on] stack AND NOT instance [attached] stack
+          actions:
+               - set_state:
+                   state: available
+                   target: instance
diff --git a/doc/source/contributor/not_operator_support_v2.rst b/doc/source/contributor/not_operator_support_v2.rst
new file mode 100644
index 000000000..b1c55fd74
--- /dev/null
+++ b/doc/source/contributor/not_operator_support_v2.rst
@@ -0,0 +1,325 @@
+==========================================
+Templates Not Operator Support - Version 2
+==========================================
+
+Overview
+--------
+
+The Templates language supports the "or" and "and" operators at the moment.
+Many scenarios can't be described by using only those two operators and thus
+we would like to add support for "not" operator as well.
+
+
+Template Structure
+==================
+The template is written in YAML language, with the following structure.
+::
+
+  metadata:
+    version: <template version>
+    name: <unique template identifier>
+    description: <what this template does>
+  definitions:
+    entities:
+        - entity: ...
+        - entity: ...
+    relationships:
+        - relationship: ...
+        - relationship: ...
+  scenarios:
+      - scenario:
+          condition: <if statement true do the action>
+          actions:
+              - action: ...
+
+
+All the sections are in use as described in the "vitrage-template-format.rst" file.
+But in the condition section it will be possible to write the "not" operator in addition to the "and" and "or" operators.
+The "not" operator can be used only before a relationship expression.
+
+
+Condition Format
+----------------
+The condition which needs to be met will be phrased using the entities and
+relationships previously defined. The condition details are described in the
+"vitrage-template-format.rst" and the addition here is the new logical operator "not":
+
+- "not" - indicates that the expression must not be satisfied in order for the
+  condition to be met.
+
+The following are examples of valid expressions, where X, Y and Z are
+relationships:
+
+- X
+- X and Y
+- X and Y and Z
+- X and not Y
+- X and not (Y or Z)
+- X and not X
+
+
+Supported Use Cases
+===================
+
+Use Case 1:
+-----------
+There exists an instance on Host but there is no Alarm on the instance.
+
+ ::
+
+    +--------+         +--------+    Not    +---------+
+    |  Host  | ------> |   Vm   | < - - - - |  Alarm  |
+    +--------+         +--------+           +---------+
+
+ ::
+
+    metadata:
+        version: 2
+        name: no_alarm_on_instance_that_contained_in_host
+        description: when host contains vm that has no alarm on it, show implications on the host
+    definitions:
+        entities:
+            - entity:
+                category: ALARM
+                name: instance_mem_performance_problem
+                template_id: instance_alarm # some string
+            - entity:
+                category: RESOURCE
+                type: nova.host
+                template_id: host
+            - entity:
+                category: RESOURCE
+                type: nova.instance
+                template_id: instance
+        relationships:
+            - relationship:
+                source: instance_alarm
+                target: instance
+                relationship_type: on
+                template_id : alarm_on_instance
+            - relationship:
+                source: host
+                target: instance
+                relationship_type: contains
+                template_id : host_contains_instance
+    scenarios:
+        - scenario:
+            condition: host_contains_instance and not alarm_on_instance
+            actions:
+                - action:
+                   action_type: set_state
+                   properties:
+                      state: available
+                   action_target:
+                      target: host
+
+
+Use Case 2:
+-----------
+
+There exists a host with no alarm.
+
+ ::
+
+    +--------+    Not    +---------+
+    |  Host  | < - - - - |  Alarm  |
+    +--------+           +---------+
+
+ ::
+
+    metadata:
+        version: 2
+        name: no_alarm_on_host
+        description: when there is no alarm on the host, show implications on the host
+    definitions:
+        entities:
+            - entity:
+                category: ALARM
+                name: host_high_mem_load
+                template_id: host_alarm # some string
+            - entity:
+                category: RESOURCE
+                type: nova.host
+                template_id: host
+            - entity:
+                category: RESOURCE
+                type: nova.instance
+                template_id: instance
+        relationships:
+            - relationship:
+                source: host_alarm  # source and target from entities section
+                target: host
+                relationship_type: on
+                template_id : alarm_on_host
+    scenarios:
+        - scenario:
+            condition: not alarm_on_host
+            actions:
+                - action:
+                   action_type: set_state
+                   properties:
+                      state: available
+                   action_target:
+                      target: instance
+
+
+Use Case 3:
+-----------
+
+The Switch is attached to a Host that contains a Vm.
+The Switch is also comprised to a Network which has a Port.
+There is no edge between the Vm and the Port.
+
+::
+
+                   +---------+           +---------+
+      +----------- |  Host   | --------> |   Vm    |
+      |            +---------+           +---------+
+      |                                       |
+      v                                       |
+ +----------+                                 | N
+ |  Switch  |                                 | o
+ +----------+                                 | t
+      |                                       |
+      |                                       |
+      |                                       v
+      |            +---------+           +---------+
+      +----------> | Network | <-------- |  Port   |
+                   +---------+           +---------+
+
+ ::
+
+    metadata:
+        version: 2
+        name: no_connection_between_vm_and_port
+        description: when there is no edge between the port and the vm, show implications on the instances
+    definitions:
+        entities:
+            - entity:
+                category: RESOURCE
+                type: nova.host
+                template_id: host
+            - entity:
+                category: RESOURCE
+                type: nova.instance
+                template_id: instance
+            - entity:
+                category: RESOURCE
+                type: switch
+                template_id: switch
+            - entity:
+                category: RESOURCE
+                type: neutron.network
+                template_id: network
+            - entity:
+                category: RESOURCE
+                type: neutron.port
+                template_id: port
+        relationships:
+            - relationship:
+                source: host
+                target: instance
+                relationship_type: contains
+                template_id : host_contains_instance
+            - relationship:
+                source: switch
+                target: host
+                relationship_type: connected
+                template_id : host_connected_switch
+            - relationship:
+                source: switch
+                target: network
+                relationship_type: has
+                template_id : switch_has_network
+            - relationship:
+                source: port
+                target: network
+                relationship_type: attached
+                template_id : port_attached_network
+            - relationship:
+                source: instance
+                target: port
+                relationship_type: connected
+                template_id : vm_connected_port
+    scenarios:
+        - scenario:
+            condition: host_contains_instance and host_connected_switch and switch_has_network and port_attached_network and not vm_connected_port
+            actions:
+                - action:
+                   action_type: raise_alarm
+                   properties:
+                      alarm_name: instance_mem_performance_problem
+                      severity: warning
+                   action_target:
+                      target: instance
+
+
+
+Unsupported Use Cases
+=====================
+
+Use Case 1:
+-----------
+
+There is a Host contains Vm, which has no edge ("connection") to a stack that has an alarm on it.
+Difference: The difference here from the graphs above, is that here there are
+two connected component subgraphs (the first is host contains vm, the second is alarm on stack),
+and the current mechanism doesn't support such a use case of not operator between many connected component subgraphs.
+In the subgraphs above, we had only one vertex which was not connected to the main connected component subgraph.
+
+ ::
+
+    +---------+           +---------+      Not       +---------+            +---------+
+    |  Host   | --------> |   Vm    |  - - - - - ->  |  Stack  | <--------- |  Alarm  |
+    +---------+           +---------+                +---------+            +---------+
+
+ ::
+
+    metadata:
+        version: 2
+        name: host_contains_vm_with_no_edge_to_stack_that_has_alarm_on_it
+        description: when host contains vm without and edge to a stack that has no alarms, show implications on the instances
+    definitions:
+        entities:
+            - entity:
+                category: RESOURCE
+                type: nova.host
+                template_id: host
+            - entity:
+                category: RESOURCE
+                type: nova.instance
+                template_id: instance
+            - entity:
+                category: RESOURCE
+                type: heat.stack
+                template_id: stack
+            - entity:
+                category: ALARM
+                name: stack_high_mem_load
+                template_id: stack_alarm
+        relationships:
+            - relationship:
+                source: host
+                target: instance
+                relationship_type: contains
+                template_id : host_contains_instance
+            - relationship:
+                source: stack_alarm
+                target: stack
+                relationship_type: on
+                template_id : alarm_on_stack
+            - relationship:
+                source: instance
+                target: stack
+                relationship_type: attached
+                template_id : instance_attached_stack
+    scenarios:
+        - scenario:
+            condition: host_contains_instance and alarm_on_stack and not instance_attached_stack
+            actions:
+                - action:
+                   action_type: set_state
+                   properties:
+                      state: available
+                   action_target:
+                      target: instance
diff --git a/doc/source/index.rst b/doc/source/index.rst
index f1b1162ef..bf53b867a 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -99,6 +99,7 @@ Design Documents
    contributor/vitrage-use-cases
    contributor/add-new-datasource
    contributor/not_operator_support
+   contributor/not_operator_support_v2
    contributor/templates-loading
    contributor/vitrage-ha-and-history-vision
    contributor/datasource-snmp-parsing-support