docs/development/actors/guard/guard.rst

   1 .. This work is licensed under a
   2 .. Creative Commons Attribution 4.0 International License.
   3 .. http://creativecommons.org/licenses/by/4.0
   4
   5 ###########
   6 GUARD Actor
   7 ###########
   8
   9 .. contents::
  10     :depth: 3
  11
  12 Overview of GUARD Actor
  13 #######################
  14
  15 Within ONAP Policy Framework, a GUARD is typically an implicit check performed at the
  16 start of each operation and is performed by making a REST call to the XACML-PDP.
  17 Previously, the request was built, and the REST call made, by the application.  However,
  18 Guard checks have now been implemented using the new Actor framework.
  19
  20 Currently, there is a single operation, *Decision*, which is implemented by the java
  21 class, *GuardOperation*.  This class is derived from *HttpOperation*.
  22
  23
  24 Request
  25 #######
  26
  27 A number of the request fields are populated from values specified in the
  28 actor/operation's configuration parameters (e.g., "onapName").  Additional fields
  29 are specified below.
  30
  31 Request ID
  32 **********
  33
  34 The "requestId" field is set to a UUID.
  35
  36
  37 Resource
  38 ********
  39
  40 The "resource" field is populated with a *Map* containing a single item, "guard".  The
  41 value of the item is set to the contents of the *payload* specified within the
  42 *ControlLoopOperationParams*.
  43
  44
  45 Examples
  46 ########
  47
  48 Suppose the *ControlLoopOperationParams* were populated as follows:
  49
  50 .. code-block:: bash
  51
  52         {
  53             "actor": "GUARD",
  54             "operation": "Decision",
  55             "payload": {
  56               "actor": "SO",
  57               "operation": "VF Module Create",
  58               "target": "OzVServer",
  59               "requestId": "c7c6a4aa-bb61-4a15-b831-ba1472dd4a65",
  60               "clname": "ControlLoop-vDNS-6f37f56d-a87d-4b85-b6a9-cc953cf779b3",
  61               "vfCount": 2
  62             }
  63         }
  64
  65 An example of a request constructed by the actor using the above parameters, sent to the
  66 GUARD REST server:
  67
  68 .. code-block:: bash
  69
  70         {
  71           "ONAPName": "Policy",
  72           "ONAPComponent": "Drools PDP",
  73           "ONAPInstance": "Usecases",
  74           "requestId": "90ee99d2-f2d8-4d90-b162-605203c30180",
  75           "action": "guard",
  76           "resource": {
  77             "guard": {
  78               "actor": "SO",
  79               "operation": "VF Module Create",
  80               "target": "OzVServer",
  81               "requestId": "c7c6a4aa-bb61-4a15-b831-ba1472dd4a65",
  82               "clname": "ControlLoop-vDNS-6f37f56d-a87d-4b85-b6a9-cc953cf779b3",
  83               "vfCount": 2
  84             }
  85           }
  86         }
  87
  88
  89 An example response received from the GUARD REST service:
  90
  91 .. code-block:: bash
  92
  93         {
  94             "status": "Permit",
  95             "advice": {},
  96             "obligations": {},
  97             "policies": {}
  98         }
  99
 100
 101 Configuration of the GUARD Actor
 102 ################################
 103
 104 The following table specifies the fields that should be provided to configure the GUARD
 105 actor.
 106
 107 =============================== =====================    ==================================================================
 108 Field name                         type                             Description
 109 =============================== =====================    ==================================================================
 110 clientName                        string                  Name of the HTTP client to use to send the request to the
 111                                                           GUARD REST server.
 112 timeoutSec                        integer (optional)      Maximum time, in seconds, to wait for a response to be received
 113                                                           from the REST server.  Defaults to 90s.
 114 path                              string                  URI appended to the URL.  This field only applies to individual
 115                                                           operations; it does not apply at the actor level.  Note: the
 116                                                           *path* should not include a leading or trailing slash.
 117 onapName                          string                  ONAP Name (e.g., "Policy")
 118 onapComponent                     string                  ONAP Component (e.g., "Drools PDP")
 119 onapInstance                      string                  ONAP Instance (e.g., "Usecases")
 120 action                            string (optional)       Used to populate the "action" request field.
 121                                                           Defaults to "guard".
 122 disabled                          boolean (optional)      **True**, to disable guard checks, **false** otherwise.
 123                                                           Defaults to *false*.
 124 =============================== =====================    ==================================================================
 125
 126 The individual operations are configured using these same field names. However, all
 127 of them, except the path, are optional, as they inherit their values from the
 128 corresponding actor-level fields.