docs/clamp/acm/design-impl/clamp-runtime-acm.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2
   3 .. _clamp-runtime-acm:
   4
   5 The CLAMP Automation Composition Runtime
   6 ########################################
   7
   8 .. contents::
   9     :depth: 3
  10
  11
  12 This article explains how CLAMP Automation Composition Runtime is implemented.
  13
  14 Terminology
  15 ***********
  16 - Broadcast message: a message for all participants (participantId=null and participantType=null)
  17 - Message to a participant: a message only for a participant (participantId and participantType properly filled)
  18 - ThreadPoolExecutor: ThreadPoolExecutor executes the given task, into SupervisionAspect class is configured to execute tasks in ordered manner, one by one
  19 - Spring Scheduling: into SupervisionAspect class, the @Scheduled annotation invokes "schedule()" method every "runtime.participantParameters.heartBeatMs" milliseconds with a fixed delay
  20 - MessageIntercept: "@MessageIntercept" annotation is used into SupervisionHandler class to intercept "handleParticipantMessage" method calls using spring aspect oriented programming
  21 - GUI: swagger-ui, Postman or policy-gui
  22
  23 Design of Rest Api
  24 ******************
  25
  26 Create of a Automation Composition Type
  27 +++++++++++++++++++++++++++++++++++++++
  28 - GUI calls POST "/commission" endpoint with a Automation Composition Type Definition (Tosca Service Template) as body
  29 - runtime-ACM receives the call by Rest-Api (CommissioningController)
  30 - It saves to DB the Tosca Service Template using PolicyModelsProvider
  31 - if there are participants registered, it triggers the execution to send a broadcast PARTICIPANT_UPDATE message
  32 - the message is built by ParticipantUpdatePublisher using Tosca Service Template data (to fill the list of ParticipantDefinition)
  33
  34 Delete of a Automation Composition Type
  35 +++++++++++++++++++++++++++++++++++++++
  36 - GUI calls DELETE "/commission" endpoint
  37 - runtime-ACM receives the call by Rest-Api (CommissioningController)
  38 - if there are participants registered, runtime-ACM triggers the execution to send a broadcast PARTICIPANT_UPDATE message
  39 - the message is built by ParticipantUpdatePublisher with an empty list of ParticipantDefinition
  40 - It deletes the Automation Composition Type from DB
  41
  42 Create of a Automation Composition
  43 ++++++++++++++++++++++++++++++++++
  44 - GUI calls POST "/instantiation" endpoint with a Automation Composition as body
  45 - runtime-ACM receives the call by Rest-Api (InstantiationController)
  46 - It validates the Automation Composition
  47 - It saves the Automation Composition to DB
  48 - Design of an update of a Automation Composition
  49 - GUI calls PUT "/instantiation" endpoint with a Automation Composition as body
  50 - runtime-ACM receives the call by Rest-Api (InstantiationController)
  51 - It validates the Automation Composition
  52 - It saves the Automation Composition to DB
  53
  54 Delete of a Automation Composition
  55 ++++++++++++++++++++++++++++++++++
  56 - GUI calls DELETE "/instantiation" endpoint
  57 - runtime-ACM receives the call by Rest-Api (InstantiationController)
  58 - It checks that Automation Composition is in UNINITIALISED status
  59 - It deletes the Automation Composition from DB
  60
  61 "issues Automation Composition commands to Automation Compositions"
  62 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  63
  64 case **UNINITIALISED to PASSIVE**
  65
  66 - GUI calls "/instantiation/command" endpoint with PASSIVE as orderedState
  67 - runtime-ACM checks if participants registered are matching with the list of Automation Composition Element
  68 - It updates Automation Composition and Automation Composition elements to DB (orderedState = PASSIVE)
  69 - It validates the status order issued
  70 - It triggers the execution to send a broadcast AUTOMATION_COMPOSITION_UPDATE message
  71 - the message is built by AutomationCompositionUpdatePublisher using Tosca Service Template data and AutomationComposition data. (with startPhase = 0)
  72 - It updates Automation Composition and Automation Composition elements to DB (state = UNINITIALISED2PASSIVE)
  73
  74 case **PASSIVE to UNINITIALISED**
  75
  76 - GUI calls "/instantiation/command" endpoint with UNINITIALISED as orderedState
  77 - runtime-ACM checks if participants registered are matching with the list of Automation Composition Element
  78 - It updates Automation Composition and Automation Composition elements to DB (orderedState = UNINITIALISED)
  79 - It validates the status order issued
  80 - It triggers the execution to send a broadcast AUTOMATION_COMPOSITION_STATE_CHANGE message
  81 - the message is built by AutomationCompositionStateChangePublisher with automationcompositionId
  82 - It updates Automation Composition and Automation Composition elements to DB (state = PASSIVE2UNINITIALISED)
  83
  84 case **PASSIVE to RUNNING**
  85
  86 - GUI calls "/instantiation/command" endpoint with RUNNING as orderedState
  87 - runtime-ACM checks if participants registered are matching with the list of Automation Composition Element.
  88 - It updates Automation Composition and Automation Composition elements to DB (orderedState = RUNNING)
  89 - It validates the status order issued
  90 - It triggers the execution to send a broadcast AUTOMATION_COMPOSITION_STATE_CHANGE message
  91 - the message is built by AutomationCompositionStateChangePublisher with automationcompositionId
  92 - It updates Automation Composition and Automation Composition elements to DB (state = PASSIVE2RUNNING)
  93
  94 case **RUNNING to PASSIVE**
  95
  96 - GUI calls "/instantiation/command" endpoint with UNINITIALISED as orderedState
  97 - runtime-ACM checks if participants registered are matching with the list of Automation Composition Element
  98 - It updates Automation Composition and Automation Composition elements to db (orderedState = RUNNING)
  99 - It validates the status order issued
 100 - It triggers the execution to send a broadcast AUTOMATION_COMPOSITION_STATE_CHANGE message
 101 - the message is built by AutomationCompositionStateChangePublisher with automationcompositionId
 102 - It updates Automation Composition and Automation Composition elements to db (state = RUNNING2PASSIVE)
 103
 104 StartPhase
 105 **********
 106 The startPhase is particularly important in Automation Composition update and Automation Composition state changes because sometime the user wishes to control the order in which the state changes in Automation Composition Elements in a Automation Composition.
 107
 108 How to define StartPhase
 109 ++++++++++++++++++++++++
 110 StartPhase is defined as shown below in the Definition of TOSCA fundamental Automation Composition Types yaml file.
 111
 112 .. code-block:: YAML
 113
 114   startPhase:
 115     type: integer
 116     required: false
 117     constraints:
 118     - greater-or-equal: 0
 119     description: A value indicating the start phase in which this Automation Composition element will be started, the
 120                  first start phase is zero. Automation Composition Elements are started in their start_phase order and stopped
 121                  in reverse start phase order. Automation Composition Elements with the same start phase are started and
 122                  stopped simultaneously
 123     metadata:
 124       common: true
 125
 126 The "common: true" value in the metadata of the startPhase property identifies that property as being a common property.
 127 This property will be set on the CLAMP GUI during Automation Composition commissioning.
 128 Example where it could be used:
 129
 130 .. code-block:: YAML
 131
 132   org.onap.domain.database.Http_PMSHMicroserviceAutomationCompositionElement:
 133     # Consul http config for PMSH.
 134     version: 1.2.3
 135     type: org.onap.policy.clamp.acm.HttpAutomationCompositionElement
 136     type_version: 1.0.1
 137     description: Automation Composition element for the http requests of PMSH microservice
 138     properties:
 139       provider: ONAP
 140       participant_id:
 141         name: HttpParticipant0
 142         version: 1.0.0
 143       participantType:
 144         name: org.onap.acm.HttpAutomationCompositionParticipant
 145         version: 2.3.4
 146       uninitializedToPassiveTimeout: 180
 147       startPhase: 1
 148
 149 How StartPhase works
 150 ++++++++++++++++++++
 151 In state changes from UNITITIALISED → PASSIVE, Automation Composition elements are started in increasing order of their startPhase.
 152
 153 Example with Http_PMSHMicroserviceAutomationCompositionElement with startPhase to 1 and PMSH_K8SMicroserviceAutomationCompositionElement with startPhase to 0
 154
 155 - runtime-ACM sends a broadcast AUTOMATION_COMPOSITION_UPDATE message to all participants with startPhase = 0
 156 - participant receives the AUTOMATION_COMPOSITION_UPDATE message and runs to PASSIVE state (only CL elements defined as startPhase = 0)
 157 - runtime-ACM receives AUTOMATION_COMPOSITION_UPDATE_ACT messages from participants and set the state (from the CL element of the message) to PASSIVE
 158 - runtime-ACM calculates that all CL elements with startPhase = 0 are set to proper state and sends a broadcast AUTOMATION_COMPOSITION_UPDATE message with startPhase = 1
 159 - participant receives the AUTOMATION_COMPOSITION_UPDATE message and runs to PASSIVE state (only CL elements defined as startPhase = 1)
 160 - runtime-ACM calculates that all CL elements are set to proper state and set CL to PASSIVE
 161
 162 In that scenario the message AUTOMATION_COMPOSITION_UPDATE has been sent two times.
 163
 164 Design of managing messages
 165 ***************************
 166
 167 PARTICIPANT_REGISTER
 168 ++++++++++++++++++++
 169 - A participant starts and send a PARTICIPANT_REGISTER message
 170 - ParticipantRegisterListener collects the message from DMaap
 171 - if not present, it saves participant reference with status UNKNOWN to DB
 172 - if is present a Automation Composition Type, it triggers the execution to send a PARTICIPANT_UPDATE message to the participant registered (message of Priming)
 173 - the message is built by ParticipantUpdatePublisher using Tosca Service Template data (to fill the list of ParticipantDefinition)
 174 - It triggers the execution to send a PARTICIPANT_REGISTER_ACK message to the participant registered
 175 - MessageIntercept intercepts that event, if PARTICIPANT_UPDATE message has been sent, it will be add a task to handle PARTICIPANT_REGISTER in SupervisionScanner
 176 - SupervisionScanner starts the monitoring for participantUpdate
 177
 178 PARTICIPANT_UPDATE_ACK
 179 ++++++++++++++++++++++
 180 - A participant sends PARTICIPANT_UPDATE_ACK message in response to a PARTICIPANT_UPDATE message
 181 - ParticipantUpdateAckListener collects the message from DMaap
 182 - MessageIntercept intercepts that event and adds a task to handle PARTICIPANT_UPDATE_ACK in SupervisionScanner
 183 - SupervisionScanner removes the monitoring for participantUpdate
 184 - It updates the status of the participant to DB
 185
 186 PARTICIPANT_STATUS
 187 ++++++++++++++++++
 188 - A participant sends a scheduled PARTICIPANT_STATUS message
 189 - ParticipantStatusListener collects the message from DMaap
 190 - MessageIntercept intercepts that event and adds a task to handle PARTICIPANT_STATUS in SupervisionScanner
 191 - SupervisionScanner clears and starts the monitoring for participantStatus
 192
 193 AUTOMATION_COMPOSITION_UPDATE_ACK
 194 +++++++++++++++++++++++++++++++++
 195 - A participant sends AUTOMATION_COMPOSITION_UPDATE_ACK message in response to a AUTOMATION_COMPOSITION_UPDATE  message. It will send a AUTOMATION_COMPOSITION_UPDATE_ACK - for each CL-elements moved to the ordered state as indicated by the AUTOMATION_COMPOSITION_UPDATE
 196 - AutomationCompositionUpdateAckListener collects the message from DMaap
 197 - It checks the status of all Automation Composition elements and checks if the Automation Composition is primed
 198 - It updates the CL to DB if it is changed
 199 - MessageIntercept intercepts that event and adds a task to handle a monitoring execution in SupervisionScanner
 200
 201 AUTOMATION_COMPOSITION_STATECHANGE_ACK
 202 ++++++++++++++++++++++++++++++++++++++
 203 Design of a AUTOMATION_COMPOSITION_STATECHANGE_ACK is similar to the design for AUTOMATION_COMPOSITION_UPDATE_ACK
 204
 205 Design of monitoring execution in SupervisionScanner
 206 ****************************************************
 207 Monitoring is designed to process the follow operations:
 208
 209 - to determine the next startPhase in a AUTOMATION_COMPOSITION_UPDATE message
 210 - to update CL state: in a scenario that "AutomationComposition.state" is in a kind of transitional state (example UNINITIALISED2PASSIVE), if all  - CL-elements are moved properly to the specific state, the "AutomationComposition.state" will be updated to that and saved to DB
 211 - to retry AUTOMATION_COMPOSITION_UPDATE/AUTOMATION_COMPOSITION_STATE_CHANGE messages. if there is a CL Element not in the proper state, it will retry a broadcast message
 212 - to retry PARTICIPANT_UPDATE message to the participant in a scenario that runtime-ACM do not receive PARTICIPANT_UPDATE_ACT from it
 213 - to send PARTICIPANT_STATUS_REQ to the participant in a scenario that runtime-ACM do not receive PARTICIPANT_STATUS from it
 214
 215 The solution Design of retry, timeout, and reporting for all Participant message dialogues are implemented into the monitoring execution.
 216
 217 - Spring Scheduling inserts the task to monitor retry execution into ThreadPoolExecutor
 218 - ThreadPoolExecutor executes the task
 219 - a message will be retry if runtime-ACM do no receive Act message before MaxWaitMs milliseconds
 220
 221 Design of Exception handling
 222 ****************************
 223 GlobalControllerExceptionHandler
 224 ++++++++++++++++++++++++++++++++
 225 If error occurred during the Rest Api call, runtime-ACM responses with a proper status error code and a JSON message error.
 226 This class is implemented to intercept and handle AutomationCompositionException, PfModelException and PfModelRuntimeException if they are thrown during the Rest Ali calls.
 227 All of those classes must implement ErrorResponseInfo that contains message error and status response code.
 228 So the Exception is converted in JSON message.
 229
 230 RuntimeErrorController
 231 ++++++++++++++++++++++
 232 If wrong end-point is called or an Exception not intercepted by GlobalControllerExceptionHandler, runtime-ACM responses with a proper status error code and a JSON message error.
 233 This class is implemented to redirect the standard Web error page to a JSON message error.
 234 Typically that happen when a wrong end-point is called, but also could be happen for not authorized call, or any other Exception not intercepted by GlobalControllerExceptionHandler.
 235
 236 Handle version and "X-ONAP-RequestID"
 237 *************************************
 238 RequestResponseLoggingFilter class handles version and "X-ONAP-RequestID" during a Rest-Api call; it works as a filter, so intercepts the Rest-Api and adds to the header those information.
 239
 240 Media Type Support
 241 ******************
 242 runtime-ACM Rest Api supports **application/json**, **application/yaml** and **text/plain** Media Types. The configuration is implemented in CoderHttpMesageConverter.
 243
 244 application/json
 245 ++++++++++++++++
 246 JSON format is a standard for Rest Api. For the conversion from JSON to Object and vice-versa will be used **org.onap.policy.common.utils.coder.StandardCoder**.
 247
 248 application/yaml
 249 ++++++++++++++++
 250 YAML format is a standard for Automation Composition Type Definition. For the conversion from YAML to Object and vice-versa will be used **org.onap.policy.common.utils.coder.StandardYamlCoder**.
 251
 252 text/plain
 253 ++++++++++
 254 Text format is used by Prometheus. For the conversion from Object to String  will be used **StringHttpMessageConverter**.