Merge "Update docs The CLAMP Automation Composition Runtime"

1 files changed, 136 insertions, 104 deletions

diff --git a/docs/clamp/acm/design-impl/clamp-runtime-acm.rst b/docs/clamp/acm/design-impl/clamp-runtime-acm.rst
index 3e99ed1d..ba5ffe33 100644
--- a/docs/clamp/acm/design-impl/clamp-runtime-acm.rst
+++ b/docs/clamp/acm/design-impl/clamp-runtime-acm.rst
@@ -13,93 +13,133 @@ 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)
+- Broadcast message: a message for all participants (participantId=null)
+- Message to a participant: a message only for a participant (participantId 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
+- Message Broker: supported message Broker are DMaap and Strimzi-Kafka
 
 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
+Check CLAMP Runtime and Participants
+++++++++++++++++++++++++++++++++++++
+- GUI calls GET "/onap/policy/clamp/acm/health" endpoint and receives the "UP" status as response
+- GUI calls GET "/onap/policy/clamp/acm/v2/participants" endpoint and receives all participants registered with supported Element Types as response
+
+Order an immediate Participant Report from all participants
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+- GUI calls PUT "/onap/policy/clamp/acm/v2/participants" endpoint
 - 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)
+- It triggers the execution to send a broadcast PARTICIPANT_STATUS_REQ message
 
-Delete of a Automation Composition Type
-+++++++++++++++++++++++++++++++++++++++
-- GUI calls DELETE "/commission" endpoint
+Create of a Automation Composition Definition Type
+++++++++++++++++++++++++++++++++++++++++++++++++++
+- GUI calls POST "/onap/policy/clamp/acm/v2/compositions" endpoint with a Automation Composition Type Definition (Tosca Service Template) as body
 - 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
+- It validates the Automation Composition Type Definition
+- It saves to DB the Tosca Service Template using AcDefinitionProvider with new compositionId and COMMISSIONED status
+- the Rest-Api call returns the compositionId generated and the list of Element Definition Type
 
-Create of a Automation Composition
-++++++++++++++++++++++++++++++++++
-- GUI calls POST "/instantiation" endpoint with a Automation Composition as body
+Update of a Automation Composition Definition Type
+++++++++++++++++++++++++++++++++++++++++++++++++++
+- 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
+- runtime-ACM receives the call by Rest-Api (CommissioningController)
+- It checks that Automation Composition Type Definition is in COMMISSIONED status
+- It validates the Automation Composition Type Definition
+- It updates to DB the Tosca Service Template using AcDefinitionProvider using the compositionId
+- the Rest-Api call returns the compositionId and the list of Element Definition Type
+
+Priming of a Automation Composition Definition Type
++++++++++++++++++++++++++++++++++++++++++++++++++++
+- GUI calls POST "/onap/policy/clamp/acm/v2/compositions/{compositionId}" endpoint with PRIME as primeOrder
+- runtime-ACM receives the call by Rest-Api (CommissioningController)
+- It checks that Automation Composition Type Definition is in COMMISSIONED status
+- It validates and update the AC Element Type Definition with supported Element Types by participants
+- It updates AC Definition to DB with PRIMING as status
+- It triggers the execution to send a broadcast PARTICIPANT_PRIME message
+- the message is built by ParticipantPrimePublisher using Tosca Service Template data
+
+Create of a Automation Composition Instance
++++++++++++++++++++++++++++++++++++++++++++
+- 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
 - 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
+- It validates the AC Instance and checks that the related composition has COMMISSIONED as status
+- It set the related participantId into the AC Element Instance using the participantId defined in AC Element Type Definition
+- It saves the Automation Composition to DB with UNDEPLOYED deployState and NONE lockState
+- the Rest-Api call returns the instanceId and the list of AC Element Instance
+
+Update of a Automation Composition Instance
++++++++++++++++++++++++++++++++++++++++++++
+- 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
 - runtime-ACM receives the call by Rest-Api (InstantiationController)
-- It validates the Automation Composition
-- It saves the Automation Composition to DB
+- It checks that AC Instance is in UNDEPLOYED deployState
+- It updates the Automation Composition to DB
+- the Rest-Api call returns the instanceId and the list of AC Element Instance
 
-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 AC instance to change status
++++++++++++++++++++++++++++++++++++
 
-"issues Automation Composition commands to Automation Compositions"
-+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+case **deployOrder: DEPLOY**
 
-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)
+- GUI calls "/onap/policy/clamp/acm/v2/compositions/{compositionId}/instances/{instanceId}" endpoint with DEPLOY as deployOrder
+- runtime-ACM receives the call by Rest-Api (InstantiationController)
+- It validates the status order issued (related AC Instance has UNDEPLOYED as deployState)
+- It updates the AC Instance to DB with DEPLOYING deployState
+- It triggers the execution to send a broadcast AUTOMATION_COMPOSITION_DEPLOY message
+- the message is built by AutomationCompositionDeployPublisher using Tosca Service Template data and Instance data. (with startPhase = first startPhase)
 
-case **PASSIVE to UNINITIALISED**
+case **lockOrder: UNLOCK**
 
-- 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
+- GUI calls "/onap/policy/clamp/acm/v2/compositions/{compositionId}/instances/{instanceId}" endpoint with UNLOCK as lockOrder
+- runtime-ACM receives the call by Rest-Api (InstantiationController)
+- It validates the status order issued (related AC Instance has DEPLOYED as deployState and LOCK as lockOrder)
+- It updates the AC Instance to DB with LOCKING lockOrder
 - 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)
+- the message is built by AutomationCompositionStateChangePublisher using Instance data. (with startPhase = first startPhase)
 
-case **PASSIVE to RUNNING**
+case **lockOrder: LOCK**
 
