From: Jim Hahn <jrh3@att.com>
Date: Mon, 18 May 2020 18:58:54 +0000 (-0400)
Subject: Document new Guard Actor
X-Git-Tag: 3.2.0~37^2
X-Git-Url: https://gerrit.onap.org/r/gitweb?p=policy%2Fparent.git;a=commitdiff_plain;h=0bdd20a42a1a9c20abf61c5925758e69f990be8c

Document new Guard Actor

Issue-ID: POLICY-2515
Change-Id: I499294ecb9ade7a069e2f6f1c3566bae7ffc0dde
Signed-off-by: Jim Hahn <jrh3@att.com>
---

diff --git a/docs/development/actors/guard/guard.rst b/docs/development/actors/guard/guard.rst
index 5a26c76d..2c7f2611 100644
--- a/docs/development/actors/guard/guard.rst
+++ b/docs/development/actors/guard/guard.rst
@@ -2,14 +2,127 @@
 .. Creative Commons Attribution 4.0 International License.
 .. http://creativecommons.org/licenses/by/4.0
 
-#################
-Guard Actor
-#################
+###########
+GUARD Actor
+###########
 
 .. contents::
     :depth: 3
 
-Overview of Guard Actor
-#############################
+Overview of GUARD Actor
+#######################
 
-This is a place-holder for the actor documentation.
+Within ONAP Policy Framework, a GUARD is typically an implicit check performed at the
+start of each operation and is performed by making a REST call to the XACML-PDP.
+Previously, the request was built, and the REST call made, by the application.  However,
+Guard checks have now been implemented using the new Actor framework.
+
+Currently, there is a single operation, *Decision*, which is implemented by the java
+class, *GuardOperation*.  This class is derived from *HttpOperation*.
+
+
+Request
+#######
+
+A number of the request fields are populated from values specified in the
+actor/operation's configuration parameters (e.g., "onapName").  Additional fields
+are specified below.
+
+Request ID
+**********
+
+The "requestId" field is set to a UUID.
+
+
+Resource
+********
+
+The "resource" field is populated with a *Map* containing a single item, "guard".  The
+value of the item is set to the contents of the *payload* specified within the
+*ControlLoopOperationParams*.
+
+
+Examples
+########
+
+Suppose the *ControlLoopOperationParams* were populated as follows:
+
+.. code-block:: bash
+
+        {
+            "actor": "GUARD",
+            "operation": "Decision",
+            "payload": {
+              "actor": "SO",
+              "operation": "VF Module Create",
+              "target": "OzVServer",
+              "requestId": "c7c6a4aa-bb61-4a15-b831-ba1472dd4a65",
+              "clname": "ControlLoop-vDNS-6f37f56d-a87d-4b85-b6a9-cc953cf779b3",
+              "vfCount": 2
+            }
+        }
+
+An example of a request constructed by the actor using the above parameters, sent to the
+GUARD REST server:
+
+.. code-block:: bash
+
+        {
+          "ONAPName": "Policy",
+          "ONAPComponent": "Drools PDP",
+          "ONAPInstance": "Usecases",
+          "requestId": "90ee99d2-f2d8-4d90-b162-605203c30180",
+          "action": "guard",
+          "resource": {
+            "guard": {
+              "actor": "SO",
+              "operation": "VF Module Create",
+              "target": "OzVServer",
+              "requestId": "c7c6a4aa-bb61-4a15-b831-ba1472dd4a65",
+              "clname": "ControlLoop-vDNS-6f37f56d-a87d-4b85-b6a9-cc953cf779b3",
+              "vfCount": 2
+            }
+          }
+        }
+
+
+An example response received from the GUARD REST service:
+
+.. code-block:: bash
+
+        {
+            "status": "Permit",
+            "advice": {},
+            "obligations": {},
+            "policies": {}
+        }
+
+
+Configuration of the GUARD Actor
+################################
+
+The following table specifies the fields that should be provided to configure the GUARD
+actor.
+
+=============================== =====================    ==================================================================
+Field name                         type                             Description
+=============================== =====================    ==================================================================
+clientName                        string                  Name of the HTTP client to use to send the request to the
+                                                          GUARD REST server.
+timeoutSec                        integer (optional)      Maximum time, in seconds, to wait for a response to be received
+                                                          from the REST server.  Defaults to 90s.
+path                              string                  URI appended to the URL.  This field only applies to individual
+                                                          operations; it does not apply at the actor level.  Note: the
+                                                          *path* should not include a leading or trailing slash.
+onapName                          string                  ONAP Name (e.g., "Policy")
+onapComponent                     string                  ONAP Component (e.g., "Drools PDP")
+onapInstance                      string                  ONAP Instance (e.g., "Usecases")
+action                            string (optional)       Used to populate the "action" request field.
+                                                          Defaults to "guard".
+disabled                          boolean (optional)      **True**, to disable guard checks, **false** otherwise.
+                                                          Defaults to *false*.
+=============================== =====================    ==================================================================
+
+The individual operations are configured using these same field names. However, all
+of them, except the path, are optional, as they inherit their values from the
+corresponding actor-level fields.