diff options
Diffstat (limited to 'docs/clamp/acm/design-impl')
| -rw-r--r-- | docs/clamp/acm/design-impl/clamp-gui-acm.rst | 140 | ||||
| -rw-r--r-- | docs/clamp/acm/design-impl/clamp-runtime-acm.rst | 182 | ||||
| -rw-r--r-- | docs/clamp/acm/design-impl/design-impl.rst | 1 | ||||
| -rw-r--r-- | docs/clamp/acm/design-impl/participants/participant-intermediary.rst | 55 |
4 files changed, 184 insertions, 194 deletions
diff --git a/docs/clamp/acm/design-impl/clamp-gui-acm.rst b/docs/clamp/acm/design-impl/clamp-gui-acm.rst deleted file mode 100644 index 600c721d..00000000 --- a/docs/clamp/acm/design-impl/clamp-gui-acm.rst +++ /dev/null @@ -1,140 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. - -.. _clamp-gui-acm: - -The Policy GUI for Automation Compositions -****************************************** - -.. contents:: - :depth: 4 - -.. _Introduction: - -1. Introduction -############### -The Policy GUI for Automation Compositions is designed to provide a user the ability to interact with the Automation Composition Runtime to perform several actions. The actual technical design of the Automation Composition Runtime is detailed in :ref:`clamp-runtime-acm`. All of the endpoints and the purpose for accessing those endpoints is discussed there. In the current release of the GUI, the main purposes are to perform the below: - -- Commission new Tosca Service Templates. -- Editing Common Properties. -- Priming/De-priming Automation Composition Definitions. -- Decommission existing Tosca Service Templates. -- Create new instances of Automation Compositions. -- Change the state of the Automation Compositions. -- Delete Automation Compositions. - -These functions can be carried out by accessing the Automation Composition Runtime alone but this should not be required for a typical user to access the system. That is why the Automation Composition GUI is required. The remainder of this document will be split into 2 main sections. The first section will show the overall architecture of Automation Composition with the GUI included, so that the reader can see where it fits in to the system. Then the section will outline the individual components required for a working GUI and outline how GUI interacts with these components and why. The final section has a diagram to show the flow of typical operations from the GUI, all the way down to the participants. - -2. GUI-focussed System Architecture -################################### -An architectural/functional diagram has bee provided in below. This does not show details of the other components involved in the GUI functionality. Most of the detail is provided for the GUI itself. - - .. image:: ../images/gui/GUI-Architecture.png - :align: center - -The remainder of this section outlines the different elements that comprise the architecture of the GUI and how the different elements connect to one another. - -2.1 Policy CLAMP GUI --------------------- - -2.1.1 CLAMP GUI -================ -The original Clamp project used the GUI to connect to various onap services, including policy api, policy pap, dcae, sdc and cds. Connection to all of these services is managed by the Camel Exchange present in the section :ref:`Policy Clamp Backend`. - -Class-based react components are used to render the different pages related to functionality around - -- Creating loop instances from existing templates that have been distributed by SDC. -- Deploying/Undeploying policies to the policy framework. -- Deploying/Undeploying microservices to the policy framework. -- Deleting Instances. - - -2.1.2 Automation Composition GUI -================================ - -The current automation composition GUI is an extension of the previously created GUI for the Clamp project. The Clamp project used the CLAMP GUI to connect to various onap services, including policy api, policy pap, dcae, sdc and cds. Although the current automation composition project builds upon this GUI, it does not rely on these connected services. Instead, the Automation Composition GUI connects to the Automation Composition Runtime only. The Automation Composition Runtime then communicates with the database and all the Automation Composition participants (indirectly) over Kafka. - -The CLAMP GUI was originally housed in the clamp repository but for the Istanbul release, it has been moved to the policy/gui repo. There are 3 different GUIs within this repository - clamp-gui (and Automation Composition gui) code is housed under the "gui-clamp" directory and the majority of development takes place within the "gui-clamp/ui-react" directory. - -The original CLAMP GUI was created using the React framework, which is a light-weight framework that promotes use of component-based architecture. Previously, a class-based style was adopted to create the Clamp components. It was decided that Automation Composition would opt for the more concise functional style of components. This architecture style allows for the logical separation of functionality into different components and minimizes bloat. As you can see from the image, there is a "Automation Composition" directory under components where all of our Automation Composition components are housed. - - .. image:: ../images/gui/ComponentFileStructure.png - -Any code that is directly involved in communication with outside services like Rest Apis is under "ui-react/src/api". The "fetch" Javascript library is used for these calls. The Automation Composition service communicates with just the Automation Composition Runtime Rest Api, so all of the communication code is within "ui-react/src/api/AutomationCompositionService.js". - -2.1.2.1 Services -"""""""""""""""" -The Automation Composition GUI is designed to be service-centric. This means that the code involved in rendering and manipulating data is housed in a different place to the code responsible for communication with outside services. The Automation Composition related services are those responsible for making calls to the commissioning and instantiation endpoints in the Automation Composition Runtime. Another detail to note is that both the Automation Composition and CLAMP GUI use a proxy to forward requests to the policy clamp backend. Any URLs called by the frontend that contain the path "restservices/clds/v2/" are forwarded to the backend. Services are detailed below: - -- A commissioning call is provided for contacting the commissioning API to commission a tosca service template. -- A decommissioning call is provided for calling the decommissioning endpoint. -- A call to retrieve the tosca service template from the runtime is provided. This is useful for carrying out manipulations on the template, such as editing the common properties. -- A call to get the common or instance properties is provided. This is used to provide the user an opportunity to edit these properties. -- Calls to allow creation and deletion of an instance are provided -- Calls to change the state of and instance are provided. -- Calls to get the current state and ordered state of the instances, effectively monitoring. - -These services provide the data and communication functionality to allow the user to perform all of the actions mentioned in the :ref:`Introduction`. - -2.1.2.2 Components -"""""""""""""""""" -The components in the architecture image reflect those rendered elements that are presented to the user. Each element is designed to be as user-friendly as possible, providing the user with clean uncluttered information. Note that all of these components relate to and were designed around specific system dialogues that are present in :ref:`system-level-label`. - -- For commissioning, the user is provided with a simple file upload. This is something the user will have seen many times before and is self explanatory. -- For the edit of common properties, a JSON editor is used to present whatever common properties that are present in the service template to the user in as simple a way possible. The user can then edit, save and recommission. -- A link is provided to manage the tosca service template, where the user can view the file that has been uploaded in JSON format and optionally delete it. -- Several functions are exposed to the user in the "Manage Instances" modal. From there they can trigger, creation of an instance, view monitoring information, delete an instance and change the state. -- Before an instance is created, the user is provided an opportunity to edit the instance properties. That is, those properties that have not been marked as common. -- The user can change the state of the instance by using the "Change" button on the "Manage Instances" modal. This is effectively where the user can deploy and undeploy an instance. -- Priming and De-priming take place as a result of the action of commissioning and decommissioning a tosca service template. A more complete discussion of priming and de-priming is found here :ref:`acm-participant-protocol-label`. -- As part of the "Manage Instances" modal, we can monitor the state of the instances in 2 ways. The color of the instance highlight in the table indicates the state (grey - uninitialised, passive - yellow, green - running). Also, there is a monitoring button that allows use to view the individual elements' state. - -.. _Policy Clamp Backend: - -2.2 Policy Clamp Backend ------------------------- -The only Rest API that the Automation Composition frontend (and CLAMP frontend) communicates with directly is the Clamp backend. The backend is written in the Springboot framework and has many functions. In this document, we will only discuss the Automation Composition related functionality. Further description of non-acm Clamp and its' architecture can be found in :ref:`architecture-label`. The backend receives the calls from the frontend and forwards the requests to other relevant APIs. In the case of the Automation Composition project, the only Rest API that it currently requires communication with is the runtime Automation Composition API. Automation Composition adopts the same "request forwarding" method as the non-acm elements in the CLAMP GUI. This forwarding is performed by Apache Camel Exchanges, which are specified in XML and can be found in the directory shown below in the Clamp repository. - - .. image:: ../images/gui/CamelDirectory.png - -The Rest Endpoints for the GUI to call are defined in "clamp-api-v2.xml" and all of the runtime Automation Composition rest endpoints that GUI requests are forwarded to are defined in acm-flows.xml. If an Endpoint is added to the runtime Automation Composition component, or some other component you wish the GUI to communicate with, a Camel XML exchange must be defined for it here. - -2.3 Automation Composition Runtime ----------------------------------- -This is where all of the endpoints for operations on Automation Compositions are defined thus far. Commissioning, decommissioning, automation composition creation, automation composition state change and automation composition deletion are all performed here. The component is written using the Springboot framework and all of the code is housed in the runtime-acm directory shown below: - - .. image:: ../images/gui/RuntimeAcmDirectory.png - -The rest endpoints are split over two main classes; CommissioningController.java and InstantiationController.java. There are also some rest endpoints defined in the MonitoringQueryController. These classes have minimal business logic defined in them and delegate these operations to other classes within the controlloop.runtime package. The Automation Composition Runtime write all data received on its' endpoints regarding commissioning and instantiation to its; database, where it can be easily accessed later by the UI. - -The Runtime also communicates with the participants over Kafka. Commissioning a automation composition definition writes it to the database but also triggers priming of the definitions over Kafka. The participants then receive those definitions and hold them in memory. Similarly, upon decommissioning, a message is sent over Kafka to the participants to trigger de-priming. - -Using Kafka, the Runtime can send; updates to the automation composition definitions, change the state of automation compositions, receive information about participants, receive state information about automation compositions and effectively supervise the automation compositions. This data is then made available via Rest APIs that can be queried by the frontend. This is how the GUI can perform monitoring operations. - -More detail on the design of the Runtime Automation Composition can be found in :ref:`clamp-runtime-acm`. - -2.4 Kafka ---------- -Kafka is component that provides data movement services that transports and processes data from any source to any target. It provides the capability to: -- Support the transfer of messages between ONAP components, as well as to other components -- Support the transfer of data between ONAP components as well as to other components. -- Data Filtering capabilities -- Data Processing capabilities -- Data routing (file based transport) -- Message routing (event based transport) -- Batch and event based processing - -Specifically, regarding the communication between the Automation Composition Runtime and the Automation Composition Participants, both components publish and subscribe to a specific topic, over which data and updates from the participants and automation compositions are sent. The Automation Composition Runtime updates the current statuses sent from the participants in the database and makes them available the the GUI over the Rest API. - -2.5 The Participants --------------------- -The purpose of the Automation Composition participants is to communicate with different services on behalf of the Automation Composition Runtime. As there are potentially many different services that a Automation Composition might require access to, there can be many different participants. For example, the kubernetes participant is responsible for carrying out operations on a kubernetes cluster with helm. As of the time of writing, there are three participants defined for the Automation Composition project; the policy participant, the kubernetes participant and the http participant. The participants are housed in the directory shown below in the policy-clamp repo. - - .. image:: ../images/gui/ParticipantsDirectory.png - -The participants communicate with the Runtime over Kafka. Tosca service template specifications, Automation Composition updates and state changes are shared with the participants via messages from runtime Automation Composition through the topic "POLICY-CLRUNTIME-PARTICIPANT". - -3. GUI Sample Flows -################### -The primary flows from the GUI to the backend, through Kafka and the participants are shown in the diagram below. This diagram just serves as an illustration of the scenarios that the user will experience in the GUI. You can see factually complete dialogues in :ref:`system-level-label`. - - .. image:: ../images/gui/GUI-Flow.png diff --git a/docs/clamp/acm/design-impl/clamp-runtime-acm.rst b/docs/clamp/acm/design-impl/clamp-runtime-acm.rst index c21cc171..46d4a85f 100644 --- a/docs/clamp/acm/design-impl/clamp-runtime-acm.rst +++ b/docs/clamp/acm/design-impl/clamp-runtime-acm.rst @@ -13,12 +13,12 @@ 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 - MessageIntercept: "@MessageIntercept" annotation is used into SupervisionHandler class to intercept "handleParticipantMessage" method calls using spring aspect oriented programming -- GUI: swagger-ui, Postman or policy-gui +- GUI: swagger-ui or Postman - Message Broker: It supports the message Broker Kafka Design of Rest Api @@ -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,17 +74,28 @@ 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 - the runtime sends an update event to the participants which performs the update operation on the deployed instances. +Migrate-Precheck 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 +- 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 only set the subState of the Automation Composition to DB +- the Rest-Api call returns the instanceId and the list of AC Element Instance +- the runtime sends a migrate-precheck event to the participants which performs the check operation on the deployed instances. + 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 @@ -94,19 +105,37 @@ Migrate of a Automation Composition Instance Issues AC instance to change status +++++++++++++++++++++++++++++++++++ +case **subOrder: PREPARE** + +- GUI calls "/onap/policy/clamp/acm/v2/compositions/{compositionId}/instances/{instanceId}" endpoint with PREPARE as subOrder +- 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 PREPARING subState +- It triggers the execution to send a broadcast AUTOMATION_COMPOSITION_PREPARE message with preDeploy set to true +- the message is built by AcPreparePublisher using Instance data. + 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 - the message is built by AutomationCompositionDeployPublisher using Tosca Service Template data and Instance data. (with startPhase = first startPhase) +case **subOrder: REVIEW** + +- GUI calls "/onap/policy/clamp/acm/v2/compositions/{compositionId}/instances/{instanceId}" endpoint with REVIEW as subOrder +- ACM-runtime receives the call by Rest-Api (InstantiationController) +- It validates the status order issued (related AC Instance has DEPLOYED as deployState) +- It updates the AC Instance to DB with REVIEWING subState +- It triggers the execution to send a broadcast AUTOMATION_COMPOSITION_PREPARE message with preDeploy set to false +- the message is built by AcPreparePublisher using Instance data. + 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 +144,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 +153,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 +162,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 +171,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 +180,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,23 +229,98 @@ 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. +Migration using Stage +********************* +The stage is particularly important in Automation Composition migration because sometime the user wishes to control +not only the order in which the state changes in Automation Composition Elements but also to execute again using the same Automation Composition Elements. + +How to define Stage ++++++++++++++++++++ +Stage is defined as shown below in the Definition of TOSCA fundamental Automation Composition Types yaml file. + +.. code-block:: YAML + + stage: + type: list + required: false + description: A list indicating the stages in which this automation composition element will be started, the + first stage is zero. Automation Composition Elements are started in their stage order. + Automation Composition Elements with the same stage are started simultaneously. + metadata: + common: true + +Example where it could be used: + +.. code-block:: YAML + + org.onap.domain.database.Http_PMSHMicroserviceAutomationCompositionElement: + # Consul http config for PMSH. + version: 1.2.3 + type: org.onap.policy.clamp.acm.HttpAutomationCompositionElement + type_version: 1.0.1 + description: Automation Composition element for the http requests of PMSH microservice + properties: + provider: ONAP + uninitializedToPassiveTimeout: 180 + stage: [0,2] + +How Stage works ++++++++++++++++ +In state changes in MIGRATING Automation Composition elements starts in increasing order from stage 0. + +Example of MIGRATE order with Http_PMSHMicroserviceAutomationCompositionElement with stage [0,2] and PMSH_K8SMicroserviceAutomationCompositionElement with startPhase to [0,1]: + +- ACM-runtime sends a broadcast AUTOMATION_COMPOSITION_MIGRATION message to all participants with stage = 0 +- participant receives the AUTOMATION_COMPOSITION_MIGRATION message and runs to DEPLOYED state (only AC elements that contains stage 0: Http_PMSHMicroserviceAutomationCompositionElement and PMSH_K8SMicroserviceAutomationCompositionElement) +- 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 stage = 0 are set to proper state and sends a broadcast AUTOMATION_COMPOSITION_MIGRATION message with stage = 1 +- participant receives the AUTOMATION_COMPOSITION_MIGRATION message and runs to DEPLOYED state (only AC elements that contains stage 1: PMSH_K8SMicroserviceAutomationCompositionElement) +- 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 stage = 1 are set to proper state and sends a broadcast AUTOMATION_COMPOSITION_MIGRATION message with stage = 2 +- participant receives the AUTOMATION_COMPOSITION_MIGRATION message and runs to DEPLOYED state (only AC elements that contains stage 2: Http_PMSHMicroserviceAutomationCompositionElement) +- 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_MIGRATION has been sent three times, +Http_PMSHMicroserviceAutomationCompositionElement and PMSH_K8SMicroserviceAutomationCompositionElement will be executed two times. + +Add and remove elements during Migration +**************************************** +When an AC instance is migrated to a new AC definition, the user has the flexibility to add a new element or remove an existing element from the instance. +The target AC composition definition should contain the new element definition added and also the respective elements removed while commissioning to ACM-R. +The new elements are further instantiated in the migration request with the instance properties, and the elements required to be undeployed are removed accordingly. +ACM-R sends the updated element list in the migration request to the participants where the participant is expected to handle the add/remove scenario. +The migration method on the participant receives the details of previously existed composition/instance as well as the updated composition/instance and hence the difference in the new and old properties for an +element can be identified by the participant. +Participants can also identify the newly added elements and the removed elements with the ElementState enum that is set for each element. + +Example: + For a newly added element in the migration, the element information about the previously existed element will contain the ElementState enum set to the value "NOT_PRESENT" by the intermediary, and the updated element object will contain the + ElementState value "NEW". Based on these enum values on both the objects, the participant can identify a new element added in the migration. The participant can choose to trigger a deployment of this new element and update the element state once the + deploy operation is complete. + + For the elements that are removed in the migration, the element information about the previously existed element will contain the ElementState enum set to the value "PRESENT" by the intermediary, and the object for the updated element info will contain the + ElementState value "REMOVED". Based on this, the participant can identify a removed element in the migration and choose to trigger an undeployment of this element. The element state after the undeploy operation need not be updated to ACM-R as the element is already removed in the ACM-R. + The participant is also expected to trigger a "DELETE" operation for the removed element if required in order to delete any element OutProperties if stored in the memory. Similarly, The element state after the delete operation need not be updated to ACM-R for the removed element. + + 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 +330,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 +346,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 +387,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 +417,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/design-impl.rst b/docs/clamp/acm/design-impl/design-impl.rst index 3c56ff91..2b8a3fad 100644 --- a/docs/clamp/acm/design-impl/design-impl.rst +++ b/docs/clamp/acm/design-impl/design-impl.rst @@ -11,5 +11,4 @@ The sections below describe the components that handle TOSCA Automation Composit :maxdepth: 1 clamp-runtime-acm - clamp-gui-acm participants/participants diff --git a/docs/clamp/acm/design-impl/participants/participant-intermediary.rst b/docs/clamp/acm/design-impl/participants/participant-intermediary.rst index 0fbaf897..92ab6d42 100644 --- a/docs/clamp/acm/design-impl/participants/participant-intermediary.rst +++ b/docs/clamp/acm/design-impl/participants/participant-intermediary.rst @@ -24,11 +24,12 @@ 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 -- PARTICIPANT_RESTART: a message received from clamp-acm runtime server with tosca definitions and the Ac instances to handle restarting +- 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 ----------------- @@ -41,33 +42,41 @@ Outbound messages Design of a PARTICIPANT_REGISTER message ---------------------------------------- -- A participant starts and send a PARTICIPANT_REGISTER message with participantId and Supported Element Definition Types -- in AC-runtime ParticipantRegisterListener collects the message from Message Broker +- A participant starts and send a PARTICIPANT_REGISTER message with participantId, replicaId and Supported Element Definition Types +- in ACM-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 ------------------------------------------ - A participant is going to close and undeploys all AC-elements and send a PARTICIPANT_DEREGISTER message -- in AC-runtime, ParticipantDeregisterListener collects the message from Message Broker +- in ACM-runtime, ParticipantDeregisterListener collects the message from Message Broker - It saves participant reference with status OFF_LINE to DB - It triggers the execution to send a PARTICIPANT_DEREGISTER_ACK message to the participant deregistered - Participant is not monitored. Prime of an Automation Composition Definition Type -------------------------------------------------- -- AC-runtime assigns the AC Definition to the participants based of Supported Element Definition Type by participant +- ACM-runtime assigns the AC Definition to the participants based of Supported Element Definition Type by participant - it triggers the execution to send a broadcast PARTICIPANT_PRIME message - the message is built by ParticipantPrimePublisher using Tosca Service Template data (to fill the list of ParticipantDefinition) - Participant-intermediary will receive a PARTICIPANT_PRIME message and stores the Tosca Service Template data on 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 +- ACM-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 @@ -85,28 +100,40 @@ Design of "issues automation composition commands to automation compositions" - Update of an Automation Composition Instance -------------------------------------------- -- AC-runtime updates the instance properties of the deployed Ac instances +- ACM-runtime updates the instance properties of the deployed Ac instances - 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 +- ACM-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 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 +- Participant-intermediary will receive AUTOMATION_COMPOSITION_STATE_CHANGE message +- Each participant performs its designated job of lock Design of Delete - case UNDEPLOYED to DELETED --------------------------------------------- @@ -118,7 +145,7 @@ Design of Delete - case UNDEPLOYED to DELETED Design of a PARTICIPANT_STATUS_REQ message ------------------------------------------ -- AC-runtime triggers the execution to send a broadcast PARTICIPANT_STATUS_REQ message or to send it to a specific participant +- ACM-runtime triggers the execution to send a broadcast PARTICIPANT_STATUS_REQ message or to send it to a specific participant - the message is built by ParticipantStatusReqPublisher - Participant-intermediary will receive a PARTICIPANT_STATUS_REQ message @@ -132,7 +159,7 @@ Design of a AUTOMATION_COMPOSITION_DEPLOY_ACK message ----------------------------------------------------- - A participant sends AUTOMATION_COMPOSITION_DEPLOY_ACK message in response to a AUTOMATION_COMPOSITION_DEPLOY message. - For each AC-elements moved to the ordered state as indicated by the AUTOMATION_COMPOSITION_DEPLOY -- AutomationCompositionUpdateAckListener in AC-runtime collects the messages from Message Broker +- AutomationCompositionUpdateAckListener in ACM-runtime collects the messages from Message Broker - It checks the deployStatus of all automation composition elements - It updates the AC-instance in DB accordingly @@ -140,6 +167,6 @@ Design of a AUTOMATIONCOMPOSITION_STATECHANGE_ACK message --------------------------------------------------------- - A participant sends AUTOMATIONCOMPOSITION_STATECHANGE_ACK message in response to a AUTOMATIONCOMPOSITION_STATECHANGE message. - For each AC-elements moved to the ordered state as indicated by the AUTOMATIONCOMPOSITION_STATECHANGE -- AutomationCompositionStateChangeAckListener in AC-runtime collects the messages from Message Broker +- AutomationCompositionStateChangeAckListener in ACM-runtime collects the messages from Message Broker - It checks the deployStatus/lockStatus of all automation composition elements - It updates the AC-instance in DB accordingly |