diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/apex/APEX-Policy-Guide.rst | 3 | ||||
| -rw-r--r-- | docs/clamp/acm/acm-participant-guide.rst | 326 | ||||
| -rw-r--r-- | docs/clamp/acm/acm-states.rst | 55 | ||||
| -rw-r--r-- | docs/clamp/acm/design-impl/clamp-runtime-acm.rst | 76 | ||||
| -rw-r--r-- | docs/clamp/acm/design-impl/participants/participant-intermediary.rst | 6 | ||||
| -rwxr-xr-x | docs/clamp/acm/files/ACM-Message-Table.csv | 20 |
6 files changed, 369 insertions, 117 deletions
diff --git a/docs/apex/APEX-Policy-Guide.rst b/docs/apex/APEX-Policy-Guide.rst index 7d2f01d3..a9dad1c6 100644 --- a/docs/apex/APEX-Policy-Guide.rst +++ b/docs/apex/APEX-Policy-Guide.rst @@ -471,7 +471,8 @@ Concept: Logic The *LogicCode* field of a Logic concept definition is a string that holds the program code that is to be executed at run time. The *LogicType* field defines the language of the code. The standard values are the logic languages - supported by APEX: `JAVASCRIPT <https://en.wikipedia.org/wiki/JavaScript>`__, `JAVA <https://java.com/en/>`__, + supported by APEX: `JAVASCRIPT <https://en.wikipedia.org/wiki/JavaScript>`__, + `JAVA <https://www.oracle.com/java/>`__, `JYTHON <http://www.jython.org/>`__, `JRUBY <http://jruby.org/>`__, or `MVEL <https://en.wikibooks.org/wiki/Transwiki:MVEL_Language_Guide>`__. diff --git a/docs/clamp/acm/acm-participant-guide.rst b/docs/clamp/acm/acm-participant-guide.rst index b4ca885d..e1f6c2de 100644 --- a/docs/clamp/acm/acm-participant-guide.rst +++ b/docs/clamp/acm/acm-participant-guide.rst @@ -48,17 +48,29 @@ and the same is configured for the 'ParticipantIntermediaryParameters' object in .. code-block:: bash + intermediaryParameters: + topics: + operationTopic: policy-acruntime-participant + syncTopic: acm-ppnt-sync clampAutomationCompositionTopics: topicSources: - - topic: POLICY-ACRUNTIME-PARTICIPANT + topic: ${participant.intermediaryParameters.topics.operationTopic} + servers: + - ${topicServer:localhost}:9092 + topicCommInfrastructure: kafka + fetchTimeout: 15000 + additionalProps: + group.id: policy-clamp-ac-name + - + topic: ${participant.intermediaryParameters.topics.syncTopic} servers: - ${topicServer:localhost}:9092 topicCommInfrastructure: kafka fetchTimeout: 15000 topicSinks: - - topic: POLICY-ACRUNTIME-PARTICIPANT + topic: ${participant.intermediaryParameters.topics.operationTopic} servers: - ${topicServer:localhost}:9092 topicCommInfrastructure: kafka @@ -92,9 +104,7 @@ AutomationCompositionElementListener: 6. void update(CompositionElementDto compositionElement, InstanceElementDto instanceElement, InstanceElementDto instanceElementUpdated) throws PfModelException; 7. void prime(CompositionDto composition) throws PfModelException; 8. void deprime(CompositionDto composition) throws PfModelException; - 9. void handleRestartComposition(CompositionDto composition, AcTypeState state) throws PfModelException; - 10. void handleRestartInstance(CompositionElementDto compositionElement, InstanceElementDto instanceElement, DeployState deployState, LockState lockState) throws PfModelException; - 11. void migrate(CompositionElementDto compositionElement, CompositionElementDto compositionElementTarget, InstanceElementDto instanceElement, InstanceElementDto instanceElementMigrate) throws PfModelException; + 9. void migrate(CompositionElementDto compositionElement, CompositionElementDto compositionElementTarget, InstanceElementDto instanceElement, InstanceElementDto instanceElementMigrate) throws PfModelException; These method from the interface are implemented independently as per the user requirement. These methods after handling the appropriate requests should also invoke the intermediary's publisher apis to notify the ACM-runtime with the acknowledgement events. @@ -124,12 +134,10 @@ The Abstract class AcElementListenerV1 supports the follow methods. 6. void update(UUID instanceId, AcElementDeploy element, Map<String, Object> inProperties) throws PfModelException; 7. void prime(UUID compositionId, List<AutomationCompositionElementDefinition> elementDefinitionList) throws PfModelException; 8. void deprime(UUID compositionId) throws PfModelException; - 9. void handleRestartComposition(UUID compositionId, List<AutomationCompositionElementDefinition> elementDefinitionList, AcTypeState state) throws PfModelException; - 10. void handleRestartInstance(UUID instanceId, AcElementDeploy element, Map<String, Object> properties, DeployState deployState, LockState lockState) throws PfModelException; - 11. void migrate(UUID instanceId, AcElementDeploy element, UUID compositionTargetId, Map<String, Object> properties) throws PfModelException; + 9. void migrate(UUID instanceId, AcElementDeploy element, UUID compositionTargetId, Map<String, Object> properties) throws PfModelException; **Note**: this class needs intermediaryApi and it should be passed by constructor. It is declared as protected and can be used. -Default implementation are supported for the methods: lock, unlock, update, migrate, delete, prime, deprime, handleRestartComposition and handleRestartInstance. +Default implementation are supported for the methods: lock, unlock, update, migrate, delete, prime and deprime. Un example of AutomationCompositionElementHandler implemented in 7.1.0 version and how to use AcElementListenerV1 abstract class: @@ -191,7 +199,7 @@ This abstract class is introduced to help to maintain the java backward compatib Any new functionality in the future will be wrapped by this class. **Note**: this class needs intermediaryApi and it should be passed by constructor. It is declared as protected and can be used. -Default implementation are supported for the methods: lock, unlock, update, migrate, delete, prime, deprime, handleRestartComposition and handleRestartInstance. +Default implementation are supported for the methods: lock, unlock, update, migrate, delete, prime and deprime. Methods: deploy, undeploy, lock, unlock and delete @@ -243,7 +251,7 @@ Method: update elementId instance element id toscaServiceTemplateFragment inProperties instance in-properties **(updated)** - outProperties instance out-properties + outProperties instance out-properties ============================== ====================================== Methods: prime, deprime @@ -283,7 +291,7 @@ Method: migrate elementId instance element id toscaServiceTemplateFragment inProperties instance in-properties **(before the migration)** - outProperties instance out-properties + outProperties instance out-properties ============================== =================================================== instanceElementMigrate: ============================== ====================================== @@ -293,7 +301,7 @@ Method: migrate elementId instance element id toscaServiceTemplateFragment inProperties instance in-properties **(updated)** - outProperties instance out-properties + outProperties instance out-properties ============================== ====================================== APIs to invoke @@ -440,13 +448,6 @@ The following code is an example how to update the property 'myProperty' and sen **Note**: In update and migrate Participants will receive the instance Properties before the merge (instanceElement) and the instance Properties merged (instanceElementUpdated / instanceElementMigrate). -Restart scenario ----------------- - Restart methods handle the scenario when participant shut down and restart. - During RESTARTING, compositions and instances will be stored in participant memory with In/Out Properties, 'useState' and 'operationalState'. - The method handleRestartComposition will be called for each composition and will be present the 'state' at the time the participant shut down. - The method handleRestartInstance will be called for each instance element and will be present the 'deployState' and the 'lockState' at the time the participant shut down. - In ONAP, the following participants are already implemented in java spring boot for various requirements. The maven modules can be referred here: @@ -507,18 +508,28 @@ The following example shows the topic parameters and the additional 'myparameter participant: myparameter: my parameter intermediaryParameters: + topics: + operationTopic: policy-acruntime-participant + syncTopic: acm-ppnt-sync reportingTimeIntervalMs: 120000 description: Participant Description participantId: 101c62b3-8918-41b9-a747-d21eb79c6c90 clampAutomationCompositionTopics: topicSources: - - topic: POLICY-ACRUNTIME-PARTICIPANT + - topic: ${participant.intermediaryParameters.topics.operationTopic} + servers: + - ${topicServer:localhost}:9092 + topicCommInfrastructure: kafka + fetchTimeout: 15000 + additionalProps: + group.id: policy-clamp-my-first-ptn + - topic: ${participant.intermediaryParameters.topics.syncTopic} servers: - ${topicServer:localhost}:9092 topicCommInfrastructure: kafka fetchTimeout: 15000 topicSinks: - - topic: POLICY-ACRUNTIME-PARTICIPANT + - topic: ${participant.intermediaryParameters.topics.operationTopic} servers: - ${topicServer:localhost}:9092 topicCommInfrastructure: kafka @@ -679,52 +690,52 @@ The following example shows the Handler implementation and how could be the impl } - @Override - public void handleRestartComposition(CompositionDto composition, AcTypeState state) throws PfModelException { - - // TODO restart process - - switch (state) { - case PRIMING -> prime(composition); - case DEPRIMING -> deprime(composition); - default -> intermediaryApi - .updateCompositionState(composition.compositionId(), state, StateChangeResult.NO_ERROR, "Restarted"); - } - } - - @Override - public void handleRestartInstance(CompositionElementDto compositionElement, InstanceElementDto instanceElement, - DeployState deployState, LockState lockState) throws PfModelException { - - // TODO restart process - - if (DeployState.DEPLOYING.equals(deployState)) { - deploy(compositionElement, instanceElement); - return; - } - if (DeployState.UNDEPLOYING.equals(deployState)) { - undeploy(compositionElement, instanceElement); - return; - } - if (DeployState.UPDATING.equals(deployState)) { - update(compositionElement, instanceElement, instanceElement); - return; - } - if (DeployState.DELETING.equals(deployState)) { - delete(compositionElement, instanceElement); - return; - } - if (LockState.LOCKING.equals(lockState)) { - lock(compositionElement, instanceElement); - return; - } - if (LockState.UNLOCKING.equals(lockState)) { - unlock(compositionElement, instanceElement); - return; - } - intermediaryApi.updateAutomationCompositionElementState(instanceElement.instanceId(), - instanceElement.elementId(), deployState, lockState, StateChangeResult.NO_ERROR, "Restarted"); - } +Allowed state from the participant perspective +---------------------------------------------- + ++------------+--------------+---------------------+-------------------------+ +| **Action** | **state** | **stChResult** | **Description** | ++------------+--------------+---------------------+-------------------------+ +| | PRIMED | NO_ERROR | Prime is completed | ++ Prime +--------------+---------------------+-------------------------+ +| | COMMISSIONED | FAILED | Prime is failed | ++------------+--------------+---------------------+-------------------------+ +| | COMMISSIONED | NO_ERROR | Deprime is completed | ++ Deprime +--------------+---------------------+-------------------------+ +| | PRIMED | FAILED | Deprime is failed | ++------------+--------------+---------------------+-------------------------+ + ++------------+-----------------+---------------+----------------+----------------------------------------+ +| **Action** | **deployState** | **lockState** | **stChResult** | **Description** | ++------------+-----------------+---------------+----------------+----------------------------------------+ +| | DEPLOYED | | NO_ERROR | Deploy is completed | ++ Deploy +-----------------+---------------+----------------+----------------------------------------+ +| | UNDEPLOYED | | FAILED | Deploy is failed | ++------------+-----------------+---------------+----------------+----------------------------------------+ +| | UNDEPLOYED | | NO_ERROR | Undeploy is completed | +| Undeploy +-----------------+---------------+----------------+----------------------------------------+ +| | DEPLOYED | | FAILED | Undeploy is failed | ++------------+-----------------+---------------+----------------+----------------------------------------+ +| | | LOCKED | NO_ERROR | Lock is completed | ++ Lock +-----------------+---------------+----------------+----------------------------------------+ +| | | UNLOCKED | FAILED | Lock is failed | ++------------+-----------------+---------------+----------------+----------------------------------------+ +| | | UNLOCKED | NO_ERROR | Unlock is completed | ++ Unlock +-----------------+---------------+----------------+----------------------------------------+ +| | | LOCKED | FAILED | Unlock is failed | ++------------+-----------------+---------------+----------------+----------------------------------------+ +| | DEPLOYED | | NO_ERROR | Update is completed | +| Update +-----------------+---------------+----------------+----------------------------------------+ +| | DEPLOYED | | FAILED | Update is failed | ++------------+-----------------+---------------+----------------+----------------------------------------+ +| | DEPLOYED | | NO_ERROR | Migrate is completed | ++ Migrate +-----------------+---------------+----------------+----------------------------------------+ +| | DEPLOYED | | FAILED | Migrate is failed | ++------------+-----------------+---------------+----------------+----------------------------------------+ +| | DELETED | | NO_ERROR | Delete is completed | +| Delete +-----------------+---------------+----------------+----------------------------------------+ +| | UNDEPLOYED | | FAILED | Delete is failed | ++------------+-----------------+---------------+----------------+----------------------------------------+ AC Element states in failure scenarios @@ -765,6 +776,179 @@ Migrate fails Deployed Considering the above mentioned behavior of the participant Intermediary, it is the responsibility of the developer to tackle the error scenarios in the participant with the suitable approach. -Tips: -If the participant tries to undeploy an element which doesn’t exist in the system any more (due to various other external factors), -it could update the element state to ‘undeployed’ using the Intermediary api. +Handle states and failure scenarios from the participant perspective +-------------------------------------------------------------------- + +It is important to make distinction between the state of the instance/element flow, and the state of the application/configuration involved. +A deployed element means that a participant has completed a deploy action, and should not be confused with a deployed application. +Example with two elements: + +1. an instance is deployed, so the two elements are DEPLOYED +2. user calls undeploy command (ACM-R sets all element as DEPLOYING) +3. participant executes the first instance element with success and sends UNDEPLOYED state +4. participant executes the second instance element with fail and sends DEPLOYED state +5. user calls undeploy command again (ACM-R sets all element as DEPLOYING) +6. participant does not know that the application related to the first element is already UNDEPLOYED when the flow state is UNDEPLOYING + +There are some contexts in a failure scenario that the participant need to know the state of the deployed application. +From participant side, using "outProperties" it could be possible to handle custom states that better suit whit the context. + +Example of a participant that deploy/undeploy applications. +The following Java code shows how to implement deploy and undeploy that avoid to repeat the action already executed. + +.. code-block:: java + + @Override + public void deploy(CompositionElementDto compositionElement, InstanceElementDto instanceElement) + throws PfModelException { + + if ("DEPLOYED".equals(instanceElement.outProperties().get("state"))) { + // deploy process already done + intermediaryApi.updateAutomationCompositionElementState(instanceElement.instanceId(), + instanceElement.elementId(), DeployState.DEPLOYED, null, StateChangeResult.NO_ERROR, + "Already Deployed"); + return; + } + + // deployment process + ....................................... + ....................................... + // end of the deployment process + + if (isDeploySuccess()) { + instanceElement.outProperties().put("state", "DEPLOYED"); + intermediaryApi.sendAcElementInfo(instanceElement.instanceId(), instanceElement.elementId(), + null, null, instanceElement.outProperties()); + + intermediaryApi.updateAutomationCompositionElementState(instanceElement.instanceId(), + instanceElement.elementId(), DeployState.DEPLOYED, null, StateChangeResult.NO_ERROR, "Deployed"); + } else { + instanceElement.outProperties().put("state", "UNDEPLOYED"); + intermediaryApi.sendAcElementInfo(instanceElement.instanceId(), instanceElement.elementId(), + null, null, instanceElement.outProperties()); + + intermediaryApi.updateAutomationCompositionElementState(instanceElement.instanceId(), + instanceElement.elementId(), DeployState.UNDEPLOYED, null, StateChangeResult.FAILED, "Deploy failed!"); + } + } + + @Override + public void undeploy(CompositionElementDto compositionElement, InstanceElementDto instanceElement) + throws PfModelException { + + if ("DEPLOYED".equals(instanceElement.outProperties().get("state"))) { + // undeploy process already done + + intermediaryApi.updateAutomationCompositionElementState(instanceElement.instanceId(), + instanceElement.elementId(), DeployState.UNDEPLOYED, null, StateChangeResult.NO_ERROR, + "Already Undeployed"); + return; + } + + // undeployment process + ....................................... + ....................................... + // end of the undeployment process + + if (isUndeploySuccess()) { + instanceElement.outProperties().put("state", "UNDEPLOYED"); + intermediaryApi.sendAcElementInfo(instanceElement.instanceId(), instanceElement.elementId(), + null, null, instanceElement.outProperties()); + + intermediaryApi.updateAutomationCompositionElementState(instanceElement.instanceId(), + instanceElement.elementId(), DeployState.UNDEPLOYED, null, StateChangeResult.NO_ERROR, "Undeployed"); + } else { + instanceElement.outProperties().put("state", "DEPLOYED"); + intermediaryApi.sendAcElementInfo(instanceElement.instanceId(), instanceElement.elementId(), + null, null, instanceElement.outProperties()); + + intermediaryApi.updateAutomationCompositionElementState(instanceElement.instanceId(), + instanceElement.elementId(), DeployState.DEPLOYED, null, StateChangeResult.FAILED, "Undeploy failed!"); + } + } + + +Example of a participant that make configurations. +The following Java code shows how to implement deploy and undeploy that needs a clean up and repeat the action. +The state of the configuration will saved in outProperties. + +.. code-block:: java + + @Override + public void deploy(CompositionElementDto compositionElement, InstanceElementDto instanceElement) throws PfModelException { + + if ("DEPLOYED".equals(instanceElement.outProperties().get("state"))) { + // clean up deployment + + } else if ("DEPLOYING".equals(state) || "UNDEPLOYING".equals(state)) { + // check and clean up + + } + + // deployment process + instanceElement.outProperties().put("state", "DEPLOYING"); + intermediaryApi.sendAcElementInfo(instanceElement.instanceId(), instanceElement.elementId(), + null, null, instanceElement.outProperties()); + + ....................................... + ....................................... + // end of the deployment process + + if (isDeploySuccess()) { + instanceElement.outProperties().put("state", "DEPLOYED"); + intermediaryApi.sendAcElementInfo(instanceElement.instanceId(), instanceElement.elementId(), + null, null, instanceElement.outProperties()); + + intermediaryApi.updateAutomationCompositionElementState(instanceElement.instanceId(), + instanceElement.elementId(), DeployState.DEPLOYED, null, StateChangeResult.NO_ERROR, "Deployed"); + } else { + instanceElement.outProperties().put("state", "UNDEPLOYED"); + intermediaryApi.sendAcElementInfo(instanceElement.instanceId(), instanceElement.elementId(), + null, null, instanceElement.outProperties()); + + intermediaryApi.updateAutomationCompositionElementState(instanceElement.instanceId(), + instanceElement.elementId(), DeployState.UNDEPLOYED, null, StateChangeResult.FAILED, "Deploy failed!"); + } + } + + @Override + public void undeploy(CompositionElementDto compositionElement, InstanceElementDto instanceElement) + throws PfModelException { + + if ("UNDEPLOYED".equals(instanceElement.outProperties().get("state"))) { + // clean up undeployment + + } else if ("DEPLOYING".equals(state) || "UNDEPLOYING".equals(state)) { + // check and clean up + + } + + // undeployment process + instanceElement.outProperties().put("state", "UNDEPLOYING"); + intermediaryApi.sendAcElementInfo(instanceElement.instanceId(), instanceElement.elementId(), + null, null, instanceElement.outProperties()); + + ....................................... + ....................................... + // end of the undeployment process + + if (isUndeploySuccess()) { + instanceElement.outProperties().put("state", "UNDEPLOYED"); + intermediaryApi.sendAcElementInfo(instanceElement.instanceId(), instanceElement.elementId(), + null, null, instanceElement.outProperties()); + + intermediaryApi.updateAutomationCompositionElementState(instanceElement.instanceId(), + instanceElement.elementId(), DeployState.UNDEPLOYED, null, StateChangeResult.NO_ERROR, "Undeployed"); + } else { + instanceElement.outProperties().put("state", "DEPLOYED"); + intermediaryApi.sendAcElementInfo(instanceElement.instanceId(), instanceElement.elementId(), + null, null, instanceElement.outProperties()); + + intermediaryApi.updateAutomationCompositionElementState(instanceElement.instanceId(), + instanceElement.elementId(), DeployState.DEPLOYED, null, StateChangeResult.FAILED, "Undeploy failed!"); + } + } + + +*In all suggestions shown before we have used labels as "DEPLOY", "UNDEPLOY", "DEPLOYING", "UNDEPLOYING" but the developer can change them as better suit with the context of the participant.* + diff --git a/docs/clamp/acm/acm-states.rst b/docs/clamp/acm/acm-states.rst index a36825a5..a6cfc2e1 100644 --- a/docs/clamp/acm/acm-states.rst +++ b/docs/clamp/acm/acm-states.rst @@ -80,4 +80,59 @@ Delete .. image:: images/acm-states/AcInstanceStatesDelete.png +How State are saved in DB +========================= +Any state will be saved in DB as number: + +Participant Replica State +------------------------- + ++--------------------+------------+ +| ParticipantState | Database | ++====================+============+ +| ON_LINE | 0 | ++--------------------+------------+ +| OFF_LINE | 1 | ++--------------------+------------+ + + +Automation Composition Type State +--------------------------------- + ++----------------+------------+ +| AcTypeState | Database | ++================+============+ +| COMMISSIONED | 0 | ++----------------+------------+ +| PRIMING | 1 | ++----------------+------------+ +| PRIMED | 2 | ++----------------+------------+ +| DEPRIMING | 3 | ++----------------+------------+ + +Automation Composition Instance State +===================================== + ++---------------+------------+ +| DeployState | Database | ++===============+============+ +| DEPLOYED | 0 | ++---------------+------------+ +| DEPLOYING | 1 | ++---------------+------------+ +| UNDEPLOYED | 2 | ++---------------+------------+ +| UNDEPLOYING | 3 | ++---------------+------------+ +| DELETING | 4 | ++---------------+------------+ +| DELETED | 5 | ++---------------+------------+ +| UPDATING | 6 | ++---------------+------------+ +| MIGRATING | 7 | ++---------------+------------+ + + End of Document diff --git a/docs/clamp/acm/design-impl/clamp-runtime-acm.rst b/docs/clamp/acm/design-impl/clamp-runtime-acm.rst index c21cc171..ba73eb04 100644 --- a/docs/clamp/acm/design-impl/clamp-runtime-acm.rst +++ b/docs/clamp/acm/design-impl/clamp-runtime-acm.rst @@ -13,7 +13,7 @@ This article explains how CLAMP Automation Composition Runtime is implemented. Terminology *********** -- Broadcast message: a message for all participants (participantId=null) +- Broadcast message: a message for all participants (participantId=null and replicaId=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 @@ -32,13 +32,13 @@ Check CLAMP Runtime and Participants 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) +- ACM-runtime receives the call by Rest-Api (CommissioningController) - It triggers the execution to send a broadcast PARTICIPANT_STATUS_REQ message 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) +- ACM-runtime receives the call by Rest-Api (CommissioningController) - 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 @@ -46,7 +46,7 @@ Create of a Automation Composition Definition Type 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) +- ACM-runtime 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 @@ -55,7 +55,7 @@ Update of a Automation Composition 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) +- ACM-runtime 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 @@ -65,7 +65,7 @@ Priming of a Automation Composition Definition Type 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) +- ACM-runtime receives the call by Rest-Api (InstantiationController) - 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 @@ -74,7 +74,7 @@ Create of a Automation Composition 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) +- ACM-runtime receives the call by Rest-Api (InstantiationController) - It checks that AC Instance is in UNDEPLOYED/DEPLOYED deployState - It updates the Automation Composition to DB - the Rest-Api call returns the instanceId and the list of AC Element Instance @@ -84,7 +84,7 @@ Migrate of a Automation Composition Instance ++++++++++++++++++++++++++++++++++++++++++++ - GUI has already a new composition definition primed - 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, the compositionTargetId and the instanceId -- runtime-ACM receives the call by Rest-Api (InstantiationController) +- ACM-runtime receives the call by Rest-Api (InstantiationController) - It checks that AC Instance is in DEPLOYED deployState - It checks that compositionTargetId is related to a primed composition definition - It updates the Automation Composition to DB @@ -97,7 +97,7 @@ Issues AC instance to change status case **deployOrder: DEPLOY** - 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) +- ACM-runtime 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 @@ -106,7 +106,7 @@ case **deployOrder: DEPLOY** case **lockOrder: UNLOCK** - 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) +- ACM-runtime 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 @@ -115,7 +115,7 @@ case **lockOrder: UNLOCK** case **lockOrder: LOCK** - 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) +- ACM-runtime 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 @@ -124,7 +124,7 @@ case **lockOrder: LOCK** case **deployOrder: UNDEPLOY** - 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) +- ACM-runtime 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 @@ -133,7 +133,7 @@ case **deployOrder: UNDEPLOY** 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) +- ACM-runtime receives the call by Rest-Api (InstantiationController) - It checks that AC Instance is in UNDEPLOYED deployState - It updates the AC Instance to DB with DELETING deployState - It triggers the execution to send a broadcast AUTOMATION_COMPOSITION_STATE_CHANGE message @@ -142,7 +142,7 @@ Delete of a Automation Composition Instance 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) +- ACM-runtime 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 @@ -151,7 +151,7 @@ Depriming of a Automation Composition Definition Type 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) +- ACM-runtime 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 @@ -200,13 +200,13 @@ In state changes from UNDEPLOYED → DEPLOYED or LOCKED → UNLOCKED, Automation 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_DEPLOY message to all participants with startPhase = 0 +- ACM-runtime 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 +- ACM-runtime receives AUTOMATION_COMPOSITION_DEPLOY_ACK messages from participants and set the state (from the AC element of the message) to DEPLOYED +- ACM-runtime 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 +- ACM-runtime receives AUTOMATION_COMPOSITION_DEPLOY_ACK messages from participants and set the state (from the AC element of the message) to DEPLOYED +- ACM-runtime calculates that all AC elements are set to proper state and set AC to DEPLOYED In that scenario the message AUTOMATION_COMPOSITION_DEPLOY has been sent two times. @@ -216,7 +216,7 @@ Configure custom namings for TOSCA node types The node type of the AC element and the Automation composition can be customised as per the user requirement. These customised names can be used in the TOSCA node type definitions of AC element and composition. All the AC element and composition definitions (node templates) should be derived from the corresponding node types. -The following parameters are provided in the config file of runtime-acm for customisation: +The following parameters are provided in the config file of ACM-runtime for customisation: .. code-block:: YAML @@ -226,7 +226,7 @@ The following parameters are provided in the config file of runtime-acm for cust toscaCompositionName: customCompositionType If there are no values provided for customisation, the default node types "org.onap.policy.clamp.acm.AutomationCompositionElement" -and "org.onap.policy.clamp.acm.AutomationComposition" are used for the AC element and composition by the runtime-acm. +and "org.onap.policy.clamp.acm.AutomationComposition" are used for the AC element and composition by the ACM-runtime. In this case, the element and composition definition has to be derived from the same in the TOSCA. For overriding the names in the onap helm chart, the following properties can be updated in the values.yaml. @@ -242,23 +242,22 @@ Design of managing messages PARTICIPANT_REGISTER ++++++++++++++++++++ -- 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 +- A participant replica starts and send a PARTICIPANT_REGISTER message with participantId, replicaId and supported Element Types +- ACM-runtime collects the message from Message Broker by ParticipantRegisterListener +- if not present, it saves participant replica reference with status ON_LINE to DB PARTICIPANT_PRIME_ACK ++++++++++++++++++++++ - 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 +- If AC Definition is fully PRIMED, ACM-runtime sends sync message to all participants replica PARTICIPANT_STATUS ++++++++++++++++++ -- 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 +- A participant sends a scheduled PARTICIPANT_STATUS message with participantId, replicaId and supported Element Types +- ACM-runtime collects the message from Message Broker by ParticipantStatusListener +- if not present, it saves participant replica reference with status ON_LINE to DB AUTOMATION_COMPOSITION_DEPLOY_ACK +++++++++++++++++++++++++++++++++ @@ -284,26 +283,27 @@ Monitoring is designed to process the follow operations: - 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 delete AC Instance: in a scenario that "AutomationComposition.deployState" is in DELETING, if all - AC elements are moved properly to DELETED, the AC Instance will be deleted from 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 +- to retry AUTOMATION_COMPOSITION_DEPLOY/AUTOMATION_COMPOSITION_STATE_CHANGE messages. if there is an AC instance with startPhase completed, it will be moved to the next startPhase and retry a broadcast message with the new startPhase +- to send sync message to all participants replica: in scenario where AC instance transition is fully completed -The solution Design of retry, timeout, and reporting for all Participant message dialogues are implemented into the monitoring execution. +The solution Design timeout and reporting for all Participant message dialogues are implemented into the monitoring execution. -- Spring Scheduling inserts the task to monitor retry execution into ThreadPoolExecutor +- Spring Scheduling inserts the task to monitor timeout execution into ThreadPoolExecutor - ThreadPoolExecutor executes the task -- a message will be retry if runtime-ACM do no receive Act message before MaxWaitMs milliseconds +- set AC instance stateChangeResult in timeout, if ACM-runtime do no receive Act message before MaxWaitMs milliseconds Design of Exception handling **************************** GlobalControllerExceptionHandler ++++++++++++++++++++++++++++++++ -If error occurred during the Rest Api call, runtime-ACM responses with a proper status error code and a JSON message error. -This class is implemented to intercept and handle AutomationCompositionException, PfModelException and PfModelRuntimeException if they are thrown during the Rest Ali calls. +If error occurred during the Rest Api call, ACM-runtime responses with a proper status error code and a JSON message error. +This class is implemented to intercept and handle AutomationCompositionException and PfModelRuntimeException if they are thrown during the Rest Ali calls. All of those classes must implement ErrorResponseInfo that contains message error and status response code. So the Exception is converted in JSON message. RuntimeErrorController ++++++++++++++++++++++ -If wrong end-point is called or an Exception not intercepted by GlobalControllerExceptionHandler, runtime-ACM responses with a proper status error code and a JSON message error. +If wrong end-point is called or an Exception not intercepted by GlobalControllerExceptionHandler, ACM-runtime responses with a proper status error code and a JSON message error. This class is implemented to redirect the standard Web error page to a JSON message error. Typically that happen when a wrong end-point is called, but also could be happen for not authorized call, or any other Exception not intercepted by GlobalControllerExceptionHandler. @@ -313,7 +313,7 @@ RequestResponseLoggingFilter class handles version and "X-ONAP-RequestID" during Media Type Support ****************** -runtime-ACM Rest Api supports **application/json**, **application/yaml** and **text/plain** Media Types. The configuration is implemented in CoderHttpMesageConverter. +ACM-runtime Rest Api supports **application/json**, **application/yaml** and **text/plain** Media Types. The configuration is implemented in CoderHttpMesageConverter. application/json ++++++++++++++++ diff --git a/docs/clamp/acm/design-impl/participants/participant-intermediary.rst b/docs/clamp/acm/design-impl/participants/participant-intermediary.rst index 0fbaf897..493022d1 100644 --- a/docs/clamp/acm/design-impl/participants/participant-intermediary.rst +++ b/docs/clamp/acm/design-impl/participants/participant-intermediary.rst @@ -28,7 +28,7 @@ Inbound messages to participants - PARTICIPANT_STATUS_REQ: A status request received from clamp-acm runtime server to send an immediate ParticipantStatus from all participants - PROPERTIES_UPDATE: a message received from clamp-acm runtime server for updating the Ac instance property values - AUTOMATION_COMPOSITION_MIGRATION: a message received from clamp-acm runtime server for migrating the Ac instance from a composition definition to a composition definition target -- PARTICIPANT_RESTART: a message received from clamp-acm runtime server with tosca definitions and the Ac instances to handle restarting +- PARTICIPANT_SYNC_MSG: a message received from clamp-acm runtime server with tosca definitions and the Ac instances to handle synchronization Outbound messages ----------------- @@ -41,12 +41,12 @@ Outbound messages Design of a PARTICIPANT_REGISTER message ---------------------------------------- -- A participant starts and send a PARTICIPANT_REGISTER message with participantId and Supported Element Definition Types +- A participant starts and send a PARTICIPANT_REGISTER message with participantId, replicaId 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 - if participant is present in DB and there are AC Definitions related to the Participant, - it triggers the execution to send a PARTICIPANT_RESTART message to the participant restarted + it triggers the execution to send a PARTICIPANT_SYNC_MSG message to synchronize participant Design of a PARTICIPANT_DEREGISTER message ------------------------------------------ diff --git a/docs/clamp/acm/files/ACM-Message-Table.csv b/docs/clamp/acm/files/ACM-Message-Table.csv index b706fe60..da17374a 100755 --- a/docs/clamp/acm/files/ACM-Message-Table.csv +++ b/docs/clamp/acm/files/ACM-Message-Table.csv @@ -1,18 +1,23 @@ 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 +,,,,replicaId,The replica ID of this participant – in UUID format ,,,,participantSupportedElementTypes,A list of element types that this participant supports ,,,,messageType,Enum indicating the type of message PARTICIPANT_REGISTER ParticipantRegisterAck,ACM Runtime,Participant,Acknowledgment of Participant Registration,participantId,The ID of this participant – in UUID format +,,,,replicaId,The replica ID of this participant – in UUID format ,,,,messageType,Enum indicating the type of message PARTICIPANT_REGISTER_ACK ParticipantDeregister,Participant,ACM Runtime,Participant deregisters with the ACM runtime,participantId,The ID of this participant – in UUID format +,,,,replicaId,The replica ID of this participant – in UUID format ,,,,messageType,Enum indicating the type of message PARTICIPANT_DEREGISTER ParticipantDeregisterAck,ACM Runtime,Participant,Acknowledgment of Participant Deegistration,participantId,The ID of this participant – in UUID format +,,,,replicaId,The replica ID of this participant – in UUID format ,,,,messageType,Enum indicating the type of message PARTICIPANT_DEREGISTER_ACK ParticipantPrime,ACM Runtime,Participant,Trigger priming/depriming in the participant,participantId,The ID of this participant – in UUID format ,,,,compositionId,The id of the AC Definition related to this message ,,,,participantDefinitionUpdates,Contains AC element definition values for a particular participant ,,,,messageType,Enum indicating the type of message PARTICIPANT_PRIME ParticipantPrimeAck,Participant,ACM Runtime,Message to confirm participant has been primed/deprimed,participantId,The ID of this participant – in UUID format +,,,,replicaId,The replica ID of this participant – in UUID format ,,,,compositionId,The id of the AC Definition related to this message ,,,,stateChangeResult,NO_ERROR/FAILED ,,,,message,A message indicating the result @@ -20,17 +25,20 @@ ParticipantPrimeAck,Participant,ACM Runtime,Message to confirm participant has b 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 +,,,,replicaId,The replica ID of this participant – in UUID format ,,,,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 ,,,,messageType,Enum indicating the type of message PARTICIPANT_STATUS 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. +,,,,replicaId,The replica ID of this participant – in UUID format ,,,,compositionId,The id of the AC Definition related to this message ,,,,automationCompositionId,The id of the automation composition related to this message ,,,,startPhase,Integer indicating the start up order of the elements ,,,,participantId,UUID indicating the participant the message is intended for ,,,,messageType,Enum indicating the type of message AUTOMATION_COMPOSITION_DEPLOY 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" +,,,,replicaId,The replica ID of this participant – in UUID format ,,,,compositionId,The id of the AC Definition related to this message ,,,,automationCompositionId,The id of the automation composition related to this message ,,,,message,A message indicating the result @@ -48,11 +56,15 @@ PropertiesUpdate,ACM Runtime,Participant,Message to request update,participantUp ,,,,automationCompositionId,The id of the automation composition related to this message ,,,,participantId,UUID indicating the participant the message is intended for ,,,,messageType,Enum indicating the type of message PROPERTIES_UPDATE -ParticipantRestart,ACM Runtime,Participant,Message to request update,participantId,The ID of this participant – in UUID format -,,,,automationcompositionList,A list of ParticipantRestartAc instances which carries details of an updated participant. +ParticipantSync,ACM Runtime,Participant,Message to request sync,participantId,The ID of this participant – in UUID format +,,,,replicaId,The replica ID of this participant – in UUID format +,,,,excludeReplicas,The list of replica ID that can ignore the message – List of UUID +,,,,automationcompositionList,A list of ParticipantRestartAc instances which carries details of an updated instances for the participant. ,,,,compositionId,The id of the AC Definition related to this message -,,,,participantDefinitionUpdates,Contains AC element definition values for a particular participant -,,,,messageType,Enum indicating the type of message PARTICIPANT_RESTART +,,,,participantDefinitionUpdates,Contains AC element definition values for the participant +,,,,delete,Flag - if true it is a delete operation +,,,,restarting,Flag - if true it is a restarting scenario +,,,,messageType,Enum indicating the type of message PARTICIPANT_SYNC_MSG AutomationCompositionMigration,ACM Runtime,Participant,Message to request update,participantUpdatesList,A list of ParticipantUpdates instances which carries details of an updated participant. ,,,,compositionId,The id of the AC Definition related to this message ,,,,compositionTargetId,The id of the AC Definition target |