docs/development/actors/so/so.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 .. _so-label:
   6
   7 ##########
   8 SO Actor
   9 ##########
  10
  11 .. contents::
  12     :depth: 3
  13
  14 Overview of SO Actor
  15 ######################
  16 ONAP Policy Framework enables SO as one of the supported actors.  SO uses a REST-based
  17 interface.  However, as requests may not complete right away, a REST-based polling
  18 interface is used to check the status of the request.  The *requestId* is extracted
  19 from the initial response and is appended to the *pathGet* configuration parameter to
  20 generate the URL used to poll for completion.
  21
  22 Each operation supported by the actor is associated with its own java class, which is
  23 responsible for populating the request structure appropriately and sending the request.
  24 Note: the request may be issued via POST, DELETE, etc., depending on the operation.
  25 The operation-specific classes are all derived from the *SoOperation* class, which is,
  26 itself, derived from *HttpOperation*.  The following operations are currently supported:
  27
  28 - VF Module Create
  29 - VF Module Delete
  30
  31
  32 Request
  33 #######
  34
  35 A number of nested structures are populated within the request.  Several of them are
  36 populated with data extracted from the A&AI Custom Query response that is retrieved
  37 using the Target resource ID specified in the *ControlLoopOperationParams*.  The
  38 following table lists the contents of some of the fields that appear within these
  39 structures.
  40
  41 +----------------------------------+---------+----------------------------------------------------------------------+
  42 | Field Name                       |  Type   |                         Description                                  |
  43 +----------------------------------+---------+----------------------------------------------------------------------+
  44 +----------------------------------+---------+----------------------------------------------------------------------+
  45 | top level:                       |         |                                                                      |
  46 +----------------------------------+---------+----------------------------------------------------------------------+
  47 | *operationType*                  | string  |   Inserted by Policy. Name of the operation.                         |
  48 +----------------------------------+---------+----------------------------------------------------------------------+
  49 +----------------------------------+---------+----------------------------------------------------------------------+
  50 | requestDetails:                  |         |                                                                      |
  51 +----------------------------------+---------+----------------------------------------------------------------------+
  52 | requestParameters                |         |   Applicable to *VF Module Create*.                                  |
  53 |                                  |         |   Set by Policy from the *requestParameters* specified in the        |
  54 |                                  |         |   *payload* of the *ControlLoopOperationParams*.                     |
  55 |                                  |         |   The value is treated as a JSON string and decoded into an          |
  56 |                                  |         |   *SoRequestParameters* object that is placed into this field.       |
  57 +----------------------------------+---------+----------------------------------------------------------------------+
  58 | configurationParameters          |         |   Applicable to *VF Module Create*.                                  |
  59 |                                  |         |   Set by Policy from the *configurationParameters* specified in the  |
  60 |                                  |         |   *payload* of the *ControlLoopOperationParams*.                     |
  61 |                                  |         |   The value is treated as a JSON string and decoded into a           |
  62 |                                  |         |   *List* of *Maps* that is placed into this field.                   |
  63 +----------------------------------+---------+----------------------------------------------------------------------+
  64 +----------------------------------+---------+----------------------------------------------------------------------+
  65 | modelInfo:                       |         |   Set by Policy.  Copied from the *target* specified in the          |
  66 |                                  |         |   *ControlLoopOperationParams*.                                      |
  67 +----------------------------------+---------+----------------------------------------------------------------------+
  68 +----------------------------------+---------+----------------------------------------------------------------------+
  69 | cloudConfiguration:              |         |                                                                      |
  70 +----------------------------------+---------+----------------------------------------------------------------------+
  71 | *tenantId*                       | string  |   The ID of the "default" Tenant selected from the A&AI Custom Query |
  72 |                                  |         |   response.                                                          |
  73 +----------------------------------+---------+----------------------------------------------------------------------+
  74 | *lcpCloudRegionId*               | string  |   The ID of the "default" Cloud Region selected from the A&AI Custom |
  75 |                                  |         |   Query response.                                                    |
  76 +----------------------------------+---------+----------------------------------------------------------------------+
  77 +----------------------------------+---------+----------------------------------------------------------------------+
  78 | relatedInstanceList[0]:          |         |   Applicable to *VF Module Create*.                                  |
  79 |                                  |         |   The "default" Service Instance selected from the A&AI Custom Query |
  80 |                                  |         |   response.                                                          |
  81 +----------------------------------+---------+----------------------------------------------------------------------+
  82 +----------------------------------+---------+----------------------------------------------------------------------+
  83 | relatedInstanceList[1]:          |         |   Applicable to *VF Module Create*.                                  |
  84 |                                  |         |   The VNF selected from the A&AI Custom Query                        |
  85 |                                  |         |   response.                                                          |
  86 +----------------------------------+---------+----------------------------------------------------------------------+
  87
  88
  89 Examples
  90 ########
  91
  92 Suppose the *ControlLoopOperationParams* were populated as follows:
  93
  94 .. code-block:: bash
  95
  96         {
  97             "actor": "SO",
  98             "operation": "Reroute",
  99             "target": {
 100                 "modelInvariantId": "2246ebc9-9b9f-42d0-a5e4-0248324fb884",
 101                 "modelName": "VlbCdsSb00..vdns..module-3",
 102                 "modelVersion": "1",
 103                 "modelCustomizationUuid": "3a74410a-6c74-4a32-94b2-71488be6da1a",
 104                 "modelVersionId": "1f94cedb-f656-4ddb-9f55-60ba1fc7d4b1",
 105                 "modelCustomizationId": "3a74410a-6c74-4a32-94b2-71488be6da1a",
 106                 "modelUuid": "1f94cedb-f656-4ddb-9f55-60ba1fc7d4b1",
 107                 "modelInvariantUuid": "2246ebc9-9b9f-42d0-a5e4-0248324fb884"
 108             },
 109             "context": {
 110                 "cqdata": {
 111                     "tenant": {
 112                         "id": "41d6d38489bd40b09ea8a6b6b852dcbd"
 113                     },
 114                     "cloud-region": {
 115                         "id": "RegionOne"
 116                     },
 117                     "service-instance": {
 118                         "id": "c14e61b5-1ee6-4925-b4a9-b9c8dbfe3f34",
 119                         "modelInvariantId": "6418bb39-61e1-45fc-a36b-3f211bb846c7",
 120                         "modelName": "vLB_CDS_SB00_02",
 121                         "modelVersion": "1.0",
 122                         "modelVersionId": "d01d9dec-afb6-4a53-bd9e-2eb10ca07a51",
 123                         "modelUuid": "d01d9dec-afb6-4a53-bd9e-2eb10ca07a51",
 124                         "modelInvariantUuid": "6418bb39-61e1-45fc-a36b-3f211bb846c7"
 125                     },
 126                     "generic-vnf": [
 127                         {
 128                             "vnfId": "6636c4d5-f608-4376-b6d8-7977e98cb16d",
 129                             "vf-modules": [
 130                                 {
 131                                     "modelInvariantId": "827356a9-cb60-4976-9713-c30b4f850b41",
 132                                     "modelName": "vLB_CDS_SB00",
 133                                     "modelVersion": "1.0",
 134                                     "modelCustomizationUuid": "6478f94b-0b20-4b44-afc0-94e48070586a",
 135                                     "modelVersionId": "ca3c4797-0cdd-4797-8bec-9a3ce78ac4da",
 136                                     "modelCustomizationId": "6478f94b-0b20-4b44-afc0-94e48070586a",
 137                                     "modelUuid": "ca3c4797-0cdd-4797-8bec-9a3ce78ac4da",
 138                                     "modelInvariantUuid": "827356a9-cb60-4976-9713-c30b4f850b41"
 139                                 }
 140                             ]
 141                         }
 142                     ]
 143                 }
 144             },
 145             "payload": {
 146                 "requestParameters": "{\"usePreload\": false}",
 147                 "configurationParameters": "[{\"ip-addr\": \"$.vf-module-topology.vf-module-parameters.param[16].value\", \"oam-ip-addr\": \"$.vf-module-topology.vf-module-parameters.param[30].value\"}]"
 148             }
 149         }
 150
 151 An example of a request constructed by the actor using the above parameters, sent to the
 152 SO REST server:
 153
 154 .. code-block:: bash
 155
 156     {
 157       "requestDetails": {
 158         "modelInfo": {
 159             "modelInvariantId": "2246ebc9-9b9f-42d0-a5e4-0248324fb884",
 160             "modelType": "vfModule",
 161             "modelName": "VlbCdsSb00..vdns..module-3",
 162             "modelVersion": "1",
 163             "modelCustomizationUuid": "3a74410a-6c74-4a32-94b2-71488be6da1a",
 164             "modelVersionId": "1f94cedb-f656-4ddb-9f55-60ba1fc7d4b1",
 165             "modelCustomizationId": "3a74410a-6c74-4a32-94b2-71488be6da1a",
 166             "modelUuid": "1f94cedb-f656-4ddb-9f55-60ba1fc7d4b1",
 167             "modelInvariantUuid": "2246ebc9-9b9f-42d0-a5e4-0248324fb884"
 168         },
 169         "cloudConfiguration": {
 170             "tenantId": "41d6d38489bd40b09ea8a6b6b852dcbd",
 171             "lcpCloudRegionId": "RegionOne"
 172         },
 173         "requestInfo": {
 174           "instanceName": "vfModuleName",
 175           "source": "POLICY",
 176           "suppressRollback": false,
 177           "requestorId": "policy"
 178         },
 179         "relatedInstanceList": [
 180           {
 181             "relatedInstance": {
 182                 "instanceId": "c14e61b5-1ee6-4925-b4a9-b9c8dbfe3f34",
 183                 "modelInfo": {
 184                     "modelInvariantId": "6418bb39-61e1-45fc-a36b-3f211bb846c7",
 185                     "modelType": "service",
 186                     "modelName": "vLB_CDS_SB00_02",
 187                     "modelVersion": "1.0",
 188                     "modelVersionId": "d01d9dec-afb6-4a53-bd9e-2eb10ca07a51",
 189                     "modelUuid": "d01d9dec-afb6-4a53-bd9e-2eb10ca07a51",
 190                     "modelInvariantUuid": "6418bb39-61e1-45fc-a36b-3f211bb846c7"
 191                 }
 192             }
 193           },
 194           {
 195             "relatedInstance": {
 196                 "instanceId": "6636c4d5-f608-4376-b6d8-7977e98cb16d",
 197                 "modelInfo": {
 198                     "modelInvariantId": "827356a9-cb60-4976-9713-c30b4f850b41",
 199                     "modelType": "vnf",
 200                     "modelName": "vLB_CDS_SB00",
 201                     "modelVersion": "1.0",
 202                     "modelCustomizationUuid": "6478f94b-0b20-4b44-afc0-94e48070586a",
 203                     "modelVersionId": "ca3c4797-0cdd-4797-8bec-9a3ce78ac4da",
 204                     "modelCustomizationId": "6478f94b-0b20-4b44-afc0-94e48070586a",
 205                     "modelUuid": "ca3c4797-0cdd-4797-8bec-9a3ce78ac4da",
 206                     "modelInvariantUuid": "827356a9-cb60-4976-9713-c30b4f850b41"
 207                 }
 208             }
 209           }
 210         ],
 211         "requestParameters": {
 212             "usePreload": false
 213         },
 214         "configurationParameters": [
 215             {
 216                 "ip-addr": "$.vf-module-topology.vf-module-parameters.param[16].value",
 217                 "oam-ip-addr": "$.vf-module-topology.vf-module-parameters.param[30].value"
 218             }
 219         ]
 220       }
 221     }
 222
 223 An example response received to the initial request, from the SO REST service:
 224
 225 .. code-block:: bash
 226
 227         {
 228             "requestReferences": {
 229                 "requestId": "70f28791-c271-4cae-b090-0c2a359e26d9",
 230                 "instanceId": "68804843-18e0-41a3-8838-a6d90a035e1a",
 231                 "requestSelfLink": "http://so.onap:8080/orchestrationRequests/v7/b789e4e6-0b92-42c3-a723-1879af9c799d"
 232             }
 233         }
 234
 235 An example URL used for the "get" (i.e., poll) request subsequently sent to SO:
 236
 237 .. code-block:: bash
 238
 239         GET https://so.onap:6969/orchestrationRequests/v5/70f28791-c271-4cae-b090-0c2a359e26d9
 240
 241 An example response received to the poll request, when SO has not completed the request:
 242
 243 .. code-block:: bash
 244
 245     {
 246         "request": {
 247             "requestId": "70f28791-c271-4cae-b090-0c2a359e26d9",
 248             "startTime": "Fri, 15 May 2020 12:12:50 GMT",
 249             "requestScope": "vfModule",
 250             "requestType": "scaleOut",
 251             "requestDetails": {
 252                 "modelInfo": {
 253                     "modelInvariantId": "2246ebc9-9b9f-42d0-a5e4-0248324fb884",
 254                     "modelType": "vfModule",
 255                     "modelName": "VlbCdsSb00..vdns..module-3",
 256                     "modelVersion": "1",
 257                     "modelCustomizationUuid": "3a74410a-6c74-4a32-94b2-71488be6da1a",
 258                     "modelVersionId": "1f94cedb-f656-4ddb-9f55-60ba1fc7d4b1",
 259                     "modelCustomizationId": "3a74410a-6c74-4a32-94b2-71488be6da1a",
 260                     "modelUuid": "1f94cedb-f656-4ddb-9f55-60ba1fc7d4b1",
 261                     "modelInvariantUuid": "2246ebc9-9b9f-42d0-a5e4-0248324fb884"
 262                 },
 263                 "requestInfo": {
 264                     "source": "POLICY",
 265                     "instanceName": "vfModuleName",
 266                     "suppressRollback": false,
 267                     "requestorId": "policy"
 268                 },
 269                 "relatedInstanceList": [
 270                     {
 271                         "relatedInstance": {
 272                             "instanceId": "c14e61b5-1ee6-4925-b4a9-b9c8dbfe3f34",
 273                             "modelInfo": {
 274                                 "modelInvariantId": "6418bb39-61e1-45fc-a36b-3f211bb846c7",
 275                                 "modelType": "service",
 276                                 "modelName": "vLB_CDS_SB00_02",
 277                                 "modelVersion": "1.0",
 278                                 "modelVersionId": "d01d9dec-afb6-4a53-bd9e-2eb10ca07a51",
 279                                 "modelUuid": "d01d9dec-afb6-4a53-bd9e-2eb10ca07a51",
 280                                 "modelInvariantUuid": "6418bb39-61e1-45fc-a36b-3f211bb846c7"
 281                             }
 282                         }
 283                     },
 284                     {
 285                         "relatedInstance": {
 286                             "instanceId": "6636c4d5-f608-4376-b6d8-7977e98cb16d",
 287                             "modelInfo": {
 288                                 "modelInvariantId": "827356a9-cb60-4976-9713-c30b4f850b41",
 289                                 "modelType": "vnf",
 290                                 "modelName": "vLB_CDS_SB00",
 291                                 "modelVersion": "1.0",
 292                                 "modelCustomizationUuid": "6478f94b-0b20-4b44-afc0-94e48070586a",
 293                                 "modelVersionId": "ca3c4797-0cdd-4797-8bec-9a3ce78ac4da",
 294                                 "modelCustomizationId": "6478f94b-0b20-4b44-afc0-94e48070586a",
 295                                 "modelUuid": "ca3c4797-0cdd-4797-8bec-9a3ce78ac4da",
 296                                 "modelInvariantUuid": "827356a9-cb60-4976-9713-c30b4f850b41"
 297                             }
 298                         }
 299                     }
 300                 ],
 301                 "cloudConfiguration": {
 302                     "tenantId": "41d6d38489bd40b09ea8a6b6b852dcbd",
 303                     "tenantName": "Integration-SB-00",
 304                     "cloudOwner": "CloudOwner",
 305                     "lcpCloudRegionId": "RegionOne"
 306                 },
 307                 "requestParameters": {
 308                     "usePreload": false
 309                 },
 310                 "configurationParameters": [
 311                     {
 312                         "ip-addr": "$.vf-module-topology.vf-module-parameters.param[16].value",
 313                         "oam-ip-addr": "$.vf-module-topology.vf-module-parameters.param[30].value"
 314                     }
 315                 ]
 316             },
 317             "instanceReferences": {
 318                 "serviceInstanceId": "c14e61b5-1ee6-4925-b4a9-b9c8dbfe3f34",
 319                 "vnfInstanceId": "6636c4d5-f608-4376-b6d8-7977e98cb16d",
 320                 "vfModuleInstanceId": "68804843-18e0-41a3-8838-a6d90a035e1a",
 321                 "vfModuleInstanceName": "vfModuleName"
 322             },
 323             "requestStatus": {
 324                 "requestState": "IN_PROGRESS",
 325                 "statusMessage": "FLOW STATUS: Execution of ActivateVfModuleBB has completed successfully, next invoking ConfigurationScaleOutBB (Execution Path progress: BBs completed = 4; BBs remaining = 2). TASK INFORMATION: Last task executed: Call SDNC RESOURCE STATUS: The vf module was found to already exist, thus no new vf module was created in the cloud via this request",
 326                 "percentProgress": 68,
 327                 "timestamp": "Fri, 15 May 2020 12:13:41 GMT"
 328             }
 329         }
 330     }
 331
 332 An example response received to the poll request, when SO has completed the request:
 333
 334 .. code-block:: bash
 335
 336     {
 337         "request": {
 338             "requestId": "70f28791-c271-4cae-b090-0c2a359e26d9",
 339             "startTime": "Fri, 15 May 2020 12:12:50 GMT",
 340             "finishTime": "Fri, 15 May 2020 12:14:21 GMT",
 341             "requestScope": "vfModule",
 342             "requestType": "scaleOut",
 343             "requestDetails": {
 344                 "modelInfo": {
 345                     "modelInvariantId": "2246ebc9-9b9f-42d0-a5e4-0248324fb884",
 346                     "modelType": "vfModule",
 347                     "modelName": "VlbCdsSb00..vdns..module-3",
 348                     "modelVersion": "1",
 349                     "modelCustomizationUuid": "3a74410a-6c74-4a32-94b2-71488be6da1a",
 350                     "modelVersionId": "1f94cedb-f656-4ddb-9f55-60ba1fc7d4b1",
 351                     "modelCustomizationId": "3a74410a-6c74-4a32-94b2-71488be6da1a",
 352                     "modelUuid": "1f94cedb-f656-4ddb-9f55-60ba1fc7d4b1",
 353                     "modelInvariantUuid": "2246ebc9-9b9f-42d0-a5e4-0248324fb884"
 354                 },
 355                 "requestInfo": {
 356                     "source": "POLICY",
 357                     "instanceName": "vfModuleName",
 358                     "suppressRollback": false,
 359                     "requestorId": "policy"
 360                 },
 361                 "relatedInstanceList": [
 362                     {
 363                         "relatedInstance": {
 364                             "instanceId": "c14e61b5-1ee6-4925-b4a9-b9c8dbfe3f34",
 365                             "modelInfo": {
 366                                 "modelInvariantId": "6418bb39-61e1-45fc-a36b-3f211bb846c7",
 367                                 "modelType": "service",
 368                                 "modelName": "vLB_CDS_SB00_02",
 369                                 "modelVersion": "1.0",
 370                                 "modelVersionId": "d01d9dec-afb6-4a53-bd9e-2eb10ca07a51",
 371                                 "modelUuid": "d01d9dec-afb6-4a53-bd9e-2eb10ca07a51",
 372                                 "modelInvariantUuid": "6418bb39-61e1-45fc-a36b-3f211bb846c7"
 373                             }
 374                         }
 375                     },
 376                     {
 377                         "relatedInstance": {
 378                             "instanceId": "6636c4d5-f608-4376-b6d8-7977e98cb16d",
 379                             "modelInfo": {
 380                                 "modelInvariantId": "827356a9-cb60-4976-9713-c30b4f850b41",
 381                                 "modelType": "vnf",
 382                                 "modelName": "vLB_CDS_SB00",
 383                                 "modelVersion": "1.0",
 384                                 "modelCustomizationUuid": "6478f94b-0b20-4b44-afc0-94e48070586a",
 385                                 "modelVersionId": "ca3c4797-0cdd-4797-8bec-9a3ce78ac4da",
 386                                 "modelCustomizationId": "6478f94b-0b20-4b44-afc0-94e48070586a",
 387                                 "modelUuid": "ca3c4797-0cdd-4797-8bec-9a3ce78ac4da",
 388                                 "modelInvariantUuid": "827356a9-cb60-4976-9713-c30b4f850b41"
 389                             }
 390                         }
 391                     }
 392                 ],
 393                 "cloudConfiguration": {
 394                     "tenantId": "41d6d38489bd40b09ea8a6b6b852dcbd",
 395                     "tenantName": "Integration-SB-00",
 396                     "cloudOwner": "CloudOwner",
 397                     "lcpCloudRegionId": "RegionOne"
 398                 },
 399                 "requestParameters": {
 400                     "usePreload": false
 401                 },
 402                 "configurationParameters": [
 403                     {
 404                         "ip-addr": "$.vf-module-topology.vf-module-parameters.param[16].value",
 405                         "oam-ip-addr": "$.vf-module-topology.vf-module-parameters.param[30].value"
 406                     }
 407                 ]
 408             },
 409             "instanceReferences": {
 410                 "serviceInstanceId": "c14e61b5-1ee6-4925-b4a9-b9c8dbfe3f34",
 411                 "vnfInstanceId": "6636c4d5-f608-4376-b6d8-7977e98cb16d",
 412                 "vfModuleInstanceId": "68804843-18e0-41a3-8838-a6d90a035e1a",
 413                 "vfModuleInstanceName": "vfModuleName"
 414             },
 415             "requestStatus": {
 416                 "requestState": "COMPLETE",
 417                 "statusMessage": "STATUS: ALaCarte-VfModule-scaleOut request was executed correctly. FLOW STATUS: Successfully completed all Building Blocks RESOURCE STATUS: The vf module was found to already exist, thus no new vf module was created in the cloud via this request",
 418                 "percentProgress": 100,
 419                 "timestamp": "Fri, 15 May 2020 12:14:21 GMT"
 420             }
 421         }
 422     }
 423
 424
 425 Configuration of the SO Actor
 426 ###############################
 427
 428 The following table specifies the fields that should be provided to configure the SO
 429 actor.
 430
 431 =============================== ====================    ==================================================================
 432 Field name                         type                             Description
 433 =============================== ====================    ==================================================================
 434 clientName                        string                  Name of the HTTP client to use to send the request to the
 435                                                           SO REST server.
 436 timeoutSec                        integer (optional)      Maximum time, in seconds, to wait for a response to be received
 437                                                           from the REST server.  Defaults to 90s.
 438 path                              string                  URI appended to the URL.  This field only applies to individual
 439                                                           operations; it does not apply at the actor level.  Note: the
 440                                                           *path* should not include a leading or trailing slash.
 441 maxGets                           integer (optional)      Maximum number of get/poll requests to make to determine the
 442                                                           final outcome of the request.  Defaults to 20.
 443 waitSecGet                        integer (optional)      Time, in seconds, to wait between issuing "get" requests.
 444                                                           Defaults to 20s.
 445 pathGet                           string (optional)       Path to use when polling (i.e., issuing "get" requests).
 446                                                           Note: this should include a trailing slash, but no leading
 447                                                           slash.
 448 =============================== ====================    ==================================================================
 449
 450 The individual operations are configured using these same field names.  However, all
 451 of them, except the *path*, are optional, as they inherit their values from the
 452 corresponding actor-level fields.