docs/actors/cds.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 CDS actor support in Policy
   6 ###########################
   7
   8 .. contents::
   9     :depth: 4
  10
  11 1. Overview of CDS Actor support in Policy
  12 ==========================================
  13 ONAP Policy Framework now enables Controller Design Studio (CDS) as one of the supported actors.
  14 This allows the users to configure Operational Policy to use CDS as an actor to remedy a situation.
  15
  16 Behind the scene, when an incoming event is received and validated against rules, Policy uses gRPC to trigger
  17 the CBA (Controller Blueprint Archive: CDS artifact) as configured in the operational policy and providing CDS
  18 with all the input parameters that is required to execute the chosen CBA.
  19
  20 2. Objective
  21 ============
  22 The goal of the user guide is to clarify the contract between Policy and CDS so that a CBA developer can respect
  23 this input contract towards CDS when implementing the CBA.
  24
  25 3. Contract between Policy and CDS
  26 ==================================
  27 Policy upon receiving an incoming event from DCAE fires the rules and decides which actor to trigger.
  28 If the CDS actor is the chosen, Policy triggers the CBA execution using gRPC.
  29
  30 The parameters required for the execution of a CBA are internally handled by Policy.
  31 It makes uses of the incoming event, the operational policy configured and AAI lookup to build the CDS request payload.
  32
  33 3.1 CDS Blueprint Execution Payload format as invoked by Policy
  34 ---------------------------------------------------------------
  35 Below are the details of the contract established between Policy and CDS to enable the automation of a remediation
  36 action within the scope of a closed loop usecase in ONAP.
  37
  38 The format of the input payload for CDS follows the below guidelines, hence a CBA developer must consider this when
  39 implementing the CBA logic.
  40 For the sake of simplicity a JSON payload is used instead of a gRPC payload and each attribute of the child-nodes
  41 is documented.
  42
  43 3.1.1 CommonHeader
  44 ******************
  45
  46 The "commonHeader" field in the CBA execute payload is built by policy.
  47
  48 =============================== =========== ================================================================
  49    "commonHeader" field name       type                             Description
  50 =============================== =========== ================================================================
  51 subRequestId                      string      Generated by Policy. Is a UUID and used internally by policy.
  52 requestId                         string      Inserted by Policy. Maps to the UUID sent by DCAE i.e. the ID
  53                                               used throughout the closed loop lifecycle to identify a request.
  54 originatorId                      string      Generated by Policy and fixed to "POLICY"
  55 =============================== =========== ================================================================
  56
  57 3.1.2 ActionIdentifiers
  58 ***********************
  59
  60 The "actionIdentifiers" field uniquely identifies the CBA and the workflow to execute.
  61
  62 ==================================== =========== =============================================================
  63    "actionIdentifiers" field name       type                         Description
  64 ==================================== =========== =============================================================
  65 mode                                   string      Inserted by Policy and fixed to "sync" presently.
  66 blueprintName                          string      Inserted by Policy. Maps to the attribute that holds the
  67                                                    blueprint-name in the operational policy configuration.
  68 blueprintVersion                       string      Inserted by Policy. Maps to the attribute that holds the
  69                                                    blueprint-version in the operational policy configuration.
  70 actionName                             string      Inserted by Policy. Maps to the attribute that holds the
  71                                                    action-name in the operational policy configuration.
  72 ==================================== =========== =============================================================
  73
  74 3.1.3 Payload
  75 *************
  76
  77 The "payload" JSON node is generated by Policy for the action-name specified in the "actionIdentifiers" field
  78 which is eventually supplied through the operational policy configuration as indicated above.
  79
  80 3.1.3.1 Action request object
  81 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  82
  83 The "$actionName-request" object is generated by CDS for the action-name specified in the "actionIdentifiers" field.
  84
  85 The "$actionName-request" object contains:
  86
  87 * a field called "resolution-key" which CDS uses to store the resolved parameters into the CDS context
  88 * a child node object called "$actionName-properties" which holds a map of all the parameters that serve
  89   as inputs to the CBA. It presently holds the below information:
  90
  91   * all the AAI enriched attributes
  92   * additional parameters embedded in the Control Loop Event format which is sent by DCAE (analytics application).
  93   * any static information supplied through operational policy configuration which is not specific to an event
  94     but applies across all the events.
  95
  96 The data description for the action request object fields is as below:
  97
  98 - Resolution-key
  99
 100 ===================================== =========== ======================================================================
 101    "$actionName-request" field name      type                                Description
 102 ===================================== =========== ======================================================================
 103 resolution-key                          string      Generated by Policy. Is a UUID, generated each time CBA execute
 104                                                     request is invoked.
 105 ===================================== =========== ======================================================================
 106
 107 - Action properties object
 108
 109 ======================================== =============== ===============================================================
 110    "$actionName-properties" field name        type                               Description
 111 ======================================== =============== ===============================================================
 112 [$aai_node_type.$aai_attribute]              map             Inserted by Policy after performing AAI enrichment.
 113                                                              Is a map that contains AAI parameters for the target and
 114                                                              conforms to the notation: $aai_node_type.$aai_attribute.
 115                                                              E.g. for PNF the map looks like below.
 116
 117                                                                        .. code-block:: json
 118
 119                                                                          {
 120                                                                            "pnf.equip-vendor":"Vendor-A",
 121                                                                            "pnf.ipaddress-v4-oam":"10.10.10.10",
 122                                                                            "pnf.in-maint":false,
 123                                                                            "pnf.pnf-ipv4-address":"3.3.3.3",
 124                                                                            "pnf.resource-version":"1570746989505",
 125                                                                            "pnf.nf-role":"ToR DC101",
 126                                                                            "pnf.equip-type":"Router",
 127                                                                            "pnf.equip-model":"model-123456",
 128                                                                            "pnf.frame-id":"3",
 129                                                                            "pnf.pnf-name":"demo-pnf"
 130                                                                          }
 131 data                                        json object       Inserted by Policy. Maps to the static payload supplied
 132                                             OR string         through operational policy configuration. Used to hold
 133                                                               any static information which applies across all the
 134                                                               events as described above. If the value of the data
 135                                                               field is a valid JSON string it is converted to a JSON
 136                                                               object, else will be retained as a string.
 137 [$additionalEventParams]                     map              Inserted by Policy. Maps to the map of
 138                                                               additionalEvent parameters embedded into the
 139                                                               Control Loop Event message from DCAE.
 140 ======================================== =============== ===============================================================
 141
 142
 143
 144 3.1.4 Summing it up: CBA execute payload generation as done by Policy
 145 *********************************************************************
 146
 147 Putting all the above information together below is the REST equivalent of the CDS blueprint execute gRPC request
 148 generated by Policy.
 149
 150 REST equivalent of the gRPC request from Policy to CDS to execute a CBA.
 151
 152 .. code-block:: bash
 153
 154     curl -X POST \
 155       'http://{{ip}}:{{port}}/api/v1/execution-service/process' \
 156       -H 'Content-Type: application/json' \
 157       -H 'cache-control: no-cache' \
 158       -d '{
 159         "commonHeader":{
 160             "subRequestId":"{generated_by_policy}",
 161             "requestId":"{req_id_from_DCAE}",
 162             "originatorId":"POLICY"
 163         },
 164         "actionIdentifiers":{
 165             "mode":"sync",
 166             "blueprintName":"{blueprint_name_from_operational_policy_config}",
 167             "blueprintVersion":"{blueprint_version_from_operational_policy_config}",
 168             "actionName":"{blueprint_action_name_from_operational_policy_config}"
 169         },
 170         "payload":{
 171             "$actionName-request":{
 172                 "resolution-key":"{generated_by_policy}",
 173                 "$actionName-properties":{
 174                     "$aai_node_type.$aai_attribute_1":"",
 175                     "$aai_node_type.$aai_attribute_2":"",
 176                     .........
 177                     "data":"{static_payload_data_from_operational_policy_config}",
 178                     "$additionalEventParam_1":"",
 179                     "$additionalEventParam_2":"",
 180                     .........
 181                 }
 182             }
 183         }
 184     }'
 185
 186 3.1.5 Examples
 187 **************
 188
 189 Sample CBA execute request generated by Policy for PNF target type when "data" field is a string:
 190
 191 .. code-block:: bash
 192
 193     curl -X POST \
 194       'http://{{ip}}:{{port}}/api/v1/execution-service/process' \
 195       -H 'Content-Type: application/json' \
 196       -H 'cache-control: no-cache' \
 197       -d '{
 198         "commonHeader":{
 199             "subRequestId":"14384b21-8224-4055-bb9b-0469397db801",
 200             "requestId":"d57709fb-bbec-491d-a2a6-8a25c8097ee8",
 201             "originatorId":"POLICY"
 202         },
 203         "actionIdentifiers":{
 204             "mode":"sync",
 205             "blueprintName":"PNF-demo",
 206             "blueprintVersion":"1.0.0",
 207             "actionName":"reconfigure-pnf"
 208         },
 209         "payload":{
 210             "reconfigure-pnf-request":{
 211                 "resolution-key":"8338b828-51ad-4e7c-ac8b-08d6978892e2",
 212                 "reconfigure-pnf-properties":{
 213                     "pnf.equip-vendor":"Vendor-A",
 214                     "pnf.ipaddress-v4-oam":"10.10.10.10",
 215                     "pnf.in-maint":false,
 216                     "pnf.pnf-ipv4-address":"3.3.3.3",
 217                     "pnf.resource-version":"1570746989505",
 218                     "pnf.nf-role":"ToR DC101",
 219                     "pnf.equip-type":"Router",
 220                     "pnf.equip-model":"model-123456",
 221                     "pnf.frame-id":"3",
 222                     "pnf.pnf-name":"demo-pnf",
 223                     "data": "peer-as=64577",
 224                     "peer-group":"demo-peer-group",
 225                     "neighbor-address":"4.4.4.4"
 226                 }
 227             }
 228         }
 229     }'
 230
 231 Sample CBA execute request generated by Policy for VNF target type when "data" field is a valid JSON string:
 232
 233 .. code-block:: bash
 234
 235     curl -X POST \
 236       'http://{{ip}}:{{port}}/api/v1/execution-service/process' \
 237       -H 'Content-Type: application/json' \
 238       -H 'cache-control: no-cache' \
 239       -d '{
 240         "commonHeader":{
 241             "subRequestId":"14384b21-8224-4055-bb9b-0469397db801",
 242             "requestId":"d57709fb-bbec-491d-a2a6-8a25c8097ee8",
 243             "originatorId":"POLICY"
 244         },
 245         "actionIdentifiers":{
 246             "mode":"sync",
 247             "blueprintName":"vFW-CDS",
 248             "blueprintVersion":"1.0.0",
 249             "actionName":"config-deploy"
 250         },
 251         "payload":{
 252             "config-deploy-request":{
 253                 "resolution-key":"6128eb53-0eac-4c79-855c-ff56a7b81141",
 254                 "config-deploy-properties":{
 255                     "service-instance.service-instance-id":"40004db6-c51f-45b0-abab-ea4156bae422",
 256                     "generic-vnf.vnf-id":"8d09e3bd-ae1d-4765-b26e-4a45f568a092",
 257                     "data":{
 258                         "active-streams":"7"
 259                     }
 260                 }
 261             }
 262         }
 263     }'
 264
 265 4. Operational Policy configuration to use CDS as an actor
 266 ==========================================================
 267
 268 TODO: Document once Operational Policy TOSCA YAML redesign is finalized.