diff options
| -rw-r--r-- | docs/clamp/acm/acm-participant-guide.rst | 449 | ||||
| -rw-r--r-- | docs/clamp/acm/acm-user-guide.rst | 102 | ||||
| -rwxr-xr-x | docs/clamp/acm/allowed-operations.rst | 13 | ||||
| -rw-r--r-- | docs/clamp/acm/defining-acms.rst | 2 | ||||
| -rw-r--r-- | docs/clamp/acm/design-impl/participants/participant-intermediary.rst | 31 | ||||
| -rw-r--r-- | docs/clamp/acm/files/AC-migrate-precheck.json | 17 | ||||
| -rw-r--r-- | docs/clamp/acm/files/AC-prepare.json | 3 | ||||
| -rw-r--r-- | docs/clamp/acm/files/AC-review.json | 3 | ||||
| -rw-r--r-- | docs/clamp/acm/files/simparticipant-parameters.json | 26 |
9 files changed, 506 insertions, 140 deletions
diff --git a/docs/clamp/acm/acm-participant-guide.rst b/docs/clamp/acm/acm-participant-guide.rst index e1f6c2de..d46c5611 100644 --- a/docs/clamp/acm/acm-participant-guide.rst +++ b/docs/clamp/acm/acm-participant-guide.rst @@ -91,7 +91,7 @@ AutomationCompositionElementListener: Every participant should implement a handler class that implements the AutomationCompositionElementListener interface from the Participant Intermediary. The intermediary listener class listens for the incoming events from the ACM-runtime and invoke the handler class implementations for various operations. This class implements the methods for deploying, - undeploying, locking, unlocking , deleting, updating, migrating, priming, depriming requests that are coming from the ACM-runtime. + undeploying, locking, unlocking , deleting, updating, preparing, reviewing, migrating, migrationPrechecking, priming, depriming requests that are coming from the ACM-runtime. The methods are as follows. .. code-block:: java @@ -104,7 +104,10 @@ 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 migrate(CompositionElementDto compositionElement, CompositionElementDto compositionElementTarget, InstanceElementDto instanceElement, InstanceElementDto instanceElementMigrate) throws PfModelException; + 9. void migrate(CompositionElementDto compositionElement, CompositionElementDto compositionElementTarget, InstanceElementDto instanceElement, InstanceElementDto instanceElementMigrate, int stage) throws PfModelException; + 10. void migratePrecheck(CompositionElementDto compositionElement, CompositionElementDto compositionElementTarget, InstanceElementDto instanceElement, InstanceElementDto instanceElementMigrate) throws PfModelException; + 11. void review(CompositionElementDto compositionElement, InstanceElementDto instanceElement) throws PfModelException; + 12. void prepare(CompositionElementDto compositionElement, InstanceElementDto instanceElement) 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. @@ -117,92 +120,196 @@ ParticipantParameters: ParticipantIntermediaryParameters getIntermediaryParameters() -Abstract class AcElementListenerV1 ----------------------------------- -This abstract class is introduced to help to maintain the java backward compatibility with AutomationCompositionElementListener implemented in 7.1.0 version. -So developers can decide to align to new functionality later. Any new functionality in the future will be wrapped by this class. - -The Abstract class AcElementListenerV1 supports the follow methods. - -.. code-block:: java - 1. void undeploy(UUID instanceId, UUID elementId) throws PfModelException; - 2. void deploy(UUID instanceId, AcElementDeploy element, Map<String, Object> inProperties) throws PfModelException; - 3. void lock(UUID instanceId, UUID elementId) throws PfModelException; - 4. void unlock(UUID instanceId, UUID elementId) throws PfModelException; - 5. void delete(UUID instanceId, UUID elementId) throws PfModelException; - 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 migrate(UUID instanceId, AcElementDeploy element, UUID compositionTargetId, Map<String, Object> properties) throws PfModelException; +Abstract class AcElementListenerV3 +---------------------------------- +This abstract class is introduced to help to maintain the java backward compatibility with AutomationCompositionElementListener from new releases. +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 and deprime. +Default implementation are supported for the methods: lock, unlock, update, migrate, delete, prime, deprime, migratePrecheck, review and prepare. -Un example of AutomationCompositionElementHandler implemented in 7.1.0 version and how to use AcElementListenerV1 abstract class: -.. code-block:: java - - @Component - @RequiredArgsConstructor - public class AutomationCompositionElementHandler implements AutomationCompositionElementListener { +Methods: deploy, undeploy, lock, unlock, delete, review and prepare + compositionElement: + ====================== ======================================= + **field** **description** + ====================== ======================================= + compositionId composition definition Id + elementDefinitionId composition definition element Id + inProperties composition definition in-properties + outProperties composition definition out-properties + ====================== ======================================= + instanceElement: + ============================== =========================== + **field** **description** + ============================== =========================== + instanceId instance id + elementId instance element id + toscaServiceTemplateFragment policies and policy types + inProperties instance in-properties + outProperties instance out-properties + ============================== =========================== - private final ParticipantIntermediaryApi intermediaryApi; - private final otherService otherService; - .............................. - } +Method: update + compositionElement: + ====================== ======================================= + **field** **description** + ====================== ======================================= + compositionId composition definition Id + elementDefinitionId composition definition element Id + inProperties composition definition in-properties + outProperties composition definition out-properties + ====================== ======================================= + instanceElement: + ============================== ================================================ + **field** **description** + ============================== ================================================ + instanceId instance id + elementId instance element id + toscaServiceTemplateFragment + inProperties instance in-properties **(before the update)** + outProperties instance out-properties + ============================== ================================================ + instanceElementUpdated: + ============================== ====================================== + **field** **description** + ============================== ====================================== + instanceId instance id + elementId instance element id + toscaServiceTemplateFragment + inProperties instance in-properties **(updated)** + outProperties instance out-properties + ============================== ====================================== - @Component - public class AutomationCompositionElementHandler extends AcElementListenerV1 { +Methods: prime, deprime + composition: + ====================== =================================================================== + **field** **description** + ====================== =================================================================== + compositionId composition definition Id + inProperties composition definition in-properties for each definition element + outProperties composition definition out-properties for each definition element + ====================== =================================================================== - private final OtherService otherService; +Method: migratePrecheck + compositionElement: + ====================== ===================================================== + **field** **description** + ====================== ===================================================== + compositionId composition definition Id + elementDefinitionId composition definition element Id + inProperties composition definition in-properties + outProperties composition definition out-properties + state element state: PRESENT, NOT_PRESENT, REMOVED, NEW + ====================== ===================================================== + compositionElementTarget: + ====================== ===================================================== + **field** **description** + ====================== ===================================================== + compositionId composition definition target Id + elementDefinitionId composition definition target element Id + inProperties composition definition target in-properties + outProperties composition definition target out-properties + state element state: PRESENT, NOT_PRESENT, REMOVED, NEW + ====================== ===================================================== + instanceElement: + ============================== =================================================== + **field** **description** + ============================== =================================================== + instanceId instance id + elementId instance element id + toscaServiceTemplateFragment + inProperties instance in-properties **(before the migration)** + outProperties instance out-properties + state element state: PRESENT, NOT_PRESENT, REMOVED, NEW + ============================== =================================================== + instanceElementMigrate: + ============================== ==================================================== + **field** **description** + ============================== ==================================================== + instanceId instance id + elementId instance element id + toscaServiceTemplateFragment + inProperties instance in-properties **(updated)** + outProperties instance out-properties + state element state: PRESENT, NOT_PRESENT, REMOVED, NEW + ============================== ==================================================== - public AutomationCompositionElementHandler(ParticipantIntermediaryApi intermediaryApi, OtherService otherService) { - super(intermediaryApi); - this.otherService = otherService; - } - .............................. - } +Method: migrate + compositionElement: + ====================== ===================================================== + **field** **description** + ====================== ===================================================== + compositionId composition definition Id + elementDefinitionId composition definition element Id + inProperties composition definition in-properties + outProperties composition definition out-properties + state element state: PRESENT, NOT_PRESENT, REMOVED, NEW + ====================== ===================================================== + compositionElementTarget: + ====================== ===================================================== + **field** **description** + ====================== ===================================================== + compositionId composition definition target Id + elementDefinitionId composition definition target element Id + inProperties composition definition target in-properties + outProperties composition definition target out-properties + state element state: PRESENT, NOT_PRESENT, REMOVED, NEW + ====================== ===================================================== + instanceElement: + ============================== =================================================== + **field** **description** + ============================== =================================================== + instanceId instance id + elementId instance element id + toscaServiceTemplateFragment + inProperties instance in-properties **(before the migration)** + outProperties instance out-properties + state element state: PRESENT, NOT_PRESENT, REMOVED, NEW + ============================== =================================================== + instanceElementMigrate: + ============================== ==================================================== + **field** **description** + ============================== ==================================================== + instanceId instance id + elementId instance element id + toscaServiceTemplateFragment + inProperties instance in-properties **(updated)** + outProperties instance out-properties + state element state: PRESENT, NOT_PRESENT, REMOVED, NEW + ============================== ==================================================== + stage: + the stage of the migration that the participant has to execute +Abstract class AcElementListenerV2 +---------------------------------- +This abstract class is introduced to help to maintain temporarily the java backward compatibility with AutomationCompositionElementListener implemented in 8.0.0 version. +So developers can decide to align to new functionality later. Any new functionality in the future will be wrapped by this class. -A second example: +The Abstract class AcElementListenerV2 supports the follow methods. .. code-block:: java - @Component - public class AutomationCompositionElementHandler implements AutomationCompositionElementListener { - - @Autowired - private ParticipantIntermediaryApi intermediaryApi; - - @Autowired - private otherService otherService; - .............................. - } - - @Component - public class AutomationCompositionElementHandler extends AcElementListenerV1 { - - @Autowired - private otherService otherService; - - public AutomationCompositionElementHandler(ParticipantIntermediaryApi intermediaryApi) { - super(intermediaryApi); - } - .............................. - } - -Abstract class AcElementListenerV2 ----------------------------------- -This abstract class is introduced to help to maintain the java backward compatibility with AutomationCompositionElementListener from new releases. -Any new functionality in the future will be wrapped by this class. + 1. void deploy(CompositionElementDto compositionElement, InstanceElementDto instanceElement) throws PfModelException; + 2. void undeploy(CompositionElementDto compositionElement, InstanceElementDto instanceElement) throws PfModelException; + 3. void lock(CompositionElementDto compositionElement, InstanceElementDto instanceElement) throws PfModelException; + 4. void unlock(CompositionElementDto compositionElement, InstanceElementDto instanceElement) throws PfModelException; + 5. void delete(CompositionElementDto compositionElement, InstanceElementDto instanceElement) throws PfModelException; + 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 migrate(CompositionElementDto compositionElement, CompositionElementDto compositionElementTarget, InstanceElementDto instanceElement, InstanceElementDto instanceElementMigrate) throws PfModelException; + 10. void migratePrecheck(CompositionElementDto compositionElement, CompositionElementDto compositionElementTarget, InstanceElementDto instanceElement, InstanceElementDto instanceElementMigrate) throws PfModelException; + 11. void review(CompositionElementDto compositionElement, InstanceElementDto instanceElement) throws PfModelException; + 12. void prepare(CompositionElementDto compositionElement, InstanceElementDto instanceElement) 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 and deprime. +Default implementation are supported for the methods: lock, unlock, update, migrate, delete, prime, deprime, migratePrecheck, review and prepare. -Methods: deploy, undeploy, lock, unlock and delete +Methods: deploy, undeploy, lock, unlock, delete, review and prepare compositionElement: ====================== ======================================= **field** **description** @@ -264,7 +371,7 @@ Methods: prime, deprime outProperties composition definition out-properties for each definition element ====================== =================================================================== -Method: migrate +Method: migrate and migratePrecheck compositionElement: ====================== ======================================= **field** **description** @@ -304,6 +411,84 @@ Method: migrate outProperties instance out-properties ============================== ====================================== + +Abstract class AcElementListenerV1 +---------------------------------- +This abstract class is introduced to help to maintain temporarily the java backward compatibility with AutomationCompositionElementListener implemented in 7.1.0 version. +So developers can decide to align to new functionality later. Any new functionality in the future will be wrapped by this class. + +The Abstract class AcElementListenerV1 supports the follow methods. + +.. code-block:: java + + 1. void undeploy(UUID instanceId, UUID elementId) throws PfModelException; + 2. void deploy(UUID instanceId, AcElementDeploy element, Map<String, Object> inProperties) throws PfModelException; + 3. void lock(UUID instanceId, UUID elementId) throws PfModelException; + 4. void unlock(UUID instanceId, UUID elementId) throws PfModelException; + 5. void delete(UUID instanceId, UUID elementId) throws PfModelException; + 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 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, migratePrecheck, review and prepare. + +Un example of AutomationCompositionElementHandler implemented in 7.1.0 version and how to use AcElementListenerV1 abstract class: + +.. code-block:: java + + @Component + @RequiredArgsConstructor + public class AutomationCompositionElementHandler implements AutomationCompositionElementListener { + + private final ParticipantIntermediaryApi intermediaryApi; + private final otherService otherService; + .............................. + } + + @Component + public class AutomationCompositionElementHandler extends AcElementListenerV1 { + + private final OtherService otherService; + + public AutomationCompositionElementHandler(ParticipantIntermediaryApi intermediaryApi, OtherService otherService) { + super(intermediaryApi); + this.otherService = otherService; + } + .............................. + } + + + +A second example: + +.. code-block:: java + + @Component + public class AutomationCompositionElementHandler implements AutomationCompositionElementListener { + + @Autowired + private ParticipantIntermediaryApi intermediaryApi; + + @Autowired + private otherService otherService; + .............................. + } + + @Component + public class AutomationCompositionElementHandler extends AcElementListenerV1 { + + @Autowired + private otherService otherService; + + public AutomationCompositionElementHandler(ParticipantIntermediaryApi intermediaryApi) { + super(intermediaryApi); + } + .............................. + } + + APIs to invoke -------------- ParticipantIntermediaryApi: @@ -423,7 +608,7 @@ In/Out instance Properties * during DEPLOIYNG (Out Properties will be take from last changes matching by elementId) * during UNDEPLOING * during LOCKING/UNLOCKING - * during UPDATING/MIGRATING + * during UPDATING/MIGRATING/PREPARE/REVIEW/MIGRATION_PRECHECKING Participants will receive the in/out instance Properties related to the element by InstanceElementDto class. @@ -628,7 +813,7 @@ The following example shows the Handler implementation and how could be the impl @Override public void update(CompositionElementDto compositionElement, InstanceElementDto instanceElement, - InstanceElementDto instanceElementUpdated) throws PfModelException { + InstanceElementDto instanceElementUpdated) throws PfModelException { // TODO update process @@ -645,15 +830,25 @@ The following example shows the Handler implementation and how could be the impl @Override public void migrate(CompositionElementDto compositionElement, CompositionElementDto compositionElementTarget, - InstanceElementDto instanceElement, InstanceElementDto instanceElementMigrate) - throws PfModelException + InstanceElementDto instanceElement, InstanceElementDto instanceElementMigrate, int stage) + throws PfModelException - // TODO migrate process + switch (instanceElementMigrate.state()) { + case NEW -> // TODO new element scenario + case REMOVED -> // TODO element remove scenario + default -> // TODO migration process + } if (isMigrateSuccess()) { - intermediaryApi.updateAutomationCompositionElementState( - instanceElement.instanceId(), instanceElement.elementId(), - DeployState.DEPLOYED, null, StateChangeResult.NO_ERROR, "Migrated"); + if (isStageCompleted()) { + intermediaryApi.updateAutomationCompositionElementState( + instanceElement.instanceId(), instanceElement.elementId(), + DeployState.DEPLOYED, null, StateChangeResult.NO_ERROR, "Migrated"); + } else { + intermediaryApi.updateAutomationCompositionElementStage( + instanceElement.instanceId(), instanceElement.elementId(), + StateChangeResult.NO_ERROR, nextStage, "stage " + stage + " Migrated"); + } } else { intermediaryApi.updateAutomationCompositionElementState( instanceElement.instanceId(), instanceElement.elementId(), @@ -662,6 +857,36 @@ The following example shows the Handler implementation and how could be the impl } @Override + public void migratePrecheck(UUID instanceId, UUID elementId) throws PfModelException { + + // TODO migration Precheck process + + intermediaryApi.updateAutomationCompositionElementState( + instanceElement.instanceId(), instanceElement.elementId(), + DeployState.DEPLOYED, null, StateChangeResult.NO_ERROR, "Migration precheck completed"); + } + + @Override + public void prepare(UUID instanceId, UUID elementId) throws PfModelException { + + // TODO prepare process + + intermediaryApi.updateAutomationCompositionElementState( + instanceElement.instanceId(), instanceElement.elementId(), + DeployState.UNDEPLOYED, null, StateChangeResult.NO_ERROR, "Prepare completed"); + } + + @Override + public void review(UUID instanceId, UUID elementId) throws PfModelException { + + // TODO review process + + intermediaryApi.updateAutomationCompositionElementState( + instanceElement.instanceId(), instanceElement.elementId(), + DeployState.DEPLOYED, null, StateChangeResult.NO_ERROR, "Review completed"); + } + + @Override public void prime(CompositionDto composition) throws PfModelException { // TODO prime process @@ -705,37 +930,43 @@ Allowed state from the participant perspective | | 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 | -+------------+-----------------+---------------+----------------+----------------------------------------+ ++------------------+-----------------+---------------+----------------+----------------------------------+ +| **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 | Migration is completed | ++ Migrate +-----------------+---------------+----------------+----------------------------------+ +| | DEPLOYED | | FAILED | Migration is failed | ++------------------+-----------------+---------------+----------------+----------------------------------+ +| Migrate Precheck | DEPLOYED | | NO_ERROR | Migration-precheck is completed | ++------------------+-----------------+---------------+----------------+----------------------------------+ +| Prepare | UNDEPLOYED | | NO_ERROR | Prepare is completed | ++------------------+-----------------+---------------+----------------+----------------------------------+ +| Review | DEPLOYED | | NO_ERROR | Review is completed | ++------------------+-----------------+---------------+----------------+----------------------------------+ +| | DELETED | | NO_ERROR | Delete is completed | +| Delete +-----------------+---------------+----------------+----------------------------------+ +| | UNDEPLOYED | | FAILED | Delete is failed | ++------------------+-----------------+---------------+----------------+----------------------------------+ AC Element states in failure scenarios diff --git a/docs/clamp/acm/acm-user-guide.rst b/docs/clamp/acm/acm-user-guide.rst index 3c56f906..0f814b4b 100644 --- a/docs/clamp/acm/acm-user-guide.rst +++ b/docs/clamp/acm/acm-user-guide.rst @@ -232,6 +232,30 @@ Example payload to update the base url of the http request :language: json +Prepare AC instance +------------------- +Once the AC instance is created, the user can prepare the instance which in turn activates the corresponding participants to execute the intended operations. +In this case, the participants that support that action will be send the result by outProperties. + +.. code-block:: bash + + Invoke a PUT request + 'http://policy_runtime_ip:port/onap/policy/clamp/acm/v2/compositions/${compositionId}/instances/${instanceId}' + +This returns a 202 response on a successful prepare order request. The elements will be in "PREPARING" sub state until the completion. +The current status and result can be fetched through the following endpoint. + +.. code-block:: bash + + Invoke a GET request + 'http://policy_runtime_ip:port/onap/policy/clamp/acm/v2/compositions/${compositionId}/instances/${instanceId}' + +Request payload + +.. literalinclude:: files/AC-prepare.json + :language: json + + Deploy AC instance ------------------ Once the AC instance is created, the user can deploy the instance which in turn activates the corresponding participants to execute the intended operations. @@ -265,6 +289,29 @@ Once all the AC elements are deployed, there should be a test microservice pod r configured to send events on the kafka by the http participant. This can be verified on the test microservice application logs. The AC instances can also be undeployed and deleted by the user. +Review AC instance +------------------ +Once the AC instance is deployed, the user can review the instance which in turn activates the corresponding participants to execute the intended operations. +In this case, the participants that support that action will be send the result by outProperties. + +.. code-block:: bash + + Invoke a PUT request + 'http://policy_runtime_ip:port/onap/policy/clamp/acm/v2/compositions/${compositionId}/instances/${instanceId}' + +This returns a 202 response on a successful review order request. The elements will be in "REVIEWING" sub state until the completion. +The current status and result can be fetched through the following endpoint. + +.. code-block:: bash + + Invoke a GET request + 'http://policy_runtime_ip:port/onap/policy/clamp/acm/v2/compositions/${compositionId}/instances/${instanceId}' + +Request payload + +.. literalinclude:: files/AC-review.json + :language: json + Update AC instance properties after deployment (Optional) --------------------------------------------------------- After the AC instance is deployed, the user can still update the instance property values if needed. In this case, the runtime updates these new values @@ -279,10 +326,28 @@ required operation. Note: Please refer the request payload section for updating the instance properties before deployment. +Migrate-Precheck AC instance +---------------------------- +After the AC instance is deployed, the user can trigger a migrate-precheck from it to other composition definition. +The target composition have to be primed. +The user can emulate an update of the instance property values if needed. + +.. code-block:: bash + + Invoke a POST request + 'http://policy_runtime_ip:port/onap/policy/clamp/acm/v2/compositions/${compositionId}/instances' + +Request Payload + +Example payload to migrate-precheck + +.. literalinclude:: files/AC-migrate-precheck.json + :language: json + Migrate AC instance ------------------- After the AC instance is deployed, the user can migrate it to other composition definition. -The target composition have to be primed and have to contain the same element definitions present in the source composition. +The target composition have to be primed. The user can update the instance property values if needed. .. code-block:: bash @@ -324,8 +389,8 @@ This deletes the AC instance from the database including all the element propert This returns a 202 response on successful delete order request. -Deprime Ac defintions ---------------------- +Deprime Ac definitions +---------------------- Once the AC instance is deleted, it can be deprimed from the participants to be safely deleted from the database. .. code-block:: bash @@ -339,8 +404,8 @@ Request payload .. literalinclude:: files/AC-depriming.json :language: json -Delete AC defintion -------------------- +Delete AC definition +-------------------- The AC definitions can be deleted if there are no instances are running and it is not primed to the participants. .. code-block:: bash @@ -393,28 +458,8 @@ Parameters like delay and success/fail could be set any time using the following The Json below is an example of configuration: -.. code-block:: json - - { - "deploySuccess": true, - "undeploySuccess": true, - "lockSuccess": true, - "unlockSuccess": true, - "deleteSuccess": true, - "updateSuccess": true, - "migrateSuccess": true, - "primeSuccess": true, - "deprimeSuccess": true, - "deployTimerMs": 1000, - "undeployTimerMs": 1000, - "migrateTimerMs": 100, - "lockTimerMs": 100, - "unlockTimerMs": 100, - "updateTimerMs": 100, - "deleteTimerMs": 100, - "primeTimerMs": 100, - "deprimeTimerMs": 100 - } +.. literalinclude:: files/simparticipant-parameters.json + :language: json Update and send composition outProperites ----------------------------------------- @@ -504,6 +549,7 @@ Default value of 'element.handler' is the most recent version. ==================== ==================== AcElementHandlerV1 AcElementListenerV1 AcElementHandlerV2 AcElementListenerV2 +AcElementHandlerV3 AcElementListenerV3 ==================== ==================== Example: @@ -511,4 +557,4 @@ Example: .. code-block:: yaml element: - handler: AcElementHandlerV1 + handler: AcElementHandlerV3 diff --git a/docs/clamp/acm/allowed-operations.rst b/docs/clamp/acm/allowed-operations.rst index 62de7ffc..12fca00e 100755 --- a/docs/clamp/acm/allowed-operations.rst +++ b/docs/clamp/acm/allowed-operations.rst @@ -129,3 +129,16 @@ Change status of Automation Composition Instance + +-----------------+---------------+----------------+---------------------------------------------------------------------------------------------+
| | DEPLOYED | LOCKING | TIMEOUT | Start Unlocking transition and send unlock to participants after LOCKING got timeout |
+------------+-----------------+---------------+----------------+---------------------------------------------------------------------------------------------+
+
+Sub status of Automation Composition Instance
+---------------------------------------------
+
++---------------------+-----------------+---------------+-----------------------------------------------------------------------------------------------------+
+| **Action** | **deployState** | **lockState** | **Description** |
++---------------------+-----------------+---------------+-----------------------------------------------------------------------------------------------------+
+| Prepare | UNDEPLOYED | | Start Preparing transition and send prepare to participants |
++---------------------+-----------------+---------------+-----------------------------------------------------------------------------------------------------+
+| Review | DEPLOYED | LOCKED | Start Reviewing transition and send review to participants |
++---------------------+-----------------+---------------+-----------------------------------------------------------------------------------------------------+
+| Migration-Precheck | DEPLOYED | LOCKED | Start Migration-Prechecking transition and send Migration-Precheck to participants |
++---------------------+-----------------+---------------+-----------------------------------------------------------------------------------------------------+
diff --git a/docs/clamp/acm/defining-acms.rst b/docs/clamp/acm/defining-acms.rst index a9f2fbef..f2fb82e2 100644 --- a/docs/clamp/acm/defining-acms.rst +++ b/docs/clamp/acm/defining-acms.rst @@ -100,7 +100,7 @@ The Kubernetes Participant runs Kubernetes Automation Composition Elements. Each Element manages a Kubernetes microservice using Helm. The user defines the Helm chart for the Kubernetes microservice as well as other properties that the microservice requires in order to execute. The Yaml file that holds the -`Kubernetes Automation Composition Element Type defintion is available in Github +`Kubernetes Automation Composition Element Type definition is available in Github <https://github.com/onap/policy-clamp/blob/master/common/src/main/resources/tosca/KubernetesAutomationCompositionElementType.yaml>`_ and is the canonical definition of the Kubernetes Automation Composition Element type. For a description of the Kubernetes Automation Composition Element and Kubernetes Participant,please see diff --git a/docs/clamp/acm/design-impl/participants/participant-intermediary.rst b/docs/clamp/acm/design-impl/participants/participant-intermediary.rst index 493022d1..909ad263 100644 --- a/docs/clamp/acm/design-impl/participants/participant-intermediary.rst +++ b/docs/clamp/acm/design-impl/participants/participant-intermediary.rst @@ -24,10 +24,11 @@ Inbound messages to participants - 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_DEPLOY: a message received from clamp-acm runtime server for a clamp-acm deploy with clamp-acm instances +- AUTOMATION_COMPOSITION_PREPARE: a message received from clamp-acm runtime server for a clamp-acm prepare/review 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 - 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 +- AUTOMATION_COMPOSITION_MIGRATION: a message received from clamp-acm runtime server for migrating/migration-precheck the Ac instance from a composition definition to a composition definition target - PARTICIPANT_SYNC_MSG: a message received from clamp-acm runtime server with tosca definitions and the Ac instances to handle synchronization Outbound messages @@ -62,12 +63,20 @@ Prime of an Automation Composition Definition Type - 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 CacheProvider +- Each participant performs its designated job of prime 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 CacheProvider +- Each participant performs its designated job of deprime + +Design of "issues automation composition commands to automation compositions" - case PREPARE +-------------------------------------------------------------------------------------------- +- AUTOMATION_COMPOSITION_PREPARE message with instantiation details and PREPARE order state is sent to participants +- Participant-intermediary will receive AUTOMATION_COMPOSITION_PREPARE message and sends the details of AutomationCompositionElements to participants +- Each participant performs its designated job of prepare Design of "issues automation composition commands to automation compositions" - case UNDEPLOYED to DEPLOYED ----------------------------------------------------------------------------------------------------------- @@ -76,6 +85,12 @@ Design of "issues automation composition commands to automation compositions" - - 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 REVIEW +------------------------------------------------------------------------------------------- +- AUTOMATION_COMPOSITION_PREPARE message with instantiation details and REVIEW order state is sent to participants +- Participant-intermediary will receive AUTOMATION_COMPOSITION_PREPARE message and sends the details of AutomationCompositionElements to participants +- Each participant performs its designated job of review + Design of "issues automation composition commands to automation compositions" - case DEPLOYED to UNDEPLOYED ----------------------------------------------------------------------------------------------------------- - AUTOMATION_COMPOSITION_STATE_CHANGE message with instantiation details and UNDEPLOY order state is sent to participants @@ -89,24 +104,35 @@ Update of an Automation Composition Instance - it triggers the execution to send a broadcast PROPERTIES_UPDATE message - the message is built by AcElementPropertiesPublisher using the REST request payload (to fill the list of elements with the updated property values) - Participant-intermediary will receive a PROPERTIES_UPDATE message and stores the updated values of the elements on CacheProvider +- Each participant performs its designated job of update by interacting with respective frameworks + +Migrate-precheck of an Automation Composition Instance +------------------------------------------------------ +- it triggers the execution to send a broadcast AUTOMATION_COMPOSITION_MIGRATION message with precheck set to true +- the message is built by AutomationCompositionMigrationPublisher using the REST request payload (to fill the compositionTargetId and list of elements with the updated property values) +- Participant-intermediary will receive a AUTOMATION_COMPOSITION_MIGRATION message and use a copy of the instance from CacheProvider to merge with data from the message +- Each participant performs its designated job of migrate-precheck Migrate of an Automation Composition Instance --------------------------------------------- - AC-runtime saves the compositionTargetId and updates the instance properties of the deployed Ac instances -- it triggers the execution to send a broadcast AUTOMATION_COMPOSITION_MIGRATION message +- it triggers the execution to send a broadcast AUTOMATION_COMPOSITION_MIGRATION message with precheck set to false - the message is built by AutomationCompositionMigrationPublisher using the REST request payload (to fill the compositionTargetId and list of elements with the updated property values) - Participant-intermediary will receive a AUTOMATION_COMPOSITION_MIGRATION message and stores the compositionTargetId and the updated values of the elements on CacheProvider +- Each participant performs its designated job of migrate by interacting with respective frameworks Design of "issues automation composition commands to automation compositions" - case LOCKED to UNLOCKED ------------------------------------------------------------------------------------------------------- - 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 +- Each participant performs its designated job of unlock Design of "issues automation composition commands to automation compositions" - case UNLOCKED to LOCKED ------------------------------------------------------------------------------------------------------- - AUTOMATION_COMPOSITION_STATE_CHANGE message with instantiation details and LOCK order state is sent to participants - Participant-intermediary validates the current lockState change +- Each participant performs its designated job of lock Design of Delete - case UNDEPLOYED to DELETED --------------------------------------------- @@ -115,6 +141,7 @@ Design of Delete - case UNDEPLOYED to DELETED - Participant-intermediary will receive AUTOMATION_COMPOSITION_STATE_CHANGE message and sends AC-element details to participants - Each participant performs its designated job of removing instantiation data if not done in undeployment - Participant-intermediary will remove instantiation data +- Each participant performs its designated job of delete Design of a PARTICIPANT_STATUS_REQ message ------------------------------------------ diff --git a/docs/clamp/acm/files/AC-migrate-precheck.json b/docs/clamp/acm/files/AC-migrate-precheck.json new file mode 100644 index 00000000..66ab17df --- /dev/null +++ b/docs/clamp/acm/files/AC-migrate-precheck.json @@ -0,0 +1,17 @@ +{ + "name": "DemoInstance0", + "version": "1.0.1", + "compositionId": "COMPOSITIONIDPLACEHOLDER", + "instanceId": "INSTANCEIDPLACEHOLDER", + "compositionTargetId": "COMPOSITIONIDTARGET", + "description": "Demo automation composition instance 0", + "precheck": true, + "elements": { + "709c62b3-8918-41b9-a747-d21eb79c6c21": { + "id": "709c62b3-8918-41b9-a747-d21eb79c6c21", + "properties": { + "baseUrl": "http://acm-starter-ac-element-impl_updated:8084" + } + } + } +} diff --git a/docs/clamp/acm/files/AC-prepare.json b/docs/clamp/acm/files/AC-prepare.json new file mode 100644 index 00000000..bc3a3c0a --- /dev/null +++ b/docs/clamp/acm/files/AC-prepare.json @@ -0,0 +1,3 @@ +{ + "subOrder": "PREPARE" +} diff --git a/docs/clamp/acm/files/AC-review.json b/docs/clamp/acm/files/AC-review.json new file mode 100644 index 00000000..e4d74348 --- /dev/null +++ b/docs/clamp/acm/files/AC-review.json @@ -0,0 +1,3 @@ +{ + "subOrder": "REVIEW" +} diff --git a/docs/clamp/acm/files/simparticipant-parameters.json b/docs/clamp/acm/files/simparticipant-parameters.json new file mode 100644 index 00000000..14fbe01a --- /dev/null +++ b/docs/clamp/acm/files/simparticipant-parameters.json @@ -0,0 +1,26 @@ +{ + "deploySuccess": true, + "undeploySuccess": true, + "lockSuccess": true, + "unlockSuccess": true, + "deleteSuccess": true, + "updateSuccess": true, + "migrateSuccess": true, + "migratePrecheck": true, + "prepare": true, + "review": true, + "primeSuccess": true, + "deprimeSuccess": true, + "deployTimerMs": 100, + "undeployTimerMs": 100, + "lockTimerMs": 100, + "unlockTimerMs": 100, + "updateTimerMs": 100, + "migrateTimerMs": 100, + "migratePrecheckTimerMs": 100, + "prepareTimerMs": 100, + "reviewTimerMs": 100, + "deleteTimerMs": 100, + "primeTimerMs": 100, + "deprimeTimerMs": 100 +} |