1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
3 .. _clamp-controlloop-runtime:
5 The CLAMP Control Loop Runtime
6 ##############################
12 This article explains how CLAMP Control Loop Runtime is implemented.
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: graphical user interface, Postman or a Front-End Application
26 Create of a Control Loop Type
27 +++++++++++++++++++++++++++++
28 - GUI calls POST "/commission" endpoint with a Control Loop Type Definition (Tosca Service Template) as body
29 - CL-runtime 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)
34 Delete of a Control Loop Type
35 +++++++++++++++++++++++++++++
36 - GUI calls DELETE "/commission" endpoint
37 - CL-runtime receives the call by Rest-Api (CommissioningController)
38 - if there are participants registered, CL-runtime 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 Control Loop Type from DB
42 Create of a Control Loop
43 ++++++++++++++++++++++++
44 - GUI calls POST "/instantiation" endpoint with a Control Loop as body
45 - CL-runtime receives the call by Rest-Api (InstantiationController)
46 - It validates the Control Loop
47 - It saves the Control Loop to DB
48 - Design of an update of a Control Loop
49 - GUI calls PUT "/instantiation" endpoint with a Control Loop as body
50 - CL-runtime receives the call by Rest-Api (InstantiationController)
51 - It validates the Control Loop
52 - It saves the Control Loop to DB
54 Delete of a Control Loop
55 ++++++++++++++++++++++++
56 - GUI calls DELETE "/instantiation" endpoint
57 - CL-runtime receives the call by Rest-Api (InstantiationController)
58 - It checks that Control Loop is in UNINITIALISED status
59 - It deletes the Control Loop from DB
61 "issues control loop commands to control loops"
62 +++++++++++++++++++++++++++++++++++++++++++++++
64 case **UNINITIALISED to PASSIVE**
66 - GUI calls "/instantiation/command" endpoint with PASSIVE as orderedState
67 - CL-runtime checks if participants registered are matching with the list of control Loop Element
68 - It updates control loop and control loop elements to DB (orderedState = PASSIVE)
69 - It validates the status order issued
70 - It triggers the execution to send a broadcast CONTROL_LOOP_UPDATE message
71 - the message is built by ControlLoopUpdatePublisher using Tosca Service Template data and ControlLoop data. (with startPhase = 0)
72 - It updates control loop and control loop elements to DB (state = UNINITIALISED2PASSIVE)
74 case **PASSIVE to UNINITIALISED**
76 - GUI calls "/instantiation/command" endpoint with UNINITIALISED as orderedState
77 - CL-runtime checks if participants registered are matching with the list of control Loop Element
78 - It updates control loop and control loop elements to DB (orderedState = UNINITIALISED)
79 - It validates the status order issued
80 - It triggers the execution to send a broadcast CONTROL_LOOP_STATE_CHANGE message
81 - the message is built by ControlLoopStateChangePublisher with controlLoopId
82 - It updates control loop and control loop elements to DB (state = PASSIVE2UNINITIALISED)
84 case **PASSIVE to RUNNING**
86 - GUI calls "/instantiation/command" endpoint with RUNNING as orderedState
87 - CL-runtime checks if participants registered are matching with the list of control Loop Element.
88 - It updates control loop and control loop elements to DB (orderedState = RUNNING)
89 - It validates the status order issued
90 - It triggers the execution to send a broadcast CONTROL_LOOP_STATE_CHANGE message
91 - the message is built by ControlLoopStateChangePublisher with controlLoopId
92 - It updates control loop and control loop elements to DB (state = PASSIVE2RUNNING)
94 case **RUNNING to PASSIVE**
96 - GUI calls "/instantiation/command" endpoint with UNINITIALISED as orderedState
97 - CL-runtime checks if participants registered are matching with the list of control Loop Element
98 - It updates control loop and control loop elements to db (orderedState = RUNNING)
99 - It validates the status order issued
100 - It triggers the execution to send a broadcast CONTROL_LOOP_STATE_CHANGE message
101 - the message is built by ControlLoopStateChangePublisher with controlLoopId
102 - It updates control loop and control loop elements to db (state = RUNNING2PASSIVE)
106 The startPhase is particularly important in control loop update and control loop state changes because sometime the user wishes to control the order in which the state changes in Control Loop Elements in a control loop.
108 How to define StartPhase
109 ++++++++++++++++++++++++
110 StartPhase is defined as shown below in the Definition of TOSCA fundamental Control Loop Types yaml file.
118 - greater-or-equal: 0
119 description: A value indicating the start phase in which this control loop element will be started, the
120 first start phase is zero. Control Loop Elements are started in their start_phase order and stopped
121 in reverse start phase order. Control Loop Elements with the same start phase are started and
122 stopped simultaneously
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 control loop commissioning.
128 Example where it could be used:
132 org.onap.domain.database.Http_PMSHMicroserviceControlLoopElement:
133 # Consul http config for PMSH.
135 type: org.onap.policy.clamp.controlloop.HttpControlLoopElement
137 description: Control loop element for the http requests of PMSH microservice
141 name: HttpParticipant0
144 name: org.onap.k8s.controlloop.HttpControlLoopParticipant
146 uninitializedToPassiveTimeout: 180
151 In state changes from UNITITIALISED → PASSIVE, control loop elements are started in increasing order of their startPhase.
153 Example with Http_PMSHMicroserviceControlLoopElement with startPhase to 1 and PMSH_K8SMicroserviceControlLoopElement with startPhase to 0
155 - CL-runtime sends a broadcast CONTROL_LOOP_UPDATE message to all participants with startPhase = 0
156 - participant receives the CONTROL_LOOP_UPDATE message and runs to PASSIVE state (only CL elements defined as startPhase = 0)
157 - CL-runtime receives CONTROL_LOOP_UPDATE_ACT messages from participants and set the state (from the CL element of the message) to PASSIVE
158 - CL-runtime calculates that all CL elements with startPhase = 0 are set to proper state and sends a broadcast CONTROL_LOOP_UPDATE message with startPhase = 1
159 - participant receives the CONTROL_LOOP_UPDATE message and runs to PASSIVE state (only CL elements defined as startPhase = 1)
160 - CL-runtime calculates that all CL elements are set to proper state and set CL to PASSIVE
162 In that scenario the message CONTROL_LOOP_UPDATE has been sent two times.
164 Design of managing messages
165 ***************************
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 Control Loop 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
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
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
193 CONTROLLOOP_UPDATE_ACK
194 ++++++++++++++++++++++
195 - A participant sends CONTROLLOOP_UPDATE_ACK message in response to a CONTROLLOOP_UPDATE message. It will send a CONTROLLOOP_UPDATE_ACK - for each CL-elements moved to the ordered state as indicated by the CONTROLLOOP_UPDATE
196 - ControlLoopUpdateAckListener collects the message from DMaap
197 - It checks the status of all control loop elements and checks if the control loop 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
201 CONTROLLOOP_STATECHANGE_ACK
202 +++++++++++++++++++++++++++
203 Design of a CONTROLLOOP_STATECHANGE_ACK is similar to the design for CONTROLLOOP_UPDATE_ACK
205 Design of monitoring execution in SupervisionScanner
206 ****************************************************
207 Monitoring is designed to process the follow operations:
209 - to determine the next startPhase in a CONTROLLOOP_UPDATE message
210 - to update CL state: in a scenario that "ControlLoop.state" is in a kind of transitional state (example UNINITIALISED2PASSIVE), if all - CL-elements are moved properly to the specific state, the "ControlLoop.state" will be updated to that and saved to DB
211 - to retry CONTROLLOOP_UPDATE/CONTROL_LOOP_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 CL-runtime do not receive PARTICIPANT_UPDATE_ACT from it
213 - to send PARTICIPANT_STATUS_REQ to the participant in a scenario that CL-runtime do not receive PARTICIPANT_STATUS from it
215 The solution Design of retry, timeout, and reporting for all Participant message dialogues are implemented into the monitoring execution.
217 - Spring Scheduling inserts the task to monitor retry execution into ThreadPoolExecutor
218 - ThreadPoolExecutor executes the task
219 - a message will be retry if CL-runtime do no receive Act message before MaxWaitMs milliseconds
221 Design of Exception handling
222 ****************************
223 GlobalControllerExceptionHandler
224 ++++++++++++++++++++++++++++++++
225 If error occurred during the Rest Api call, CL-runtime responses with a proper status error code and a JSON message error.
226 This class is implemented to intercept and handle ControlLoopException, 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.
230 RuntimeErrorController
231 ++++++++++++++++++++++
232 If wrong end-point is called or an Exception not intercepted by GlobalControllerExceptionHandler, CL-runtime 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.
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.
242 CL-runtime Rest Api supports **application/json**, **application/yaml** and **text/plain** Media Types. The configuration is implemented in CoderHttpMesageConverter.
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**.
250 YAML format is a standard for Control Loop Type Definition. For the conversion from YAML to Object and vice-versa will be used **org.onap.policy.common.utils.coder.StandardYamlCoder**.
254 Text format is used by Prometheus. For the conversion from Object to String will be used **StringHttpMessageConverter**.