From: Jim Hahn Date: Thu, 14 May 2020 19:45:02 +0000 (-0400) Subject: Document new APPC LCM actor X-Git-Tag: 3.2.0~45 X-Git-Url: https://gerrit.onap.org/r/gitweb?p=policy%2Fparent.git;a=commitdiff_plain;h=2defadb832998063be6bc330204d16f2fc173b47 Document new APPC LCM actor Issue-ID: POLICY-2515 Change-Id: I88574c20ee0a091b76ec84f8ba52e7964457ccbe Signed-off-by: Jim Hahn --- diff --git a/docs/development/actors/appc-legacy/appc-legacy.rst b/docs/development/actors/appc-legacy/appc-legacy.rst index 1af71fe4..5d1bd7c0 100644 --- a/docs/development/actors/appc-legacy/appc-legacy.rst +++ b/docs/development/actors/appc-legacy/appc-legacy.rst @@ -2,6 +2,8 @@ .. Creative Commons Attribution 4.0 International License. .. http://creativecommons.org/licenses/by/4.0 +.. _appc-legacy-label: + ################# APPC Legacy Actor ################# @@ -88,6 +90,9 @@ Suppose the *ControlLoopOperationParams* were populated as follows: "my-key-B": "{\"output\":\"world\"}" }, "context": { + "event": { + "requestId": "c7c6a4aa-bb61-4a15-b831-ba1472dd4a65" + }, "cqdata": { "generic-vnf": [ { @@ -112,7 +117,7 @@ to the APPC topic: "CommonHeader": { "TimeStamp": 1589400050910, "APIver": "1.01", - "RequestID": "79e1d7d4-bac1-4399-8ee5-f84419c5723d", + "RequestID": "c7c6a4aa-bb61-4a15-b831-ba1472dd4a65", "SubRequestID": "ee3f2dc0-a2e0-4ae8-98c3-478c784b8eb5", "RequestTrack": [], "Flags": [] diff --git a/docs/development/actors/appclcm/appclcm.rst b/docs/development/actors/appclcm/appclcm.rst index 55d3937f..e9ea684f 100644 --- a/docs/development/actors/appclcm/appclcm.rst +++ b/docs/development/actors/appclcm/appclcm.rst @@ -2,14 +2,226 @@ .. Creative Commons Attribution 4.0 International License. .. http://creativecommons.org/licenses/by/4.0 -################# +.. _appclcm-label: + +############## APPC LCM Actor -################# +############## .. contents:: :depth: 3 Overview of APPC LCM Actor -############################# +########################## +ONAP Policy Framework enables APPC as one of the supported actors. The APPC LCM Actor +contains operations supporting both the LCM interface and the legacy interface. +As such, this actor supersedes the APPC Legacy actor. Its sequence number is lower +than the APPC Legacy actor's sequence number, which ensures that it is loaded +first. + +APPC Legacy uses a single DMaaP topic for both requests and responses. The class(es) +supporting this interface are described in :ref:`appc-legacy-label`. The APPC LCM +Actor only supports the APPC Legacy operation, *ModifyConfig*. + +The APPC LCM interface, on the other hand, uses two DMaaP topics, one to which requests +are published, and another from which responses are received. Similar to the legacy +interface, APPC LCM may generate more than one response for a particular request, the +first response simply indicating that the request was accepted, while the second +response indicates completion of the request. + +For each request, a unique sub-request ID is generated. This is used to match the +received responses with the published requests. (APPC LCM also has a "correlation-id" +field, which could potentially be used to match the response to the request, but +apparently APPC LCM has not implemented that capability yet.) + +All APPC LCM operations are currently supported by a single java class, +*AppcLcmOperation*, which is responsible for populating the request structure +appropriately. This class is derived from *BidirectionalTopicOperation*. + + +**The remainder of this discussion describes the operations that are specific to APPC +LCM.** + + +Request +####### + +CommonHeader +************ + +The "common-header" field in the request is built by policy. + +=============================== =========== ================================================================== + "common-header" field name type Description +=============================== =========== ================================================================== +sub-request-id string Generated by Policy. Is a UUID and used internally by policy + to match the response with the request. +request-id string Inserted by Policy. Maps to the UUID sent by DCAE i.e. the ID + used throughout the closed loop lifecycle to identify a request. +originator-id string Copy of the request-id. +=============================== =========== ================================================================== + + +Action +****** + +The "action" field uniquely identifies the operation to perform. Currently, the +following operations are supported: + +- Restart +- Rebuild +- Migrate +- ConfigModify + +The valid operations are listed in *AppcLcmConstants*. These are the values that must +be specified in the policy. However, before being stuffed into the "action" field, +they are converted to camel case, stripping any hyphens, and translating the first +character to upper case, if it isn't already. + + +Action Identifiers +****************** + +Currently, the "action-identifiers" field contains only the VNF ID, which should be the +*targetEntity* specified within the *ControlLoopOperationParams*. + + +Payload +******* + +The "payload" field is populated based on the *payload* specified within the +*ControlLoopOperationParams*. Unlike the APPC Legacy operations, which inject POJOs +into the "payload" field, the APPC LCM operations simply encode the entire +parameter *payload* into a JSON string, and then place the encoded string into the +"payload" field of the request. + + +Examples +######## + +Suppose the *ControlLoopOperationParams* were populated as follows: + +.. code-block:: bash + + { + "actor": "APPC", + "operation": "Restart", + "targetEntity": "my-target", + "payload": { + "my-key-A": "hello", + "my-key-B": "world" + }, + "context": { + "event": { + "requestId": "664be3d2-6c12-4f4b-a3e7-c349acced200" + } + } + } + +An example of a request constructed by the actor using the above parameters, published +to the APPC LCM request topic: + +.. code-block:: bash + + { + "version": "2.0", + "rpc-name": "restart", + "correlation-id": "664be3d2-6c12-4f4b-a3e7-c349acced200-8c4c1914-00ed-4be0-ae3b-49dd22e8f461", + "type": "request", + "body": { + "input": { + "common-header": { + "timestamp": "2020-05-14T19:19:32.619890900Z", + "api-ver": "2.00", + "originator-id": "664be3d2-6c12-4f4b-a3e7-c349acced200", + "request-id": "664be3d2-6c12-4f4b-a3e7-c349acced200", + "sub-request-id": "8c4c1914-00ed-4be0-ae3b-49dd22e8f461", + "flags": {} + }, + "action": "Restart", + "action-identifiers": { + "vnf-id": "my-target" + }, + "payload": "{\"my-key-A\":\"hello\", \"my-key-B\":\"world\"}" + } + } + } + + +An example initial response received from the APPC LCM response topic: + +.. code-block:: bash + + { + "body": { + "output": { + "common-header": { + "timestamp": "2020-05-14T19:19:32.619897000Z", + "api-ver": "5.00", + "originator-id": "664be3d2-6c12-4f4b-a3e7-c349acced200", + "request-id": "664be3d2-6c12-4f4b-a3e7-c349acced200", + "sub-request-id": "8c4c1914-00ed-4be0-ae3b-49dd22e8f461", + "flags": {} + }, + "status": { + "code": 100, + "message": "Restart accepted" + } + } + }, + "version": "2.0", + "rpc-name": "restart", + "correlation-id": "664be3d2-6c12-4f4b-a3e7-c349acced200-1", + "type": "response" + } + + +An example final response received from the APPC LCM on the same response topic: + +.. code-block:: bash + + { + "body": { + "output": { + "common-header": { + "timestamp": "2020-05-14T19:19:32.619898000Z", + "api-ver": "5.00", + "originator-id": "664be3d2-6c12-4f4b-a3e7-c349acced200", + "request-id": "664be3d2-6c12-4f4b-a3e7-c349acced200", + "sub-request-id": "8c4c1914-00ed-4be0-ae3b-49dd22e8f461", + "flags": {} + }, + "status": { + "code": 400, + "message": "Restart Successful" + } + } + }, + "version": "2.0", + "rpc-name": "restart", + "correlation-id": "664be3d2-6c12-4f4b-a3e7-c349acced200-1", + "type": "response" + } + + +Configuration of the APPC LCM Actor +################################### + +The following table specifies the fields that should be provided to configure the APPC +LCM actor. + +=============================== ==================== ================================================================== +Field name type Description +=============================== ==================== ================================================================== +sinkTopic string Name of the topic to which the request should be published. +sourceTopic string Name of the topic from which the response should be read. + This must not be the same as the *sinkTopic*. +timeoutSec integer (optional) Maximum time, in seconds, to wait for a response to be received + on the topic. +=============================== ==================== ================================================================== -This is a place-holder for the actor documentation. +The individual operations are configured using these same field names. However, all +of them are optional, as they inherit their values from the corresponding actor-level +fields. That being said, the APPC Legacy operation(s) use a different topic than the +APPC LCM operations. As a result, the sink and source topics should be specified for +each APPC Legacy operation supported by this actor.