1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
5 The CLAMP Automation Composition Runtime
6 ########################################
12 This article explains how CLAMP Automation Composition Runtime is implemented.
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
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
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
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
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
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
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
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 performs the update operation on the deployed instances.
83 Migrate of a Automation Composition Instance
84 ++++++++++++++++++++++++++++++++++++++++++++
85 - GUI has already a new composition definition primed
86 - 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, the compositionTargetId and the instanceId
87 - runtime-ACM receives the call by Rest-Api (InstantiationController)
88 - It checks that AC Instance is in DEPLOYED deployState
89 - It checks that compositionTargetId is related to a primed composition definition
90 - It updates the Automation Composition to DB
91 - the Rest-Api call returns the instanceId and the list of AC Element Instance
92 - the runtime sends a migrate event to the participants which performs the migrate operation on the deployed instances.
94 Issues AC instance to change status
95 +++++++++++++++++++++++++++++++++++
97 case **deployOrder: DEPLOY**
99 - GUI calls "/onap/policy/clamp/acm/v2/compositions/{compositionId}/instances/{instanceId}" endpoint with DEPLOY as deployOrder
100 - runtime-ACM receives the call by Rest-Api (InstantiationController)
101 - It validates the status order issued (related AC Instance has UNDEPLOYED as deployState)
102 - It updates the AC Instance to DB with DEPLOYING deployState
103 - It triggers the execution to send a broadcast AUTOMATION_COMPOSITION_DEPLOY message
104 - the message is built by AutomationCompositionDeployPublisher using Tosca Service Template data and Instance data. (with startPhase = first startPhase)
106 case **lockOrder: UNLOCK**
108 - GUI calls "/onap/policy/clamp/acm/v2/compositions/{compositionId}/instances/{instanceId}" endpoint with UNLOCK as lockOrder
109 - runtime-ACM receives the call by Rest-Api (InstantiationController)
110 - It validates the status order issued (related AC Instance has DEPLOYED as deployState and LOCK as lockOrder)
111 - It updates the AC Instance to DB with LOCKING lockOrder
112 - It triggers the execution to send a broadcast AUTOMATION_COMPOSITION_STATE_CHANGE message
113 - the message is built by AutomationCompositionStateChangePublisher using Instance data. (with startPhase = first startPhase)
115 case **lockOrder: LOCK**
117 - GUI calls "/onap/policy/clamp/acm/v2/compositions/{compositionId}/instances/{instanceId}" endpoint with LOCK as lockOrder
118 - runtime-ACM receives the call by Rest-Api (InstantiationController)
119 - It validates the status order issued (related AC Instance has DEPLOYED as deployState and UNLOCK as lockOrder)
120 - It updates the AC Instance to DB with UNLOCKING lockOrder
121 - It triggers the execution to send a broadcast AUTOMATION_COMPOSITION_STATE_CHANGE message
122 - the message is built by AutomationCompositionStateChangePublisher using Instance data. (with startPhase = last StartPhase)
124 case **deployOrder: UNDEPLOY**
126 - GUI calls "/onap/policy/clamp/acm/v2/compositions/{compositionId}/instances/{instanceId}" endpoint with UNDEPLOY as deployOrder
127 - runtime-ACM receives the call by Rest-Api (InstantiationController)
128 - It validates the status order issued (related AC Instance has DEPLOYED as deployState and LOCK as lockOrder)
129 - It updates the AC Instance to DB with UNDEPLOYING deployState
130 - It triggers the execution to send a broadcast AUTOMATION_COMPOSITION_STATE_CHANGE message
131 - the message is built by AutomationCompositionStateChangePublisher using Instance data. (with startPhase = last StartPhase)
133 Delete of a Automation Composition Instance
134 +++++++++++++++++++++++++++++++++++++++++++
135 - GUI calls DELETE "/onap/policy/clamp/acm/v2/compositions/{compositionId}/instances/{instanceId}" endpoint
136 - runtime-ACM receives the call by Rest-Api (InstantiationController)
137 - It checks that AC Instance is in UNDEPLOYED deployState
138 - It updates the AC Instance to DB with DELETING deployState
139 - It triggers the execution to send a broadcast AUTOMATION_COMPOSITION_STATE_CHANGE message
140 - the message is built by AutomationCompositionStateChangePublisher using Instance data. (with startPhase = last StartPhase)
142 Depriming of a Automation Composition Definition Type
143 +++++++++++++++++++++++++++++++++++++++++++++++++++++
144 - GUI calls POST "/onap/policy/clamp/acm/v2/compositions/{compositionId}" endpoint with DEPRIME as primeOrder
145 - runtime-ACM receives the call by Rest-Api (CommissioningController)
146 - It checks that Automation Composition Type Definition is in PRIMED status
147 - It updates AC Definition to DB with DEPRIMING as status
148 - It triggers the execution to send a broadcast PARTICIPANT_PRIME message
149 - the message is built by ParticipantPrimePublisher using Tosca Service Template data
151 Delete of a Automation Composition Definition Type
152 ++++++++++++++++++++++++++++++++++++++++++++++++++
153 - GUI calls DELETE "/onap/policy/clamp/acm/v2/compositions/{compositionId}" endpoint
154 - runtime-ACM receives the call by Rest-Api (CommissioningController)
155 - It checks that AC Definition Type is in COMMISSIONED status
156 - It deletes the Automation Composition Type from DB
160 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.
162 How to define StartPhase
163 ++++++++++++++++++++++++
164 StartPhase is defined as shown below in the Definition of TOSCA fundamental Automation Composition Types yaml file.
172 - greater-or-equal: 0
173 description: A value indicating the start phase in which this Automation Composition element will be started, the
174 first start phase is zero. Automation Composition Elements are started in their start_phase order and stopped
175 in reverse start phase order. Automation Composition Elements with the same start phase are started and
176 stopped simultaneously
180 The "common: true" value in the metadata of the startPhase property identifies that property as being a common property.
181 This property will be set on the CLAMP GUI during Automation Composition commissioning.
182 Example where it could be used:
186 org.onap.domain.database.Http_PMSHMicroserviceAutomationCompositionElement:
187 # Consul http config for PMSH.
189 type: org.onap.policy.clamp.acm.HttpAutomationCompositionElement
191 description: Automation Composition element for the http requests of PMSH microservice
194 uninitializedToPassiveTimeout: 180
199 In state changes from UNDEPLOYED → DEPLOYED or LOCKED → UNLOCKED, Automation Composition elements are started in increasing order of their startPhase.
201 Example of DEPLOY order with Http_PMSHMicroserviceAutomationCompositionElement with startPhase to 1 and PMSH_K8SMicroserviceAutomationCompositionElement with startPhase to 0
203 - runtime-ACM sends a broadcast AUTOMATION_COMPOSITION_DEPLOY message to all participants with startPhase = 0
204 - participant receives the AUTOMATION_COMPOSITION_DEPLOY message and runs to DEPLOYED state (only AC elements defined as startPhase = 0)
205 - runtime-ACM receives AUTOMATION_COMPOSITION_DEPLOY_ACK messages from participants and set the state (from the AC element of the message) to DEPLOYED
206 - 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
207 - participant receives the AUTOMATION_COMPOSITION_DEPLOY message and runs to DEPLOYED state (only AC elements defined as startPhase = 1)
208 - runtime-ACM receives AUTOMATION_COMPOSITION_DEPLOY_ACK messages from participants and set the state (from the AC element of the message) to DEPLOYED
209 - runtime-ACM calculates that all AC elements are set to proper state and set AC to DEPLOYED
211 In that scenario the message AUTOMATION_COMPOSITION_DEPLOY has been sent two times.
213 Configure custom namings for TOSCA node types
214 *********************************************
216 The node type of the AC element and the Automation composition can be customised as per the user requirement.
217 These customised names can be used in the TOSCA node type definitions of AC element and composition. All the
218 AC element and composition definitions (node templates) should be derived from the corresponding node types.
219 The following parameters are provided in the config file of runtime-acm for customisation:
225 toscaElementName: customElementType
226 toscaCompositionName: customCompositionType
228 If there are no values provided for customisation, the default node types "org.onap.policy.clamp.acm.AutomationCompositionElement"
229 and "org.onap.policy.clamp.acm.AutomationComposition" are used for the AC element and composition by the runtime-acm.
230 In this case, the element and composition definition has to be derived from the same in the TOSCA. For overriding the names in the
231 onap helm chart, the following properties can be updated in the values.yaml.
236 toscaElementName: customElementName
237 toscaCompositionName: customCompositionName
240 Design of managing messages
241 ***************************
245 - A participant starts and send a PARTICIPANT_REGISTER message with participantId and supported Element Types
246 - runtime-ACM collects the message from Message Broker by ParticipantRegisterListener
247 - if not present, it saves participant reference with status ON_LINE to DB
249 PARTICIPANT_PRIME_ACK
250 ++++++++++++++++++++++
251 - A participant sends PARTICIPANT_PRIME_ACK message in response to a PARTICIPANT_PRIME message
252 - ParticipantPrimeAckListener collects the message from Message Broker
253 - It updates AC Definition to DB with PRIMED/DEPRIMED as status
257 - A participant sends a scheduled PARTICIPANT_STATUS message with participantId and supported Element Types
258 - runtime-ACM collects the message from Message Broker by ParticipantStatusListener
259 - if not present, it saves participant reference with status ON_LINE to DB
260 - MessageIntercept intercepts that event and adds a task to handle PARTICIPANT_STATUS in SupervisionScanner
261 - SupervisionScanner clears and starts the monitoring for participantStatus
263 AUTOMATION_COMPOSITION_DEPLOY_ACK
264 +++++++++++++++++++++++++++++++++
265 - 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
266 - AutomationCompositionUpdateAckListener collects the message from Message Broker
267 - It checks the status of all Automation Composition elements and checks if the Automation Composition is fully DEPLOYED
268 - It updates the AC to DB
269 - MessageIntercept intercepts that event and adds a task to handle a monitoring execution in SupervisionScanner
271 AUTOMATION_COMPOSITION_STATECHANGE_ACK
272 ++++++++++++++++++++++++++++++++++++++
273 - 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
274 - AutomationCompositionStateChangeAckListener collects the message from Message Broker
275 - It checks the status of all Automation Composition elements and checks if the transition process of the Automation Composition is terminated
276 - It updates the AC to DB
277 - MessageIntercept intercepts that event and adds a task to handle a monitoring execution in SupervisionScanner
279 Design of monitoring execution in SupervisionScanner
280 ****************************************************
281 Monitoring is designed to process the follow operations:
283 - to determine the next startPhase in a AUTOMATION_COMPOSITION_DEPLOY message
284 - 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
285 - 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
286 - 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
287 - 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
289 The solution Design of retry, timeout, and reporting for all Participant message dialogues are implemented into the monitoring execution.
291 - Spring Scheduling inserts the task to monitor retry execution into ThreadPoolExecutor
292 - ThreadPoolExecutor executes the task
293 - a message will be retry if runtime-ACM do no receive Act message before MaxWaitMs milliseconds
295 Design of Exception handling
296 ****************************
297 GlobalControllerExceptionHandler
298 ++++++++++++++++++++++++++++++++
299 If error occurred during the Rest Api call, runtime-ACM responses with a proper status error code and a JSON message error.
300 This class is implemented to intercept and handle AutomationCompositionException, PfModelException and PfModelRuntimeException if they are thrown during the Rest Ali calls.
301 All of those classes must implement ErrorResponseInfo that contains message error and status response code.
302 So the Exception is converted in JSON message.
304 RuntimeErrorController
305 ++++++++++++++++++++++
306 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.
307 This class is implemented to redirect the standard Web error page to a JSON message error.
308 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.
310 Handle version and "X-ONAP-RequestID"
311 *************************************
312 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.
316 runtime-ACM Rest Api supports **application/json**, **application/yaml** and **text/plain** Media Types. The configuration is implemented in CoderHttpMesageConverter.
320 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**.
324 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**.
328 Text format is used by Prometheus. For the conversion from Object to String will be used **StringHttpMessageConverter**.