Merge "Add guard filter documentation"

7 files changed, 185 insertions, 0 deletions

diff --git a/docs/api/api.rst b/docs/api/api.rst
index c2c20ffc..b9f31482 100644
--- a/docs/api/api.rst
+++ b/docs/api/api.rst
@@ -132,6 +132,7 @@ To ease policy creation, we preload several widely used policy types in policy d
    "Controlloop.Guard.Common.Blacklist", `onap.policies.controlloop.guard.common.Blacklist.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.controlloop.guard.common.Blacklist.yaml>`_
    "Controlloop.Guard.Common.FrequencyLimiter", `onap.policies.controlloop.guard.common.FrequencyLimiter.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.controlloop.guard.common.FrequencyLimiter.yaml>`_
    "Controlloop.Guard.Common.MinMax", `onap.policies.controlloop.guard.common.MinMax.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.controlloop.guard.common.MinMax.yaml>`_
+   "Controlloop.Guard.Common.Filter", `onap.policies.controlloop.guard.common.Filter.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.controlloop.guard.common.Filter.yaml>`_
    "Controlloop.Guard.Coordination.FirstBlocksSecond", `onap.policies.controlloop.guard.coordination.FirstBlocksSecond.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.controlloop.guard.coordination.FirstBlocksSecond.yaml>`_
    "Controlloop.Operational.Common", `onap.policies.controlloop.operational.Common.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.controlloop.operational.Common.yaml>`_
    "Controlloop.Operational.Common.Apex", `onap.policies.controlloop.operational.common.Apex.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.controlloop.operational.common.Apex.yaml>`_
diff --git a/docs/design/design.rst b/docs/design/design.rst
index 44a2e25c..d543e461 100644
--- a/docs/design/design.rst
+++ b/docs/design/design.rst
@@ -176,6 +176,13 @@ The Blacklist Guard Supports blacklisting control loop actions from being perfor
 
 Please see the definition of the `Guard Blacklist Policy Type <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.controlloop.guard.common.Blacklist.yaml>`_
 
+3.4 Filter Guard onap.policies.controlloop.guard.common.Filter
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The Filter Guard Supports filtering control loop actions from being performed on specific entity id's.
+
+Please see the definition of the `Guard Filter Policy Type <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.controlloop.guard.common.Filter.yaml>`_
+
 4 Optimization onap.policies.Optimization
 -----------------------------------------
 