-- 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
+- GUI calls "/onap/policy/clamp/acm/v2/compositions/{compositionId}/instances/{instanceId}" endpoint with LOCK as lockOrder
+- runtime-ACM receives the call by Rest-Api (InstantiationController)
+- It validates the status order issued (related AC Instance has DEPLOYED as deployState and UNLOCK as lockOrder)
+- It updates the AC Instance to DB with UNLOCKING lockOrder
 - 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)
+- the message is built by AutomationCompositionStateChangePublisher using Instance data. (with startPhase = last StartPhase)
 
-case **RUNNING to PASSIVE**
+case **deployOrder: UNDEPLOY**
 
-- 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
+- GUI calls "/onap/policy/clamp/acm/v2/compositions/{compositionId}/instances/{instanceId}" endpoint with UNDEPLOY as deployOrder
+- runtime-ACM receives the call by Rest-Api (InstantiationController)
+- It validates the status order issued (related AC Instance has DEPLOYED as deployState and LOCK as lockOrder)
+- It updates the AC Instance to DB with UNDEPLOYING deployState
 - 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)
+- the message is built by AutomationCompositionStateChangePublisher using Instance data. (with startPhase = last StartPhase)
+
+Delete of a Automation Composition Instance
++++++++++++++++++++++++++++++++++++++++++++
+- GUI calls DELETE "/onap/policy/clamp/acm/v2/compositions/{compositionId}/instances/{instanceId}" endpoint
+- runtime-ACM receives the call by Rest-Api (InstantiationController)
+- It checks that AC Instance is in UNDEPLOYED deployState
+- It deletes the AC Instance from DB
+
+Depriming of a Automation Composition Definition Type
++++++++++++++++++++++++++++++++++++++++++++++++++++++
+- GUI calls POST "/onap/policy/clamp/acm/v2/compositions/{compositionId}" endpoint with DEPRIME as primeOrder
+- runtime-ACM receives the call by Rest-Api (CommissioningController)
+- It checks that Automation Composition Type Definition is in PRIMED status
+- It updates AC Definition to DB with DEPRIMING as status
+- It triggers the execution to send a broadcast PARTICIPANT_PRIME message
+- the message is built by ParticipantPrimePublisher using Tosca Service Template data
+
+Delete of a Automation Composition Definition Type
+++++++++++++++++++++++++++++++++++++++++++++++++++
+- GUI calls DELETE "/onap/policy/clamp/acm/v2/compositions/{compositionId}" endpoint
+- runtime-ACM receives the call by Rest-Api (CommissioningController)
+- It checks that AC Definition Type is in COMMISSIONED status
+- It deletes the Automation Composition Type from DB
 
 StartPhase
 **********
@@ -137,80 +177,72 @@ Example where it could be used:
     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.
+In state changes from UNDEPLOYED → DEPLOYED or LOCKED → UNLOCKED, 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
+Example of DEPLOY order 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
+- runtime-ACM sends a broadcast AUTOMATION_COMPOSITION_DEPLOY message to all participants with startPhase = 0
+- participant receives the AUTOMATION_COMPOSITION_DEPLOY message and runs to DEPLOYED state (only AC elements defined as startPhase = 0)
+- runtime-ACM receives AUTOMATION_COMPOSITION_DEPLOY_ACK messages from participants and set the state (from the AC element of the message) to DEPLOYED
+- 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
+- participant receives the AUTOMATION_COMPOSITION_DEPLOY message and runs to DEPLOYED state (only AC elements defined as startPhase = 1)
+- runtime-ACM receives AUTOMATION_COMPOSITION_DEPLOY_ACK messages from participants and set the state (from the AC element of the message) to DEPLOYED
+- runtime-ACM calculates that all AC elements are set to proper state and set AC to DEPLOYED
 
-In that scenario the message AUTOMATION_COMPOSITION_UPDATE has been sent two times.
+In that scenario the message AUTOMATION_COMPOSITION_DEPLOY 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 starts and send a PARTICIPANT_REGISTER message with participantId and supported Element Types
+- runtime-ACM collects the message from Message Broker by ParticipantRegisterListener
+- if not present, it saves participant reference with status ON_LINE to DB
+
+PARTICIPANT_PRIME_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
+- A participant sends PARTICIPANT_PRIME_ACK message in response to a PARTICIPANT_PRIME message
+- ParticipantPrimeAckListener collects the message from Message Broker
+- It updates AC Definition to DB with PRIMED/DEPRIMED as status
 
 PARTICIPANT_STATUS
 ++++++++++++++++++
-- A participant sends a scheduled PARTICIPANT_STATUS message
-- ParticipantStatusListener collects the message from DMaap
+- A participant sends a scheduled PARTICIPANT_STATUS message with participantId and supported Element Types
+- runtime-ACM collects the message from Message Broker by ParticipantStatusListener
+- if not present, it saves participant reference with status ON_LINE to DB
 - 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
+AUTOMATION_COMPOSITION_DEPLOY_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
+- 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
+- AutomationCompositionUpdateAckListener collects the message from Message Broker
+- It checks the status of all Automation Composition elements and checks if the Automation Composition is fully DEPLOYED
+- It updates the AC to DB
 - 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
+- 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
+- AutomationCompositionStateChangeAckListener collects the message from Message Broker
+- It checks the status of all Automation Composition elements and checks if the transition process of the Automation Composition is terminated
+- It updates the AC to DB
+- MessageIntercept intercepts that event and adds a task to handle a monitoring execution in SupervisionScanner
 
 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
+- to determine the next startPhase in a AUTOMATION_COMPOSITION_DEPLOY message
+- 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
+- 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
+- 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
 
 The solution Design of retry, timeout, and reporting for all Participant message dialogues are implemented into the monitoring execution.