docs/development/actors/appclcm/appclcm.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 .. _appclcm-label:
   6
   7 ##############
   8 APPC LCM Actor
   9 ##############
  10
  11 .. contents::
  12     :depth: 3
  13
  14 Overview of APPC LCM Actor
  15 ##########################
  16 ONAP Policy Framework enables APPC as one of the supported actors.  The APPC LCM Actor
  17 contains operations supporting both the LCM interface and the legacy interface.
  18 As such, this actor supersedes the APPC Legacy actor.  Its sequence number is lower
  19 than the APPC Legacy actor's sequence number, which ensures that it is loaded
  20 first.
  21
  22 APPC Legacy uses a single DMaaP topic for both requests and responses.  The class(es)
  23 supporting this interface are described in :ref:`appc-legacy-label`.  The APPC LCM
  24 Actor only supports the APPC Legacy operation, *ModifyConfig*.
  25
  26 The APPC LCM interface, on the other hand, uses two DMaaP topics, one to which requests
  27 are published, and another from which responses are received.  Similar to the legacy
  28 interface, APPC LCM may generate more than one response for a particular request, the
  29 first response simply indicating that the request was accepted, while the second
  30 response indicates completion of the request.
  31
  32 For each request, a unique sub-request ID is generated.  This is used to match the
  33 received responses with the published requests.  (APPC LCM also has a "correlation-id"
  34 field, which could potentially be used to match the response to the request, but
  35 apparently APPC LCM has not implemented that capability yet.)
  36
  37 All APPC LCM operations are currently supported by a single java class,
  38 *AppcLcmOperation*, which is responsible for populating the request structure
  39 appropriately.  This class is derived from *BidirectionalTopicOperation*.
  40
  41
  42 **The remainder of this discussion describes the operations that are specific to APPC
  43 LCM.**
  44
  45
  46 Request
  47 #######
  48
  49 CommonHeader
  50 ************
  51
  52 The "common-header" field in the request is built by policy.
  53
  54 =============================== =========== ==================================================================
  55    "common-header" field name       type                             Description
  56 =============================== =========== ==================================================================
  57 sub-request-id                    string      Generated by Policy. Is a UUID and used internally by policy
  58                                               to match the response with the request.
  59 request-id                        string      Inserted by Policy. Maps to the UUID sent by DCAE i.e. the ID
  60                                               used throughout the closed loop lifecycle to identify a request.
  61 originator-id                     string      Copy of the request-id.
  62 =============================== =========== ==================================================================
  63
  64
  65 Action
  66 ******
  67
  68 The "action" field uniquely identifies the operation to perform.  Currently, the
  69 following operations are supported:
  70
  71 - Restart
  72 - Rebuild
  73 - Migrate
  74 - ConfigModify
  75
  76 The valid operations are listed in *AppcLcmConstants*.  These are the values that must
  77 be specified in the policy.  However, before being stuffed into the "action" field,
  78 they are converted to camel case, stripping any hyphens, and translating the first
  79 character to upper case, if it isn't already.
  80
  81
  82 Action Identifiers
  83 ******************
  84
  85 Currently, the "action-identifiers" field contains only the VNF ID, which should be the
  86 *targetEntity* specified within the *ControlLoopOperationParams*.
  87
  88
  89 Payload
  90 *******
  91
  92 The "payload" field is populated based on the *payload* specified within the
  93 *ControlLoopOperationParams*.  Unlike the APPC Legacy operations, which inject POJOs
  94 into the "payload" field, the APPC LCM operations simply encode the entire
  95 parameter *payload* into a JSON string, and then place the encoded string into the
  96 "payload" field of the request.
  97
  98
  99 Examples
 100 ########
 101
 102 Suppose the *ControlLoopOperationParams* were populated as follows:
 103
 104 .. code-block:: bash
 105
 106         {
 107             "actor": "APPC",
 108             "operation": "Restart",
 109             "targetEntity": "my-target",
 110             "payload": {
 111                 "my-key-A": "hello",
 112                 "my-key-B": "world"
 113             },
 114             "context": {
 115                 "event": {
 116                     "requestId": "664be3d2-6c12-4f4b-a3e7-c349acced200"
 117                 }
 118             }
 119         }
 120
 121 An example of a request constructed by the actor using the above parameters, published
 122 to the APPC LCM request topic:
 123
 124 .. code-block:: bash
 125
 126         {
 127           "version": "2.0",
 128           "rpc-name": "restart",
 129           "correlation-id": "664be3d2-6c12-4f4b-a3e7-c349acced200-8c4c1914-00ed-4be0-ae3b-49dd22e8f461",
 130           "type": "request",
 131           "body": {
 132             "input": {
 133               "common-header": {
 134                 "timestamp": "2020-05-14T19:19:32.619890900Z",
 135                 "api-ver": "2.00",
 136                 "originator-id": "664be3d2-6c12-4f4b-a3e7-c349acced200",
 137                 "request-id": "664be3d2-6c12-4f4b-a3e7-c349acced200",
 138                 "sub-request-id": "8c4c1914-00ed-4be0-ae3b-49dd22e8f461",
 139                 "flags": {}
 140               },
 141               "action": "Restart",
 142               "action-identifiers": {
 143                 "vnf-id": "my-target"
 144               },
 145               "payload": "{\"my-key-A\":\"hello\", \"my-key-B\":\"world\"}"
 146             }
 147           }
 148         }
 149
 150
 151 An example initial response received from the APPC LCM response topic:
 152
 153 .. code-block:: bash
 154
 155         {
 156           "body": {
 157             "output": {
 158               "common-header": {
 159                 "timestamp": "2020-05-14T19:19:32.619897000Z",
 160                 "api-ver": "5.00",
 161                 "originator-id": "664be3d2-6c12-4f4b-a3e7-c349acced200",
 162                 "request-id": "664be3d2-6c12-4f4b-a3e7-c349acced200",
 163                 "sub-request-id": "8c4c1914-00ed-4be0-ae3b-49dd22e8f461",
 164                 "flags": {}
 165               },
 166               "status": {
 167                 "code": 100,
 168                 "message": "Restart accepted"
 169               }
 170             }
 171           },
 172           "version": "2.0",
 173           "rpc-name": "restart",
 174           "correlation-id": "664be3d2-6c12-4f4b-a3e7-c349acced200-1",
 175           "type": "response"
 176         }
 177
 178
 179 An example final response received from the APPC LCM on the same response topic:
 180
 181 .. code-block:: bash
 182
 183         {
 184           "body": {
 185             "output": {
 186               "common-header": {
 187                 "timestamp": "2020-05-14T19:19:32.619898000Z",
 188                 "api-ver": "5.00",
 189                 "originator-id": "664be3d2-6c12-4f4b-a3e7-c349acced200",
 190                 "request-id": "664be3d2-6c12-4f4b-a3e7-c349acced200",
 191                 "sub-request-id": "8c4c1914-00ed-4be0-ae3b-49dd22e8f461",
 192                 "flags": {}
 193               },
 194               "status": {
 195                 "code": 400,
 196                 "message": "Restart Successful"
 197               }
 198             }
 199           },
 200           "version": "2.0",
 201           "rpc-name": "restart",
 202           "correlation-id": "664be3d2-6c12-4f4b-a3e7-c349acced200-1",
 203           "type": "response"
 204         }
 205
 206
 207 Configuration of the APPC LCM Actor
 208 ###################################
 209
 210 The following table specifies the fields that should be provided to configure the APPC
 211 LCM actor.
 212
 213 =============================== ====================    ==================================================================
 214 Field name                         type                             Description
 215 =============================== ====================    ==================================================================
 216 sinkTopic                         string                  Name of the topic to which the request should be published.
 217 sourceTopic                       string                  Name of the topic from which the response should be read.
 218                                                           This must not be the same as the *sinkTopic*.
 219 timeoutSec                        integer (optional)      Maximum time, in seconds, to wait for a response to be received
 220                                                           on the topic.
 221 =============================== ====================    ==================================================================
 222
 223 The individual operations are configured using these same field names.  However, all
 224 of them are optional, as they inherit their values from the corresponding actor-level
 225 fields.  That being said, the APPC Legacy operation(s) use a different topic than the
 226 APPC LCM operations.  As a result, the sink and source topics should be specified for
 227 each APPC Legacy operation supported by this actor.