diff --git a/docs/xacml/example.guard.blacklist.yaml b/docs/xacml/example.guard.blacklist.yaml
new file mode 100644
index 00000000..d8499571
--- /dev/null
+++ b/docs/xacml/example.guard.blacklist.yaml
@@ -0,0 +1,17 @@
+tosca_definitions_version: tosca_simple_yaml_1_1_0
+topology_template:
+    policies:
+    -   guard.blacklist.scaleout:
+            type: onap.policies.controlloop.guard.common.Blacklist
+            type_version: 1.0.0
+            version: 1.0.0
+            name: guard.blacklist.scaleout
+            metadata:
+                policy-id: guard.blacklist.scaleout
+            properties:
+                actor: APPC
+                operation: Restart
+                id: my-controlloop
+                blacklist:
+                - vnf-id-1
+                - vnf-id-2
\ No newline at end of file
diff --git a/docs/xacml/example.guard.filter.yaml b/docs/xacml/example.guard.filter.yaml
new file mode 100644
index 00000000..261ffbee
--- /dev/null
+++ b/docs/xacml/example.guard.filter.yaml
@@ -0,0 +1,39 @@
+tosca_definitions_version: tosca_simple_yaml_1_1_0
+topology_template:
+   policies:
+   -  filter.block.region.allow.one.vnf:
+         description: Block this region from Control Loop actions, but allow a specific vnf.
+         type: onap.policies.controlloop.guard.common.Filter
+         type_version: 1.0.0
+         version: 1.0.0
+         properties:
+            actor: SO
+            operation: VF Module Create
+            algorithm: whitelist-overrides
+            filters:
+            -  field: cloud-region.cloud-region-id
+               filter: RegionOne
+               function: string-equal
+               blacklist: true
+            -  field: generic-vnf.vnf-id
+               filter: e6130d03-56f1-4b0a-9a1d-e1b2ebc30e0e
+               function: string-equal
+               blacklist: false
+   -  filter.allow.region.block.one.vnf:
+         description: allow this region to do Control Loop actions, but block a specific vnf.
+         type: onap.policies.controlloop.guard.common.Filter
+         type_version: 1.0.0
+         version: 1.0.0
+         properties:
+            actor: SO
+            operation: VF Module Create
+            algorithm: blacklist-overrides
+            filters:
+            -  field: cloud-region.cloud-region-id
+               filter: RegionTwo
+               function: string-equal
+               blacklist: false
+            -  field: generic-vnf.vnf-id
+               filter: f17face5-69cb-4c88-9e0b-7426db7edddd
+               function: string-equal
+               blacklist: true
\ No newline at end of file
diff --git a/docs/xacml/example.guard.limiter.yaml b/docs/xacml/example.guard.limiter.yaml
new file mode 100644
index 00000000..703be4f7
--- /dev/null
+++ b/docs/xacml/example.guard.limiter.yaml
@@ -0,0 +1,19 @@
+tosca_definitions_version: tosca_simple_yaml_1_1_0
+topology_template:
+  policies:
+    -
+      guard.frequency.scaleout:
+        type: onap.policies.controlloop.guard.common.FrequencyLimiter
+        type_version: 1.0.0
+        version: 1.0.0
+        name: guard.frequency.scaleout
+        description: Here we limit the number of Restarts for my-controlloop to 3 in a ten minute period.
+        metadata:
+          policy-id : guard.frequency.scaleout
+        properties:
+          actor: APPC
+          operation: Restart
+          id: my-controlloop
+          timeWindow: 10
+          timeUnits: minute
+          limit: 3
\ No newline at end of file
diff --git a/docs/xacml/example.guard.minmax.yaml b/docs/xacml/example.guard.minmax.yaml
new file mode 100644
index 00000000..5411378a
--- /dev/null
+++ b/docs/xacml/example.guard.minmax.yaml
@@ -0,0 +1,17 @@
+tosca_definitions_version: tosca_simple_yaml_1_1_0
+topology_template:
+    policies:
+    -   guard.minmax.scaleout:
+            type: onap.policies.controlloop.guard.common.MinMax
+            type_version: 1.0.0
+            version: 1.0.0
+            name: guard.minmax.scaleout
+            metadata:
+                policy-id: guard.minmax.scaleout
+            properties:
+                actor: SO
+                operation: VF Module Create
+                id: my-controlloop
+                target: the-vfmodule-id
+                min: 1
+                max: 2
\ No newline at end of file
diff --git a/docs/xacml/xacml.rst b/docs/xacml/xacml.rst
index f5e2977a..1010f8ed 100644
--- a/docs/xacml/xacml.rst
+++ b/docs/xacml/xacml.rst
@@ -106,6 +106,7 @@ These Policy Types are used by Control Loop Drools Engine to support guarding co
    "onap.policies.controlloop.guard.common.FrequencyLimiter", "guard", "Limits frequency of actions over a specified time period"
    "onap.policies.controlloop.guard.common.Blacklist", "guard", "Blacklists a regexp of VNF IDs"
    "onap.policies.controlloop.guard.common.MinMax", "guard", "For scaling, enforces a min/max number of VNFS"
+   "onap.policies.controlloop.guard.common.Filter", "guard", "Used for filtering entities in A&AI from Control Loop actions"
    "onap.policies.controlloop.guard.coordination.FirstBlocksSecond", "guard", "Gives priority to one control loop vs another"
 
 This is an example Decision API payload made to retrieve a decision for a Guard Policy Type.
@@ -118,6 +119,90 @@ The return decision simply has "permit" or "deny" in the response to tell the ca
 .. literalinclude:: decision.guard.response.json
   :language: JSON
 
