diff options
| -rw-r--r-- | docs/clamp/acm/controlloop-architecture.rst | 2 | ||||
| -rw-r--r-- | docs/clamp/acm/design-impl/clamp-controlloop-runtime.rst | 254 | ||||
| -rw-r--r-- | docs/clamp/acm/design-impl/clamp-gui-controlloop.rst | 4 | ||||
| -rw-r--r-- | docs/clamp/acm/design-impl/clamp-runtime-acm.rst | 254 | ||||
| -rw-r--r-- | docs/clamp/acm/design-impl/design-impl.rst | 2 | ||||
| -rw-r--r-- | docs/development/devtools/clamp-cl-participant-protocol-smoke.rst | 124 | ||||
| -rw-r--r-- | docs/development/devtools/devtools.rst | 3 | ||||
| -rw-r--r-- | docs/development/devtools/distribution-smoke.rst | 136 | ||||
| -rw-r--r-- | docs/development/devtools/images/message-commissioning-participant.png | bin | 0 -> 101491 bytes | |||
| -rw-r--r-- | docs/development/devtools/policy-gui-acm-smoke.rst (renamed from docs/development/devtools/policy-gui-controlloop-smoke.rst) | 44 |
10 files changed, 480 insertions, 343 deletions
diff --git a/docs/clamp/acm/controlloop-architecture.rst b/docs/clamp/acm/controlloop-architecture.rst index c5977ee4..1c09bea0 100644 --- a/docs/clamp/acm/controlloop-architecture.rst +++ b/docs/clamp/acm/controlloop-architecture.rst @@ -461,7 +461,7 @@ The APIs and Protocols used by CLAMP for Control Loops are described on the page The design and implementation of TOSCA Control Loops in CLAMP is described for each executable entity on the pages below: -#. :ref:`The CLAMP Control Loop Runtime Server <clamp-controlloop-runtime>` +#. :ref:`The CLAMP Control Loop Runtime Server <clamp-runtime-acm>` #. :ref:`CLAMP Control Loop Participants <clamp-controlloop-participants>` #. :ref:`Managing Control Loops using The CLAMP GUI <clamp-gui-controlloop>` diff --git a/docs/clamp/acm/design-impl/clamp-controlloop-runtime.rst b/docs/clamp/acm/design-impl/clamp-controlloop-runtime.rst deleted file mode 100644 index 0077b3de..00000000 --- a/docs/clamp/acm/design-impl/clamp-controlloop-runtime.rst +++ /dev/null @@ -1,254 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. - -.. _clamp-controlloop-runtime: - -The CLAMP Control Loop Runtime -############################## - -.. contents:: - :depth: 3 - - -This article explains how CLAMP Control Loop Runtime is implemented. - -Terminology -*********** -- Broadcast message: a message for all participants (participantId=null and participantType=null) -- Message to a participant: a message only for a participant (participantId and participantType properly filled) -- ThreadPoolExecutor: ThreadPoolExecutor executes the given task, into SupervisionAspect class is configured to execute tasks in ordered manner, one by one -- Spring Scheduling: into SupervisionAspect class, the @Scheduled annotation invokes "schedule()" method every "runtime.participantParameters.heartBeatMs" milliseconds with a fixed delay -- MessageIntercept: "@MessageIntercept" annotation is used into SupervisionHandler class to intercept "handleParticipantMessage" method calls using spring aspect oriented programming -- GUI: graphical user interface, Postman or a Front-End Application - -Design of Rest Api -****************** - -Create of a Control Loop Type -+++++++++++++++++++++++++++++ -- GUI calls POST "/commission" endpoint with a Control Loop Type Definition (Tosca Service Template) as body -- CL-runtime receives the call by Rest-Api (CommissioningController) -- It saves to DB the Tosca Service Template using PolicyModelsProvider -- if there are participants registered, it triggers the execution to send a broadcast PARTICIPANT_UPDATE message -- the message is built by ParticipantUpdatePublisher using Tosca Service Template data (to fill the list of ParticipantDefinition) - -Delete of a Control Loop Type -+++++++++++++++++++++++++++++ -- GUI calls DELETE "/commission" endpoint -- CL-runtime receives the call by Rest-Api (CommissioningController) -- if there are participants registered, CL-runtime triggers the execution to send a broadcast PARTICIPANT_UPDATE message -- the message is built by ParticipantUpdatePublisher with an empty list of ParticipantDefinition -- It deletes the Control Loop Type from DB - -Create of a Control Loop -++++++++++++++++++++++++ -- GUI calls POST "/instantiation" endpoint with a Control Loop as body -- CL-runtime receives the call by Rest-Api (InstantiationController) -- It validates the Control Loop -- It saves the Control Loop to DB -- Design of an update of a Control Loop -- GUI calls PUT "/instantiation" endpoint with a Control Loop as body -- CL-runtime receives the call by Rest-Api (InstantiationController) -- It validates the Control Loop -- It saves the Control Loop to DB - -Delete of a Control Loop -++++++++++++++++++++++++ -- GUI calls DELETE "/instantiation" endpoint -- CL-runtime receives the call by Rest-Api (InstantiationController) -- It checks that Control Loop is in UNINITIALISED status -- It deletes the Control Loop from DB - -"issues control loop commands to control loops" -+++++++++++++++++++++++++++++++++++++++++++++++ - -case **UNINITIALISED to PASSIVE** - -- GUI calls "/instantiation/command" endpoint with PASSIVE as orderedState -- CL-runtime checks if participants registered are matching with the list of control Loop Element -- It updates control loop and control loop elements to DB (orderedState = PASSIVE) -- It validates the status order issued -- It triggers the execution to send a broadcast CONTROL_LOOP_UPDATE message -- the message is built by ControlLoopUpdatePublisher using Tosca Service Template data and ControlLoop data. (with startPhase = 0) -- It updates control loop and control loop elements to DB (state = UNINITIALISED2PASSIVE) - -case **PASSIVE to UNINITIALISED** - -- GUI calls "/instantiation/command" endpoint with UNINITIALISED as orderedState -- CL-runtime checks if participants registered are matching with the list of control Loop Element -- It updates control loop and control loop elements to DB (orderedState = UNINITIALISED) -- It validates the status order issued -- It triggers the execution to send a broadcast CONTROL_LOOP_STATE_CHANGE message -- the message is built by ControlLoopStateChangePublisher with controlLoopId -- It updates control loop and control loop elements to DB (state = PASSIVE2UNINITIALISED) - -case **PASSIVE to RUNNING** - -- GUI calls "/instantiation/command" endpoint with RUNNING as orderedState -- CL-runtime checks if participants registered are matching with the list of control Loop Element. -- It updates control loop and control loop elements to DB (orderedState = RUNNING) -- It validates the status order issued -- It triggers the execution to send a broadcast CONTROL_LOOP_STATE_CHANGE message -- the message is built by ControlLoopStateChangePublisher with controlLoopId -- It updates control loop and control loop elements to DB (state = PASSIVE2RUNNING) - -case **RUNNING to PASSIVE** - -- GUI calls "/instantiation/command" endpoint with UNINITIALISED as orderedState -- CL-runtime checks if participants registered are matching with the list of control Loop Element -- It updates control loop and control loop elements to db (orderedState = RUNNING) -- It validates the status order issued -- It triggers the execution to send a broadcast CONTROL_LOOP_STATE_CHANGE message -- the message is built by ControlLoopStateChangePublisher with controlLoopId -- It updates control loop and control loop elements to db (state = RUNNING2PASSIVE) - -StartPhase -********** -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. - -How to define StartPhase -++++++++++++++++++++++++ -StartPhase is defined as shown below in the Definition of TOSCA fundamental Control Loop Types yaml file. - -.. code-block:: YAML - - startPhase: - type: integer - required: false - constraints: - - greater-or-equal: 0 - description: A value indicating the start phase in which this control loop element will be started, the - first start phase is zero. Control Loop Elements are started in their start_phase order and stopped - in reverse start phase order. Control Loop Elements with the same start phase are started and - stopped simultaneously - metadata: - common: true - -The "common: true" value in the metadata of the startPhase property identifies that property as being a common property. -This property will be set on the CLAMP GUI during control loop commissioning. -Example where it could be used: - -.. code-block:: YAML - - org.onap.domain.database.Http_PMSHMicroserviceControlLoopElement: - # Consul http config for PMSH. - version: 1.2.3 - type: org.onap.policy.clamp.controlloop.HttpControlLoopElement - type_version: 1.0.1 - description: Control loop element for the http requests of PMSH microservice - properties: - provider: ONAP - participant_id: - name: HttpParticipant0 - version: 1.0.0 - participantType: - name: org.onap.k8s.controlloop.HttpControlLoopParticipant - version: 2.3.4 - uninitializedToPassiveTimeout: 180 - startPhase: 1 - -How StartPhase works -++++++++++++++++++++ -In state changes from UNITITIALISED → PASSIVE, control loop elements are started in increasing order of their startPhase. - -Example with Http_PMSHMicroserviceControlLoopElement with startPhase to 1 and PMSH_K8SMicroserviceControlLoopElement with startPhase to 0 - -- CL-runtime sends a broadcast CONTROL_LOOP_UPDATE message to all participants with startPhase = 0 -- participant receives the CONTROL_LOOP_UPDATE message and runs to PASSIVE state (only CL elements defined as startPhase = 0) -- CL-runtime receives CONTROL_LOOP_UPDATE_ACT messages from participants and set the state (from the CL element of the message) to PASSIVE -- 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 -- participant receives the CONTROL_LOOP_UPDATE message and runs to PASSIVE state (only CL elements defined as startPhase = 1) -- CL-runtime calculates that all CL elements are set to proper state and set CL to PASSIVE - -In that scenario the message CONTROL_LOOP_UPDATE has been sent two times. - -Design of managing messages -*************************** - -PARTICIPANT_REGISTER -++++++++++++++++++++ -- A participant starts and send a PARTICIPANT_REGISTER message -- ParticipantRegisterListener collects the message from DMaap -- if not present, it saves participant reference with status UNKNOWN to DB -- if is present a Control Loop Type, it triggers the execution to send a PARTICIPANT_UPDATE message to the participant registered (message of Priming) -- the message is built by ParticipantUpdatePublisher using Tosca Service Template data (to fill the list of ParticipantDefinition) -- It triggers the execution to send a PARTICIPANT_REGISTER_ACK message to the participant registered -- MessageIntercept intercepts that event, if PARTICIPANT_UPDATE message has been sent, it will be add a task to handle PARTICIPANT_REGISTER in SupervisionScanner -- SupervisionScanner starts the monitoring for participantUpdate - -PARTICIPANT_UPDATE_ACK -++++++++++++++++++++++ -- A participant sends PARTICIPANT_UPDATE_ACK message in response to a PARTICIPANT_UPDATE message -- ParticipantUpdateAckListener collects the message from DMaap -- MessageIntercept intercepts that event and adds a task to handle PARTICIPANT_UPDATE_ACK in SupervisionScanner -- SupervisionScanner removes the monitoring for participantUpdate -- It updates the status of the participant to DB - -PARTICIPANT_STATUS -++++++++++++++++++ -- A participant sends a scheduled PARTICIPANT_STATUS message -- ParticipantStatusListener collects the message from DMaap -- MessageIntercept intercepts that event and adds a task to handle PARTICIPANT_STATUS in SupervisionScanner -- SupervisionScanner clears and starts the monitoring for participantStatus - -CONTROLLOOP_UPDATE_ACK -++++++++++++++++++++++ -- 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 -- ControlLoopUpdateAckListener collects the message from DMaap -- It checks the status of all control loop elements and checks if the control loop is primed -- It updates the CL to DB if it is changed -- MessageIntercept intercepts that event and adds a task to handle a monitoring execution in SupervisionScanner - -CONTROLLOOP_STATECHANGE_ACK -+++++++++++++++++++++++++++ -Design of a CONTROLLOOP_STATECHANGE_ACK is similar to the design for CONTROLLOOP_UPDATE_ACK - -Design of monitoring execution in SupervisionScanner -**************************************************** -Monitoring is designed to process the follow operations: - -- to determine the next startPhase in a CONTROLLOOP_UPDATE message -- 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 -- 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 -- to retry PARTICIPANT_UPDATE message to the participant in a scenario that CL-runtime do not receive PARTICIPANT_UPDATE_ACT from it -- to send PARTICIPANT_STATUS_REQ to the participant in a scenario that CL-runtime do not receive PARTICIPANT_STATUS from it - -The solution Design of retry, timeout, and reporting for all Participant message dialogues are implemented into the monitoring execution. - -- Spring Scheduling inserts the task to monitor retry execution into ThreadPoolExecutor -- ThreadPoolExecutor executes the task -- a message will be retry if CL-runtime do no receive Act message before MaxWaitMs milliseconds - -Design of Exception handling -**************************** -GlobalControllerExceptionHandler -++++++++++++++++++++++++++++++++ -If error occurred during the Rest Api call, CL-runtime responses with a proper status error code and a JSON message error. -This class is implemented to intercept and handle ControlLoopException, PfModelException and PfModelRuntimeException if they are thrown during the Rest Ali calls. -All of those classes must implement ErrorResponseInfo that contains message error and status response code. -So the Exception is converted in JSON message. - -RuntimeErrorController -++++++++++++++++++++++ -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. -This class is implemented to redirect the standard Web error page to a JSON message error. -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. - -Handle version and "X-ONAP-RequestID" -************************************* -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. - -Media Type Support -****************** -CL-runtime Rest Api supports **application/json**, **application/yaml** and **text/plain** Media Types. The configuration is implemented in CoderHttpMesageConverter. - -application/json -++++++++++++++++ -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**. - -application/yaml -++++++++++++++++ -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**. - -text/plain -++++++++++ -Text format is used by Prometheus. For the conversion from Object to String will be used **StringHttpMessageConverter**. diff --git a/docs/clamp/acm/design-impl/clamp-gui-controlloop.rst b/docs/clamp/acm/design-impl/clamp-gui-controlloop.rst index 71d0a053..41e3558c 100644 --- a/docs/clamp/acm/design-impl/clamp-gui-controlloop.rst +++ b/docs/clamp/acm/design-impl/clamp-gui-controlloop.rst @@ -12,7 +12,7 @@ The Policy GUI for Control Loops 1. Introduction ############### -The Policy GUI for Control Loops is designed to provide a user the ability to interact with the Control Loop Runtime to perform several actions. The actual technical design of the Control Loop Runtime is detailed in :ref:`clamp-controlloop-runtime`. All of the endpoints and the purpose for accessing those endpoints is discussed there. In the current release of the GUI, the main purposes are to perform the below: +The Policy GUI for Control Loops is designed to provide a user the ability to interact with the Control Loop Runtime to perform several actions. The actual technical design of the Control Loop Runtime is detailed in :ref:`clamp-runtime-acm`. All of the endpoints and the purpose for accessing those endpoints is discussed there. In the current release of the GUI, the main purposes are to perform the below: - Commission new Tosca Service Templates. - Editing Common Properties. @@ -111,7 +111,7 @@ The Runtime also communicates with the participants over DMAAP. Commissioning a Using DMAAP, the Runtime can send; updates to the control loop definitions, change the state of control loops, receive information about participants, receive state information about control loops and effectively supervise the control loops. This data is then made available via Rest APIs that can be queried by the frontend. This is how the GUI can perform monitoring operations. -More detail on the design of the Runtime ControlLoop can be found in :ref:`clamp-controlloop-runtime`. +More detail on the design of the Runtime ControlLoop can be found in :ref:`clamp-runtime-acm`. 2.4 DMAAP --------- diff --git a/docs/clamp/acm/design-impl/clamp-runtime-acm.rst b/docs/clamp/acm/design-impl/clamp-runtime-acm.rst new file mode 100644 index 00000000..3e99ed1d --- /dev/null +++ b/docs/clamp/acm/design-impl/clamp-runtime-acm.rst @@ -0,0 +1,254 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. + +.. _clamp-runtime-acm: + +The CLAMP Automation Composition Runtime +######################################## + +.. contents:: + :depth: 3 + + +This article explains how CLAMP Automation Composition Runtime is implemented. + +Terminology +*********** +- Broadcast message: a message for all participants (participantId=null and participantType=null) +- Message to a participant: a message only for a participant (participantId and participantType properly filled) +- ThreadPoolExecutor: ThreadPoolExecutor executes the given task, into SupervisionAspect class is configured to execute tasks in ordered manner, one by one +- Spring Scheduling: into SupervisionAspect class, the @Scheduled annotation invokes "schedule()" method every "runtime.participantParameters.heartBeatMs" milliseconds with a fixed delay +- MessageIntercept: "@MessageIntercept" annotation is used into SupervisionHandler class to intercept "handleParticipantMessage" method calls using spring aspect oriented programming +- GUI: swagger-ui, Postman or policy-gui + +Design of Rest Api +****************** + +Create of a Automation Composition Type ++++++++++++++++++++++++++++++++++++++++ +- GUI calls POST "/commission" endpoint with a Automation Composition Type Definition (Tosca Service Template) as body +- runtime-ACM receives the call by Rest-Api (CommissioningController) +- It saves to DB the Tosca Service Template using PolicyModelsProvider +- if there are participants registered, it triggers the execution to send a broadcast PARTICIPANT_UPDATE message +- the message is built by ParticipantUpdatePublisher using Tosca Service Template data (to fill the list of ParticipantDefinition) + +Delete of a Automation Composition Type ++++++++++++++++++++++++++++++++++++++++ +- GUI calls DELETE "/commission" endpoint +- runtime-ACM receives the call by Rest-Api (CommissioningController) +- if there are participants registered, runtime-ACM triggers the execution to send a broadcast PARTICIPANT_UPDATE message +- the message is built by ParticipantUpdatePublisher with an empty list of ParticipantDefinition +- It deletes the Automation Composition Type from DB + +Create of a Automation Composition +++++++++++++++++++++++++++++++++++ +- GUI calls POST "/instantiation" endpoint with a Automation Composition as body +- runtime-ACM receives the call by Rest-Api (InstantiationController) +- It validates the Automation Composition +- It saves the Automation Composition to DB +- Design of an update of a Automation Composition +- GUI calls PUT "/instantiation" endpoint with a Automation Composition as body +- runtime-ACM receives the call by Rest-Api (InstantiationController) +- It validates the Automation Composition +- It saves the Automation Composition to DB + +Delete of a Automation Composition +++++++++++++++++++++++++++++++++++ +- GUI calls DELETE "/instantiation" endpoint +- runtime-ACM receives the call by Rest-Api (InstantiationController) +- It checks that Automation Composition is in UNINITIALISED status +- It deletes the Automation Composition from DB + +"issues Automation Composition commands to Automation Compositions" ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +case **UNINITIALISED to PASSIVE** + +- GUI calls "/instantiation/command" endpoint with PASSIVE as orderedState +- runtime-ACM checks if participants registered are matching with the list of Automation Composition Element +- It updates Automation Composition and Automation Composition elements to DB (orderedState = PASSIVE) +- It validates the status order issued +- It triggers the execution to send a broadcast AUTOMATION_COMPOSITION_UPDATE message +- the message is built by AutomationCompositionUpdatePublisher using Tosca Service Template data and AutomationComposition data. (with startPhase = 0) +- It updates Automation Composition and Automation Composition elements to DB (state = UNINITIALISED2PASSIVE) + +case **PASSIVE to UNINITIALISED** + +- GUI calls "/instantiation/command" endpoint with UNINITIALISED as orderedState +- runtime-ACM checks if participants registered are matching with the list of Automation Composition Element +- It updates Automation Composition and Automation Composition elements to DB (orderedState = UNINITIALISED) +- It validates the status order issued +- It triggers the execution to send a broadcast AUTOMATION_COMPOSITION_STATE_CHANGE message +- the message is built by AutomationCompositionStateChangePublisher with automationcompositionId +- It updates Automation Composition and Automation Composition elements to DB (state = PASSIVE2UNINITIALISED) + +case **PASSIVE to RUNNING** + +- GUI calls "/instantiation/command" endpoint with RUNNING as orderedState +- runtime-ACM checks if participants registered are matching with the list of Automation Composition Element. +- It updates Automation Composition and Automation Composition elements to DB (orderedState = RUNNING) +- It validates the status order issued +- It triggers the execution to send a broadcast AUTOMATION_COMPOSITION_STATE_CHANGE message +- the message is built by AutomationCompositionStateChangePublisher with automationcompositionId +- It updates Automation Composition and Automation Composition elements to DB (state = PASSIVE2RUNNING) + +case **RUNNING to PASSIVE** + +- GUI calls "/instantiation/command" endpoint with UNINITIALISED as orderedState +- runtime-ACM checks if participants registered are matching with the list of Automation Composition Element +- It updates Automation Composition and Automation Composition elements to db (orderedState = RUNNING) +- It validates the status order issued +- It triggers the execution to send a broadcast AUTOMATION_COMPOSITION_STATE_CHANGE message +- the message is built by AutomationCompositionStateChangePublisher with automationcompositionId +- It updates Automation Composition and Automation Composition elements to db (state = RUNNING2PASSIVE) + +StartPhase +********** +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. + +How to define StartPhase +++++++++++++++++++++++++ +StartPhase is defined as shown below in the Definition of TOSCA fundamental Automation Composition Types yaml file. + +.. code-block:: YAML + + startPhase: + type: integer + required: false + constraints: + - greater-or-equal: 0 + description: A value indicating the start phase in which this Automation Composition element will be started, the + first start phase is zero. Automation Composition Elements are started in their start_phase order and stopped + in reverse start phase order. Automation Composition Elements with the same start phase are started and + stopped simultaneously + metadata: + common: true + +The "common: true" value in the metadata of the startPhase property identifies that property as being a common property. +This property will be set on the CLAMP GUI during Automation Composition commissioning. +Example where it could be used: + +.. code-block:: YAML + + org.onap.domain.database.Http_PMSHMicroserviceAutomationCompositionElement: + # Consul http config for PMSH. + version: 1.2.3 + type: org.onap.policy.clamp.acm.HttpAutomationCompositionElement + type_version: 1.0.1 + description: Automation Composition element for the http requests of PMSH microservice + properties: + provider: ONAP + participant_id: + name: HttpParticipant0 + version: 1.0.0 + participantType: + name: org.onap.acm.HttpAutomationCompositionParticipant + version: 2.3.4 + uninitializedToPassiveTimeout: 180 + startPhase: 1 + +How StartPhase works +++++++++++++++++++++ +In state changes from UNITITIALISED → PASSIVE, Automation Composition elements are started in increasing order of their startPhase. + +Example with Http_PMSHMicroserviceAutomationCompositionElement with startPhase to 1 and PMSH_K8SMicroserviceAutomationCompositionElement with startPhase to 0 + +- runtime-ACM sends a broadcast AUTOMATION_COMPOSITION_UPDATE message to all participants with startPhase = 0 +- participant receives the AUTOMATION_COMPOSITION_UPDATE message and runs to PASSIVE state (only CL elements defined as startPhase = 0) +- runtime-ACM receives AUTOMATION_COMPOSITION_UPDATE_ACT messages from participants and set the state (from the CL element of the message) to PASSIVE +- 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 +- participant receives the AUTOMATION_COMPOSITION_UPDATE message and runs to PASSIVE state (only CL elements defined as startPhase = 1) +- runtime-ACM calculates that all CL elements are set to proper state and set CL to PASSIVE + +In that scenario the message AUTOMATION_COMPOSITION_UPDATE has been sent two times. + +Design of managing messages +*************************** + +PARTICIPANT_REGISTER +++++++++++++++++++++ +- A participant starts and send a PARTICIPANT_REGISTER message +- ParticipantRegisterListener collects the message from DMaap +- if not present, it saves participant reference with status UNKNOWN to DB +- if is present a Automation Composition Type, it triggers the execution to send a PARTICIPANT_UPDATE message to the participant registered (message of Priming) +- the message is built by ParticipantUpdatePublisher using Tosca Service Template data (to fill the list of ParticipantDefinition) +- It triggers the execution to send a PARTICIPANT_REGISTER_ACK message to the participant registered +- MessageIntercept intercepts that event, if PARTICIPANT_UPDATE message has been sent, it will be add a task to handle PARTICIPANT_REGISTER in SupervisionScanner +- SupervisionScanner starts the monitoring for participantUpdate + +PARTICIPANT_UPDATE_ACK +++++++++++++++++++++++ +- A participant sends PARTICIPANT_UPDATE_ACK message in response to a PARTICIPANT_UPDATE message +- ParticipantUpdateAckListener collects the message from DMaap +- MessageIntercept intercepts that event and adds a task to handle PARTICIPANT_UPDATE_ACK in SupervisionScanner +- SupervisionScanner removes the monitoring for participantUpdate +- It updates the status of the participant to DB + +PARTICIPANT_STATUS +++++++++++++++++++ +- A participant sends a scheduled PARTICIPANT_STATUS message +- ParticipantStatusListener collects the message from DMaap +- MessageIntercept intercepts that event and adds a task to handle PARTICIPANT_STATUS in SupervisionScanner +- SupervisionScanner clears and starts the monitoring for participantStatus + +AUTOMATION_COMPOSITION_UPDATE_ACK ++++++++++++++++++++++++++++++++++ +- 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 +- AutomationCompositionUpdateAckListener collects the message from DMaap +- It checks the status of all Automation Composition elements and checks if the Automation Composition is primed +- It updates the CL to DB if it is changed +- MessageIntercept intercepts that event and adds a task to handle a monitoring execution in SupervisionScanner + +AUTOMATION_COMPOSITION_STATECHANGE_ACK +++++++++++++++++++++++++++++++++++++++ +Design of a AUTOMATION_COMPOSITION_STATECHANGE_ACK is similar to the design for AUTOMATION_COMPOSITION_UPDATE_ACK + +Design of monitoring execution in SupervisionScanner +**************************************************** +Monitoring is designed to process the follow operations: + +- to determine the next startPhase in a AUTOMATION_COMPOSITION_UPDATE message +- 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 +- 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 +- to retry PARTICIPANT_UPDATE message to the participant in a scenario that runtime-ACM do not receive PARTICIPANT_UPDATE_ACT from it +- to send PARTICIPANT_STATUS_REQ to the participant in a scenario that runtime-ACM do not receive PARTICIPANT_STATUS from it + +The solution Design of retry, timeout, and reporting for all Participant message dialogues are implemented into the monitoring execution. + +- Spring Scheduling inserts the task to monitor retry execution into ThreadPoolExecutor +- ThreadPoolExecutor executes the task +- a message will be retry if runtime-ACM do no receive Act message before MaxWaitMs milliseconds + +Design of Exception handling +**************************** +GlobalControllerExceptionHandler +++++++++++++++++++++++++++++++++ +If error occurred during the Rest Api call, runtime-ACM responses with a proper status error code and a JSON message error. +This class is implemented to intercept and handle AutomationCompositionException, PfModelException and PfModelRuntimeException if they are thrown during the Rest Ali calls. +All of those classes must implement ErrorResponseInfo that contains message error and status response code. +So the Exception is converted in JSON message. + +RuntimeErrorController +++++++++++++++++++++++ +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. +This class is implemented to redirect the standard Web error page to a JSON message error. +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. + +Handle version and "X-ONAP-RequestID" +************************************* +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. + +Media Type Support +****************** +runtime-ACM Rest Api supports **application/json**, **application/yaml** and **text/plain** Media Types. The configuration is implemented in CoderHttpMesageConverter. + +application/json +++++++++++++++++ +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**. + +application/yaml +++++++++++++++++ +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**. + +text/plain +++++++++++ +Text format is used by Prometheus. For the conversion from Object to String will be used **StringHttpMessageConverter**. diff --git a/docs/clamp/acm/design-impl/design-impl.rst b/docs/clamp/acm/design-impl/design-impl.rst index 50ebb2e7..979ace92 100644 --- a/docs/clamp/acm/design-impl/design-impl.rst +++ b/docs/clamp/acm/design-impl/design-impl.rst @@ -10,6 +10,6 @@ The sections below describe the components that handle TOSCA Control Loops. .. toctree:: :maxdepth: 1 - clamp-controlloop-runtime + clamp-runtime-acm clamp-gui-controlloop participants/participants diff --git a/docs/development/devtools/clamp-cl-participant-protocol-smoke.rst b/docs/development/devtools/clamp-cl-participant-protocol-smoke.rst index 67005fa3..4ad03984 100644 --- a/docs/development/devtools/clamp-cl-participant-protocol-smoke.rst +++ b/docs/development/devtools/clamp-cl-participant-protocol-smoke.rst @@ -7,8 +7,8 @@ CLAMP Participant Protocol Smoke Tests 1. Introduction *************** -The CLAMP Control Loop Participant protocol is an asynchronous protocol that is used by the CLAMP runtime -to coordinate life cycle management of Control Loop instances. +The CLAMP Automation Composition Participant protocol is an asynchronous protocol that is used by the CLAMP runtime +to coordinate life cycle management of Automation Composition instances. This document will serve as a guide to do smoke tests on the different usecases that are involved when working with the Participant protocol and outline how they operate. It will also show a developer how to set up their environment for carrying out smoke tests on the participants. @@ -32,10 +32,10 @@ Linux user - although the majority of the steps show will be exactly the same in 2.2 Setting up the components ============================= -- Controlloop runtime component docker image is started and running. +- Automation Composition runtime component docker image is started and running. - Participant docker images policy-clamp-cl-pf-ppnt, policy-clamp-cl-http-ppnt, policy-clamp-cl-k8s-ppnt are started and running. - Dmaap simulator for communication between components. -- mariadb docker container for policy and controlloop database. +- mariadb docker container for policy and clampacm database. - policy-api for communication between policy participant and policy-framework In this setup guide, we will be setting up all the components technically required for a working convenient @@ -47,7 +47,7 @@ example. We will be using Docker to run our mariadb instance. It will have a total of two databases running in it. -- controlloop: the runtime-controlloop db +- clampacm: the runtime-clampacm db - policyadmin: the policy-api db 3. Running Tests of protocol dialogues @@ -81,107 +81,107 @@ Test result: 3.3 Participant Priming ======================= -When a control loop is primed, the portion of the Control Loop Type Definition and Common Property values for the participants -of each participant type mentioned in the Control Loop Definition are sent to the participants. -Action: Invoke a REST API to prime controlloop type definitions and set values of common properties +When a automation composition is primed, the portion of the Automation Composition Type Definition and Common Property values for the participants +of each participant type mentioned in the Automation Composition Definition are sent to the participants. +Action: Invoke a REST API to prime acm type definitions and set values of common properties Test result: -- Observe PARTICIPANT_UPDATE going from runtime to participant with controlloop type definitions and common property values for participant types -- Observe that the controlloop type definitions and common property values for participant types are stored on ParticipantHandler +- Observe PARTICIPANT_UPDATE going from runtime to participant with acm type definitions and common property values for participant types +- Observe that the acm type definitions and common property values for participant types are stored on ParticipantHandler - Observe PARTICIPANT_UPDATE_ACK going from runtime to participant 3.4 Participant DePriming ========================= -When a control loop is de-primed, the portion of the Control Loop Type Definition and Common Property values for the participants -of each participant type mentioned in the Control Loop Definition are deleted on participants. -Action: Invoke a REST API to deprime controlloop type definitions +When a automation composition is de-primed, the portion of the Automation Composition Type Definition and Common Property values for the participants +of each participant type mentioned in the Automation Composition Definition are deleted on participants. +Action: Invoke a REST API to deprime acm type definitions Test result: -- If controlloop instances exist in runtime database, return a response for the REST API with error response saying "Cannot decommission controlloop type definition" -- If no controlloop instances exist in runtime database, Observe PARTICIPANT_UPDATE going from runtime to participant with definitions as null -- Observe that the controlloop type definitions and common property values for participant types are removed on ParticipantHandler +- If acm instances exist in runtime database, return a response for the REST API with error response saying "Cannot decommission acm type definition" +- If no acm instances exist in runtime database, Observe PARTICIPANT_UPDATE going from runtime to participant with definitions as null +- Observe that the acm type definitions and common property values for participant types are removed on ParticipantHandler - Observe PARTICIPANT_UPDATE_ACK going from runtime to participant -3.5 Control Loop Update -======================= +3.5 Automation Composition Update +================================= -Control Loop Update handles creation, change, and deletion of control loops on participants. -Action: Trigger controlloop instantiation from GUI +Automation Composition Update handles creation, change, and deletion of automation compositions on participants. +Action: Trigger acm instantiation from GUI Test result: -- Observe CONTROL_LOOP_UPDATE going from runtime to participant -- Observe that the controlloop type instances and respective property values for participant types are stored on ControlLoopHandler -- Observe that the controlloop state is UNINITIALISED -- Observe CONTROL_LOOP_UPDATE_ACK going from participant to runtime +- Observe AUTOMATION_COMPOSITION_UPDATE going from runtime to participant +- Observe that the acm type instances and respective property values for participant types are stored on AutomationCompositionHandler +- Observe that the acm state is UNINITIALISED +- Observe AUTOMATION_COMPOSITION_UPDATE_ACK going from participant to runtime -3.6 Control Loop state change to PASSIVE -======================================== +3.6 Automation Composition state change to PASSIVE +================================================== -Control Loop Update handles creation, change, and deletion of control loops on participants. -Action: Change state of the controlloop to PASSIVE +Automation Composition Update handles creation, change, and deletion of automation compositions on participants. +Action: Change state of the acm to PASSIVE Test result: -- Observe CONTROL_LOOP_STATE_CHANGE going from runtime to participant -- Observe that the ControlLoopElements state is PASSIVE -- Observe that the controlloop state is PASSIVE -- Observe CONTROL_LOOP_STATE_CHANGE_ACK going from participant to runtime +- Observe AUTOMATION_COMPOSITION_STATE_CHANGE going from runtime to participant +- Observe that the AutomationCompositionElements state is PASSIVE +- Observe that the acm state is PASSIVE +- Observe AUTOMATION_COMPOSITION_STATE_CHANGE_ACK going from participant to runtime -3.7 Control Loop state change to RUNNING -======================================== +3.7 Automation Composition state change to RUNNING +================================================== -Control Loop Update handles creation, change, and deletion of control loops on participants. -Action: Change state of the controlloop to RUNNING +Automation Composition Update handles creation, change, and deletion of automation compositions on participants. +Action: Change state of the acm to RUNNING Test result: -- Observe CONTROL_LOOP_STATE_CHANGE going from runtime to participant -- Observe that the ControlLoopElements state is RUNNING -- Observe that the controlloop state is RUNNING -- Observe CONTROL_LOOP_STATE_CHANGE_ACK going from participant to runtime +- Observe AUTOMATION_COMPOSITION_STATE_CHANGE going from runtime to participant +- Observe that the AutomationCompositionElements state is RUNNING +- Observe that the acm state is RUNNING +- Observe AUTOMATION_COMPOSITION_STATE_CHANGE_ACK going from participant to runtime -3.8 Control Loop state change to PASSIVE -======================================== +3.8 Automation Composition state change to PASSIVE +================================================== -Control Loop Update handles creation, change, and deletion of control loops on participants. -Action: Change state of the controlloop to PASSIVE +Automation Composition Update handles creation, change, and deletion of automation compositions on participants. +Action: Change state of the acm to PASSIVE Test result: -- Observe CONTROL_LOOP_STATE_CHANGE going from runtime to participant -- Observe that the ControlLoopElements state is PASSIVE -- Observe that the controlloop state is PASSIVE -- Observe CONTROL_LOOP_STATE_CHANGE_ACK going from participant to runtime +- Observe AUTOMATION_COMPOSITION_STATE_CHANGE going from runtime to participant +- Observe that the AutomationCompositionElements state is PASSIVE +- Observe that the acm state is PASSIVE +- Observe AUTOMATION_COMPOSITION_STATE_CHANGE_ACK going from participant to runtime -3.9 Control Loop state change to UNINITIALISED -============================================== +3.9 Automation Composition state change to UNINITIALISED +======================================================== -Control Loop Update handles creation, change, and deletion of control loops on participants. -Action: Change state of the controlloop to UNINITIALISED +Automation Composition Update handles creation, change, and deletion of automation compositions on participants. +Action: Change state of the acm to UNINITIALISED Test result: -- Observe CONTROL_LOOP_STATE_CHANGE going from runtime to participant -- Observe that the ControlLoopElements state is UNINITIALISED -- Observe that the controlloop state is UNINITIALISED -- Observe that the ControlLoopElements undeploy the instances from respective frameworks -- Observe that the control loop instances are removed from participants -- Observe CONTROL_LOOP_STATE_CHANGE_ACK going from participant to runtime +- Observe AUTOMATION_COMPOSITION_STATE_CHANGE going from runtime to participant +- Observe that the AutomationCompositionElements state is UNINITIALISED +- Observe that the acm state is UNINITIALISED +- Observe that the AutomationCompositionElements undeploy the instances from respective frameworks +- Observe that the automation composition instances are removed from participants +- Observe AUTOMATION_COMPOSITION_STATE_CHANGE_ACK going from participant to runtime -3.10 Control Loop monitoring and reporting -========================================== +3.10 Automation Composition monitoring and reporting +==================================================== -This dialogue is used as a heartbeat mechanism for participants, to monitor the status of Control Loop Elements, and to gather statistics on control loops. The ParticipantStatus message is sent periodically by each participant. The reporting interval for sending the message is configurable +This dialogue is used as a heartbeat mechanism for participants, to monitor the status of Automation Composition Elements, and to gather statistics on automation compositions. The ParticipantStatus message is sent periodically by each participant. The reporting interval for sending the message is configurable Action: Bring up participant Test result: - Observe that PARTICIPANT_STATUS message is sent from participants to runtime in a regular interval -- Trigger a PARTICIPANT_STATUS_REQ from runtime and observe a PARTICIPANT_STATUS message with tosca definitions of control loop type definitions sent +- Trigger a PARTICIPANT_STATUS_REQ from runtime and observe a PARTICIPANT_STATUS message with tosca definitions of automation composition type definitions sent from all the participants to runtime This concluded the required smoke tests diff --git a/docs/development/devtools/devtools.rst b/docs/development/devtools/devtools.rst index e2ccb887..6ea36899 100644 --- a/docs/development/devtools/devtools.rst +++ b/docs/development/devtools/devtools.rst @@ -273,7 +273,7 @@ familiar with the Policy Framework components and test any local changes. .. toctree:: :maxdepth: 1 - policy-gui-controlloop-smoke.rst + policy-gui-acm-smoke.rst db-migrator-smoke.rst cl-participants-smoke.rst clamp-smoke.rst @@ -282,6 +282,7 @@ familiar with the Policy Framework components and test any local changes. api-smoke.rst pap-smoke.rst apex-smoke.rst + distribution-smoke.rst .. drools-smoke.rst diff --git a/docs/development/devtools/distribution-smoke.rst b/docs/development/devtools/distribution-smoke.rst new file mode 100644 index 00000000..8afa715a --- /dev/null +++ b/docs/development/devtools/distribution-smoke.rst @@ -0,0 +1,136 @@ +.. This work is licensed under a +.. Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +.. _policy-distribution-smoke-testing-label: + +Policy Distribution Smoke Test +################################ + +The policy-distribution smoke testing is executed against a custom ONAP docker installation as defined in the "policy/docker/csit/docker-compose-distribution-smoke.yml" +This test verifies the execution of the REST api's exposed by the component to make sure the CSAR Decoding and Forwarding works as expected. + +General Setup +***************** +In policy/docker/csit/ + +.. code-block:: bash + + ./start-grafana.sh distribution + +This script will compose the ONAP components used during the smoke tests are: + +- Policy API to perform CRUD of policies. +- Policy DB to store the policies, and DB Migrator to start the db. +- DMAAP Simulator for the communication between components. +- Policy PAP to perform runtime administration (deploy/undeploy/status/statistics/etc). +- Policy Apex-PDP to deploy & undeploy policies. And send heartbeats to PAP. +- Policy Drools-PDP to deploy & undeploy policies. And send heartbeats to PAP. +- Policy Xacml-PDP to deploy & undeploy policies. And send heartbeats to PAP. + +- Policy Distribution to test the Decoding and Farwarding functions. + +Use this script to easly bring down the containers : + +.. code-block:: bash + + ./stop-grafana.sh + +Testing procedure +********************** + +The test set is focused on the following use cases: + +- Wait until Distribution starts and reach the built-in REST endpoints for fetching healthcheck & statistics. +- Execute some of the REST api's exposed by policy-pap component. + +Starting Policy Distribution +------------------------------------ + +Check the docker logs to see when Distribution service is up and running. + +Get the ips of distribution and pap services: + +.. code:: + :number-lines: + + ./get-instance-ip.sh policy-distribution + ./get-instance-ip.sh policy-pap + +Health check status & statistical data of running distribution system. + +.. code-block:: bash + + curl -u 'healthcheck:zb!XztG34' --basic http://{POLICY_DISTRIBUTION_IP}:6969/healthcheck + curl -u 'healthcheck:zb!XztG34' --basic http://{POLICY_DISTRIBUTION_IP}:6969/statistics + +Expected result for healthcheck + +.. code-block:: json + + {"name":"Policy SSD","url":"policy-distribution","healthy":true,"code":200,"message":"alive"} + +Expected result for statistics + +.. code-block:: json + + {"code":200,"totalDistributionCount":0,"distributionSuccessCount":0,"distributionFailureCount":0,"totalDownloadCount":0,"downloadSuccessCount":0,"downloadFailureCount":0} + +Trigger Policy Distribution Core +------------------------------------------ + +In order to test policy-distribution, we need to trigger the decoding copying a .csar in the mapped volume, +defined in the docker-compose-distribution-smoke.yml as : + +.. code-block:: yaml + + volumes: + - ./distribution/config/temp/:/opt/app/policy/distribution/etc/temp/ + +So now copy the "sample_csar_with_apex_policy.csar" from ./distribution/config/csar/ to ./distribution/config/temp/ + +If the commissioning is successful we should see from the logs this message + +.. image:: images/message-commissioning-participant.png + +So if we check the distribution statistics again + +.. code-block:: bash + + {"code":200,"totalDistributionCount":1,"distributionSuccessCount":1,"distributionFailureCount":0,"totalDownloadCount":1,"downloadSuccessCount":1,"downloadFailureCount":0} + +Execute policy-pap testing +------------------------------------ +.. note:: + The user for pap is different. + +Check the details of policies deployed + +.. code-block:: bash + + curl -k --user 'policyadmin:zb!XztG34' http://{POLICY_PAP_IP}:6969/policy/pap/v1/policies/status + +Expected SUCCESS result + +.. code-block:: json + + [{"pdpGroup":"defaultGroup","pdpType":"apex","pdpId":"apex-91fa25a1-0456-42fa-9556-6a4d2bd613fc","policy":{"name":"operational.apex.sampledomain","version":"1.0.0"},"policyType":{"name":"onap.policies.native.Apex","version":"1.0.0"},"deploy":true,"state":"SUCCESS"},{"pdpGroup":"defaultGroup","pdpType":"xacml","pdpId":"xacml-83e19452-0854-41dd-9f17-8b0a68f11813","policy":{"name":"SDNC_Policy.ONAP_NF_NAMING_TIMESTAMP","version":"1.0.0"},"policyType":{"name":"onap.policies.Naming","version":"1.0.0"},"deploy":true,"state":"SUCCESS"}] + +Check number of policies deployed + +.. code-block:: bash + + curl -k --user 'policyadmin:zb!XztG34' http://{POLICY_PAP_IP}:6969/policy/pap/v1/policies/deployed + +Expected success-count result + +.. code-block:: json + + [{"policy-type":"onap.policies.native.Apex","policy-type-version":"1.0.0","policy-id":"operational.apex.sampledomain","policy-version":"1.0.0","success-count":1,"failure-count":0,"incomplete-count":0},{"policy-type":"onap.policies.Naming","policy-type-version":"1.0.0","policy-id":"SDNC_Policy.ONAP_NF_NAMING_TIMESTAMP","policy-version":"1.0.0","success-count":1,"failure-count":0,"incomplete-count":0}] + +Or download & execute the steps in postman collection for verifying policy-pap component. +The steps needs to be performed sequentially one after another. And no input is required from user. + +`Policy Framework Administration API <https://github.com/onap/policy-pap/blob/master/postman/pap-api-collection.json>`_ + +Make sure to execute the delete steps in order to clean the setup after testing. diff --git a/docs/development/devtools/images/message-commissioning-participant.png b/docs/development/devtools/images/message-commissioning-participant.png Binary files differnew file mode 100644 index 00000000..82957848 --- /dev/null +++ b/docs/development/devtools/images/message-commissioning-participant.png diff --git a/docs/development/devtools/policy-gui-controlloop-smoke.rst b/docs/development/devtools/policy-gui-acm-smoke.rst index aa319651..8070204c 100644 --- a/docs/development/devtools/policy-gui-controlloop-smoke.rst +++ b/docs/development/devtools/policy-gui-acm-smoke.rst @@ -1,20 +1,20 @@ .. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. _clamp-gui-controlloop-smoke-tests: +.. _clamp-gui-acm-smoke-tests: CLAMP GUI Smoke Tests --------------------------- 1. Introduction *************** -The CLAMP GUI for Control Loops is designed to provide a user the ability to interact -with the Control Loop Runtime to perform several actions. +The CLAMP GUI for Automation Compositions is designed to provide a user the ability to interact +with the Automation Composition Runtime to perform several actions. - Commission new Tosca Service Templates. - Editing Common Properties. - Decommission existing Tosca Service Templates. -- Create new instances of Control Loops. -- Change the state of the Control Loops. -- Delete Control Loops. +- Create new instances of Automation Compositions. +- Change the state of the Automation Compositions. +- Delete Automation Compositions. This document will serve as a guide to do smoke tests on the different components that are involved when working with the GUI and outline how they operate. It will also show a developer how to set up their environment for carrying out smoke tests on the GUI. @@ -56,7 +56,7 @@ In this setup guide, we will be setting up all the components technically requir ^^^^^^^^^^^^^^^^^^^ We will be using Docker to run our mariadb instance. It will have a total of three databases running in it. -- controlloop: the runtime-controlloop db +- acm: the clampacm db - cldsdb4: the clamp backend db - policyadmin: the policy-api db @@ -69,16 +69,16 @@ The easiest way to do this is to perform a small alteration on an SQL script pro DROP USER 'clds'; CREATE USER 'clds'; GRANT ALL on cldsdb4.* to 'clds' identified by 'sidnnd83K' with GRANT OPTION; - CREATE DATABASE `controlloop`; - USE `controlloop`; + CREATE DATABASE `clampacm`; + USE `clampacm`; DROP USER 'policy'; CREATE USER 'policy'; - GRANT ALL on controlloop.* to 'policy' identified by 'P01icY' with GRANT OPTION; + GRANT ALL on clampacm.* to 'policy' identified by 'P01icY' with GRANT OPTION; CREATE DATABASE `policyadmin`; USE `policyadmin`; DROP USER 'policy_user'; CREATE USER 'policy_user'; - GRANT ALL on controlloop.* to 'policy_user' identified by 'policy_user' with GRANT OPTION; + GRANT ALL on clampacm.* to 'policy_user' identified by 'policy_user' with GRANT OPTION; FLUSH PRIVILEGES; Once this has been done, we can run the bash script provided here: "runtime/extra/bin-for-dev/start-db.sh" @@ -157,7 +157,7 @@ Next, navigate to the "/main" directory. You can then run the following command 2.3.6 Clamp Backend ^^^^^^^^^^^^^^^^^^^ -The Clamp Backend can potentially make calls to policy pap, policy api, cds, sdc and others. For controlloop development purposes, we only need to connect with the controlloop runtime api. For convenience, there has been an emulator provided to respond to requests from Clamp to all those services that we do not care about. This emulator can be run by running the following bash script "runtime/extra/bin-for-dev/start-emulator.sh" +The Clamp Backend can potentially make calls to policy pap, policy api, cds, sdc and others. For acm development purposes, we only need to connect with the acm runtime api. For convenience, there has been an emulator provided to respond to requests from Clamp to all those services that we do not care about. This emulator can be run by running the following bash script "runtime/extra/bin-for-dev/start-emulator.sh" .. code-block:: bash @@ -169,19 +169,19 @@ Once the emulator is running, we can then run the clamp backend. Before doing th ./start-backend.sh -Once the clamp backend is running, we can start the controlloop runtime. +Once the clamp backend is running, we can start the acm runtime. -2.3.7 Controlloop Runtime -^^^^^^^^^^^^^^^^^^^^^^^^^ -To start the controlloop runtime we need to go the "runtime-controlloop" directory in the clamp repo. There is a config file that is used, by default, for the controlloop runtime. That config file is here: "src/main/resources/application.yaml". For development in your local environment, it shouldn't need any adjustment and we can just run the controlloop runtime with: +2.3.7 Automation Composition Runtime +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +To start the acm runtime we need to go the "runtime-acm" directory in the clamp repo. There is a config file that is used, by default, for the acm runtime. That config file is here: "src/main/resources/application.yaml". For development in your local environment, it shouldn't need any adjustment and we can just run the acm runtime with: .. code-block:: bash mvn spring-boot:run -2.3.8 Controlloop GUI -^^^^^^^^^^^^^^^^^^^^^ -At this point, all of the components required to test out the controlloop gui are running.We can start to make changes, and have those changes reflected in the UI for immediate feedback on our changes. But first, we must run the GUI. +2.3.8 Automation Composition GUI +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +At this point, all of the components required to test out the acm gui are running.We can start to make changes, and have those changes reflected in the UI for immediate feedback on our changes. But first, we must run the GUI. Firstly, go to the GUI repo and navigate to "gui-clamp/ui-react". To setup for development, we must install the dependencies of the GUI. We can do this using the npm package manager. In the directory, simply run: @@ -224,7 +224,7 @@ This confirms that commissioning has been complete. 3.2 Edit Common Properties ========================== -At this stage we can edit the common properties. These properties will be common to all instances of the control loop definitions we uploaded with the tosca service template. Once an instance is created, we will not be able to alter these common properties again. We can simply click on "Edit Common Properties" in the dropdown menu and we will be taken to the modal shown below. +At this stage we can edit the common properties. These properties will be common to all instances of the automation composition definitions we uploaded with the tosca service template. Once an instance is created, we will not be able to alter these common properties again. We can simply click on "Edit Common Properties" in the dropdown menu and we will be taken to the modal shown below. .. image:: images/gui/CommonPropertiesModal.png @@ -232,8 +232,8 @@ The arrows to the left of the modal can be used to expand and contract the eleme .. image:: images/gui/ViewEditedCommonProperties.png -3.3 Create New Instances of Control Loops -========================================= +3.3 Create New Instances of Automation Compositions +=================================================== Once the template is commissioned, we can start to create instances. In the dropdown, click on "Instantiation Management". In the modal, you will see an empty table, as shown. .. image:: images/gui/ManageInstancesModal.png |
