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)
  17 - Message to a participant: a message only for a participant (participantId 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 - Message Broker: supported message Broker are DMaap and Strimzi-Kafka
  23
  24 Design of Rest Api
  25 ******************
  26
  27 Check CLAMP Runtime and Participants
  28 ++++++++++++++++++++++++++++++++++++
  29 - GUI calls GET "/onap/policy/clamp/acm/health" endpoint and receives the "UP" status as response
  30 - GUI calls GET "/onap/policy/clamp/acm/v2/participants" endpoint and receives all participants registered with supported Element Types as response
  31
  32 Order an immediate Participant Report from all participants
  33 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  34 - GUI calls PUT "/onap/policy/clamp/acm/v2/participants" endpoint
  35 - runtime-ACM receives the call by Rest-Api (CommissioningController)
  36 - It triggers the execution to send a broadcast PARTICIPANT_STATUS_REQ message
  37
  38 Create of a Automation Composition Definition Type
  39 ++++++++++++++++++++++++++++++++++++++++++++++++++
  40 - GUI calls POST "/onap/policy/clamp/acm/v2/compositions" endpoint with a Automation Composition Type Definition (Tosca Service Template) as body
  41 - runtime-ACM receives the call by Rest-Api (CommissioningController)
  42 - It validates the Automation Composition Type Definition
  43 - It saves to DB the Tosca Service Template using AcDefinitionProvider with new compositionId and COMMISSIONED status
  44 - the Rest-Api call returns the compositionId generated and the list of Element Definition Type
  45
  46 Update of a Automation Composition Definition Type
  47 ++++++++++++++++++++++++++++++++++++++++++++++++++
  48 - GUI calls POST "/onap/policy/clamp/acm/v2/compositions" endpoint with a Automation Composition Type Definition (Tosca Service Template) as body. It have to contain the compositionId
  49 - runtime-ACM receives the call by Rest-Api (CommissioningController)
  50 - It checks that Automation Composition Type Definition is in COMMISSIONED status
  51 - It validates the Automation Composition Type Definition
  52 - It updates to DB the Tosca Service Template using AcDefinitionProvider using the compositionId
  53 - the Rest-Api call returns the compositionId and the list of Element Definition Type
  54
  55 Priming of a Automation Composition Definition Type
  56 +++++++++++++++++++++++++++++++++++++++++++++++++++
  57 - GUI calls POST "/onap/policy/clamp/acm/v2/compositions/{compositionId}" endpoint with PRIME as primeOrder
  58 - runtime-ACM receives the call by Rest-Api (CommissioningController)
  59 - It checks that Automation Composition Type Definition is in COMMISSIONED status
  60 - It validates and update the AC Element Type Definition with supported Element Types by participants
  61 - It updates AC Definition to DB with PRIMING as status
  62 - It triggers the execution to send a broadcast PARTICIPANT_PRIME message
  63 - the message is built by ParticipantPrimePublisher using Tosca Service Template data
  64
  65 Create of a Automation Composition Instance
  66 +++++++++++++++++++++++++++++++++++++++++++
  67 - GUI calls POST "/onap/policy/clamp/acm/v2/compositions/{compositionId}/instances" endpoint with a Automation Composition Instance as body. It have to contain the compositionId
  68 - runtime-ACM receives the call by Rest-Api (InstantiationController)
  69 - It validates the AC Instance and checks that the related composition has COMMISSIONED as status
  70 - It set the related participantId into the AC Element Instance using the participantId defined in AC Element Type Definition
  71 - It saves the Automation Composition to DB with UNDEPLOYED deployState and NONE lockState
  72 - the Rest-Api call returns the instanceId and the list of AC Element Instance
  73
  74 Update of a Automation Composition Instance
  75 +++++++++++++++++++++++++++++++++++++++++++
  76 - GUI calls POST "/onap/policy/clamp/acm/v2/compositions/{compositionId}/instances" endpoint with a Automation Composition Instance as body. It have to contain the compositionId and the instanceId
  77 - runtime-ACM receives the call by Rest-Api (InstantiationController)
  78 - It checks that AC Instance is in UNDEPLOYED/DEPLOYED deployState
  79 - It updates the Automation Composition to DB
  80 - the Rest-Api call returns the instanceId and the list of AC Element Instance
  81 - the runtime sends an update event to the participants which inturn performs the update operation on the deployed instances.
  82
  83 Issues AC instance to change status
  84 +++++++++++++++++++++++++++++++++++
  85
  86 case **deployOrder: DEPLOY**
  87
  88 - GUI calls "/onap/policy/clamp/acm/v2/compositions/{compositionId}/instances/{instanceId}" endpoint with DEPLOY as deployOrder
  89 - runtime-ACM receives the call by Rest-Api (InstantiationController)
  90 - It validates the status order issued (related AC Instance has UNDEPLOYED as deployState)
  91 - It updates the AC Instance to DB with DEPLOYING deployState
  92 - It triggers the execution to send a broadcast AUTOMATION_COMPOSITION_DEPLOY message
  93 - the message is built by AutomationCompositionDeployPublisher using Tosca Service Template data and Instance data. (with startPhase = first startPhase)
  94
  95 case **lockOrder: UNLOCK**
  96
  97 - GUI calls "/onap/policy/clamp/acm/v2/compositions/{compositionId}/instances/{instanceId}" endpoint with UNLOCK as lockOrder
  98 - runtime-ACM receives the call by Rest-Api (InstantiationController)
  99 - It validates the status order issued (related AC Instance has DEPLOYED as deployState and LOCK as lockOrder)
 100 - It updates the AC Instance to DB with LOCKING lockOrder
 101 - It triggers the execution to send a broadcast AUTOMATION_COMPOSITION_STATE_CHANGE message
 102 - the message is built by AutomationCompositionStateChangePublisher using Instance data. (with startPhase = first startPhase)
 103
 104 case **lockOrder: LOCK**
 105
 106 - GUI calls "/onap/policy/clamp/acm/v2/compositions/{compositionId}/instances/{instanceId}" endpoint with LOCK as lockOrder
 107 - runtime-ACM receives the call by Rest-Api (InstantiationController)
 108 - It validates the status order issued (related AC Instance has DEPLOYED as deployState and UNLOCK as lockOrder)
 109 - It updates the AC Instance to DB with UNLOCKING lockOrder
 110 - It triggers the execution to send a broadcast AUTOMATION_COMPOSITION_STATE_CHANGE message
 111 - the message is built by AutomationCompositionStateChangePublisher using Instance data. (with startPhase = last StartPhase)
 112
 113 case **deployOrder: UNDEPLOY**
 114
 115 - GUI calls "/onap/policy/clamp/acm/v2/compositions/{compositionId}/instances/{instanceId}" endpoint with UNDEPLOY as deployOrder
 116 - runtime-ACM receives the call by Rest-Api (InstantiationController)
 117 - It validates the status order issued (related AC Instance has DEPLOYED as deployState and LOCK as lockOrder)
 118 - It updates the AC Instance to DB with UNDEPLOYING deployState
 119 - It triggers the execution to send a broadcast AUTOMATION_COMPOSITION_STATE_CHANGE message
 120 - the message is built by AutomationCompositionStateChangePublisher using Instance data. (with startPhase = last StartPhase)
 121
 122 Delete of a Automation Composition Instance
 123 +++++++++++++++++++++++++++++++++++++++++++
 124 - GUI calls DELETE "/onap/policy/clamp/acm/v2/compositions/{compositionId}/instances/{instanceId}" endpoint
 125 - runtime-ACM receives the call by Rest-Api (InstantiationController)
 126 - It checks that AC Instance is in UNDEPLOYED deployState
 127 - It updates the AC Instance to DB with DELETING deployState
 128 - It triggers the execution to send a broadcast AUTOMATION_COMPOSITION_STATE_CHANGE message
 129 - the message is built by AutomationCompositionStateChangePublisher using Instance data. (with startPhase = last StartPhase)
 130
 131 Depriming of a Automation Composition Definition Type
 132 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 133 - GUI calls POST "/onap/policy/clamp/acm/v2/compositions/{compositionId}" endpoint with DEPRIME as primeOrder
 134 - runtime-ACM receives the call by Rest-Api (CommissioningController)
 135 - It checks that Automation Composition Type Definition is in PRIMED status
 136 - It updates AC Definition to DB with DEPRIMING as status
 137 - It triggers the execution to send a broadcast PARTICIPANT_PRIME message
 138 - the message is built by ParticipantPrimePublisher using Tosca Service Template data
 139
 140 Delete of a Automation Composition Definition Type
 141 ++++++++++++++++++++++++++++++++++++++++++++++++++
 142 - GUI calls DELETE "/onap/policy/clamp/acm/v2/compositions/{compositionId}" endpoint
 143 - runtime-ACM receives the call by Rest-Api (CommissioningController)
 144 - It checks that AC Definition Type is in COMMISSIONED status
 145 - It deletes the Automation Composition Type from DB
 146
 147 StartPhase
 148 **********
 149 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.
 150
 151 How to define StartPhase
 152 ++++++++++++++++++++++++
 153 StartPhase is defined as shown below in the Definition of TOSCA fundamental Automation Composition Types yaml file.
 154
 155 .. code-block:: YAML
 156
 157   startPhase:
 158     type: integer
 159     required: false
 160     constraints:
 161     - greater-or-equal: 0
 162     description: A value indicating the start phase in which this Automation Composition element will be started, the
 163                  first start phase is zero. Automation Composition Elements are started in their start_phase order and stopped
 164                  in reverse start phase order. Automation Composition Elements with the same start phase are started and
 165                  stopped simultaneously
 166     metadata:
 167       common: true
 168
 169 The "common: true" value in the metadata of the startPhase property identifies that property as being a common property.
 170 This property will be set on the CLAMP GUI during Automation Composition commissioning.
 171 Example where it could be used:
 172
 173 .. code-block:: YAML
 174
 175   org.onap.domain.database.Http_PMSHMicroserviceAutomationCompositionElement:
 176     # Consul http config for PMSH.
 177     version: 1.2.3
 178     type: org.onap.policy.clamp.acm.HttpAutomationCompositionElement
 179     type_version: 1.0.1
 180     description: Automation Composition element for the http requests of PMSH microservice
 181     properties:
 182       provider: ONAP
 183       uninitializedToPassiveTimeout: 180
 184       startPhase: 1
 185
 186 How StartPhase works
 187 ++++++++++++++++++++
 188 In state changes from UNDEPLOYED → DEPLOYED or LOCKED → UNLOCKED, Automation Composition elements are started in increasing order of their startPhase.
 189
 190 Example of DEPLOY order with Http_PMSHMicroserviceAutomationCompositionElement with startPhase to 1 and PMSH_K8SMicroserviceAutomationCompositionElement with startPhase to 0
 191
 192 - runtime-ACM sends a broadcast AUTOMATION_COMPOSITION_DEPLOY message to all participants with startPhase = 0
 193 - participant receives the AUTOMATION_COMPOSITION_DEPLOY message and runs to DEPLOYED state (only AC elements defined as startPhase = 0)
 194 - runtime-ACM receives AUTOMATION_COMPOSITION_DEPLOY_ACK messages from participants and set the state (from the AC element of the message) to DEPLOYED
 195 - runtime-ACM calculates that all AC elements with startPhase = 0 are set to proper state and sends a broadcast AUTOMATION_COMPOSITION_DEPLOY message with startPhase = 1
 196 - participant receives the AUTOMATION_COMPOSITION_DEPLOY message and runs to DEPLOYED state (only AC elements defined as startPhase = 1)
 197 - runtime-ACM receives AUTOMATION_COMPOSITION_DEPLOY_ACK messages from participants and set the state (from the AC element of the message) to DEPLOYED
 198 - runtime-ACM calculates that all AC elements are set to proper state and set AC to DEPLOYED
 199
 200 In that scenario the message AUTOMATION_COMPOSITION_DEPLOY has been sent two times.
 201
 202 Design of managing messages
 203 ***************************
 204
 205 PARTICIPANT_REGISTER
 206 ++++++++++++++++++++
 207 - A participant starts and send a PARTICIPANT_REGISTER message with participantId and supported Element Types
 208 - runtime-ACM collects the message from Message Broker by ParticipantRegisterListener
 209 - if not present, it saves participant reference with status ON_LINE to DB
 210
 211 PARTICIPANT_PRIME_ACK
 212 ++++++++++++++++++++++
 213 - A participant sends PARTICIPANT_PRIME_ACK message in response to a PARTICIPANT_PRIME message
 214 - ParticipantPrimeAckListener collects the message from Message Broker
 215 - It updates AC Definition to DB with PRIMED/DEPRIMED as status
 216
 217 PARTICIPANT_STATUS
 218 ++++++++++++++++++
 219 - A participant sends a scheduled PARTICIPANT_STATUS message with participantId and supported Element Types
 220 - runtime-ACM collects the message from Message Broker by ParticipantStatusListener
 221 - if not present, it saves participant reference with status ON_LINE to DB
 222 - MessageIntercept intercepts that event and adds a task to handle PARTICIPANT_STATUS in SupervisionScanner
 223 - SupervisionScanner clears and starts the monitoring for participantStatus
 224
 225 AUTOMATION_COMPOSITION_DEPLOY_ACK
 226 +++++++++++++++++++++++++++++++++
 227 - A participant sends AUTOMATION_COMPOSITION_DEPLOY_ACK message in response to a AUTOMATION_COMPOSITION_DEPLOY message. It will send a AUTOMATION_COMPOSITION_DEPLOY_ACK - for each AC elements moved to the DEPLOYED state
 228 - AutomationCompositionUpdateAckListener collects the message from Message Broker
 229 - It checks the status of all Automation Composition elements and checks if the Automation Composition is fully DEPLOYED
 230 - It updates the AC to DB
 231 - MessageIntercept intercepts that event and adds a task to handle a monitoring execution in SupervisionScanner
 232
 233 AUTOMATION_COMPOSITION_STATECHANGE_ACK
 234 ++++++++++++++++++++++++++++++++++++++
 235 - A participant sends AUTOMATION_COMPOSITION_STATECHANGE_ACK message in response to a AUTOMATION_COMPOSITION_STATECHANGE message. It will send a AUTOMATION_COMPOSITION_DEPLOY_ACK - for each AC elements moved to the ordered state
 236 - AutomationCompositionStateChangeAckListener collects the message from Message Broker
 237 - It checks the status of all Automation Composition elements and checks if the transition process of the Automation Composition is terminated
 238 - It updates the AC to DB
 239 - MessageIntercept intercepts that event and adds a task to handle a monitoring execution in SupervisionScanner
 240
 241 Design of monitoring execution in SupervisionScanner
 242 ****************************************************
 243 Monitoring is designed to process the follow operations:
 244
 245 - to determine the next startPhase in a AUTOMATION_COMPOSITION_DEPLOY message
 246 - to update AC deployState: in a scenario that "AutomationComposition.deployState" is in a kind of transitional state (example DEPLOYING), if all  - AC elements are moved properly to the specific state, the "AutomationComposition.deployState" will be updated to that and saved to DB
 247 - to update AC lockState: in a scenario that "AutomationComposition.lockState" is in a kind of transitional state (example LOCKING), if all  - AC elements are moved properly to the specific state, the "AutomationComposition.lockState" will be updated to that and saved to DB
 248 - to delete AC Instance: in a scenario that "AutomationComposition.deployState" is in DELETING, if all  - AC elements are moved properly to DELETED, the AC Instance will be deleted from DB
 249 - to retry AUTOMATION_COMPOSITION_DEPLOY/AUTOMATION_COMPOSITION_STATE_CHANGE messages. if there is a AC Element not in the proper state, it will retry a broadcast message
 250
 251 The solution Design of retry, timeout, and reporting for all Participant message dialogues are implemented into the monitoring execution.
 252
 253 - Spring Scheduling inserts the task to monitor retry execution into ThreadPoolExecutor
 254 - ThreadPoolExecutor executes the task
 255 - a message will be retry if runtime-ACM do no receive Act message before MaxWaitMs milliseconds
 256
 257 Design of Exception handling
 258 ****************************
 259 GlobalControllerExceptionHandler
 260 ++++++++++++++++++++++++++++++++
 261 If error occurred during the Rest Api call, runtime-ACM responses with a proper status error code and a JSON message error.
 262 This class is implemented to intercept and handle AutomationCompositionException, PfModelException and PfModelRuntimeException if they are thrown during the Rest Ali calls.
 263 All of those classes must implement ErrorResponseInfo that contains message error and status response code.
 264 So the Exception is converted in JSON message.
 265
 266 RuntimeErrorController
 267 ++++++++++++++++++++++
 268 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.
 269 This class is implemented to redirect the standard Web error page to a JSON message error.
 270 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.
 271
 272 Handle version and "X-ONAP-RequestID"
 273 *************************************
 274 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.
 275
 276 Media Type Support
 277 ******************
 278 runtime-ACM Rest Api supports **application/json**, **application/yaml** and **text/plain** Media Types. The configuration is implemented in CoderHttpMesageConverter.
 279
 280 application/json
 281 ++++++++++++++++
 282 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**.
 283
 284 application/yaml
 285 ++++++++++++++++
 286 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**.
 287
 288 text/plain
 289 ++++++++++
 290 Text format is used by Prometheus. For the conversion from Object to String  will be used **StringHttpMessageConverter**.