+Guard Common Base Policy Type
+-----------------------------
+Each guard Policy Type derives from **onap.policies.controlloop.guard.Common** base policy type. Thus, they share a set of common
+properties.
+
+.. csv-table:: Common Properties for all Guards
+   :header: "Property", "Examples", "Required", "Type", "Description"
+
+   "actor", "APPC, SO", "Required", "String", "Identifies the actor involved in the Control Loop operation."
+   "operation", "Restart, VF Module Create", "Required", "String", "Identifies the Control Loop operation the actor must perform."
+   "timeRange", "start_time: T00:00:00Z end_time: T08:00:00Z", "Optional", "tosca.datatypes.TimeInterval", "A given time range the guard is in effect. Following the TOSCA specification the format should be ISO 8601 format "
+   "id", "control-loop-id", "Optional", "String", "A specific Control Loop id the guard is in effect."
+
+`Common Guard Policy Type <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.controlloop.guard.Common.yaml>`__
+
+Frequency Limiter Guard Policy Type
+-----------------------------------
+The Frequency Limiter Guard is used to specify limits as to how many operations can occur over a given time period.
+
+.. csv-table:: Frequency Guard Properties
+   :header: "Property", "Examples", "Required", "Type", "Description"
+
+   "timeWindow", "10, 60", "Required", "integer", "The time window to count the actions against."
+   "timeUnits", "second minute, hour, day, week, month, year", "Required", "String", "The units of time the window is counting"
+   "limit", "5", "Required", "integer", "The limit value to be checked against."
+
+.. literalinclude:: example.guard.limiter.yaml
+  :language: YAML
+
+`Frequency Limiter Guard Policy Type <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.controlloop.guard.common.FrequencyLimiter.yaml>`__
+
+Min/Max Guard Policy Type
+-------------------------
+The Min/Max Guard is used to specify a minimum or maximum number of instantiated entities in A&AI. Typically this is a VFModule for Scaling operations. One should specify either a min or a max value, or **both** a min and max value. At least one must be specified.
+
+.. csv-table:: Min/Max Guard Properties
+   :header: "Property", "Examples", "Required", "Type", "Description"
+
+   "target", "e6130d03-56f1-4b0a-9a1d-e1b2ebc30e0e", "Required", "String", "The target entity that has scaling restricted."
+   "min", "1", "Optional", "integer", "Minimum value. Optional only if max is not specified."
+   "max", "5", "Optional", "integer", "Maximum value. Optional only if min is not specified."
+
+.. literalinclude:: example.guard.minmax.yaml
+  :language: YAML
+
+`Min/Max Guard Policy Type <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.controlloop.guard.common.MinMax.yaml>`__
+
+Blacklist Guard Policy Type
+---------------------------
+The Blacklist Guard is used to specify a list of A&AI entities that are blacklisted from having an operation performed on them. Recommendation is to use the vnf-id for the A&AI entity.
+
+.. csv-table:: Blacklist Guard Properties
+   :header: "Property", "Examples", "Required", "Type", "Description"
+
+   "blacklist", "e6130d03-56f1-4b0a-9a1d-e1b2ebc30e0e", "Required", "list of string", "List of target entity's that are blacklisted from an operation."
+
+.. literalinclude:: example.guard.blacklist.yaml
+  :language: YAML
+
+`Blacklist Guard Policy Type <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.controlloop.guard.common.Blacklist.yaml>`__
+
+Filter Guard Policy Type
+------------------------
+The Filter Guard is a more robust guard for blacklisting and whitelisting A&AI entities when performing control loop operations. The intent for this guard is to filter in or out a block of entities, while allowing the ability to filter in or out specific entities. This allows a DevOps team to control the introduction of a Control Loop for a region or specific VNF's, as well as block specific VNF's that are being negatively affected when poor network conditions arise. Care and testing should be taken to understand the ramifications when combining multiple filters as well as their use in conjunction with other Guard Policy Types.
+
+.. csv-table:: Filter Guard Properties
+   :header: "Property", "Examples", "Required", "Type", "Description"
+
+   "algorithm", "blacklist-overrides", "Required", "What algorithm to be applied", "blacklist-overrides or whitelist-overrides are the valid values. Indicates whether blacklisting or whitelisting has precedence."
+   "filters", "see table below", "Required", "list of onap.datatypes.guard.filter", "List of datatypes that describe the filter."
+
+.. csv-table:: Filter Guard onap.datatypes.guard.filter Properties
+   :header: "Property", "Examples", "Required", "Type", "Description"
+
+   "field", "generic-vnf.vnf-name", "Required", "String", "Field used to perform filter on and must be a string value. See the Policy Type below for valid values."
+   "filter", "vnf-id-1", "Required", "String", "The filter being applied."
+   "function", "string-equal", "Required", "String", "The function that is applied to the filter. See the Policy Type below for valid values."
+   "blacklist", "true", "Required", "boolean", "Whether the result of the filter function applied to the filter is blacklisted or whitelisted (eg Deny or Permit)."
+
+.. literalinclude:: example.guard.filter.yaml
+  :language: YAML
+
+`Filter Guard Policy Type <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.controlloop.guard.common.Filter.yaml>`__
+
 .. _xacml-optimization-label:
 
 Optimization Policy Types