docs/development/actors/cds/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       -u 'ccsdkapps:ccsdkapps' \
 157       -H 'Content-Type: application/json' \
 158       -H 'cache-control: no-cache' \
 159       -d '{
 160         "commonHeader":{
 161             "subRequestId":"{generated_by_policy}",
 162             "requestId":"{req_id_from_DCAE}",
 163             "originatorId":"POLICY"
 164         },
 165         "actionIdentifiers":{
 166             "mode":"sync",
 167             "blueprintName":"{blueprint_name_from_operational_policy_config}",
 168             "blueprintVersion":"{blueprint_version_from_operational_policy_config}",
 169             "actionName":"{blueprint_action_name_from_operational_policy_config}"
 170         },
 171         "payload":{
 172             "$actionName-request":{
 173                 "resolution-key":"{generated_by_policy}",
 174                 "$actionName-properties":{
 175                     "$aai_node_type.$aai_attribute_1":"",
 176                     "$aai_node_type.$aai_attribute_2":"",
 177                     .........
 178                     "data":"{static_payload_data_from_operational_policy_config}",
 179                     "$additionalEventParam_1":"",
 180                     "$additionalEventParam_2":"",
 181                     .........
 182                 }
 183             }
 184         }
 185     }'
 186
 187 3.1.5 Examples
 188 **************
 189
 190 Sample CBA execute request generated by Policy for PNF target type when "data" field is a string:
 191
 192 .. code-block:: bash
 193
 194     curl -X POST \
 195       'http://{{ip}}:{{port}}/api/v1/execution-service/process' \
 196       -u 'ccsdkapps:ccsdkapps' \
 197       -H 'Content-Type: application/json' \
 198       -H 'cache-control: no-cache' \
 199       -d '{
 200         "commonHeader":{
 201             "subRequestId":"14384b21-8224-4055-bb9b-0469397db801",
 202             "requestId":"d57709fb-bbec-491d-a2a6-8a25c8097ee8",
 203             "originatorId":"POLICY"
 204         },
 205         "actionIdentifiers":{
 206             "mode":"sync",
 207             "blueprintName":"PNF-demo",
 208             "blueprintVersion":"1.0.0",
 209             "actionName":"reconfigure-pnf"
 210         },
 211         "payload":{
 212             "reconfigure-pnf-request":{
 213                 "resolution-key":"8338b828-51ad-4e7c-ac8b-08d6978892e2",
 214                 "reconfigure-pnf-properties":{
 215                     "pnf.equip-vendor":"Vendor-A",
 216                     "pnf.ipaddress-v4-oam":"10.10.10.10",
 217                     "pnf.in-maint":false,
 218                     "pnf.pnf-ipv4-address":"3.3.3.3",
 219                     "pnf.resource-version":"1570746989505",
 220                     "pnf.nf-role":"ToR DC101",
 221                     "pnf.equip-type":"Router",
 222                     "pnf.equip-model":"model-123456",
 223                     "pnf.frame-id":"3",
 224                     "pnf.pnf-name":"demo-pnf",
 225                     "data": "peer-as=64577",
 226                     "peer-group":"demo-peer-group",
 227                     "neighbor-address":"4.4.4.4"
 228                 }
 229             }
 230         }
 231     }'
 232
 233 Sample CBA execute request generated by Policy for VNF target type when "data" field is a valid JSON string:
 234
 235 .. code-block:: bash
 236
 237     curl -X POST \
 238       'http://{{ip}}:{{port}}/api/v1/execution-service/process' \
 239       -u 'ccsdkapps:ccsdkapps' \
 240       -H 'Content-Type: application/json' \
 241       -H 'cache-control: no-cache' \
 242       -d '{
 243         "commonHeader":{
 244             "subRequestId":"14384b21-8224-4055-bb9b-0469397db801",
 245             "requestId":"d57709fb-bbec-491d-a2a6-8a25c8097ee8",
 246             "originatorId":"POLICY"
 247         },
 248         "actionIdentifiers":{
 249             "mode":"sync",
 250             "blueprintName":"vFW-CDS",
 251             "blueprintVersion":"1.0.0",
 252             "actionName":"config-deploy"
 253         },
 254         "payload":{
 255             "config-deploy-request":{
 256                 "resolution-key":"6128eb53-0eac-4c79-855c-ff56a7b81141",
 257                 "config-deploy-properties":{
 258                     "service-instance.service-instance-id":"40004db6-c51f-45b0-abab-ea4156bae422",
 259                     "generic-vnf.vnf-id":"8d09e3bd-ae1d-4765-b26e-4a45f568a092",
 260                     "data":{
 261                         "active-streams":"7"
 262                     }
 263                 }
 264             }
 265         }
 266     }'
 267
 268 4. Operational Policy configuration to use CDS as an actor
 269 ==========================================================
 270
 271 4.1 TOSCA compliant Control Loop Operational Policy to support CDS actor
 272 ------------------------------------------------------------------------
 273
 274 A common base TOSCA policy type for defining an operational policy is documented below:
 275
 276 * https://gerrit.onap.org/r/gitweb?p=policy/models.git;a=blob;f=models-examples/src/main/resources/policytypes/onap.policies.controlloop.operational.Common.yaml;h=fe6f974bb98a90e2e41639621ba35cc853679ee5;hb=HEAD
 277
 278 APEX PDP specific operational policy is derived from the common operational TOSCA policy type as defined in the link below:
 279 * https://gerrit.onap.org/r/gitweb?p=policy/models.git;a=blob;f=models-examples/src/main/resources/policytypes/onap.policies.controlloop.operational.common.Apex.yaml;h=54b69c2d8a78ab7fd8d41d3f7c05632c4d7e433d;hb=HEAD
 280
 281 Drools PDP specific operational policy is also derived from the common operational TOSCA policy type and is defined in the link below:
 282 * https://gerrit.onap.org/r/gitweb?p=policy/models.git;a=blob;f=models-examples/src/main/resources/policytypes/onap.policies.controlloop.operational.common.Drools.yaml;h=69d73db5827cb6743172f9e0b1930eca8ba4ec0c;hb=HEAD
 283
 284 For integration testing CLAMP UI can be used to configure the Operational Policy.
 285
 286 E.g. Sample Operational Policy definition for vFW usecase to use CDS as an actor:
 287
 288 .. code-block:: bash
 289
 290     tosca_definitions_version: tosca_simple_yaml_1_1_0
 291     topology_template:
 292         policies:
 293         -   operational.modifyconfig.cds:
 294                 type: onap.policies.controlloop.operational.common.Drools
 295                 type_version: 1.0.0
 296                 version: 1.0.0
 297                 metadata:
 298                     policy-id: operational.modifyconfig.cds
 299                 properties:
 300                     id: ControlLoop-vFirewall-d0a1dfc6-94f5-4fd4-a5b5-4630b438850a
 301                     timeout: 1200
 302                     abatement: false
 303                     trigger: unique-policy-id-1-modifyConfig
 304                     operations:
 305                     -   id: unique-policy-id-1-modifyConfig
 306                         description: Modify the packet generator
 307                         operation:
 308                             actor: CDS
 309                             operation: ModifyConfig
 310                             target:
 311                                 targetType: VNF
 312                                 entityId:
 313                                     resourceID: bbb3cefd-01c8-413c-9bdd-2b92f9ca3d38
 314                             payload:
 315                                 artifact_name: vfw-cds
 316                                 artifact_version: 1.0.0
 317                                 mode: async
 318                                 data: '{"active-streams":"7"}'
 319                         timeout: 300
 320                         retries: 0
 321                         success: final_success
 322                         failure: final_failure
 323                         failure_timeout: final_failure_timeout
 324                         failure_retries: final_failure_retries
 325                         failure_exception: final_failure_exception
 326                         failure_guard: final_failure_guard
 327                     controllerName: usecases
 328
 329 4.2 API to configure the Control Loop Operational policy
 330 --------------------------------------------------------
 331
 332 4.2.1 Policy creation
 333 *********************
 334
 335 Policy API endpoint is used to create policy i.e. an instance of the TOSCA compliant Operational policy type.
 336 E.g. For vFW usecase the policy-type is "onap.policies.controlloop.operational.common.Drools".
 337
 338 In the below rest endpoint, the hostname points to K8S service "policy-api" and internal port 6969.
 339
 340 .. code-block:: bash
 341
 342     curl POST 'https://{$POLICY_API_URL}:{$POLICY_API_SERVICE_PORT}/policy/api/v1/policytypes/onap.policies.controlloop.operational.common.Drools/versions/1.0.0/policies/operational.modifyconfig/versions/1.0.0' \
 343     -H 'Accept: application/json' \
 344     -H 'Content-Type: application/json' \
 345     -u 'healthcheck:zb!XztG34' \
 346     -d '{$vfw-tosca-policy}
 347
 348 Note: In order to create an operational policy when using APEX PDP use the policy-type:
 349 "onap.policies.controlloop.operational.common.Apex".
 350
 351 4.2.2 Policy deployment to PDP
 352 ******************************
 353
 354 Policy PAP endpoint is used in order to deploy the policy to the appropriate PDP instance.
 355 In the rest endpoint URI, the hostname points to the service "policy-pap" and internal port 6969.
 356
 357 .. code-block:: bash
 358
 359     curl POST 'https://{$POLICY_PAP_URL}:{$POLICY_PAP_SERVICE_PORT}/policy/pap/v1/pdps/deployments/batch' \
 360     -H 'Content-Type: application/json' \
 361     -H 'Accept: application/json' \
 362     -u 'healthcheck:zb!XztG34' \
 363     -d '{
 364         "groups": [
 365             {
 366                 "name": "defaultGroup",
 367                 "deploymentSubgroups": [
 368                     {
 369                         "pdpType": "drools",
 370                         "action": "POST",
 371                         "policies": [{
 372                                 "name": "operational.modifyconfig.cds",
 373                                 "version": "1.0.0"
 374                             }]
 375                     }
 376                 ]
 377             }
 378         ]
 379     }'
 380
 381 To view the configured policies use the below REST API.
 382
 383 .. code-block:: bash
 384
 385     curl GET 'https://{$POLICY_API_URL}:{$POLICY_API_SERVICE_PORT}/policy/api/v1/policytypes/onap.policies.controlloop.operational.common.Drools/versions/1.0.0/policies/operational.modifyconfig/versions/1.0.0' \
 386     -H 'Accept: application/json' \
 387     -u 'healthcheck:zb!XztG34'
 388
 389 .. code-block:: bash
 390
 391     curl --location --request GET 'https://{$POLICY_PAP_URL}:{$POLICY_PAP_SERVICE_PORT}/policy/pap/v1/pdps' \
 392     -H 'Accept: application/json' \
 393     -u 'healthcheck:zb!XztG34'