diff options
Diffstat (limited to 'docs')
21 files changed, 326 insertions, 467 deletions
diff --git a/docs/clamp/acm/api-protocol/acm-participant-protocol.rst b/docs/clamp/acm/api-protocol/acm-participant-protocol.rst index 449e2096..2dae2b00 100644 --- a/docs/clamp/acm/api-protocol/acm-participant-protocol.rst +++ b/docs/clamp/acm/api-protocol/acm-participant-protocol.rst @@ -5,7 +5,7 @@ The ACM Automation Composition Participant Protocol ################################################### -The CLAMP Automation Composition protocol is an asynchronous protocol that is used by the CLAMP +The ACM Automation Composition protocol is an asynchronous protocol that is used by the ACM runtime to coordinate lifecycle management of Automation Composition instances. The protocol supports the functions described in the sections below. @@ -18,32 +18,42 @@ The protocol supports the dialogues described below. Participant Registration and De-Registration -------------------------------------------- -Registration when a participant comes up and update of participant with Automation Composition type -information and common parameter values for its Automation Composition types. +Participant Registration is performed by a Participant when it starts up. It registers its ID and the ACM Element Types it supports with the ACM runtime. -.. image:: ../images/acm-participants-protocol/participant-registering.png +.. image:: ../images/system-dialogues/RegisterParticipant.png -De-registration is executed as a participant goes down. +Participant Deregistration is performed by a Participant when it shuts down. It deregisters its ID and type with the ACM runtime. The participant should already have cleared down all its' ACM Element instances and set their states to “Not In Service”. -.. image:: ../images/acm-participants-protocol/participant-deregistration.png +.. image:: ../images/system-dialogues/DeregisterParticipant.png Automation Composition Priming and De-Priming --------------------------------------------- -When an 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. +The Priming operation sends Automation Composition Types and common property values to participants for each Automation Composition Element Type in the Automation Composition Type. The ParticipantPrime message type is sent to trigger priming and depriming in participants in participants -.. image:: ../images/acm-participants-protocol/acm-priming.png +.. image:: ../images/system-dialogues/PrimeAcTypeOnPpnts.png -When an 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. +A participant should respond for each Automation Composition Element Type, thus causing the full Automation Composition Type to become primed. Note that if more than one participant can support an Automation Composition Element Type the ACM Runtime uses the participant in the first response it receives for that Automation Composition Element Type. -.. image:: ../images/acm-participants-protocol/acm-depriming.png +.. image:: ../images/system-dialogues/PrimeAcTypeMultiplePpnts.png +The ACM Runtime updates the priming information in the database. + +.. image:: ../images/system-dialogues/PrimeInfoUpdatedInDb.png + +The Depriming operation removes Automation Composition Types and common property values on participants for each Automation Composition Element Type in the Automation Composition Type. + +.. image:: ../images/system-dialogues/DeprimeOnParticipants.png + +A participant should respond for each Automation Composition Element Type, thus causing the full Automation Composition Type to become deprimed. + +.. image:: ../images/system-dialogues/DeprimeElements.png + +The ACM Runtime updates the priming information in the database. + +.. image:: ../images/system-dialogues/UpdateDeprimeInDb.png Automation Composition Update ----------------------------- @@ -72,26 +82,28 @@ The *startPhase* in the `Definition of TOSCA fundamental Automation Composition <https://github.com/onap/policy-clamp/blob/master/common/src/main/resources/tosca/AutomationCompositionTOSCAServiceTemplateTypes.yaml>`_ is particularly important in Automation Composition state changes because sometimes the user wishes to control the order in which the state changes in Automation Composition Elements in an Automation -Composition. In-state changes from *UNITITIALISED → PASSIVE* and from *PASSIVE → RUNNING*, +Composition. In-state changes from *UNDEPLOYED → DEPLOYED*, Automation Composition elements are started in increasing order of their startPhase. In-state -changes from *RUNNING → PASSIVE* and from *PASSIVE → UNITITIALISED*, Automation Composition +changes from *DEPLOYED → UNDEPLOYED*, Automation Composition elements are started in decreasing order of their *startPhase*. -The CLAMP runtime controls the state change process described in the diagram below. The CLAMP -runtime sends an Automation Composition state change message on DMaaP to all participants in a +The ACM runtime controls the state change process described in the diagram below. The ACM +runtime sends an Automation Composition state change message on the messaging system (e.g. Kafka) to all participants in a particular start phase so, in each state change multiple Automation Composition State Change messages are sent, one for each start phase in the Automation Composition. If more than one Automation Composition Element has the same start phase, those Automation Composition Elements -receive the same Automation Composition State Change message from DMaaP and start in parallel. +receive the same Automation Composition State Change message from Kafka and start in parallel. -The Participant reads each State Change Message it sees on DMaaP. If the start phase on the +The Participant reads each State Change Message it sees on Kafka. If the start phase on the Automation Composition State Change message matches the Start Phase of the Automation Composition Element, the participant processes the state change message. Otherwise, the participant ignores the message. .. image:: ../images/acm-participants-protocol/acm-state-change.png -The handling of an ACMStateChange message in each participant is as shown below. +The flow of the DEPLOY/UNDEPLOY state change messages are shown below. But the same flow is true for LOCK/UNLOCK + +.. note:: More details of the state machine are available on :ref:`ACM States <acm-states-label>` .. image:: ../images/acm-participants-protocol/acm-state-change-msg.png @@ -115,369 +127,9 @@ see the `CLAMP code at Github <https://github.com/onap/policy-clamp/tree/master/models/src/main/java/org/onap/policy/clamp/models/acm/messages/dmaap/participant>`_ . All messages are carried on DMaaP. - -.. list-table:: - :widths: 15 10 10 15 15 35 - :header-rows: 1 - - * - Message - - Source - - Target - - Purpose - - Important Fields - - Field Descriptions - * - ParticipantRegister - - Participant - - CLAMP Runtime - - Participant registers with the CLAMP runtime - - ParticipantId - - The ID of this participant - * - - - - - - - - - ParticipantType - - The type of the participant; maps to the capabilities of the participant in Automation - Composition Type Definitions - * - ParticipantRegisterAck - - CLAMP Runtime - - Participant - - Acknowledgment of Participant Registration - - ParticipantId - - The ID of this participant - * - - - - - - - - - ParticipantType - - The type of the participant; maps to the capabilities of the participant in Automation - Composition Type Definitions - * - - - - - - - - - Result - - Success/Fail - * - - - - - - - - - Message - - A message indicating the reason for failure - * - ParticipantUpdate - - CLAMP Runtime - - Participant - - CLAMP Runtime sends Automation Composition Element Definitions and Common Parameter Values - to Participants - - ParticipantDefinitionUpdateMap - - Map with Participant ID as its key, each value on the map is an ACMElementDefintionMap - * - - - - - - - - - ACMElementDefintionMap - - List of ACMElementDefinition values for a particular participant, keyed by its Automation - Composition Element Definition ID - * - - - - - - - - - ACMElementDefinition - - An ACMElementToscaServiceTemplate containing the definition of the Automation Composition - Element and a CommonPropertiesMap with the values of the common property values for - Automation Composition Elements of this type - * - - - - - - - - - ACMElementToscaServiceTemplate - - The definition of the Automation Composition Element in TOSCA - * - - - - - - - - - CommonPropertiesMap - - A <String, String> map indexed by the property name. Each map entry is the serialized value - of the property, which can be deserialized into an instance of the type of the property. - * - ParticipantUpdateAck - - Participant - - CLAMP Runtime - - Acknowledgment of Participant Update - - ParticipantId - - The ID of this participant - * - - - - - - - - - ParticipantType - - The type of the participant; maps to the capabilities of the participant in Automation - Composition Type Definitions - * - - - - - - - - - Result - - Success/Fail - * - - - - - - - - - Message - - A message indicating the reason for failure - * - ParticipantDeregister - - Participant - - CLAMP Runtime - - Participant deregisters with the CLAMP runtime - - ParticipantId - - The ID of this participant - * - - - - - - - - - ParticipantType - - The type of the participant; maps to the capabilities of the participant in Automation - Composition Type Definitions - * - ParticipantDeregisterAck - - CLAMP Runtime - - Participant - - Acknowledgment of Participant Deegistration - - ParticipantId - - The ID of this participant - * - - - - - - - - - ParticipantType - - The type of the participant; maps to the capabilities of the participant in Automation - Composition Type Definitions - * - - - - - - - - - Result - - Success/Fail - * - - - - - - - - - Message - - A message indicating the reason for failure - * - ACMUpdate - - CLAMP Runtime - - Participant - - CLAMP Runtime sends Automation Composition Element instances and Instance Specific Parameter - Values for an Automation Composition Instance to Participants - - ACMId - - The name and version of the Automation Composition - * - - - - - - - - - ParticipantUpdateMap - - Map with Participant ID as its key, each value on the map is an ACMElementList - * - - - - - - - - - ACMElementList - - List of ACMElement values for the Automation Composition - * - - - - - - - - - ACMElement - - An ACMElement, which contains among other things a PropertiesMap with the values of the - property values for this Automation Composition Element instance and a - ToscaServiceTemplateFragment with extra concept definitions and instances that a participant - may need. - * - - - - - - - - - PropertiesMap - - A <String, String> map indexed by the property name. Each map entry is the serialized value - of the property, which can be deserialized into an instance of the type of the property. - * - - - - - - - - - ToscaServiceTemplateFragment - - A well-formed TOSCA service template containing extra concept definitions and instances that - a participant may need. For example, the Policy Participant may need policy type definitions - or policy instances to be provided if they are not already stored in the Policy Framework. - * - ACMUpdateAck - - Participant - - CLAMP Runtime - - Acknowledgment of Automation Composition Update - - ParticipantId - - The ID of this participant - * - - - - - - - - - ParticipantType - - The type of the participant; maps to the capabilities of the participant in Automation - Composition Type Definitions - * - - - - - - - - - ACMId - - The name and version of the Automation Composition - * - - - - - - - - - ACMResult - - Holds a Result and Message for the overall operation on the participant and a map of Result - and Message fields for each Automation Composition Element of the Automation Composition on - this participant - * - - - - - - - - - Result - - Success/Fail - * - - - - - - - - - Message - - A message indicating the reason for failure - * - ACMStateChange - - CLAMP Runtime - - Participant - - CLAMP Runtime asks Participants to change the state of an Automation Composition - - ACMId - - The name and version of the Automation Composition - * - - - - - - - - - currentState - - The current state of the Automation Composition - * - - - - - - - - - orderedState - - The state that the Automation Composition should transition to - * - - - - - - - - - startPhase - - The start phase to which this ACMStateChange message applies - * - ACMStateChangeAck - - Participant - - CLAMP Runtime - - Acknowledgment of Automation Composition State Change - - ParticipantId - - The ID of this participant - * - - - - - - - - - ParticipantType - - The type of the participant; maps to the capabilities of the participant in Automation - Composition Type Definitions - * - - - - - - - - - ACMId - - The name and version of the Automation Composition - * - - - - - - - - - startPhase - - The start phase to which this ACMStateChangeAck message applies - * - - - - - - - - - ACMResult - - Holds a Result and Message for the overall operation on the participant and a map of Result - and Message fields for each Automation Composition Element of the Automation Composition on - this participant - * - - - - - - - - - Result - - Success/Fail - * - - - - - - - - - Message - - A message indicating the reason for failure - * - ParticipantStatusReq - - CLAMP Runtime - - Participant - - Request that the specified participants return a ParticipantStatus message immediately - - ParticipantId - - The ID of this participant, if not specified, all participants respond. - * - ParticipantStatus - - Participant - - CLAMP Runtime - - Periodic or on-demand report for heartbeat, Participant Status, Automation Composition - Status, and Automation Composition Statistics - - ParticipantId - - The ID of this participant - * - - - - - - - - - ParticipantType - - The type of the participant; maps to the capabilities of the participant in Automation - Composition Type Definitions - * - - - - - - - - - ParticipantDefinitionUpdateMap (returned in repsonse to ParticipantStatusReq only) - - See ParticipantUpdate message above for definition of this field - * - - - - - - - - - ParticipantStatus - - The current status of the participant for monitoring - * - - - - - - - - - ParticipantStatistics - - Statistics on the participant such as uptime, or messages processed. Can include participant - specific data in a string blob that is opaque to CLAMP - * - - - - - - - - - ACMInfoMap - - A map of ACMInfo types indexed by ACMId, one entry for each Automation Composition - running on the participant - * - - - - - - - - - ACMInfo - - The ACMStatus and ACMStatistics for a given Automation Composition - * - - - - - - - - - ACMStatus - - The current status of the Automation Composition for monitoring - * - - - - - - - - - ACMStatistics - - Statistics on the Automation Composition such as uptime, or messages processed. Can include - participant specific data in a string blob that is opaque to CLAMP +.. csv-table:: ACM Messages + :file: ../files/ACM-Message-Table.csv + :header-rows: 1 End of Document diff --git a/docs/clamp/acm/api-protocol/puml/ParticipantDepriming.puml b/docs/clamp/acm/api-protocol/puml/ParticipantDepriming.puml new file mode 100644 index 00000000..589e2cc3 --- /dev/null +++ b/docs/clamp/acm/api-protocol/puml/ParticipantDepriming.puml @@ -0,0 +1,11 @@ +@startuml +Commissioning_REST -> CLAMP_Runtime: De-Prime Automation Composition Type Definition +alt Automation Composition Instances exist for Automation Composition Type + Commissioning_REST <- CLAMP_Runtime: Cannot decommission Automation Composition Type Definition +else No Automation Composition Instances exist for Automation Composition Type + Participant <- CLAMP_Runtime: Participant Update\n[Remove Automation Composition Element Definitions\nfrom Participants in Automation Composition] + activate Participant + Participant -> Participant: Delete Automation Composition Element\nType Definitions and\nCommon Property Values + Participant -> CLAMP_Runtime: Participant Update Ack [from each Participant mentioned in Participant Update message] + deactivate Participant +@enduml diff --git a/docs/clamp/acm/api-protocol/puml/ParticipantDeregister.puml b/docs/clamp/acm/api-protocol/puml/ParticipantDeregister.puml new file mode 100644 index 00000000..8b6a18ea --- /dev/null +++ b/docs/clamp/acm/api-protocol/puml/ParticipantDeregister.puml @@ -0,0 +1,5 @@ +@startuml +Participant -> CLAMP_Runtime: Participant Deregistration +Participant <- CLAMP_Runtime: Participant Deregistration Ack +Participant -> Participant: Shutdown Participant +@enduml diff --git a/docs/clamp/acm/api-protocol/puml/ParticipantHandleStateChange.puml b/docs/clamp/acm/api-protocol/puml/ParticipantHandleStateChange.puml new file mode 100644 index 00000000..8429c227 --- /dev/null +++ b/docs/clamp/acm/api-protocol/puml/ParticipantHandleStateChange.puml @@ -0,0 +1,52 @@ +@startuml + +(*) --> "Process State Change Message" + +if "All Automation Composition Elements with my Participant ID processed?" then + --> [yes] "Send State Change Ack Message" + --> (*) +else + --> [no] "Process next Automation Composition Element with my ID" + if "State Change Message Start Phase equals Automation Composition Element start phase" then + [true] if "Current State is DEPLOYED?" then + [true] if "Change to UNDEPLOYED?" then + --> [true] "Change Automation Composition Element to state UNDEPLOYED" + --> "Wait for DEPLOYED->UNDEPLOYED State Change to complete" + if "State Change?" then + --> [success] "Record Success for State Change Ack message" + --> "Process State Change Message" + else + --> [fail] "Record Error for State Change Ack message" + --> "Process State Change Message" + endif + else + --> [false] "Record Error for State Change Ack message" + --> "Process State Change Message" + endif + else + [false] if "Current State is UNDEPLOYED?" then + [true] if "Change to DEPLOYED?" then + --> [true] "Change Automation Composition Element to state DEPLOYED" + --> "Wait for UNDEPLOYED->DEPLOYED State Change to complete" + if "State Change?" then + --> [success] "Record Success for State Change Ack message" + --> "Process State Change Message" + else + --> [fail] "Record Error for State Change Ack message" + --> "Process State Change Message" + endif + else + --> [false] "Record Error for State Change Ack message" + --> "Process State Change Message" + endif + else + --> [false] "Record Error for State Change Ack message" + --> "Process State Change Message" + endif + endif + else + --> [false] "Skip Automation Composition Element" + --> "Process State Change Message" +endif + +@enduml diff --git a/docs/clamp/acm/api-protocol/puml/ParticipantMonitoring.puml b/docs/clamp/acm/api-protocol/puml/ParticipantMonitoring.puml new file mode 100644 index 00000000..24f25d7c --- /dev/null +++ b/docs/clamp/acm/api-protocol/puml/ParticipantMonitoring.puml @@ -0,0 +1,3 @@ +@startuml +Participant -> CLAMP_Runtime: Participant Status [periodically from each Participant in all Automation Compositions] +@enduml diff --git a/docs/clamp/acm/api-protocol/puml/ParticipantPriming.puml b/docs/clamp/acm/api-protocol/puml/ParticipantPriming.puml new file mode 100644 index 00000000..064f913e --- /dev/null +++ b/docs/clamp/acm/api-protocol/puml/ParticipantPriming.puml @@ -0,0 +1,13 @@ +@startuml +Commissioning_REST -> CLAMP_Runtime: Prime Automation Composition Type Defintions and\nset values of Common Properties +activate CLAMP_Runtime +loop over Participant Types in Automation Composition Type Definition + CLAMP_Runtime -> CLAMP_Runtime: Collect Automation Composition Element Type Definitions and\nCommon Property Values for Participant Type +end +Participant <- CLAMP_Runtime: Participant Update\n[Automation Composition Element Type Definitions and\nCommon Property Values for Participant Types] +deactivate CLAMP_Runtime +activate Participant +Participant -> Participant: Store Automation Composition Element Type Definitions and\nCommon Property Values +Participant -> CLAMP_Runtime: Participant Update Ack\n[from each Participant mentioned in Participant Update message] +deactivate Participant +@enduml diff --git a/docs/clamp/acm/api-protocol/puml/ParticipantRegister.puml b/docs/clamp/acm/api-protocol/puml/ParticipantRegister.puml new file mode 100644 index 00000000..af42d571 --- /dev/null +++ b/docs/clamp/acm/api-protocol/puml/ParticipantRegister.puml @@ -0,0 +1,17 @@ +@startuml +activate Participant +Participant -> Participant: Start Participant +deactivate Participant +Participant -> CLAMP_Runtime: Participant Registration +Participant <- CLAMP_Runtime: Participant Registration Ack +activate CLAMP_Runtime +loop over Automation Composition Type Definitions + CLAMP_Runtime -> CLAMP_Runtime: Collect Automation Composition Element Type Definitions and\nCommon Property Values for\nParticipant Type of this Participant +end +deactivate CLAMP_Runtime +Participant <- CLAMP_Runtime: Participant Update\n[Automation Composition Element Type Definitions and\nCommon Property Values for\nParticipant Type of Participant] +activate Participant +Participant -> Participant: Store Automation Composition Element Type Definitions and\nCommon Property Values +Participant -> CLAMP_Runtime: Participant Update Ack +deactivate Participant +@enduml diff --git a/docs/clamp/acm/api-protocol/puml/ParticipantStateChangeDialogue.puml b/docs/clamp/acm/api-protocol/puml/ParticipantStateChangeDialogue.puml new file mode 100644 index 00000000..af8779da --- /dev/null +++ b/docs/clamp/acm/api-protocol/puml/ParticipantStateChangeDialogue.puml @@ -0,0 +1,35 @@ +@startuml + +activate CLAMP_Runtime +CLAMP_Runtime -> CLAMP_Runtime: Build an ordered list of the Start Phases in the Automation Composition Instance +deactivate CLAMP_Runtime + +alt "State Change UNDEPLOYED_to_DEPLOYED or LOCKED_to_UNLOCKED" + loop over Start Phases list in increasing order + CLAMP_Runtime -> Participant: Automation Composition State Change\n[to all Participants in Automation Composition with this Start Phase] + CLAMP_Runtime -> CLAMP_Runtime: Asynchronously wait for answers from Participants + CLAMP_Runtime <- Participant: Automation Composition State Change Ack [from each Participant in this Start Phase of Automation Composition] + alt "State Change Ack reports success" + CLAMP_Runtime -> CLAMP_Runtime: Log success + else "State Change Ack reports an error" + CLAMP_Runtime -> CLAMP_Runtime: Log error + CLAMP_Runtime -> CLAMP_Runtime: Reset state of Automation Composition CLAMP_Runtime -> CLAMP_Runtime: Abort State Change operation + end + end +else "State Change DEPLOYED_to_UNDEPLOYED or UNLOCKED_to_LOCKED" + loop over Start Phases list in decreasing order + CLAMP_Runtime -> Participant: Automation Composition State Change\n[to all Participants in Automation Composition with this Start Phase] + CLAMP_Runtime -> CLAMP_Runtime: Asynchronously wait for answers from Participants + CLAMP_Runtime <- Participant: Automation Composition State Change Ack [from each Participant in this Start Phase of Automation Composition] + alt "State Change Ack reports success" + CLAMP_Runtime -> CLAMP_Runtime: Log success + else "State Change Ack reports an error" + CLAMP_Runtime -> CLAMP_Runtime: Log error + CLAMP_Runtime -> CLAMP_Runtime: Reset state of Automation Composition CLAMP_Runtime -> CLAMP_Runtime: Abort State Change operation + end + end +end + +CLAMP_Runtime -> CLAMP_Runtime: Set overall state of Automation Composition + +@enduml diff --git a/docs/clamp/acm/api-protocol/puml/ParticipantUpdateMessage.puml b/docs/clamp/acm/api-protocol/puml/ParticipantUpdateMessage.puml new file mode 100644 index 00000000..ccf7acc9 --- /dev/null +++ b/docs/clamp/acm/api-protocol/puml/ParticipantUpdateMessage.puml @@ -0,0 +1,48 @@ +@startuml + +(*) --> "Process Update Message" + +if "All Automation Composition Elements with my Participant ID processed?" then + --> [yes] "Send Update Ack Message" + --> (*) +else + --> [no] "Process next Automation Composition Element with my ID" + if "New Automation Composition Element?" then + --> [yes] "Create Automation Composition Element" + --> "Set Automation Composition Element to state UNDEPLOYED/LOCKED" + --> "Order Deployment/Unlock of Automation Composition Element" + --> "Pass Parameters to Automation Composition Element" + --> "Wait for Deployment/Unlock to complete" + if "Automation Composition Element Deployed/Unlocked?" then + --> [success] "Record Success for Update Ack message" + --> "Process Update Message" + else + --> [fail] "Delete Automation Composition Element" + --> "Record Error for Update Ack message" + --> "Process Update Message" + endif + else + --> [no] "Check Automation Composition Element State" + endif + if "DEPLOYED/UNLOCKED and Automation Composition Version change != patch?" then + --> [true] "Record Error for Update Ack message" + --> "Process Update Message" + else + [false] if "NOT DEPLOYED/UNLOCKED and Automation Composition Version change == major?" then + --> [true] "Record Error for Update Ack message" + --> "Process Update Message" + else + --> [false] "Pass Changed Parameters to Automation Composition Element" + --> "Wait for reconfiguration to complete" + if "Automation Composition Element Reconfiguration?" then + --> [success] "Record Success for Update Ack message" + --> "Process Update Message" + else + --> [fail] "Roll back reconfiguration" + --> "Record Error for Update Ack message" + --> "Process Update Message" + endif + endif +endif + +@enduml diff --git a/docs/clamp/acm/design-impl/participants/participant-intermediary.rst b/docs/clamp/acm/design-impl/participants/participant-intermediary.rst index d9d24ceb..6ebc76f9 100644 --- a/docs/clamp/acm/design-impl/participants/participant-intermediary.rst +++ b/docs/clamp/acm/design-impl/participants/participant-intermediary.rst @@ -12,18 +12,19 @@ Automation Composition Element state. 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) - MessageSender: a class that takes care of sending messages from participant-intermediary - GUI: graphical user interface, Postman or a Front-End Application +- Message Broker: supported message Broker are DMaap and Strimzi-Kafka Inbound messages to participants -------------------------------- - PARTICIPANT_REGISTER_ACK: received as a response from clamp-acm runtime server as an acknowledgement to ParticipantRegister message sent from a participant - PARTICIPANT_DEREGISTER_ACK: received as a response from clamp-acm runtime server as an acknowledgement to ParticipantDeregister message sent from a participant - AUTOMATION_COMPOSITION_STATE_CHANGE: a message received from clamp-acm runtime server for a state change of clamp-acm -- AUTOMATION_COMPOSITION_UPDATE: a message received from clamp-acm runtime server for a clamp-acm update with clamp-acm instances -- PARTICIPANT_UPDATE: a message received from clamp-acm runtime server for a participant update with tosca definitions of clamp-acm +- AUTOMATION_COMPOSITION_DEPLOY: a message received from clamp-acm runtime server for a clamp-acm deploy with clamp-acm instances +- PARTICIPANT_PRIME: a message received from clamp-acm runtime server for a participant update with tosca definitions of clamp-acm - PARTICIPANT_STATUS_REQ: A status request received from clamp-acm runtime server to send an immediate ParticipantStatus from all participants Outbound messages @@ -32,98 +33,86 @@ Outbound messages - PARTICIPANT_DEREGISTER: is sent by a participant during shutdown - PARTICIPANT_STATUS: is sent by a participant as heartbeat with the status and health of a participant - AUTOMATIONCOMPOSITION_STATECHANGE_ACK: is an acknowledgement sent by a participant as a response to AutomationCompositionStateChange -- AUTOMATIONCOMPOSITION_UPDATE_ACK: is an acknowledgement sent by a participant as a response to AutomationCompositionUpdate -- PARTICIPANT_UPDATE_ACK: is an acknowledgement sent by a participant as a response to ParticipantUpdate +- AUTOMATION_COMPOSITION_DEPLOY_ACK: is an acknowledgement sent by a participant as a response to AutomationCompositionDeploy +- PARTICIPANT_PRIME_ACK: is an acknowledgement sent by a participant as a response to ParticipantPrime Design of a PARTICIPANT_REGISTER message ---------------------------------------- -- A participant starts and send a PARTICIPANT_REGISTER message -- ParticipantRegisterListener collects the message from DMaap -- if participant is not present in DB, it saves participant reference with status UNKNOWN to DB -- if participant is present in DB, 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) +- A participant starts and send a PARTICIPANT_REGISTER message with participantId and Supported Element Definition Types +- in AC-runtime ParticipantRegisterListener collects the message from Message Broker +- if participant is not present in DB, it saves participant reference with status ON_LINE to DB - 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 Design of a PARTICIPANT_DEREGISTER message ------------------------------------------ -- A participant starts and send a PARTICIPANT_DEREGISTER message -- ParticipantDeregisterListener collects the message from DMaap -- if participant is not present in DB, do nothing -- if participant is present in DB, it triggers the execution to send a PARTICIPANT_UPDATE message to the participant registered (message of DePriming) -- the message is built by ParticipantUpdatePublisher using Tosca Service Template data as null -- ParticipantHandler removes the tosca definitions stored -- It triggers the execution to send a PARTICIPANT_DEREGISTER_ACK message to the participant registered +- A participant is going to close and undeploys all AC-elements and send a PARTICIPANT_DEREGISTER message +- in AC-runtime, ParticipantDeregisterListener collects the message from Message Broker +- if participant has AC-elements instance, it updates with UNDEPLOYED deployStatus +- It triggers the execution to send a PARTICIPANT_DEREGISTER_ACK message to the participant deregistered - Participant is not monitored. -Design of a creation of an Automation Composition Type ------------------------------------------------------- -- If there are participants registered with CL-runtime, 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) -- Participant-intermediary will receive a PARTICIPANT_UDPATE message and stores the Tosca Service Template data on ParticipantHandler - -Design of a deletion of an Automation Composition Type ------------------------------------------------------- -- 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 Automation Composition Type from DB -- Participant-intermediary will receive a PARTICIPANT_UDPATE message and deletes the Tosca Service Template data on ParticipantHandler - -Design of a creation of an Automation Composition -------------------------------------------------- -- AUTOMATION_COMPOSITION_UPDATE message with instantiation details and UNINITIALISED state is sent to participants -- Participant-intermediary validates the current state change -- Participant-intermediary will recieve AUTOMATION_COMPOSITION_UPDATE message and sends the details of AutomationCompositionElements to participants -- Each participant performs its designated job of deployment by interacting with respective frameworks +Prime of an Automation Composition Definition Type +-------------------------------------------------- +- AC-runtime assigns the AC Definition to the participants based of Supported Element Definition Type by participant +- it triggers the execution to send a broadcast PARTICIPANT_PRIME message +- the message is built by ParticipantPrimePublisher using Tosca Service Template data (to fill the list of ParticipantDefinition) +- Participant-intermediary will receive a PARTICIPANT_PRIME message and stores the Tosca Service Template data on ParticipantHandler -Design of a deletion of an Automation Composition -------------------------------------------------- -- AUTOMATION_COMPOSITION_STATE_CHANGE message with UNINITIALISED state is sent to participants -- Participant-intermediary validates the current state change -- Participant-intermediary will recieve AUTOMATION_COMPOSITION_STATE_CHANGE message and sends the details of AutomationCompositionElements to participants -- Each participant performs its designated job of undeployment by interacting with respective frameworks +DePrime of an Automation Composition Definition Type +---------------------------------------------------- +- AC-runtime triggers the execution to send a broadcast PARTICIPANT_PRIME message +- the message is built by ParticipantPrimePublisher with an empty list of ParticipantDefinition +- Participant-intermediary will receive a PARTICIPANT_PRIME message and deletes the Tosca Service Template data on ParticipantHandler -Design of "issues automation composition commands to automation compositions" - case UNINITIALISED to PASSIVE -------------------------------------------------------------------------------------------------------------- -- AUTOMATION_COMPOSITION_STATE_CHANGE message with state changed from UNINITIALISED to PASSIVE is sent to participants -- Participant-intermediary validates the current state change -- Participant-intermediary will recieve AUTOMATION_COMPOSITION_STATE_CHANGE message and sends the details of state change to participants -- Each participant performs its designated job of state change by interacting with respective frameworks - -Design of "issues automation composition commands to automation compositions" - case PASSIVE to UNINITIALISED -------------------------------------------------------------------------------------------------------------- -- AUTOMATION_COMPOSITION_STATE_CHANGE message with state changed from PASSIVE to UNINITIALISED is sent to participants -- Participant-intermediary validates the current state change -- Participant-intermediary will recieve AUTOMATION_COMPOSITION_STATE_CHANGE message and sends the details of state change to participants -- Each participant performs its designated job of state change by interacting with respective frameworks - -Design of "issues automation composition commands to automation compositions" - case PASSIVE to RUNNING +Design of "issues automation composition commands to automation compositions" - case UNDEPLOY to DEPLOY ------------------------------------------------------------------------------------------------------- -- AUTOMATION_COMPOSITION_STATE_CHANGE message with state changed from PASSIVE to RUNNING is sent to participants -- Participant-intermediary validates the current state change -- Participant-intermediary will recieve AUTOMATION_COMPOSITION_STATE_CHANGE message and sends the details of state change to participants -- Each participant performs its designated job of state change by interacting with respective frameworks +- AUTOMATION_COMPOSITION_DEPLOY message with instantiation details and DEPLOY order state is sent to participants +- Participant-intermediary validates the current deployState change +- Participant-intermediary will receive AUTOMATION_COMPOSITION_DEPLOY message and sends the details of AutomationCompositionElements to participants +- Each participant performs its designated job of deployment by interacting with respective frameworks -Design of "issues automation composition commands to automation compositions" - case RUNNING to PASSIVE +Design of "issues automation composition commands to automation compositions" - case DEPLOY to UNDEPLOY ------------------------------------------------------------------------------------------------------- -- AUTOMATION_COMPOSITION_STATE_CHANGE message with state changed from RUNNING to PASSIVE is sent to participants -- Participant-intermediary validates the current state change -- Participant-intermediary will recieve AUTOMATION_COMPOSITION_STATE_CHANGE message and sends the details of state change to participants -- Each participant performs its designated job of state change by interacting with respective frameworks +- AUTOMATION_COMPOSITION_STATE_CHANGE message with instantiation details and UNDEPLOY order state is sent to participants +- Participant-intermediary validates the current deployState change +- Participant-intermediary will receive AUTOMATION_COMPOSITION_STATE_CHANGE message and sends AC-element details to participants +- Each participant performs its designated job of undeployment by interacting with respective frameworks + +Design of "issues automation composition commands to automation compositions" - case LOCK to UNLOCK +--------------------------------------------------------------------------------------------------- +- AUTOMATION_COMPOSITION_STATE_CHANGE message with instantiation details and UNLOCK order state is sent to participants +- Participant-intermediary validates the current lockState change +- Participant-intermediary will receive AUTOMATION_COMPOSITION_STATE_CHANGE message + +Design of "issues automation composition commands to automation compositions" - case UNLOCK to LOCK +--------------------------------------------------------------------------------------------------- +- AUTOMATION_COMPOSITION_STATE_CHANGE message with instantiation details and LOCK order state is sent to participants +- Participant-intermediary validates the current lockState change + +Design of a PARTICIPANT_STATUS_REQ message +------------------------------------------ +- AC-runtime triggers the execution to send a broadcast PARTICIPANT_STATUS_REQ message or to send it to a specific participant +- the message is built by ParticipantStatusReqPublisher +- Participant-intermediary will receive a PARTICIPANT_STATUS_REQ message Design of a PARTICIPANT_STATUS message -------------------------------------- -- A participant sends a scheduled PARTICIPANT_STATUS message +- A participant sends a scheduled PARTICIPANT_STATUS message or in response to a PARTICIPANT_STATUS_REQ message - This message will hold the state and healthStatus of all the participants running actively - PARTICIPANT_STATUS message holds a special attribute to return Tosca definitions, this attribute is populated only in response to PARTICIPANT_STATUS_REQ -Design of a AUTOMATIONCOMPOSITION_UPDATE_ACK message ----------------------------------------------------- -- A participant sends AUTOMATIONCOMPOSITION_UPDATE_ACK message in response to a AUTOMATIONCOMPOSITION_UPDATE message. -- For each CL-elements moved to the ordered state as indicated by the AUTOMATIONCOMPOSITION_UPDATE -- AutomationCompositionUpdateAckListener in CL-runtime collects the messages from DMaap -- It checks the status of all automation composition elements and checks if the automation composition is primed -- It updates the clamp-acm in DB accordingly - -Design of a AUTOMATIONCOMPOSITION_STATECHANGE_ACK is similar to the design for AUTOMATIONCOMPOSITION_UPDATE_ACK +Design of a AUTOMATION_COMPOSITION_DEPLOY_ACK message +----------------------------------------------------- +- A participant sends AUTOMATION_COMPOSITION_DEPLOY_ACK message in response to a AUTOMATION_COMPOSITION_DEPLOY message. +- For each AC-elements moved to the ordered state as indicated by the AUTOMATION_COMPOSITION_DEPLOY +- AutomationCompositionUpdateAckListener in AC-runtime collects the messages from Message Broker +- It checks the deployStatus of all automation composition elements +- It updates the AC-instance in DB accordingly + +Design of a AUTOMATIONCOMPOSITION_STATECHANGE_ACK message +--------------------------------------------------------- +- A participant sends AUTOMATIONCOMPOSITION_STATECHANGE_ACK message in response to a AUTOMATIONCOMPOSITION_STATECHANGE message. +- For each AC-elements moved to the ordered state as indicated by the AUTOMATIONCOMPOSITION_STATECHANGE +- AutomationCompositionStateChangeAckListener in AC-runtime collects the messages from Message Broker +- It checks the deployStatus/lockStatus of all automation composition elements +- It updates the AC-instance in DB accordingly diff --git a/docs/clamp/acm/design-impl/participants/policy-framework-participant.rst b/docs/clamp/acm/design-impl/participants/policy-framework-participant.rst index 9ce120c0..3ebdae5c 100644 --- a/docs/clamp/acm/design-impl/participants/policy-framework-participant.rst +++ b/docs/clamp/acm/design-impl/participants/policy-framework-participant.rst @@ -12,9 +12,9 @@ Automation Composition Elements in the Policy Framework Participant are configur The Policy Framework participant receives messages through participant-intermediary common code, and handles them by invoking REST APIs towards policy-framework. -For example, When a AutomationCompositionUpdate message is received by policy participant, it contains full ToscaServiceTemplate describing all components participating in an automation composition. When the automation composition element state changed from UNINITIALIZED to PASSIVE, the Policy-participant triggers the creation of policy-types and policies in Policy-Framework. +For example, When a PARTICIPANT_UPDATE message is received by policy participant prompted by a PRIME, it contains the Automation Composition Element Definitions from the Tosca Service Template that was commissioned. An Automation Composition Instance can then be created from the commissioned definitions. When the automation composition instance element state changed from UNDEPLOYED to DEPLOYED, the Policy-participant receives a AUTOMATION_COMPOSITION_DEPLOY message, which triggers the creation of policy-types and policies in Policy-Framework. -When the state changes from PASSIVE to UNINITIALIZED, Policy-Participant deletes the policies, policy-types by invoking REST APIs towards the policy-framework. +When the state changes from DEPLOYED to UNDEPLOYED, Policy-Participant deletes the policies, policy-types by invoking REST APIs towards the policy-framework. Run Policy Framework Participant command line using Maven +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ @@ -31,7 +31,9 @@ Distributing Policies The Policy Framework participant uses the Policy PAP API to deploy and undeploy policies. -When a Policy Framework Automation Composition Element changes from state UNINITIALISED to state PASSIVE, the policy is deployed. When it changes from state PASSIVE to state UNINITIALISED, the policy is undeployed. +When a Policy Framework Automation Composition Element changes from state UNDEPLOYED to state DEPLOYED, the policy is deployed. When it changes from state DEPLOYED to state UNDEPLOYED, the policy is undeployed. + +For more complete detail of the state machines please go to the state machines page :ref:`acm-states-label`. The PDP group to which the policy should be deployed is specified in the Automation Composition Element metadata, see the Policy Automation Composition Element type definition. If the PDP group specified for policy deployment does not exist, an error is reported. @@ -76,4 +78,4 @@ The Policy Participant uses the following steps for Policy References: successfully stored, execution proceeds, otherwise an error is reported. #. If the Policy has not been specified, the Participant checks that the Policy is already in the Policy framework. If - the Policy already exists, execution proceeds, otherwise an error is reported.
\ No newline at end of file + the Policy already exists, execution proceeds, otherwise an error is reported. diff --git a/docs/clamp/acm/files/ACM-Message-Table.csv b/docs/clamp/acm/files/ACM-Message-Table.csv new file mode 100644 index 00000000..725ac1ec --- /dev/null +++ b/docs/clamp/acm/files/ACM-Message-Table.csv @@ -0,0 +1,32 @@ +Message,Source,Target,Purpose,Important Fields,Field Descriptions +ParticipantRegister,Participant,ACM Runtime,Participant registers with the ACM runtime,participantId,The ID of this participant – in UUID format +,,,,participantSupportedElementTypes,A list of element types that this participant supports +ParticipantRegisterAck,ACM Runtime,Participant,Acknowledgment of Participant Registration,participantId,The ID of this participant – in UUID format +,,,,Result,Success/Fail +,,,,Message,A message indicating the reason for failure +ParticipantDeregister,Participant,ACM Runtime,Participant deregisters with the ACM runtime,participantId,The ID of this participant – in UUID format +ParticipantDeregisterAck,ACM Runtime,Participant,Acknowledgment of Participant Deegistration,participantId,The ID of this participant – in UUID format +,,,,Result,Success/Fail +,,,,Message,A message indicating the reason for failure +ParticipantPrime,ACM Runtime,Participant,Trigger priming/depriming in the participant,participantId,The ID of this participant – in UUID format +,,,,participantDefinitionUpdates,Contains AC element definition values for a particular participant +,,,,Result,Success/Fail +,,,,Message,A message indicating the reason for failure +ParticipantPrimeAck,Participant,ACM Runtime,Message to confirm participant has been primed/deprimed,participantId,The ID of this participant – in UUID format +,,,,Result,Success/Fail +,,,,Message,A message indicating the reason for failure +ParticipantStatusReq,ACM Runtime,Participant,Message sent to reques a status update from the participant,participantId,The ID of the participant to request update from – in UUID format +,,,,messageType,Enum indicating the type of message PARTICIPANT_STATUS_REQ +ParticipantStatus,Participant,ACM Runtime,Status update message,state,Enum indicating the current state of the participant +,,,,participantDefinitionUpdates,"A list of ParticipantDefinition updates, returned in response to ParticipantStatusReq only" +,,,,automationCompositionInfoList,List of AutomationCompositionInfo types with AutomationCompositionId and its state +,,,,participantSupportedElementTypes,Ac element types that this participant is capable for deployinh/supporting +AutomationCompositionDeploy,ACM Runtime,Participant,Message to request change state of composition to DEPLOY,participantUpdatesList,A list of ParticipantUpdates instances which carries details of an updated participant. +,,,,startPhase,Integer indicating the start up order of the elements +,,,,participantId,UUID indicating the participant the message is intended for +AutomationCompositionDeployAck,Participant,ACM Runtime,Message to acknowledge that deploy or state change message has been received by participant,automationCompositionResultMap,"A map with AutomationCompositionElementID as its key, and a pair of result and message as value per AutomationCompositionElement" +,,,,automationCompositionId,The id of the automation composition related to this message +AutomationCompositionStateChange,ACM Runtime,Participant,Message to request change state of composition to states other than DEPLOY,deployOrderedState,Enum indicating the deployment state being requested +,,,,lockOrderedState,Enum indicating the lock state being requested +,,,,startPhase,Integer indicating the start up order of the elements +,,,,participantId,UUID indicating the participant the message is intended for diff --git a/docs/clamp/acm/images/acm-participants-protocol/acm-depriming.png b/docs/clamp/acm/images/acm-participants-protocol/acm-depriming.png Binary files differindex 7bcc9b15..7ea51967 100644 --- a/docs/clamp/acm/images/acm-participants-protocol/acm-depriming.png +++ b/docs/clamp/acm/images/acm-participants-protocol/acm-depriming.png diff --git a/docs/clamp/acm/images/acm-participants-protocol/acm-monitoring.png b/docs/clamp/acm/images/acm-participants-protocol/acm-monitoring.png Binary files differindex dcc996e4..ec9ba5e1 100644 --- a/docs/clamp/acm/images/acm-participants-protocol/acm-monitoring.png +++ b/docs/clamp/acm/images/acm-participants-protocol/acm-monitoring.png diff --git a/docs/clamp/acm/images/acm-participants-protocol/acm-priming.png b/docs/clamp/acm/images/acm-participants-protocol/acm-priming.png Binary files differindex 918a292e..4aec6a4a 100644 --- a/docs/clamp/acm/images/acm-participants-protocol/acm-priming.png +++ b/docs/clamp/acm/images/acm-participants-protocol/acm-priming.png diff --git a/docs/clamp/acm/images/acm-participants-protocol/acm-state-change-msg.png b/docs/clamp/acm/images/acm-participants-protocol/acm-state-change-msg.png Binary files differindex d1393bab..1211b8ce 100644 --- a/docs/clamp/acm/images/acm-participants-protocol/acm-state-change-msg.png +++ b/docs/clamp/acm/images/acm-participants-protocol/acm-state-change-msg.png diff --git a/docs/clamp/acm/images/acm-participants-protocol/acm-state-change.png b/docs/clamp/acm/images/acm-participants-protocol/acm-state-change.png Binary files differindex fd55a069..f2966763 100644 --- a/docs/clamp/acm/images/acm-participants-protocol/acm-state-change.png +++ b/docs/clamp/acm/images/acm-participants-protocol/acm-state-change.png diff --git a/docs/clamp/acm/images/acm-participants-protocol/acm-update-msg.png b/docs/clamp/acm/images/acm-participants-protocol/acm-update-msg.png Binary files differindex 3886e440..f9ea2331 100644 --- a/docs/clamp/acm/images/acm-participants-protocol/acm-update-msg.png +++ b/docs/clamp/acm/images/acm-participants-protocol/acm-update-msg.png diff --git a/docs/clamp/acm/images/acm-participants-protocol/acm-update.png b/docs/clamp/acm/images/acm-participants-protocol/acm-update.png Binary files differindex 2a7aac1f..3dc124d4 100644 --- a/docs/clamp/acm/images/acm-participants-protocol/acm-update.png +++ b/docs/clamp/acm/images/acm-participants-protocol/acm-update.png diff --git a/docs/clamp/acm/images/acm-participants-protocol/participant-deregistration.png b/docs/clamp/acm/images/acm-participants-protocol/participant-deregistration.png Binary files differindex bb2ec9a3..9c86d626 100644 --- a/docs/clamp/acm/images/acm-participants-protocol/participant-deregistration.png +++ b/docs/clamp/acm/images/acm-participants-protocol/participant-deregistration.png diff --git a/docs/clamp/acm/images/acm-participants-protocol/participant-registering.png b/docs/clamp/acm/images/acm-participants-protocol/participant-registering.png Binary files differindex 2f7b5d8e..7bc68751 100644 --- a/docs/clamp/acm/images/acm-participants-protocol/participant-registering.png +++ b/docs/clamp/acm/images/acm-participants-protocol/participant-registering.png |
