diff options
Diffstat (limited to 'docs/clamp/acm/api-protocol')
4 files changed, 115 insertions, 56 deletions
diff --git a/docs/clamp/acm/api-protocol/acm-participant-protocol.rst b/docs/clamp/acm/api-protocol/acm-participant-protocol.rst index 2b6beaca..d384633a 100644 --- a/docs/clamp/acm/api-protocol/acm-participant-protocol.rst +++ b/docs/clamp/acm/api-protocol/acm-participant-protocol.rst @@ -14,18 +14,21 @@ Protocol Dialogues ================== The protocol supports the dialogues described below. +Any participant could have more than one replica. All replicas of a specific participant, have same participant ID. +All replica data are synchronized by ACM-runtime through a sync message. This message will be triggered at any change in composition and instance. Participant Registration and De-Registration -------------------------------------------- -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. -In a scenario where Participant has been restarted, ACM runtime have to provide all Primed ACM Definition and Deployed ACM instances of the Participant sending a Restart message. +Participant Registration is performed by a Participant when it starts up. +It registers its replica ID, participant ID and the ACM Element Types it supports with the ACM runtime. +In a scenario where a replica of a Participant has been restarted, ACM runtime have to provide all Primed ACM Definition and Deployed ACM instances of the Replica sending a Sync message. .. image:: ../images/system-dialogues/RegisterParticipant.png -Participant Deregistration is performed by a Participant when it shuts down. It deregisters its ID and type with the ACM runtime. +Participant Deregistration is performed by a Participant when it shuts down. It deregisters its replica ID with the ACM runtime. .. image:: ../images/system-dialogues/DeregisterParticipant.png @@ -33,7 +36,7 @@ Participant Deregistration is performed by a Participant when it shuts down. It Automation Composition Priming and De-Priming --------------------------------------------- -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 +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. .. image:: ../images/system-dialogues/PrimeAcTypeOnPpnts.png @@ -62,7 +65,7 @@ Automation Composition Update Automation Composition Update handles creation, change, and deletion of Automation Compositions on participants. Change of Automation Compositions uses a semantic versioning approach and follows the -semantics described on the page :ref:`4.1 Management of Automation Composition Instance +semantics described on the page :ref:`5.1 Management of Automation Composition Instance Configurations <management-acm-instance-configs>`. .. image:: ../images/acm-participants-protocol/acm-update.png diff --git a/docs/clamp/acm/api-protocol/puml/ParticipantDeregister.puml b/docs/clamp/acm/api-protocol/puml/ParticipantDeregister.puml index acbec2ad..78689689 100644 --- a/docs/clamp/acm/api-protocol/puml/ParticipantDeregister.puml +++ b/docs/clamp/acm/api-protocol/puml/ParticipantDeregister.puml @@ -1,6 +1,11 @@ @startuml + +participant Participant +participant "ACM Runtime" +database "ACM Database" + Participant -> "ACM Runtime": [ASYNC] Deregister -"ACM Runtime" -> "ACM Database": Set Participant State as OFF_LINE +"ACM Runtime" -> "ACM Database": Set Participant Replica State as OFF_LINE Participant <- "ACM Runtime": [ASYNC] Deregistration Accepted Participant -> Participant: Shutdown Participant @enduml diff --git a/docs/clamp/acm/api-protocol/puml/ParticipantRegister.puml b/docs/clamp/acm/api-protocol/puml/ParticipantRegister.puml index f8aeee81..54be2af4 100644 --- a/docs/clamp/acm/api-protocol/puml/ParticipantRegister.puml +++ b/docs/clamp/acm/api-protocol/puml/ParticipantRegister.puml @@ -1,20 +1,24 @@ @startuml + +participant Participant +participant "ACM Runtime" +database "ACM Database" + activate Participant - Participant -> "CLAMP Runtime": [ASYNC] Register -activate "CLAMP Runtime" + Participant -> "ACM Runtime": [ASYNC] Register +activate "ACM Runtime" deactivate Participant - "CLAMP Runtime" -> "CLAMP Database": Create or Update Perticipant Registration,\n store supported ACM element types \n and set Perticipant State as ON_LINE - "CLAMP Runtime" -> Participant: [ASYNC] Registration Accepted - loop over ACM Definition - "CLAMP Runtime" -> "CLAMP Database": Mark all ACM element instances deployed\n on Participant as Restarting - "CLAMP Runtime" -> Participant: [ASYNC] Restart\n send Common Property Values\n and Instance Elements of this Participant] -deactivate "CLAMP Runtime" + "ACM Runtime" -> "ACM Database": Create a Participant Replica Registration,\n store supported ACM element types \n and set Replica State as ON_LINE + loop ACM Definition + "ACM Runtime" -> Participant: [ASYNC] Sync message\n send Common Property Values\n and Instance Elements of this Participant activate Participant -Participant -> Participant: Store Common Property Values and Instance Elements -Participant -> "CLAMP Runtime": [ASYNC] State Change Ack -activate "CLAMP Runtime" + Participant -> Participant: Store Common Property Values and Instance Elements + end loop + alt + "ACM Runtime" -> Participant: [ASYNC] Registration Accepted +deactivate "ACM Runtime" +Participant -> Participant: set participant as registered +Participant -> "ACM Runtime": [ASYNC] Status message deactivate Participant - "CLAMP Runtime" -> "CLAMP Database": Remove Restarting from all Compositions \n and Instances of this Participant -deactivate "CLAMP Runtime" - end +end @enduml diff --git a/docs/clamp/acm/api-protocol/system-level-dialogues.rst b/docs/clamp/acm/api-protocol/system-level-dialogues.rst index 0ef5f200..ec03353c 100644 --- a/docs/clamp/acm/api-protocol/system-level-dialogues.rst +++ b/docs/clamp/acm/api-protocol/system-level-dialogues.rst @@ -16,7 +16,8 @@ Priming The CLAMP Automation Composition Runtime Lifecycle Management uses the f 1.1 Register a Participant -------------------------- -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. +Participant Registration is performed by a Participant when it starts up. +It registers its replica ID, participant ID and the ACM Element Types it supports with the ACM runtime. .. image:: ../images/system-dialogues/RegisterParticipant.png @@ -28,11 +29,17 @@ Participant Deregistration is performed by a Participant when it shuts down. It 1.3 Supervise Participants -------------------------- -Participant Supervision is performed periodically between participants and the ACM runtime server to ensure that registered participants are available over time. Participants send a heartbeat message to the ACM runtime at a configured interval. The heartbeat message contains updated status information for each AC Element Instance that has changed status since the last Heartbeat message sent by the participant. +Participant Supervision is performed periodically between participants and the ACM runtime server to ensure that registered participants are available over time. +Participants send a heartbeat Status message to the ACM runtime at a configured interval. .. image:: ../images/system-dialogues/SuperviseParticipantsStatusUpdate.png -The ACM runtime regularly checks the heartbeat reports from participants and takes action if participants time out. If a heartbeat message is not received for a participant in the Timeout Interval, the participant is marked as timed out and its ACM element instances are informed. +Participants could send outProperties update using Status message to the ACM runtime. +When Status message contains outProperties, ACM-runtime updates the Database and triggers a sync message to all replicas. + +.. image:: ../images/system-dialogues/SuperviseParticipantsStatusOutPropertiesUpdate.png + +The ACM runtime regularly checks the heartbeat reports from participants and takes action if participants time out. If a heartbeat message is not received for a participant replica in the Timeout Interval, the participant replica is marked as timed out. .. image:: ../images/system-dialogues/SuperviseParticipantsTimeout.png @@ -77,7 +84,7 @@ A participant should respond for each Automation Composition Element Type, thus .. image:: ../images/system-dialogues/PrimeAcTypeMultiplePpnts.png -The ACM Runtime updates the priming information in the database. +The ACM Runtime updates the priming information in the database, and send sync message to all replicas. .. image:: ../images/system-dialogues/PrimeInfoUpdatedInDb.png @@ -91,7 +98,7 @@ A participant should respond for each Automation Composition Element Type, thus .. image:: ../images/system-dialogues/DeprimeElements.png -The ACM Runtime updates the priming information in the database. +The ACM Runtime updates the priming information in the database, and send sync message to all replicas. .. image:: ../images/system-dialogues/UpdateDeprimeInDb.png @@ -122,11 +129,26 @@ Each participant deletes its AC Element Instances from the AC Instance .. image:: ../images/system-dialogues/DeleteInstanceElements.png -The ACM Runtime receives and stores the responses, when all instances element are deleted, it delete the instance. +The ACM Runtime receives and stores the responses, when all instances element are deleted, it delete the instance and send sync message to all replicas. .. image:: ../images/system-dialogues/DeleteResponseStored.png -3.3 Deploy Automation Composition Instance +3.3 Prepare Automation Composition Instance +------------------------------------------- +Prepare is a check system from participant before the deployment of an instance, the result will stored in outProperties and not other changes are allowed. +The user requests the AC Instance to be prepared using a REST endpoint. The ACM Runtime orders the AC Instance to be prepared to Participants. + +.. image:: ../images/system-dialogues/PrepareAcInstance.png + +Each participant prepares its AC Element Instances from the AC Instance. + +.. image:: ../images/system-dialogues/PrepareAcInstanceElements.png + +The ACM Runtime receives and stores the responses, and send sync message to all replicas. + +.. image:: ../images/system-dialogues/PrepareResponseStored.png + +3.4 Deploy Automation Composition Instance ------------------------------------------ The user requests the AC Instance to be deployed using a REST endpoint. The ACM Runtime orders the AC Instance to be deployed to Participants. @@ -136,11 +158,26 @@ Each participant deploys its AC Element Instances from the AC Instance. .. image:: ../images/system-dialogues/DeployAcInstanceElements.png -The ACM Runtime receives and stores the responses. +The ACM Runtime receives and stores the responses, and send sync message to all replicas. .. image:: ../images/system-dialogues/DeployResponseStored.png -3.4 Update Automation Composition Instance +3.5 Review Automation Composition Instance +------------------------------------------ +Review is a check system from participant after the deployment of an instance, the result will stored in outProperties and not other changes are allowed. +The user requests the AC Instance to be Reviewed using a REST endpoint. The ACM Runtime orders the AC Instance to be reviewed to Participants. + +.. image:: ../images/system-dialogues/ReviewAcInstance.png + +Each participant reviews its AC Element Instances from the AC Instance. + +.. image:: ../images/system-dialogues/ReviewAcInstanceElements.png + +The ACM Runtime receives and stores the responses, and send sync message to all replicas. + +.. image:: ../images/system-dialogues/ReviewResponseStored.png + +3.6 Update Automation Composition Instance ------------------------------------------ The user requests the AC Instance to be updated using a REST endpoint. The ACM Runtime orders the AC Instance to be updated. @@ -150,11 +187,26 @@ Each participant updates its AC Element from the AC Instance .. image:: ../images/system-dialogues/UpdateAcElements.png -The ACM Runtime receives and stores the responses. +The ACM Runtime receives and stores the responses, and send sync message to all replicas. .. image:: ../images/system-dialogues/UpdateAcElementsResponse.png -3.5 Migrate Automation Composition Instance +3.7 Migration Precheck Automation Composition Instance +------------------------------------------------------ +Migration Precheck is a check system from participant before the migration of an instance, the result will stored in outProperties and not other changes are allowed. +The user requests a Migration Precheck for the AC Instance using a REST endpoint. The ACM Runtime orders the Migration Precheck for AC Instance to Participants. + +.. image:: ../images/system-dialogues/MigrationPrecheckAcInstance.png + +Each participant execute a Migration Precheck to its AC Element Instances from the AC Instance. + +.. image:: ../images/system-dialogues/MigrationPrecheckAcInstanceElements.png + +The ACM Runtime receives and stores the responses, and send sync message to all replicas. + +.. image:: ../images/system-dialogues/MigrationPrecheckResponseStored.png + +3.8 Migrate Automation Composition Instance ------------------------------------------- The user requests the AC Instance to be migrated using a REST endpoint. The ACM Runtime orders the AC Instance to be migrated. @@ -164,11 +216,11 @@ Each participant migrated its AC Element from the AC Instance .. image:: ../images/system-dialogues/MigrateAcElements.png -The ACM Runtime receives and stores the responses. +The ACM Runtime receives and stores the responses, and send sync message to all replicas. .. image:: ../images/system-dialogues/MigrateAcElementsResponse.png -3.6 Undeploy Automation Composition Instance +3.9 Undeploy Automation Composition Instance -------------------------------------------- The user requests the AC Instance to be undeployed using a REST endpoint. The ACM Runtime orders the AC Instance to be undeployed. @@ -178,17 +230,17 @@ Each participant undeploys its AC Element Instances from the AC Instance .. image:: ../images/system-dialogues/UndeployInstanceElements.png -The ACM Runtime receives and stores the responses. +The ACM Runtime receives and stores the responses, and send sync message to all replicas. .. image:: ../images/system-dialogues/UndeployResponseStored.png -3.7 Read Automation Composition Instances ------------------------------------------ +3.10 Read Automation Composition Instances +------------------------------------------ .. image:: ../images/system-dialogues/ReadAcInstances.png -3.8 Unlock Automation Composition Instance ------------------------------------------- +3.11 Unlock Automation Composition Instance +------------------------------------------- The user requests the AC Instance to be unlocked using a REST endpoint. The ACM Runtime orders the AC Instance to be unlocked on Participants. .. image:: ../images/system-dialogues/OrderInstanceUnlock.png @@ -197,12 +249,12 @@ Each participant unlocks its AC Element Instances from the AC Instance. .. image:: ../images/system-dialogues/UnlockInstanceElements.png -The ACM Runtime receives and stores the responses. +The ACM Runtime receives and stores the responses, and send sync message to all replicas. .. image:: ../images/system-dialogues/UnlockResponseStored.png -3.9 Lock Automation Composition Instance ----------------------------------------- +3.12 Lock Automation Composition Instance +----------------------------------------- The user requests the AC Instance to be locked using a REST endpoint. The ACM Runtime orders the AC Instance to be locked on Participants. .. image:: ../images/system-dialogues/LockAcInstance.png @@ -211,21 +263,16 @@ Each participant locks its AC Element Instances from the AC Instance. .. image:: ../images/system-dialogues/LockAcInstanceElements.png -The ACM Runtime receives and stores the responses. +The ACM Runtime receives and stores the responses, and send sync message to all replicas. .. image:: ../images/system-dialogues/LockResponseStored.png -3.10 Update Operational State on Automation Composition Instance ----------------------------------------------------------------- +3.13 Update Operational State, Use State and outProperties on Automation Composition Instance +--------------------------------------------------------------------------------------------- .. image:: ../images/system-dialogues/UpdateOperationalState.png -3.11 Update Usage State on Automation Composition Instance ----------------------------------------------------------- - -.. image:: ../images/system-dialogues/UpdateUsageState.png - -3.12 Failure handling in ACM +3.14 Failure handling in ACM ---------------------------- After any ACM operation is completed, one of the following result messages will be updated in the ACM. These result values are updated along with the overall state of the ACM instance. @@ -270,17 +317,17 @@ The following flow shown and example of deployment that get stuck, and the user .. image:: ../images/system-dialogues/TimeoutParticipant.png -3.13 OFF_LINE handling in ACM +3.15 OFF_LINE handling in ACM ----------------------------- -Runtime marks the participant state with the value 'OFF_LINE' when the participant fails to report the periodic heartbeat, -the participant state is then marked as 'OFF_LINE' by the ACM-R after the configured waiting limit is reached. -That scenario might happen when participant is shutdown, in that scenario all on going operations with that participant are marked 'TIMEOUT' due the missing messages back. +Runtime marks the participant state with the value 'OFF_LINE' when the participant replica fails to report the periodic heartbeat, +the participant replica state is then marked as 'OFF_LINE' by the ACM-R after the configured waiting limit is reached. +That scenario might happen when participant replica is shutdown, in that scenario all on going operations with that participant are marked 'TIMEOUT' due the missing messages back. -The user cannot trigger any state change events when participant state is 'OFF_LINE'. +The user cannot trigger any state change events when all participant replicas state are 'OFF_LINE' (no one is available 'ONLINE'). .. image:: ../images/system-dialogues/OfflineAcmResult.png -When a participant state is marked 'OFF_LINE', it might come back ONLINE and the user can trigger state change events to the ACM. +When a participant replica state is marked 'OFF_LINE', it might come back ONLINE and the user can trigger state change events to the ACM. End of Document |