diff options
Diffstat (limited to 'docs')
64 files changed, 1476 insertions, 1556 deletions
diff --git a/docs/_static/logo_onap_2024.png b/docs/_static/logo_onap_2024.png Binary files differnew file mode 100644 index 00000000..55d307fc --- /dev/null +++ b/docs/_static/logo_onap_2024.png diff --git a/docs/apex/APEX-MyFirstPolicyExample.rst b/docs/apex/APEX-MyFirstPolicyExample.rst index 089ead02..d58eeb1d 100644 --- a/docs/apex/APEX-MyFirstPolicyExample.rst +++ b/docs/apex/APEX-MyFirstPolicyExample.rst @@ -39,7 +39,10 @@ Introduction In this document we will show how APEX and APEX Policies can be used to achieve this, starting with a simple policy, building up to more complicated policy - that demonstrates the features of APEX. + that demonstrates the features of APEX. This example demonstrates + the data models, events and task logics that can be considered + for the scenario. From Oslo release, only apex cli editor can be used + for generating the policies. Data Models ^^^^^^^^^^^ @@ -270,28 +273,6 @@ New Policy Model define many Policy Models, each containing a different set of policies. - .. container:: paragraph - - So the first step is to create a new empty Policy Model - called ``MyFirstPolicyModel``. Using the APEX Policy - Editor, click on the 'File' menus and select 'New'. Then - define our new policy model called - ``MyFirstPolicyModel``. Use the 'Generate UUID' button to - create a new unique ID for the policy model, and fill in - a description for the policy model. Press the ``Submit`` - button to save your changes. - - .. container:: imageblock - - .. container:: content - - |File > New to create a new Policy Model| - - .. container:: imageblock - - .. container:: content - - |Create a new Policy Model| Events ------ @@ -300,45 +281,14 @@ Events .. container:: sect1 - .. rubric:: Create the input event ``SALE_INPUT`` and the + .. rubric:: Define the input event ``SALE_INPUT`` and the output event ``SALE_AUTH`` :name: create_the_input_event_code_sale_input_code_and_the_output_event_code_sale_auth_code .. container:: paragraph - Using the APEX Policy Editor, click on the 'Events' tab. - In the 'Events' pane, right click and select 'New': - - .. container:: imageblock - - .. container:: content - - |Right click to create a new event| - - .. container:: paragraph - - Create a new event type called ``SALE_INPUT``. Use the - 'Generate UUID' button to create a new unique ID for the - event type, and fill in a description for the event. Add - a namespace, e.g. ``com.hyperm``. We can add hard-coded - strings for the ``Source`` and ``Target``, e.g. ``POS`` - and ``APEX``. At this stage we will not add any parameter - fields, we will leave this until later. Use the - ``Submit`` button to create the event. - - .. container:: imageblock - - .. container:: content - - |Fill in the necessary information for the - 'SALE_INPUT' event and click 'Submit'| - - .. container:: paragraph + Define the new event types called ``SALE_INPUT`` and ``SALE_AUTH``. - Repeat the same steps for a new event type called - ``SALE_AUTH``. Just use ``APEX`` as source and ``POS`` as - target, since this is the output event coming from APEX - going to the sales point. .. container:: paragraph @@ -348,18 +298,6 @@ Events .. container:: paragraph - To create new item schemas, click on the 'Context Item - Schemas' tab. In that 'Context Item Schemas' pane, right - click and select 'Create new ContextSchema'. - - .. container:: imageblock - - .. container:: content - - |Right click to create a new Item Schema| - - .. container:: paragraph - Create item schemas with the following characteristics, each with its own unique UUID: @@ -411,20 +349,6 @@ Events | | | | values | +-----------------+-----------------+-----------------+-----------------+ - .. container:: imageblock - - .. container:: content - - |Create a new Item Schema| - - .. container:: paragraph - - The item schemas can now be seen on the 'Context Item - Schemas' tab, and can be updated at any time by - right-clicking on the item schemas on the 'Context Item - Schemas' tab. Now we can go back to the event definitions - for ``SALE_INPUT`` and ``SALE_AUTH`` and add some - parameter fields. .. TIP:: @@ -443,16 +367,12 @@ Events .. container:: paragraph - ``Avro`` schema definitions can be any valid `Avro <https://avro.apac - he.org/docs/current/spec.html>`__ schema. For events using fields defined with + ``Avro`` schema definitions can be any valid `Avro <https://avro.apache.org/docs/1.12.0/specification/>`__ schema. For events using fields defined with Avro schemas, any incoming event containing that field must contain a value that conforms to the Avro schema. .. container:: paragraph - Click on the 'Events' tab, then right click the - ``SALE_INPUT`` row and select 'Edit Event - :literal:`SALE_INPUT’. To add a new event parameter use the 'Add Event Parameter' button at the bottom of the screen. For the `SALE_INPUT` - event add the following event parameters: + Add the following event parameters: .. table:: Table 2. Event Parameter Fields for the ``SALE_INPUT`` Event @@ -476,10 +396,6 @@ Events | notes | notes_type | *yes* | +----------------------+----------------------+-----------------------+ - .. container:: paragraph - - Remember to click the 'Submit' button at the bottom of - the event definition pane. .. TIP:: @@ -490,16 +406,10 @@ Events passed to APEX. If an *optional* field is not set for an output event then value will be set to ``null``. - .. container:: imageblock - - .. container:: content - - |Add new event parameters to an event| .. container:: paragraph - Select the ``SALE_AUTH`` event and add the following - event parameters: + Add the following event parameters for ``SALE_AUTH`` event: .. table:: Table 3. Event Parameter Fields for the ``SALE_AUTH`` Event @@ -527,10 +437,6 @@ Events | notes | notes_type | *yes* | +----------------------+----------------------+-----------------------+ - .. container:: paragraph - - Remember to click the 'Submit' button at the bottom of - the event definition pane. .. container:: paragraph @@ -569,32 +475,8 @@ New Policy .. container:: paragraph Therefore, to create a new policy we must first define - one or more tasks. - - .. container:: paragraph - - To create a new Task click on the 'Tasks' tab. In the - 'Tasks' pane, right click and select 'Create new Task'. - Create a new Task called ``MorningBoozeCheck``. Use the - 'Generate UUID' button to create a new unique ID for the - task, and fill in a description for the task. - - .. container:: imageblock - - .. container:: content - - |Right click to create a new task| - - .. container:: paragraph - - Tasks are configured with a set of *input fields* and a - set of *output fields*. To add new input/output fields - for a task use the 'Add Task Input Field' and 'Add Task - Output Field' button. The list of input and out fields to - add for the ``MorningBoozeCheck`` task are given below. - The input fields are drawn from the parameters in the - state’s input event, and the task’s output fields are - used to populate the state’s output event. The task’s + one or more tasks. Tasks are configured with a set of + *input fields* and a set of *output fields*. The task’s input and output fields must be a subset of the event parameters defined for the input and output events for any state that uses that task. (You may have noticed that @@ -651,11 +533,6 @@ New Policy | notes | notes_type | +-----------------------------------+-----------------------------------+ - .. container:: imageblock - - .. container:: content - - |Add input and out fields for the task| .. container:: paragraph @@ -687,12 +564,6 @@ New Policy Programmers Guide. - .. container:: imageblock - - .. container:: content - - |Add task logic the task| - .. container:: paragraph An alternative version of the same logic is available in @@ -701,40 +572,17 @@ New Policy .. container:: paragraph - The task definition is now complete so click the 'Submit' - button to save the task. The task can now be seen on the - 'Tasks' tab, and can be updated at any time by - right-clicking on the task on the 'Task' tab. Now that we + The task definition is now complete. Now that we have created our task, we can can create a policy that uses that task. .. container:: paragraph - To create a new Policy click on the 'Policies' tab. In - the 'Policies' pane, right click and select 'Create new - Policy': - - .. container:: paragraph - - Create a new Policy called ``MyFirstPolicy``. Use the - 'Generate UUID' button to create a new unique ID for the - policy, and fill in a description for the policy. Use - 'FREEFORM' as the 'Policy Flavour'. - - .. container:: paragraph - - Each policy must have at least one state. Since this is + Create a new Policy called ``MyFirstPolicy``.Each policy + must have at least one state. Since this is 'freeform' policy we can add as many states as we wish. Let’s start with one state. Add a new state called - ``BoozeAuthDecide`` to this ``MyFirstPolicy`` policy - using the 'Add new State' button after filling in the - name of our new state. - - .. container:: imageblock - - .. container:: content - - |Create a new policy| + ``BoozeAuthDecide`` to this ``MyFirstPolicy`` policy. .. container:: paragraph @@ -754,17 +602,11 @@ New Policy will automatically select ``SALE_INPUT`` as the 'Policy Trigger Event' for our policy. - .. container:: imageblock - - .. container:: content - - |Create a state| .. container:: paragraph In this case we will create a reference the pre-existing - ``MorningBoozeCheck`` task that we defined above using - the 'Add New Task' button. Select the + ``MorningBoozeCheck`` task that we defined above. Select the ``MorningBoozeCheck`` task, and use the name of the task as the 'Local Name' for the task. @@ -832,57 +674,6 @@ New Policy ``MorningBoozeCheck`` task directly into outgoing ``SALE_AUTH`` events.) - .. container:: imageblock - - .. container:: content - - |Add a Task and Output Mapping| - - .. container:: paragraph - - Click the 'Submit' button to complete the definition of - our ``MyFirstPolicy`` policy. The policy - ``MyFirstPolicy`` can now be seen in the list of policies - on the 'Policies' tab, and can be updated at any time by - right-clicking on the policy on the 'Policies' tab. - - .. container:: paragraph - - The ``MyFirstPolicyModel``, including our - ``MyFirstPolicy`` policy can now be checked for errors. - Click on the 'Model' menu and select 'Validate'. The - model should validate without any 'Warning' or 'Error' - messages. If you see any 'Error' or 'Warning' messages, - carefully read the message as a hint to find where you - might have made a mistake when defining some aspect of - your policy model. - - .. container:: imageblock - - .. container:: content - - |Validate the policy model for error using the 'Model' - > 'Validate' menu item| - - .. container:: paragraph - - Congratulations, you have now completed your first APEX - policy. The policy model containing our new policy can - now be exported from the editor and saved. Click on the - 'File' menu and select 'Download' to save the policy - model in JSON format. The exported policy model is then - available in the directory you selected, for instance - ``$APEX_HOME/examples/models/MyFirstPolicy/1/MyFirstPolicyModel_0.0.1.json``. - The exported policy can now be loaded into the APEX - Policy Engine, or can be re-loaded and edited by the APEX - Policy Editor. - - .. container:: imageblock - - .. container:: content - - |Download the completed policy model using the 'File' - > 'Download' menu item| Test The Policy --------------- @@ -961,7 +752,7 @@ CLI Editor File .. container:: paragraph An equivalent version of the ``MyFirstPolicyModel`` - policy model can again be generated using the APEX CLI + policy model can be generated using the APEX CLI editor. A sample APEX CLI script is shown below: .. container:: ulist @@ -1013,14 +804,8 @@ Extend Policy Model .. container:: paragraph - To create a new Task click on the 'Tasks' tab. In the - 'Tasks' pane, right click and select 'Create new Task': - - .. container:: paragraph - - Create a new Task called ``MorningBoozeCheckAlt1``. Use - the 'Generate UUID' button to create a new unique ID for - the task, and fill in a description for the task. Select + Create a new Task called ``MorningBoozeCheckAlt1``. Create a + new unique ID for the task, and fill in a description for the task. Use the same input and output fields that we used earlier when we defined the ``MorningBoozeCheck`` task earlier. @@ -1099,49 +884,13 @@ Extend Policy Model of the other supported languages please refer to APEX Programmers Guide. - .. container:: imageblock - - .. container:: content - - |Create a new alternative task - \`MorningBoozeCheckAlt1\`| - .. container:: paragraph - The task definition is now complete so click the 'Submit' - button to save the task. Now that we have created our + The task definition is now complete. Now that we have created our task, we can can add this task to the single pre-existing state (``BoozeAuthDecide``) in our policy. - .. container:: paragraph - To edit the ``BoozeAuthDecide`` state in our policy click - on the 'Policies' tab. In the 'Policies' pane, right - click on our ``MyFirstPolicy`` policy and select 'Edit'. - Navigate to the ``BoozeAuthDecide`` state in the 'states' - section at the bottom of the policy definition pane. - - .. container:: imageblock - - .. container:: content - - |Right click to edit a policy| - - .. container:: paragraph - - To add our new task ``MorningBoozeCheckAlt1``, scroll - down to the ``BoozeAuthDecide`` state in the 'States' - section. In the 'State Tasks' section for - ``BoozeAuthDecide`` use the 'Add new task' button. Select - our new ``MorningBoozeCheckAlt1`` task, and use the name - of the task as the 'Local Name' for the task. The - ``MorningBoozeCheckAlt1`` task can reuse the same - ``MorningBoozeCheck_Output_Direct`` 'Direct State Output - Mapping' that we used for the ``MorningBoozeCheck`` task. - (Recall that the role of the 'State Output Mapping' is to - select the output event for the state, and select the - next state to be executed. These both remain the same as - before.) .. container:: paragraph @@ -1164,18 +913,13 @@ Extend Policy Model logic using the ```JavaScript`` <https://en.wikipedia.org/wiki/JavaScript>`__ scripting language. Sample task selection logic code - is given here (|policy2_taskSelectionLogic_link|). Paste the script text into the 'Task - Selection Logic' box, and use "JAVASCRIPT" as the 'Task - Selection Logic Type / Flavour'. It is necessary to mark + is given here (|policy2_taskSelectionLogic_link|). It is necessary to mark one of the tasks as the 'Default Task' so that the task selection logic always has a fallback default option in cases where a particular task cannot be selected. In this case the ``MorningBoozeCheck`` task can be the default task. - - .. container:: imageblock - .. container:: content |State definition with 2 Tasks and Task Selection @@ -1183,13 +927,6 @@ Extend Policy Model .. container:: paragraph - When complete don’t forget to click the 'Submit' button - at the bottom of 'Policies' pane for our - ``MyFirstPolicy`` policy after updating the - ``BoozeAuthDecide`` state. - - .. container:: paragraph - Congratulations, you have now completed the second step towards your first APEX policy. The policy model containing our new policy can again be validated and @@ -1197,11 +934,9 @@ Extend Policy Model .. container:: paragraph - The exported policy model is then available in the - directory you selected, as **MyFirstPolicyModel_0.0.1.json**. - The exported policy can now be loaded into the APEX - Policy Engine, or can be re-loaded and edited by the APEX - Policy Editor. + Congratulations, you have now completed the second step + towards your first APEX policy.The policy can now be loaded into the APEX + Policy Engine. Test The Policy --------------- @@ -1289,7 +1024,7 @@ CLI Editor File .. container:: paragraph An equivalent version of the ``MyFirstPolicyModel`` - policy model can again be generated using the APEX CLI + policy model can be generated using the APEX CLI editor. A sample APEX CLI script is shown below: .. container:: ulist @@ -1303,23 +1038,6 @@ CLI Editor File 2.3.0-SNAPSHOT Last updated 2020-04-03 16:04:24 IST -.. |File > New to create a new Policy Model| image:: images/mfp/MyFirstPolicy_P1_newPolicyModel1.png -.. |Create a new Policy Model| image:: images/mfp/MyFirstPolicy_P1_newPolicyModel2.png -.. |Right click to create a new event| image:: images/mfp/MyFirstPolicy_P1_newEvent1.png -.. |Fill in the necessary information for the 'SALE_INPUT' event and click 'Submit'| image:: images/mfp/MyFirstPolicy_P1_newEvent2.png -.. |Right click to create a new Item Schema| image:: images/mfp/MyFirstPolicy_P1_newItemSchema1.png -.. |Create a new Item Schema| image:: images/mfp/MyFirstPolicy_P1_newItemSchema2.png -.. |Add new event parameters to an event| image:: images/mfp/MyFirstPolicy_P1_newEvent3.png -.. |Right click to create a new task| image:: images/mfp/MyFirstPolicy_P1_newTask1.png -.. |Add input and out fields for the task| image:: images/mfp/MyFirstPolicy_P1_newTask2.png -.. |Add task logic the task| image:: images/mfp/MyFirstPolicy_P1_newTask3.png -.. |Create a new policy| image:: images/mfp/MyFirstPolicy_P1_newPolicy1.png -.. |Create a state| image:: images/mfp/MyFirstPolicy_P1_newState1.png -.. |Add a Task and Output Mapping| image:: images/mfp/MyFirstPolicy_P1_newState2.png -.. |Validate the policy model for error using the 'Model' > 'Validate' menu item| image:: images/mfp/MyFirstPolicy_P1_validatePolicyModel.png -.. |Download the completed policy model using the 'File' > 'Download' menu item| image:: images/mfp/MyFirstPolicy_P1_exportPolicyModel1.png -.. |Create a new alternative task `MorningBoozeCheckAlt1`| image:: images/mfp/MyFirstPolicy_P2_newTask1.png -.. |Right click to edit a policy| image:: images/mfp/MyFirstPolicy_P2_editPolicy1.png .. |State definition with 2 Tasks and Task Selection Logic| image:: images/mfp/MyFirstPolicy_P2_editState1.png .. |taskLogicMvel_link| raw:: html diff --git a/docs/apex/APEX-Policy-Guide.rst b/docs/apex/APEX-Policy-Guide.rst index a9dad1c6..60468917 100644 --- a/docs/apex/APEX-Policy-Guide.rst +++ b/docs/apex/APEX-Policy-Guide.rst @@ -145,7 +145,7 @@ APEX Policy Model .. container:: paragraph The APEX policy model is shown in UML notation in the figure below. A policy model can be stored in JSON or XML - format in a file or can be held in a database. The APEX editor creates and modifies APEX policy models. APEX + format in a file or can be held in a database. The APEX Cli editor creates and modifies APEX policy models. APEX deployment deploys policy models, and a policy model is loaded into APEX engines so that the engines can run the policies in the policy model. @@ -327,7 +327,7 @@ Concept: ContextMap The set of context that is available for use by the policies of a *PolicyModel* is defined as *ContextMap* concept instances. The *PolicyModel* holds a map of all the *ContextMap* definitions. A *ContextMap* is itself a container for a group of related context items, each of which is represented by a *ContextItem* concept instance. *ContextMap* - concepts are keyed with an ``ArtifactKey`` key. A developer can use the APEX Policy Editor to create context maps for + concepts are keyed with an ``ArtifactKey`` key. A developer can use the APEX Policy Cli Editor to create context maps for their application domain. .. container:: paragraph diff --git a/docs/apex/APEX-User-Manual.rst b/docs/apex/APEX-User-Manual.rst index 8a4996b1..81e5cd1f 100644 --- a/docs/apex/APEX-User-Manual.rst +++ b/docs/apex/APEX-User-Manual.rst @@ -2099,7 +2099,7 @@ Configure Context Schema Handler are supported. Characters commonly used in field names, such as ``.`` and ``-``, are not supported by AVRO. for more information see `Avro Spec: - Names <https://avro.apache.org/docs/1.8.1/spec.html#names>`__. + Names <https://avro.apache.org/docs/1.12.0/specification/>`__. .. container:: paragraph diff --git a/docs/clamp/acm/acm-architecture.rst b/docs/clamp/acm/acm-architecture.rst index c3e7d568..82753c2e 100644 --- a/docs/clamp/acm/acm-architecture.rst +++ b/docs/clamp/acm/acm-architecture.rst @@ -311,7 +311,7 @@ deletions are not allowed on Automation Composition Types that have instances de The Instantiation component manages the Life Cycle Management of Automation Composition Instances and their Automation Composition Elements. It publishes a REST interface that is used to create Automation Composition Instances and set values for Common and Instance Specific properties. This REST interface is -public and is used by the ACM GUI. It may also be used by any other client via the public +public. It may also be used by any other client via the public REST interface. The REST interface also allows the state of Automation Composition Instances to be changed. A user can change the state of Automation Composition Instances as described in the state transition diagram shown in section 2 above. The Instantiation component issues update and state change @@ -496,6 +496,5 @@ The design and implementation of TOSCA Automation Compositions in CLAMP is descr #. :ref:`The CLAMP Automation Composition Runtime Server <clamp-runtime-acm>` #. :ref:`CLAMP Automation Composition Participants <clamp-acm-participants>` -#. :ref:`Managing Automation Compositions using The CLAMP GUI <clamp-gui-acm>` End of Document diff --git a/docs/clamp/acm/acm-participant-guide.rst b/docs/clamp/acm/acm-participant-guide.rst index 49eaee7f..56710a4c 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. - -Un example of AutomationCompositionElementHandler implemented in 7.1.0 version and how to use AcElementListenerV1 abstract class: +Default implementation are supported for the methods: lock, unlock, update, migrate, delete, prime, deprime, migratePrecheck, review and prepare. -.. 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: @@ -339,6 +524,7 @@ This following methods are invoked to update the AC element state or AC element 1. void updateAutomationCompositionElementState(UUID instanceId, UUID elementId, DeployState deployState, LockState lockState, StateChangeResult stateChangeResult, String message); 2. void updateCompositionState(UUID compositionId, AcTypeState state, StateChangeResult stateChangeResult, String message); + 3. void updateAutomationCompositionElementStage(UUID instance, UUID elementId, StateChangeResult stateChangeResult, int stage, String message); In/Out composition Properties ----------------------------- @@ -423,7 +609,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. @@ -544,7 +730,7 @@ The following example shows the Handler implementation and how could be the impl .. code-block:: java @Component - public class AutomationCompositionElementHandler extends AcElementListenerV2 { + public class AutomationCompositionElementHandler extends AcElementListenerV3 { @Override public void deploy(CompositionElementDto compositionElement, InstanceElementDto instanceElement) @@ -628,7 +814,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 +831,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 +858,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 @@ -690,6 +916,60 @@ The following example shows the Handler implementation and how could be the impl } +Allowed state from the participant perspective +---------------------------------------------- + ++------------+--------------+---------------------+-------------------------+ +| **Action** | **state** | **stChResult** | **Description** | ++------------+--------------+---------------------+-------------------------+ +| | PRIMED | NO_ERROR | Prime is completed | ++ Prime +--------------+---------------------+-------------------------+ +| | COMMISSIONED | FAILED | Prime is failed | ++------------+--------------+---------------------+-------------------------+ +| | COMMISSIONED | NO_ERROR | Deprime is completed | ++ Deprime +--------------+---------------------+-------------------------+ +| | PRIMED | FAILED | Deprime is failed | ++------------+--------------+---------------------+-------------------------+ + ++------------------+-----------------+---------------+----------------+----------------------------------+ +| **Action** | **deployState** | **lockState** | **stChResult** | **Description** | ++------------------+-----------------+---------------+----------------+----------------------------------+ +| | DEPLOYED | | NO_ERROR | Deploy is completed | ++ Deploy +-----------------+---------------+----------------+----------------------------------+ +| | UNDEPLOYED | | FAILED | Deploy is failed | ++------------------+-----------------+---------------+----------------+----------------------------------+ +| | UNDEPLOYED | | NO_ERROR | Undeploy is completed | +| Undeploy +-----------------+---------------+----------------+----------------------------------+ +| | DEPLOYED | | FAILED | Undeploy is failed | ++------------------+-----------------+---------------+----------------+----------------------------------+ +| | | LOCKED | NO_ERROR | Lock is completed | ++ Lock +-----------------+---------------+----------------+----------------------------------+ +| | | UNLOCKED | FAILED | Lock is failed | ++------------------+-----------------+---------------+----------------+----------------------------------+ +| | | UNLOCKED | NO_ERROR | Unlock is completed | ++ Unlock +-----------------+---------------+----------------+----------------------------------+ +| | | LOCKED | FAILED | Unlock is failed | ++------------------+-----------------+---------------+----------------+----------------------------------+ +| | DEPLOYED | | NO_ERROR | Update is completed | +| Update +-----------------+---------------+----------------+----------------------------------+ +| | DEPLOYED | | FAILED | Update is failed | ++------------------+-----------------+---------------+----------------+----------------------------------+ +| | DEPLOYED | | NO_ERROR | 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 -------------------------------------- @@ -728,6 +1008,179 @@ Migrate fails Deployed Considering the above mentioned behavior of the participant Intermediary, it is the responsibility of the developer to tackle the error scenarios in the participant with the suitable approach. -Tips: -If the participant tries to undeploy an element which doesn’t exist in the system any more (due to various other external factors), -it could update the element state to ‘undeployed’ using the Intermediary api. +Handle states and failure scenarios from the participant perspective +-------------------------------------------------------------------- + +It is important to make distinction between the state of the instance/element flow, and the state of the application/configuration involved. +A deployed element means that a participant has completed a deploy action, and should not be confused with a deployed application. +Example with two elements: + +1. an instance is deployed, so the two elements are DEPLOYED +2. user calls undeploy command (ACM-R sets all element as DEPLOYING) +3. participant executes the first instance element with success and sends UNDEPLOYED state +4. participant executes the second instance element with fail and sends DEPLOYED state +5. user calls undeploy command again (ACM-R sets all element as DEPLOYING) +6. participant does not know that the application related to the first element is already UNDEPLOYED when the flow state is UNDEPLOYING + +There are some contexts in a failure scenario that the participant need to know the state of the deployed application. +From participant side, using "outProperties" it could be possible to handle custom states that better suit whit the context. + +Example of a participant that deploy/undeploy applications. +The following Java code shows how to implement deploy and undeploy that avoid to repeat the action already executed. + +.. code-block:: java + + @Override + public void deploy(CompositionElementDto compositionElement, InstanceElementDto instanceElement) + throws PfModelException { + + if ("DEPLOYED".equals(instanceElement.outProperties().get("state"))) { + // deploy process already done + intermediaryApi.updateAutomationCompositionElementState(instanceElement.instanceId(), + instanceElement.elementId(), DeployState.DEPLOYED, null, StateChangeResult.NO_ERROR, + "Already Deployed"); + return; + } + + // deployment process + ....................................... + ....................................... + // end of the deployment process + + if (isDeploySuccess()) { + instanceElement.outProperties().put("state", "DEPLOYED"); + intermediaryApi.sendAcElementInfo(instanceElement.instanceId(), instanceElement.elementId(), + null, null, instanceElement.outProperties()); + + intermediaryApi.updateAutomationCompositionElementState(instanceElement.instanceId(), + instanceElement.elementId(), DeployState.DEPLOYED, null, StateChangeResult.NO_ERROR, "Deployed"); + } else { + instanceElement.outProperties().put("state", "UNDEPLOYED"); + intermediaryApi.sendAcElementInfo(instanceElement.instanceId(), instanceElement.elementId(), + null, null, instanceElement.outProperties()); + + intermediaryApi.updateAutomationCompositionElementState(instanceElement.instanceId(), + instanceElement.elementId(), DeployState.UNDEPLOYED, null, StateChangeResult.FAILED, "Deploy failed!"); + } + } + + @Override + public void undeploy(CompositionElementDto compositionElement, InstanceElementDto instanceElement) + throws PfModelException { + + if ("DEPLOYED".equals(instanceElement.outProperties().get("state"))) { + // undeploy process already done + + intermediaryApi.updateAutomationCompositionElementState(instanceElement.instanceId(), + instanceElement.elementId(), DeployState.UNDEPLOYED, null, StateChangeResult.NO_ERROR, + "Already Undeployed"); + return; + } + + // undeployment process + ....................................... + ....................................... + // end of the undeployment process + + if (isUndeploySuccess()) { + instanceElement.outProperties().put("state", "UNDEPLOYED"); + intermediaryApi.sendAcElementInfo(instanceElement.instanceId(), instanceElement.elementId(), + null, null, instanceElement.outProperties()); + + intermediaryApi.updateAutomationCompositionElementState(instanceElement.instanceId(), + instanceElement.elementId(), DeployState.UNDEPLOYED, null, StateChangeResult.NO_ERROR, "Undeployed"); + } else { + instanceElement.outProperties().put("state", "DEPLOYED"); + intermediaryApi.sendAcElementInfo(instanceElement.instanceId(), instanceElement.elementId(), + null, null, instanceElement.outProperties()); + + intermediaryApi.updateAutomationCompositionElementState(instanceElement.instanceId(), + instanceElement.elementId(), DeployState.DEPLOYED, null, StateChangeResult.FAILED, "Undeploy failed!"); + } + } + + +Example of a participant that make configurations. +The following Java code shows how to implement deploy and undeploy that needs a clean up and repeat the action. +The state of the configuration will saved in outProperties. + +.. code-block:: java + + @Override + public void deploy(CompositionElementDto compositionElement, InstanceElementDto instanceElement) throws PfModelException { + + if ("DEPLOYED".equals(instanceElement.outProperties().get("state"))) { + // clean up deployment + + } else if ("DEPLOYING".equals(state) || "UNDEPLOYING".equals(state)) { + // check and clean up + + } + + // deployment process + instanceElement.outProperties().put("state", "DEPLOYING"); + intermediaryApi.sendAcElementInfo(instanceElement.instanceId(), instanceElement.elementId(), + null, null, instanceElement.outProperties()); + + ....................................... + ....................................... + // end of the deployment process + + if (isDeploySuccess()) { + instanceElement.outProperties().put("state", "DEPLOYED"); + intermediaryApi.sendAcElementInfo(instanceElement.instanceId(), instanceElement.elementId(), + null, null, instanceElement.outProperties()); + + intermediaryApi.updateAutomationCompositionElementState(instanceElement.instanceId(), + instanceElement.elementId(), DeployState.DEPLOYED, null, StateChangeResult.NO_ERROR, "Deployed"); + } else { + instanceElement.outProperties().put("state", "UNDEPLOYED"); + intermediaryApi.sendAcElementInfo(instanceElement.instanceId(), instanceElement.elementId(), + null, null, instanceElement.outProperties()); + + intermediaryApi.updateAutomationCompositionElementState(instanceElement.instanceId(), + instanceElement.elementId(), DeployState.UNDEPLOYED, null, StateChangeResult.FAILED, "Deploy failed!"); + } + } + + @Override + public void undeploy(CompositionElementDto compositionElement, InstanceElementDto instanceElement) + throws PfModelException { + + if ("UNDEPLOYED".equals(instanceElement.outProperties().get("state"))) { + // clean up undeployment + + } else if ("DEPLOYING".equals(state) || "UNDEPLOYING".equals(state)) { + // check and clean up + + } + + // undeployment process + instanceElement.outProperties().put("state", "UNDEPLOYING"); + intermediaryApi.sendAcElementInfo(instanceElement.instanceId(), instanceElement.elementId(), + null, null, instanceElement.outProperties()); + + ....................................... + ....................................... + // end of the undeployment process + + if (isUndeploySuccess()) { + instanceElement.outProperties().put("state", "UNDEPLOYED"); + intermediaryApi.sendAcElementInfo(instanceElement.instanceId(), instanceElement.elementId(), + null, null, instanceElement.outProperties()); + + intermediaryApi.updateAutomationCompositionElementState(instanceElement.instanceId(), + instanceElement.elementId(), DeployState.UNDEPLOYED, null, StateChangeResult.NO_ERROR, "Undeployed"); + } else { + instanceElement.outProperties().put("state", "DEPLOYED"); + intermediaryApi.sendAcElementInfo(instanceElement.instanceId(), instanceElement.elementId(), + null, null, instanceElement.outProperties()); + + intermediaryApi.updateAutomationCompositionElementState(instanceElement.instanceId(), + instanceElement.elementId(), DeployState.DEPLOYED, null, StateChangeResult.FAILED, "Undeploy failed!"); + } + } + + +*In all suggestions shown before we have used labels as "DEPLOY", "UNDEPLOY", "DEPLOYING", "UNDEPLOYING" but the developer can change them as better suit with the context of the participant.* + diff --git a/docs/clamp/acm/acm-states.rst b/docs/clamp/acm/acm-states.rst index a6cfc2e1..7a3222a5 100644 --- a/docs/clamp/acm/acm-states.rst +++ b/docs/clamp/acm/acm-states.rst @@ -80,6 +80,12 @@ Delete .. image:: images/acm-states/AcInstanceStatesDelete.png +Automation Composition Instance Sub State +========================================= +The sub states that an Automation Composition Instance can have are shown in the diagram below. + +.. image:: images/acm-states/AcInstanceSubStates.png + How State are saved in DB ========================= Any state will be saved in DB as number: @@ -111,8 +117,8 @@ Automation Composition Type State | DEPRIMING | 3 | +----------------+------------+ -Automation Composition Instance State -===================================== +Automation Composition Instance DeployState +=========================================== +---------------+------------+ | DeployState | Database | @@ -134,5 +140,36 @@ Automation Composition Instance State | MIGRATING | 7 | +---------------+------------+ +Automation Composition Instance Lock State +========================================== + ++-------------+------------+ +| LockState | Database | ++=============+============+ +| LOCKED | 0 | ++-------------+------------+ +| LOCKING | 1 | ++-------------+------------+ +| UNLOCKED | 2 | ++-------------+------------+ +| UNLOCKING | 3 | ++-------------+------------+ +| NONE | 4 | ++-------------+------------+ + +Automation Composition Instance Sub State +========================================= + ++-------------------------+------------+ +| SubState | Database | ++=========================+============+ +| NONE | 0 | ++-------------------------+------------+ +| MIGRATION_PRECHECKING | 1 | ++-------------------------+------------+ +| PREPARING | 2 | ++-------------------------+------------+ +| REVIEWING | 3 | ++-------------------------+------------+ End of Document diff --git a/docs/clamp/acm/acm-user-guide.rst b/docs/clamp/acm/acm-user-guide.rst index 3c56f906..8cc4c40f 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,11 +326,33 @@ 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 user can update the instance property values if needed. +The target composition have to be primed and there can be an addition/removal of elements at this stage. +The user can update the instance property values for the existing elements if needed. +A new element can be added and any elements that are no longer needed can be removed from the target composition and +the migration payload. +The migration payload should contain the updated element list for the instance. + .. code-block:: bash @@ -293,6 +362,8 @@ The user can update the instance property values if needed. Request Payload Example payload to migrate and update the base url of the http request +A new element with id "709c62b3-8918-41b9-a747-d21eb79c6c22" has been added during migration which will be deployed +by the participant. .. literalinclude:: files/AC-migrate.json :language: json @@ -324,8 +395,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 +410,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 +464,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 +555,7 @@ Default value of 'element.handler' is the most recent version. ==================== ==================== AcElementHandlerV1 AcElementListenerV1 AcElementHandlerV2 AcElementListenerV2 +AcElementHandlerV3 AcElementListenerV3 ==================== ==================== Example: @@ -511,4 +563,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/api-protocol/acm-participant-protocol.rst b/docs/clamp/acm/api-protocol/acm-participant-protocol.rst index 2a8e05a0..d384633a 100644 --- a/docs/clamp/acm/api-protocol/acm-participant-protocol.rst +++ b/docs/clamp/acm/api-protocol/acm-participant-protocol.rst @@ -36,7 +36,7 @@ Participant Deregistration is performed by a Participant when it shuts down. It Automation Composition Priming and De-Priming --------------------------------------------- -The Priming operation sends Automation Composition Types and common property values to participants for each Automation Composition Element Type in the Automation Composition Type. The ParticipantPrime message type is sent to trigger priming and depriming in participants in participants +The Priming operation sends Automation Composition Types and common property values to participants for each Automation Composition Element Type in the Automation Composition Type. The ParticipantPrime message type is sent to trigger priming and depriming in participants. .. image:: ../images/system-dialogues/PrimeAcTypeOnPpnts.png @@ -65,7 +65,7 @@ Automation Composition Update Automation Composition Update handles creation, change, and deletion of Automation Compositions on participants. Change of Automation Compositions uses a semantic versioning approach and follows the -semantics described on the page :ref:`4.1 Management of Automation Composition Instance +semantics described on the page :ref:`5.1 Management of Automation Composition Instance Configurations <management-acm-instance-configs>`. .. image:: ../images/acm-participants-protocol/acm-update.png diff --git a/docs/clamp/acm/api-protocol/system-level-dialogues.rst b/docs/clamp/acm/api-protocol/system-level-dialogues.rst index f3612b49..ec03353c 100644 --- a/docs/clamp/acm/api-protocol/system-level-dialogues.rst +++ b/docs/clamp/acm/api-protocol/system-level-dialogues.rst @@ -133,7 +133,22 @@ The ACM Runtime receives and stores the responses, when all instances element ar .. image:: ../images/system-dialogues/DeleteResponseStored.png -3.3 Deploy Automation Composition Instance +3.3 Prepare Automation Composition Instance +------------------------------------------- +Prepare is a check system from participant before the deployment of an instance, the result will stored in outProperties and not other changes are allowed. +The user requests the AC Instance to be prepared using a REST endpoint. The ACM Runtime orders the AC Instance to be prepared to Participants. + +.. image:: ../images/system-dialogues/PrepareAcInstance.png + +Each participant prepares its AC Element Instances from the AC Instance. + +.. image:: ../images/system-dialogues/PrepareAcInstanceElements.png + +The ACM Runtime receives and stores the responses, and send sync message to all replicas. + +.. image:: ../images/system-dialogues/PrepareResponseStored.png + +3.4 Deploy Automation Composition Instance ------------------------------------------ The user requests the AC Instance to be deployed using a REST endpoint. The ACM Runtime orders the AC Instance to be deployed to Participants. @@ -147,7 +162,22 @@ The ACM Runtime receives and stores the responses, and send sync message to all .. image:: ../images/system-dialogues/DeployResponseStored.png -3.4 Update Automation Composition Instance +3.5 Review Automation Composition Instance +------------------------------------------ +Review is a check system from participant after the deployment of an instance, the result will stored in outProperties and not other changes are allowed. +The user requests the AC Instance to be Reviewed using a REST endpoint. The ACM Runtime orders the AC Instance to be reviewed to Participants. + +.. image:: ../images/system-dialogues/ReviewAcInstance.png + +Each participant reviews its AC Element Instances from the AC Instance. + +.. image:: ../images/system-dialogues/ReviewAcInstanceElements.png + +The ACM Runtime receives and stores the responses, and send sync message to all replicas. + +.. image:: ../images/system-dialogues/ReviewResponseStored.png + +3.6 Update Automation Composition Instance ------------------------------------------ The user requests the AC Instance to be updated using a REST endpoint. The ACM Runtime orders the AC Instance to be updated. @@ -161,7 +191,22 @@ The ACM Runtime receives and stores the responses, and send sync message to all .. image:: ../images/system-dialogues/UpdateAcElementsResponse.png -3.5 Migrate Automation Composition Instance +3.7 Migration Precheck Automation Composition Instance +------------------------------------------------------ +Migration Precheck is a check system from participant before the migration of an instance, the result will stored in outProperties and not other changes are allowed. +The user requests a Migration Precheck for the AC Instance using a REST endpoint. The ACM Runtime orders the Migration Precheck for AC Instance to Participants. + +.. image:: ../images/system-dialogues/MigrationPrecheckAcInstance.png + +Each participant execute a Migration Precheck to its AC Element Instances from the AC Instance. + +.. image:: ../images/system-dialogues/MigrationPrecheckAcInstanceElements.png + +The ACM Runtime receives and stores the responses, and send sync message to all replicas. + +.. image:: ../images/system-dialogues/MigrationPrecheckResponseStored.png + +3.8 Migrate Automation Composition Instance ------------------------------------------- The user requests the AC Instance to be migrated using a REST endpoint. The ACM Runtime orders the AC Instance to be migrated. @@ -175,7 +220,7 @@ The ACM Runtime receives and stores the responses, and send sync message to all .. image:: ../images/system-dialogues/MigrateAcElementsResponse.png -3.6 Undeploy Automation Composition Instance +3.9 Undeploy Automation Composition Instance -------------------------------------------- The user requests the AC Instance to be undeployed using a REST endpoint. The ACM Runtime orders the AC Instance to be undeployed. @@ -189,13 +234,13 @@ The ACM Runtime receives and stores the responses, and send sync message to all .. image:: ../images/system-dialogues/UndeployResponseStored.png -3.7 Read Automation Composition Instances ------------------------------------------ +3.10 Read Automation Composition Instances +------------------------------------------ .. image:: ../images/system-dialogues/ReadAcInstances.png -3.8 Unlock Automation Composition Instance ------------------------------------------- +3.11 Unlock Automation Composition Instance +------------------------------------------- The user requests the AC Instance to be unlocked using a REST endpoint. The ACM Runtime orders the AC Instance to be unlocked on Participants. .. image:: ../images/system-dialogues/OrderInstanceUnlock.png @@ -208,8 +253,8 @@ The ACM Runtime receives and stores the responses, and send sync message to all .. image:: ../images/system-dialogues/UnlockResponseStored.png -3.9 Lock Automation Composition Instance ----------------------------------------- +3.12 Lock Automation Composition Instance +----------------------------------------- The user requests the AC Instance to be locked using a REST endpoint. The ACM Runtime orders the AC Instance to be locked on Participants. .. image:: ../images/system-dialogues/LockAcInstance.png @@ -222,12 +267,12 @@ The ACM Runtime receives and stores the responses, and send sync message to all .. image:: ../images/system-dialogues/LockResponseStored.png -3.10 Update Operational State, Use State and outProperties on Automation Composition Instance +3.13 Update Operational State, Use State and outProperties on Automation Composition Instance --------------------------------------------------------------------------------------------- .. image:: ../images/system-dialogues/UpdateOperationalState.png -3.11 Failure handling in ACM +3.14 Failure handling in ACM ---------------------------- After any ACM operation is completed, one of the following result messages will be updated in the ACM. These result values are updated along with the overall state of the ACM instance. @@ -272,7 +317,7 @@ The following flow shown and example of deployment that get stuck, and the user .. image:: ../images/system-dialogues/TimeoutParticipant.png -3.12 OFF_LINE handling in ACM +3.15 OFF_LINE handling in ACM ----------------------------- Runtime marks the participant state with the value 'OFF_LINE' when the participant replica fails to report the periodic heartbeat, the participant replica state is then marked as 'OFF_LINE' by the ACM-R after the configured waiting limit is reached. 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/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 ba73eb04..46d4a85f 100644 --- a/docs/clamp/acm/design-impl/clamp-runtime-acm.rst +++ b/docs/clamp/acm/design-impl/clamp-runtime-acm.rst @@ -18,7 +18,7 @@ Terminology - 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 @@ -80,6 +80,17 @@ Update of a Automation Composition Instance - 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 @@ -94,6 +105,15 @@ 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 @@ -103,6 +123,15 @@ case **deployOrder: DEPLOY** - 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 @@ -210,6 +239,81 @@ Example of DEPLOY order with Http_PMSHMicroserviceAutomationCompositionElement w 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 ********************************************* 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 493022d1..92ab6d42 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 @@ -42,7 +43,7 @@ Outbound messages Design of a PARTICIPANT_REGISTER message ---------------------------------------- - A participant starts and send a PARTICIPANT_REGISTER message with participantId, replicaId and Supported Element Definition Types -- in AC-runtime ParticipantRegisterListener collects the message from Message Broker +- 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, @@ -51,23 +52,31 @@ Design of a PARTICIPANT_REGISTER message 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 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-migrate.json b/docs/clamp/acm/files/AC-migrate.json index 32b56fd4..27932fca 100755 --- a/docs/clamp/acm/files/AC-migrate.json +++ b/docs/clamp/acm/files/AC-migrate.json @@ -11,6 +11,12 @@ "properties": { "baseUrl": "http://acm-starter-ac-element-impl_updated:8084" } + }, + "709c62b3-8918-41b9-a747-d21eb79c6c22": { + "id": "709c62b3-8918-41b9-a747-d21eb79c6c22", + "properties": { + "baseUrl": "http://acm-sink-ac-element-impl_updated:8085" + } } } } 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/ACM-Message-Table.csv b/docs/clamp/acm/files/ACM-Message-Table.csv index da17374a..b3f09a7a 100755 --- a/docs/clamp/acm/files/ACM-Message-Table.csv +++ b/docs/clamp/acm/files/ACM-Message-Table.csv @@ -31,13 +31,13 @@ ParticipantStatus,Participant,ACM Runtime,Status update message,state,Enum indic ,,,,participantSupportedElementTypes,Ac element types that this participant is capable for deployinh/supporting ,,,,messageType,Enum indicating the type of message PARTICIPANT_STATUS AutomationCompositionDeploy,ACM Runtime,Participant,Message to request change state of composition to DEPLOY,participantUpdatesList,A list of ParticipantUpdates instances which carries details of an updated participant. -,,,,replicaId,The replica ID of this participant – in UUID format ,,,,compositionId,The id of the AC Definition related to this message ,,,,automationCompositionId,The id of the automation composition related to this message ,,,,startPhase,Integer indicating the start up order of the elements ,,,,participantId,UUID indicating the participant the message is intended for ,,,,messageType,Enum indicating the type of message AUTOMATION_COMPOSITION_DEPLOY AutomationCompositionDeployAck,Participant,ACM Runtime,Message to acknowledge that deploy or state change message has been received by participant,automationCompositionResultMap,"A map with AutomationCompositionElementID as its key, and a pair of result and message as value per AutomationCompositionElement" +,,,,stage,The next stage that participant is supposed to receiving ,,,,replicaId,The replica ID of this participant – in UUID format ,,,,compositionId,The id of the AC Definition related to this message ,,,,automationCompositionId,The id of the automation composition related to this message @@ -66,8 +66,14 @@ ParticipantSync,ACM Runtime,Participant,Message to request sync,participantId,Th ,,,,restarting,Flag - if true it is a restarting scenario ,,,,messageType,Enum indicating the type of message PARTICIPANT_SYNC_MSG AutomationCompositionMigration,ACM Runtime,Participant,Message to request update,participantUpdatesList,A list of ParticipantUpdates instances which carries details of an updated participant. +,,,,precheck,Flag - if true it is a Migration Precheck ,,,,compositionId,The id of the AC Definition related to this message ,,,,compositionTargetId,The id of the AC Definition target ,,,,automationCompositionId,The id of the automation composition related to this message ,,,,participantId,UUID indicating the participant the message is intended for -,,,,messageType,Enum indicating the type of message PROPERTIES_UPDATE +,,,,messageType,Enum indicating the type of message AUTOMATION_COMPOSITION_MIGRATION +AutomationCompositionPrepare,ACM Runtime,Participant,Message to request prepare/review,participantList,A list of ParticipantUpdates instances which carries details of an updated participant. +,,,,preDeploy,Flag - if true the instance is Undeployed and the action is a Prepare - otherwise (false) the instance is Deployed and the action is a Review +,,,,compositionId,The id of the AC Definition related to this message +,,,,automationCompositionId,The id of the automation composition related to this message +,,,,messageType,Enum indicating the type of message AUTOMATION_COMPOSITION_PREPARE 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 +} diff --git a/docs/clamp/acm/images/acm-states/AcInstanceSubStates.png b/docs/clamp/acm/images/acm-states/AcInstanceSubStates.png Binary files differnew file mode 100644 index 00000000..f27ea679 --- /dev/null +++ b/docs/clamp/acm/images/acm-states/AcInstanceSubStates.png diff --git a/docs/clamp/acm/images/system-dialogues/MigrationPrecheckAcInstance.png b/docs/clamp/acm/images/system-dialogues/MigrationPrecheckAcInstance.png Binary files differnew file mode 100644 index 00000000..1d0514ca --- /dev/null +++ b/docs/clamp/acm/images/system-dialogues/MigrationPrecheckAcInstance.png diff --git a/docs/clamp/acm/images/system-dialogues/MigrationPrecheckAcInstanceElements.png b/docs/clamp/acm/images/system-dialogues/MigrationPrecheckAcInstanceElements.png Binary files differnew file mode 100644 index 00000000..3fbf7196 --- /dev/null +++ b/docs/clamp/acm/images/system-dialogues/MigrationPrecheckAcInstanceElements.png diff --git a/docs/clamp/acm/images/system-dialogues/MigrationPrecheckResponseStored.png b/docs/clamp/acm/images/system-dialogues/MigrationPrecheckResponseStored.png Binary files differnew file mode 100644 index 00000000..7b66c5b2 --- /dev/null +++ b/docs/clamp/acm/images/system-dialogues/MigrationPrecheckResponseStored.png diff --git a/docs/clamp/acm/images/system-dialogues/PrepareAcInstance.png b/docs/clamp/acm/images/system-dialogues/PrepareAcInstance.png Binary files differnew file mode 100644 index 00000000..3220fa2a --- /dev/null +++ b/docs/clamp/acm/images/system-dialogues/PrepareAcInstance.png diff --git a/docs/clamp/acm/images/system-dialogues/PrepareAcInstanceElements.png b/docs/clamp/acm/images/system-dialogues/PrepareAcInstanceElements.png Binary files differnew file mode 100644 index 00000000..7802642e --- /dev/null +++ b/docs/clamp/acm/images/system-dialogues/PrepareAcInstanceElements.png diff --git a/docs/clamp/acm/images/system-dialogues/PrepareResponseStored.png b/docs/clamp/acm/images/system-dialogues/PrepareResponseStored.png Binary files differnew file mode 100644 index 00000000..2bf2997a --- /dev/null +++ b/docs/clamp/acm/images/system-dialogues/PrepareResponseStored.png diff --git a/docs/clamp/acm/images/system-dialogues/ReviewAcInstance.png b/docs/clamp/acm/images/system-dialogues/ReviewAcInstance.png Binary files differnew file mode 100644 index 00000000..35e12764 --- /dev/null +++ b/docs/clamp/acm/images/system-dialogues/ReviewAcInstance.png diff --git a/docs/clamp/acm/images/system-dialogues/ReviewAcInstanceElements.png b/docs/clamp/acm/images/system-dialogues/ReviewAcInstanceElements.png Binary files differnew file mode 100644 index 00000000..50b49c8f --- /dev/null +++ b/docs/clamp/acm/images/system-dialogues/ReviewAcInstanceElements.png diff --git a/docs/clamp/acm/images/system-dialogues/ReviewResponseStored.png b/docs/clamp/acm/images/system-dialogues/ReviewResponseStored.png Binary files differnew file mode 100644 index 00000000..671b23fb --- /dev/null +++ b/docs/clamp/acm/images/system-dialogues/ReviewResponseStored.png diff --git a/docs/clamp/acm/plantuml/states/AcInstanceSubStates.puml b/docs/clamp/acm/plantuml/states/AcInstanceSubStates.puml new file mode 100644 index 00000000..918a03b3 --- /dev/null +++ b/docs/clamp/acm/plantuml/states/AcInstanceSubStates.puml @@ -0,0 +1,18 @@ +@startuml + +UNDEPLOYED --> DEPLOYING: Deploy +DEPLOYING --> DEPLOYED: AC Instance Elements\nall DEPLOYED + +state UNDEPLOYED { + NONE:UNDEPLOYED --> PREPARING: Prepare + PREPARING --> NONE:UNDEPLOYED: Completed +} + +state DEPLOYED { + NONE:DEPLOYED --> REVIEWING: Review + REVIEWING --> NONE:DEPLOYED: Completed + NONE:DEPLOYED --> MIGRATION_PRECHECKING: Migrate precheck + MIGRATION_PRECHECKING --> NONE:DEPLOYED: Completed +} + +@enduml diff --git a/docs/clamp/acm/plantuml/system-dialogues/MigrationPrecheckAcInstance.puml b/docs/clamp/acm/plantuml/system-dialogues/MigrationPrecheckAcInstance.puml new file mode 100644 index 00000000..14252f22 --- /dev/null +++ b/docs/clamp/acm/plantuml/system-dialogues/MigrationPrecheckAcInstance.puml @@ -0,0 +1,18 @@ +@startuml +participant REST +participant "ACM Runtime" +participant Participants +database "ACM Database" + +REST -> "ACM Runtime": Migration Precheck Automation Composition Instance +"ACM Runtime" -> "ACM Database": Read Automation Composition Instance Information + +alt Automation Composition Instance exists + "ACM Runtime" -> Participants: [ASYNC] Migration Precheck AC Element Instances for this AC Instance + "ACM Runtime" -> "ACM Database": Set AC Instance and its AC Element Instances to subState MIGRATION_PRECHECKING + "ACM Runtime" -> REST: Migration Precheck of Automation Composition Instance has been requested +else + "ACM Runtime" -> REST: Automation Composition instance does not exist +end + +@enduml diff --git a/docs/clamp/acm/plantuml/system-dialogues/MigrationPrecheckAcInstanceElements.puml b/docs/clamp/acm/plantuml/system-dialogues/MigrationPrecheckAcInstanceElements.puml new file mode 100644 index 00000000..39d71b69 --- /dev/null +++ b/docs/clamp/acm/plantuml/system-dialogues/MigrationPrecheckAcInstanceElements.puml @@ -0,0 +1,25 @@ +@startuml +participant "ACM Runtime" +participant Participant +participant "Participant API" + +"ACM Runtime" -> Participant: [ASYNC] Migration Precheck AC Element Instances for this AC Instance + +loop over AC Element Instances in AC Instance + alt Does the primed Participant ID on this AC Element Instance\nmatch my Participant ID? + Participant -> "Participant API": Migration Precheck AC Element Instance + activate "Participant API" + Participant <- "Participant API": AC Element Instance Migration Precheck Response + deactivate "Participant API" + alt AC Element Migration Precheck completed + Participant -> Participant: Set AC Element Instance administrative subState to NONE + "ACM Runtime" <- Participant: [ASYNC] INFO: Migration Precheck AC Element has been completed + end + else + note left of Participant + Ignore this AC Element instance as its for another participant + end note + end +end + +@enduml diff --git a/docs/clamp/acm/plantuml/system-dialogues/MigrationPrecheckResponseStored.puml b/docs/clamp/acm/plantuml/system-dialogues/MigrationPrecheckResponseStored.puml new file mode 100644 index 00000000..cc63e9dd --- /dev/null +++ b/docs/clamp/acm/plantuml/system-dialogues/MigrationPrecheckResponseStored.puml @@ -0,0 +1,19 @@ +@startuml + +participant "ACM Runtime" +database "ACM Database" +participant "Participant Replica 1" +participant "Participant Replica 2" + +"ACM Runtime" <- "Participant Replica 1": [ASYNC] Migration Precheck Automation Composition Element \nInstance Response +"ACM Runtime" -> "ACM Database": Store Automation Composition Element Instance \nResponse Information + +alt Is Migration Precheck AC Element Instance Completed? + "ACM Runtime" -> "ACM Database": Set AC Element Instance SubState as NONE + alt Are all the other AC Element Instances in this AC Instance in state NONE? + "ACM Runtime" -> "ACM Database": Set AC Instance SubState as NONE + "ACM Runtime" -> "Participant Replica 2": [ASYNC] Send sync message + end +end + +@enduml diff --git a/docs/clamp/acm/plantuml/system-dialogues/PrepareAcInstance.puml b/docs/clamp/acm/plantuml/system-dialogues/PrepareAcInstance.puml new file mode 100644 index 00000000..dd7cc7ee --- /dev/null +++ b/docs/clamp/acm/plantuml/system-dialogues/PrepareAcInstance.puml @@ -0,0 +1,18 @@ +@startuml +participant REST +participant "ACM Runtime" +participant Participants +database "ACM Database" + +REST -> "ACM Runtime": Prepare Automation Composition Instance +"ACM Runtime" -> "ACM Database": Read Automation Composition Instance Information + +alt Automation Composition Instance exists + "ACM Runtime" -> Participants: [ASYNC] Prepare AC Element Instances for this AC Instance + "ACM Runtime" -> "ACM Database": Set AC Instance and its AC Element Instances to subState PREPARING + "ACM Runtime" -> REST: Prepare of Automation Composition Instance has been requested +else + "ACM Runtime" -> REST: Automation Composition instance does not exist +end + +@enduml diff --git a/docs/clamp/acm/plantuml/system-dialogues/PrepareAcInstanceElements.puml b/docs/clamp/acm/plantuml/system-dialogues/PrepareAcInstanceElements.puml new file mode 100644 index 00000000..5c5fbcee --- /dev/null +++ b/docs/clamp/acm/plantuml/system-dialogues/PrepareAcInstanceElements.puml @@ -0,0 +1,25 @@ +@startuml +participant "ACM Runtime" +participant Participant +participant "Participant API" + +"ACM Runtime" -> Participant: [ASYNC] Prepare AC Element Instances for this AC Instance + +loop over AC Element Instances in AC Instance + alt Does the primed Participant ID on this AC Element Instance\nmatch my Participant ID? + Participant -> "Participant API": Prepare AC Element Instance + activate "Participant API" + Participant <- "Participant API": AC Element Instance Prepare Response + deactivate "Participant API" + alt AC Element Prepare completed + Participant -> Participant: Set AC Element Instance administrative subState to NONE + "ACM Runtime" <- Participant: [ASYNC] INFO: Prepare AC Element has been completed + end + else + note left of Participant + Ignore this AC Element instance as its for another participant + end note + end +end + +@enduml diff --git a/docs/clamp/acm/plantuml/system-dialogues/PrepareResponseStored.puml b/docs/clamp/acm/plantuml/system-dialogues/PrepareResponseStored.puml new file mode 100644 index 00000000..51ff03b1 --- /dev/null +++ b/docs/clamp/acm/plantuml/system-dialogues/PrepareResponseStored.puml @@ -0,0 +1,19 @@ +@startuml + +participant "ACM Runtime" +database "ACM Database" +participant "Participant Replica 1" +participant "Participant Replica 2" + +"ACM Runtime" <- "Participant Replica 1": [ASYNC] Prepare Automation Composition Element \nInstance Response +"ACM Runtime" -> "ACM Database": Store Automation Composition Element Instance \nResponse Information + +alt Is Prepare AC Element Instance Completed? + "ACM Runtime" -> "ACM Database": Set AC Element Instance SubState as NONE + alt Are all the other AC Element Instances in this AC Instance in state NONE? + "ACM Runtime" -> "ACM Database": Set AC Instance SubState as NONE + "ACM Runtime" -> "Participant Replica 2": [ASYNC] Send sync message + end +end + +@enduml diff --git a/docs/clamp/acm/plantuml/system-dialogues/ReviewAcInstance.puml b/docs/clamp/acm/plantuml/system-dialogues/ReviewAcInstance.puml new file mode 100644 index 00000000..ce40a003 --- /dev/null +++ b/docs/clamp/acm/plantuml/system-dialogues/ReviewAcInstance.puml @@ -0,0 +1,18 @@ +@startuml +participant REST +participant "ACM Runtime" +participant Participants +database "ACM Database" + +REST -> "ACM Runtime": Review Automation Composition Instance +"ACM Runtime" -> "ACM Database": Read Automation Composition Instance Information + +alt Automation Composition Instance exists + "ACM Runtime" -> Participants: [ASYNC] Review AC Element Instances for this AC Instance + "ACM Runtime" -> "ACM Database": Set AC Instance and its AC Element Instances to subState REVIEWING + "ACM Runtime" -> REST: Review of Automation Composition Instance has been requested +else + "ACM Runtime" -> REST: Automation Composition instance does not exist +end + +@enduml diff --git a/docs/clamp/acm/plantuml/system-dialogues/ReviewAcInstanceElements.puml b/docs/clamp/acm/plantuml/system-dialogues/ReviewAcInstanceElements.puml new file mode 100644 index 00000000..45454e6a --- /dev/null +++ b/docs/clamp/acm/plantuml/system-dialogues/ReviewAcInstanceElements.puml @@ -0,0 +1,25 @@ +@startuml +participant "ACM Runtime" +participant Participant +participant "Participant API" + +"ACM Runtime" -> Participant: [ASYNC] Review AC Element Instances for this AC Instance + +loop over AC Element Instances in AC Instance + alt Does the primed Participant ID on this AC Element Instance\nmatch my Participant ID? + Participant -> "Participant API": Review AC Element Instance + activate "Participant API" + Participant <- "Participant API": AC Element Instance Review Response + deactivate "Participant API" + alt AC Element Review completed + Participant -> Participant: Set AC Element Instance administrative subState to NONE + "ACM Runtime" <- Participant: [ASYNC] INFO: Review AC Element has been completed + end + else + note left of Participant + Ignore this AC Element instance as its for another participant + end note + end +end + +@enduml diff --git a/docs/clamp/acm/plantuml/system-dialogues/ReviewResponseStored.puml b/docs/clamp/acm/plantuml/system-dialogues/ReviewResponseStored.puml new file mode 100644 index 00000000..13287e61 --- /dev/null +++ b/docs/clamp/acm/plantuml/system-dialogues/ReviewResponseStored.puml @@ -0,0 +1,19 @@ +@startuml + +participant "ACM Runtime" +database "ACM Database" +participant "Participant Replica 1" +participant "Participant Replica 2" + +"ACM Runtime" <- "Participant Replica 1": [ASYNC] Review Automation Composition Element \nInstance Response +"ACM Runtime" -> "ACM Database": Store Automation Composition Element Instance \nResponse Information + +alt Is Review AC Element Instance Completed? + "ACM Runtime" -> "ACM Database": Set AC Element Instance SubState as NONE + alt Are all the other AC Element Instances in this AC Instance in state NONE? + "ACM Runtime" -> "ACM Database": Set AC Instance SubState as NONE + "ACM Runtime" -> "Participant Replica 2": [ASYNC] Send sync message + end +end + +@enduml diff --git a/docs/conf.py b/docs/conf.py index 41f7e7b1..b4e839ec 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -15,7 +15,7 @@ html_theme = "sphinx_rtd_theme" html_theme_options = { "style_nav_header_background": "white", "sticky_navigation": "False" } -html_logo = "_static/logo_onap_2017.png" +html_logo = "_static/logo_onap_2024.png" html_favicon = "_static/favicon.ico" html_static_path = ["_static"] html_show_sphinx = False diff --git a/docs/development/devtools/devtools.rst b/docs/development/devtools/devtools.rst index 682b9e6b..4e63fdbc 100644 --- a/docs/development/devtools/devtools.rst +++ b/docs/development/devtools/devtools.rst @@ -65,7 +65,6 @@ and the A&AI Schema module. policy/drools-applications \ policy/xacml-pdp \ policy/distribution \ - policy/gui \ policy/clamp " ## @@ -156,7 +155,6 @@ Execution of the script above results in the following directory hierarchy in yo * ~/git/onap/policy/models * ~/git/onap/policy/api * ~/git/onap/policy/pap - * ~/git/onap/policy/gui * ~/git/onap/policy/docker * ~/git/onap/policy/drools-applications * ~/git/onap/policy/drools-pdp @@ -206,7 +204,6 @@ file in the directory *~/git/onap/policy*. <module>drools-pdp</module> <module>drools-applications</module> <module>distribution</module> - <module>gui</module> <module>clamp</module> </modules> </project> @@ -237,34 +234,17 @@ With docker images: Developing and Debugging each Policy Component ********************************************** -Running a MariaDb Instance -++++++++++++++++++++++++++ - -The Policy Framework requires a MariaDb instance running. The easiest way to do this is to run a docker image locally. - -One example on how to do this is to use the scripts used by the policy/api S3P tests. - -`Simulator Setup Script Example <https://gerrit.onap.org/r/gitweb?p=policy/api.git;a=tree;f=testsuites/stability/src/main/resources/simulatorsetup;h=9038413f67cff2e2a79d6345f198f96ee0c57de1;hb=refs/heads/master>`_ - - .. code-block:: bash - - cd ~/git/onap/api/testsuites/stability/src/main/resources/simulatorsetup - ./setup_components.sh - -Another example on how to run the MariaDb is using the docker compose file used by the Policy API CSITs: - -`Example Compose Script to run MariaDB <https://gerrit.onap.org/r/gitweb?p=integration/csit.git;a=blob;f=scripts/policy/docker-compose-api.yml;h=e32190f1e6cb6d9b64ddf53a2db2c746723a0c6a;hb=refs/heads/master>`_ Running the API component standalone ++++++++++++++++++++++++++++++++++++ Assuming you have successfully built the codebase using the instructions above. The only requirement for the API -component to run is a running MariaDb database instance. The easiest way to do this is to run the docker image, please -see the mariadb documentation for the latest information on doing so. Once the mariadb is up and running, a -configuration file must be provided to the api in order for it to know how to connect to the mariadb. You can locate -the default configuration file in the packaging of the api component: +component to run is a running MariaDb/Postgres database instance. The easiest way to do this is to run the docker +image, please see the official documentation for the latest information on doing so. Once the database is up and +running, a configuration file must be provided to the api in order for it to know how to connect to the database. +You can locate the default configuration file in the packaging of the api component: -`Default Policy API Configuration <https://gerrit.onap.org/r/gitweb?p=policy/api.git;a=blob;f=packages/policy-api-tarball/src/main/resources/etc/apiParameters.yaml;h=2c19199a8a889cb0ab203334182662fe15e1635e;hb=refs/heads/master>`_ +`Default Policy API Configuration <https://github.com/onap/policy-api/blob/master/packages/policy-api-tarball/src/main/resources/etc/apiParameters.yaml>`_ You will want to change the fields pertaining to "host", "port" and "databaseUrl" to your local environment settings and start the policy-api springboot application either using your IDE of choice or using the run goal from Spring Boot @@ -275,22 +255,21 @@ Running the API component using Docker Compose An example of running the api using a docker compose script is located in the Policy Integration CSIT test repository. -`Policy CSIT API Docker Compose <https://gerrit.onap.org/r/gitweb?p=integration/csit.git;a=blob;f=scripts/policy/docker-compose-api.yml;h=e32190f1e6cb6d9b64ddf53a2db2c746723a0c6a;hb=refs/heads/master>`_ +`Policy CSIT Docker Compose <https://github.com/onap/policy-docker/blob/master/compose/compose.yaml>`_ Running the PAP component standalone ++++++++++++++++++++++++++++++++++++ -Once you have successfully built the PAP codebase, a running MariaDb database and DMaaP instance will also be required -to start up the application. For MariaDb instance, the easiest way is to run the docker image, please see the mariadb -documentation for the latest information on doing so. For DMaaP, the easiest way during development is to run the DMaaP -simulator which is explained in the below sections. Once the mariadb and DMaaP are running, a configuration file must -be provided to the PAP component in order for it to know how to connect to the mariadb and DMaaP along with other -relevant configuration details. You can locate the default configuration file in the packaging of the PAP component: +Once you have successfully built the PAP codebase, a running MariaDb/Postgres database and Kafka instance will also be +required to start up the application. To start database and Kafka, check official documentation on how to run an +instance of each. After database and Kafka are up and running, a configuration file must be provided to the PAP +component in order for it to know how to connect to the database and Kafka along with other relevant configuration +details. You can locate the default configuration file in the packaging of the PAP component: -`Default PAP Configuration <https://gerrit.onap.org/r/gitweb?p=policy/pap.git;a=blob;f=packages/policy-pap-tarball/src/main/resources/etc/papParameters.yaml;h=06dd45f4946fd0a11ed8ef859f8fc5bcf409a3f0;hb=HEAD>`_ +`Default PAP Configuration <https://github.com/onap/policy-pap/blob/master/packages/policy-pap-tarball/src/main/resources/etc/papParameters.yaml>`_ -Update the fields related to MariaDB, DMaaP and the RestServer for the application as per your local environment settings. -Then to start the application, just run the Spring Boot application using IDE or command line. +Update the fields related to database, Kafka and the RestServer for the application as per your local environment +settings. Then to start the application, just run the Spring Boot application using IDE or command line. Running the Smoke Tests @@ -302,7 +281,6 @@ familiar with the Policy Framework components and test any local changes. .. toctree:: :maxdepth: 1 - smoke/policy-gui-acm-smoke.rst smoke/db-migrator-smoke.rst smoke/acm-participants-smoke.rst smoke/clamp-smoke.rst @@ -319,8 +297,8 @@ familiar with the Policy Framework components and test any local changes. Running the Stability/Performance Tests *************************************** -The following links contain instructions on how to run the S3P Stability and Performance tests. These may be helpful to developers to become -familiar with the Policy Framework components and test any local changes. +The following links contain instructions on how to run the S3P Stability and Performance tests. These may be helpful +to developers to become familiar with the Policy Framework components and test any local changes. .. toctree:: :maxdepth: 2 @@ -338,8 +316,8 @@ familiar with the Policy Framework components and test any local changes. Running the Pairwise Tests ************************** -The following links contain instructions on how to run the pairwise tests. These may be helpful to developers check that -the Policy Framework works in a full ONAP deployment. +The following links contain instructions on how to run the pairwise tests. These may be helpful to developers check +that the Policy Framework works in a full ONAP deployment. .. toctree:: :maxdepth: 1 @@ -430,7 +408,8 @@ To test these images, CSITs will be run. Running Policy Components Locally ********************************* -The following page outlines how to run the policy framework components locally using IntelliJ, Eclipse and the Command Line. +The following page outlines how to run the policy framework components locally using IntelliJ, +Eclipse and the Command Line. .. toctree:: :maxdepth: 1 @@ -461,57 +440,14 @@ Using the Swagger-UI maven dependency Swagger HTML documentation can be accessed - The generated swagger.json can be accessed at: *https://service_IP:service_port/v2/api-docs* - Swagger UI can be accessed at: *https://service_IP:service_port/swagger-ui/index.html* -Running the DMaaP Simulator during Development -********************************************** -It is sometimes convenient to run the DMaaP simulator during development. You can run it from the command line using Maven or from within your IDE. - -Running on the Command Line -+++++++++++++++++++++++++++ -1. Check out the policy models repository -2. Go to the *models-sim/policy-models-simulators* subdirectory in the policy-models repo -3. Run the following Maven command: - - .. code-block:: bash - - mvn exec:java -Dexec.mainClass=org.onap.policy.models.simulators.Main -Dexec.args="src/test/resources/simParameters.json" - -Running in Eclipse -++++++++++++++++++ -1. Check out the policy models repository -2. Go to the *models-sim/policy-models-simulators* module in the policy-models repo -3. Specify a run configuration using the class *org.onap.policy.models.simulators.Main* as the main class -4. Specify an argument of *src/test/resources/simParameters.json* to the run configuration -5. Run the configuration - -Specifying a local configuration file -+++++++++++++++++++++++++++++++++++++ - -You may specify a local configuration file instead of *src/test/resources/simParameters.json* on the command line or as an argument in the run configuration in eclipse: - -.. code-block:: json - - { - "dmaapProvider": { - "name": "DMaaP simulator", - "topicSweepSec": 900 - }, - "restServers": [ - { - "name": "DMaaP simulator", - "providerClass": "org.onap.policy.models.sim.dmaap.rest.DmaapSimRestControllerV1", - "host": "localhost", - "port": 3904, - "https": false - } - ] - } Bringing up Strimzi-Kafka Deploment with Policy Framework ********************************************************* -This page will explain how to setup a local Kubernetes cluster and minimal helm setup to run and deploy Policy Framework on a single host. +This page will explain how to setup a local Kubernetes cluster and minimal helm setup to run and deploy +Policy Framework on a single host. -This is meant for a development purpose only as we are going to use microk8s in this page +This is meant for a development purpose only as we are going to use microk8s in this page: .. toctree:: :maxdepth: 1 diff --git a/docs/development/devtools/smoke/policy-gui-acm-smoke.rst b/docs/development/devtools/smoke/policy-gui-acm-smoke.rst deleted file mode 100644 index cd600199..00000000 --- a/docs/development/devtools/smoke/policy-gui-acm-smoke.rst +++ /dev/null @@ -1,277 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. - -.. _clamp-gui-acm-smoke-tests: - -CLAMP GUI Smoke Tests ---------------------- -1. Introduction -*************** -The CLAMP GUI for Automation Compositions is designed to provide a user the ability to interact -with the Automation Composition Runtime to perform several actions. - -- Commission new Tosca Service Templates. -- Editing Common Properties. -- Decommission existing Tosca Service Templates. -- Create new instances of Automation Compositions. -- Change the state of the Automation Compositions. -- Delete Automation Compositions. - -This document will serve as a guide to do smoke tests on the different components that are involved when working with the GUI and outline how they operate. It will also show a developer how to set up their environment for carrying out smoke tests on the GUI. - -2. Setup Guide -************** -This section will show the developer how to set up their environment to start testing in GUI with some instruction on how to carry out the tests. There are several prerequisites. Note that this guide is written by a Linux user - although the majority of the steps show will be exactly the same in Windows or other systems. The IDE used in the examples here is Intellij but most or all of what is described should be the same across IDEs. - -2.1 Prerequisites -================= -- Java 11 -- node -- npm -- Docker -- Maven 3 -- Git -- Refer to this guide for basic environment setup `Setting up dev environment <https://wiki.onap.org/display/DW/Setting+Up+Your+Development+Environment>`_ - -2.2 Assumptions -=============== -- You are accessing the policy repositories through gerrit -- You are using "git review". - -The following repositories are required for development in this project. These repositories should be present on your machine and you should run "mvn clean install" on all of them so that the packages are present in your .m2 repository. - -- policy/parent -- policy/common -- policy/models -- policy/clamp -- policy/docker -- policy/gui -- policy/api - -In this setup guide, we will be setting up all the components technically required for a working convenient dev environment. We will not be setting up all of the participants - we will setup only the policy participant as an example. - -2.3 Setting up the components -============================= - -2.3.3 MariaDB Setup -^^^^^^^^^^^^^^^^^^^ -We will be using Docker to run our mariadb instance. It will have a total of three databases running in it. - -- acm: the clampacm db -- cldsdb4: the clamp backend db -- policyadmin: the policy-api db - -The easiest way to do this is to perform a small alteration on an SQL script provided by the clamp backend in the file "runtime/extra/sql/bulkload/create-db.sql" - -.. code-block:: mysql - - CREATE DATABASE `cldsdb4`; - USE `cldsdb4`; - DROP USER 'clds'; - CREATE USER 'clds'; - GRANT ALL on cldsdb4.* to 'clds' identified by 'sidnnd83K' with GRANT OPTION; - CREATE DATABASE `clampacm`; - USE `clampacm`; - DROP USER 'policy'; - CREATE USER 'policy'; - GRANT ALL on clampacm.* to 'policy' identified by 'P01icY' with GRANT OPTION; - CREATE DATABASE `policyadmin`; - USE `policyadmin`; - DROP USER 'policy_user'; - CREATE USER 'policy_user'; - GRANT ALL on clampacm.* to 'policy_user' identified by 'policy_user' with GRANT OPTION; - FLUSH PRIVILEGES; - -Once this has been done, we can run the bash script provided here: "runtime/extra/bin-for-dev/start-db.sh" - -.. code-block:: bash - - ./start-db.sh - -This will setup all three databases. It will also ensure that the tables in cldsdb4 are created. The database will be exposed locally on port 3306 and will be backed by an anonymous docker volume. - -2.3.4 DMAAP Simulator -^^^^^^^^^^^^^^^^^^^^^ -For convenience, a dmaap simulator has been provided in the policy/models repository. To start the simulator, you can do the following: - -1. Navigate to /models-sim/policy-models-simulators in the policy/models repository. -2. Add a configuration file to src/test/resources with the following contents: - -.. code-block:: json - - { - "dmaapProvider":{ - "name":"DMaaP simulator", - "topicSweepSec":900 - }, - "restServers":[ - { - "name":"DMaaP simulator", - "providerClass":"org.onap.policy.models.sim.dmaap.rest.DmaapSimRestControllerV1", - "host":"localhost", - "port":3904, - "https":false - } - ] - } - -3. You can then start dmaap with: - -.. code-block:: bash - - mvn exec:java -Dexec.mainClass=org.onap.policy.models.simulators.Main -Dexec.args="src/test/resources/YOUR_CONF_FILE.json" - -At this stage the dmaap simulator should be running on your local machine on port 3904. - -2.3.5 Policy API -^^^^^^^^^^^^^^^^ -In the policy-api repo, you should fine the file "src/main/resources/etc/defaultConfig.json". This file must be altered slightly - as below with the restServerParameters and databaseProviderParameters shown. Note how the database parameters match-up with what you setup in Mariadb: - -.. code-block:: json - - { - "restServerParameters": { - "host": "0.0.0.0", - "port": 6970, - "userName": "healthcheck", - "password": "zb!XztG34", - "prometheus": true, - "https": false, - "aaf": false - }, - "databaseProviderParameters": { - "name": "PolicyProviderParameterGroup", - "implementation": "org.onap.policy.models.provider.impl.DatabasePolicyModelsProviderImpl", - "databaseDriver": "org.mariadb.jdbc.Driver", - "databaseUrl": "jdbc:mariadb://mariadb:3306/policyadmin", - "databaseUser": "policy_user", - "databasePassword": "policy_user", - "persistenceUnit": "PolicyMariaDb" - }, - } - -Next, navigate to the "/main" directory. You can then run the following command to start the policy api: - -.. code-block:: bash - - mvn exec:java -Dexec.mainClass=org.onap.policy.api.main.startstop.Main -Dexec.args=" -c ../packages/policy-api-tarball/src/main/resources/etc/defaultConfig.json" - -2.3.6 Clamp Backend -^^^^^^^^^^^^^^^^^^^ -The Clamp Backend can potentially make calls to policy pap, policy api, cds, sdc and others. For acm development purposes, we only need to connect with the acm runtime api. For convenience, there has been an emulator provided to respond to requests from Clamp to all those services that we do not care about. This emulator can be run by running the following bash script "runtime/extra/bin-for-dev/start-emulator.sh" - -.. code-block:: bash - - ./start-emulator.sh - -Once the emulator is running, we can then run the clamp backend. Before doing this, we need to make sure that all of the calls from the clamp backend are directed towards the correct places. We can do this by editing the application-noaaf.properties file: "src/main/resources/application-noaaf.properties". For development purposes and because we are running the components in a non-https way, this file will not need to be altered currently. The clamp backend can then be run with the script "runtime/extra/bin-for-dev/start-backend.sh". - -.. code-block:: bash - - ./start-backend.sh - -Once the clamp backend is running, we can start the acm runtime. - -2.3.7 Automation Composition Runtime -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -To start the acm runtime we need to go the "runtime-acm" directory in the clamp repo. There is a config file that is used, by default, for the acm runtime. That config file is here: "src/main/resources/application.yaml". For development in your local environment, it shouldn't need any adjustment and we can just run the acm runtime with: - -.. code-block:: bash - - mvn spring-boot:run - -2.3.8 Automation Composition GUI -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -At this point, all of the components required to test out the acm gui are running. We can start to make changes, and have those changes reflected in the UI for immediate feedback on our changes. But first, we must run the GUI. - -Firstly, go to the GUI repo and navigate to "gui-clamp/ui-react". To setup for development, we must install the dependencies of the GUI. We can do this using the npm package manager. In the directory, simply run: - -.. code-block:: bash - - npm install - -This will trigger installation of the required packages. The application is configured to proxy all relevant calls to the clamp backend. The application can be started with a simple: - -.. code-block:: bash - - npm start - -This uses nodes internal test dev web server to server the GUI. Once started, you can navigate to the server at "localhost:3000" and login with "admin/password". - -That completes the development setup of the environment. - -3. Running Tests -**************** -In this section, we will run through the functionalities mentioned at the start of this document is section 1. Each functionality will be tested and we will confirm that they were carried out successfully. There is a tosca service template that can be used for this test - -:download:`Tosca Service Template <tosca/tosca-for-gui-smoke-tests.yaml>` - - -3.1 Commissioning -================= -We can carry out commissioning using the GUI. To do so, from the main page, we can select "Upload Tosca to Commissioning" as shown in the image below: - -.. image:: images/gui/CommissioningUpload.png - -Clicking this will take us to a screen where we can upload a file. Select a file to upload and click on the upload button. - -.. image:: images/gui/CommissioningModal.png - -After clicking upload, you should get a message on the modal to tell you that the upload was successful. You can then look in the logs of the policy-participant to see that the message has been received from the runtime: - -.. image:: images/gui/CommissioningMessageOnParticipant.png - -This confirms that commissioning has been complete. - -3.2 Edit Common Properties -========================== -At this stage we can edit the common properties. These properties will be common to all instances of the automation composition definitions we uploaded with the tosca service template. Once an instance is created, we will not be able to alter these common properties again. We can simply click on "Edit Common Properties" in the dropdown menu and we will be taken to the modal shown below. - -.. image:: images/gui/CommonPropertiesModal.png - -The arrows to the left of the modal can be used to expand and contract the elements. If we expand one of the elements, we can see that the provider is one of the properties that we can edit. Edit this property to be "Ericsson Software Technologies". Press "Save" and then press "Commission". You should get a success message. Once you do, you can look at the full tosca service template to confirm the change in provider has been recorder. Click on "Manage Commissioned Tosca Template". Then click on "Pull Tosca Service Template". You should receive the full template on the screen. You should find your change as shown below. - -.. image:: images/gui/ViewEditedCommonProperties.png - -3.3 Create New Instances of Automation Compositions -=================================================== -Once the template is commissioned, we can start to create instances. In the dropdown, click on "Instantiation Management". In the modal, you will see an empty table, as shown. - -.. image:: images/gui/ManageInstancesModal.png - -Then we will click on "Create Instance". That takes us to a page where we can edit the properties of the instance. Not the common properties, but the instance properties. The last element has Provider set as an instance property. In the same way as we did for the common properties, change the provider to "Some Other Company" - then click save. You should get a success message if all went ok. You can then go back to the instantiation management table and you should now see an instance there. - -.. image:: images/gui/InstanceUninitialised.png - -Since the instance is uninitialised, the policies and policy types are not being deployed to the policy api. We can confirm this by looking at the policy-apis database. See the image below. - -.. image:: images/gui/PolicyTypeNotPresent.png - -3.3 Change the State of the Instance -==================================== -Now we will change the instance state to PASSIVE. This should trigger the deployment of the policy types onto the policy-api. To trigger the change of state, click on the "change" button on the instance in the instance management table. This will bring up another modal to allow you to change the state. - -.. image:: images/gui/ChangeState.png - -Pick PASSIVE and then click save. If we once again navigate to the Instance Management table, we can see that our actual state has become passive. - -.. image:: images/gui/PassiveState.png - -This should also mean that our policies and policy types should be written to the policy-api database. We can query that DB again. In the images below, we can see that the policies and the policy types have been written successfully. - -.. image:: images/gui/PolicyTypeSuccess.png - -and - -.. image:: images/gui/PolicySuccess.png - -Following the same procedure as changing the state to PASSIVE, we can then change to UNINITIALISED. This deletes the policies and policy types through the policy api and changes the overall state of the loop. we can then delete it from the Manage Instances table by clicking on Delete. - -Decommissioning -=============== -Finally, we can decommission the template. On the dropdown menu, click "Manage Commissioned Tosca Template" and then pull it. Clicking the "Delete Tosca Service Template" button will fully decommission the template. You will receive a success message if the deletion was successful. - -.. image:: images/gui/ViewEditedCommonProperties.png - -This concluded the required smoke tests - - diff --git a/docs/drools/pdpdApps.rst b/docs/drools/pdpdApps.rst index 5ef0a3fc..6dceee5f 100644 --- a/docs/drools/pdpdApps.rst +++ b/docs/drools/pdpdApps.rst @@ -44,9 +44,9 @@ for the latest images: .. code-block:: bash - docker pull onap/policy-pdpd-cl:1.8.2 + docker pull onap/policy-pdpd-cl:3.0.0 -At the time of this writing *1.8.2* is the latest version. +At the time of this writing *3.0.0* is the latest version. The *onap/policy-pdpd-cl* image extends the *onap/policy-drools* image with the *usecases* controller that realizes the *control loop* application. @@ -120,10 +120,6 @@ The enabled features in the *onap/policy-pdpd-cl* image are: - **controlloop-management**: generic controller capabilities. - **controlloop-usecases**: new *controller* introduced in the guilin release to realize the ONAP use cases. -The following features are installed but disabled: - -- **controlloop-tdjam**: experimental java-only *controller* to be deprecated post guilin. -- **controlloop-utils**: *actor* simulators. Control Loops Transaction (controlloop-trans) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -146,11 +142,6 @@ It is the *guilin* release implementation of the ONAP use cases. It relies on the new *Actor* model framework to carry out a policy's execution. -TDJAM Controller (controlloop-tdjam) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This is an experimental, java-only controller that will be deprecated after the -guilin release. Utilities (controlloop-utils) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -273,10 +264,6 @@ First create an environment file (in this example *env.conf*) to configure the P DCAE_SERVERS=localhost DCAE_CONSUMER_GROUP=dcae.policy.shared - # Open DMaaP - - DMAAP_SERVERS=localhost - # AAI AAI_HOST=localhost @@ -311,18 +298,6 @@ First create an environment file (in this example *env.conf*) to configure the P Configuration ~~~~~~~~~~~~~ -noop.pre.sh -""""""""""" - -In order to avoid the noise in the logs that relate to dmaap configuration, a startup script (*noop.pre.sh*) is added -to convert *dmaap* endpoints to *noop* in the host directory to be mounted. - -.. code-block:: bash - - #!/bin/bash -x - - sed -i "s/^dmaap/noop/g" $POLICY_HOME/config/*.properties - features.pre.sh """"""""""""""" @@ -878,7 +853,7 @@ The reader can also look at the `policy/docker repository <https://github.com/on More specifically, these directories have examples of other PDP-D Control Loop configurations: * `plans <https://github.com/onap/policy-docker/tree/master/compose>`__: startup & teardown scripts. -* `scripts <https://github.com/onap/policy-docker/blob/master/compose/docker-compose.yml>`__: docker-compose file. +* `scripts <https://github.com/onap/policy-docker/blob/master/compose/compose.yaml>`__: docker-compose file. * `tests <https://github.com/onap/policy-docker/blob/master/csit/resources/tests/drools-applications-test.robot>`__: test plan. Additional information diff --git a/docs/drools/pdpdEngine.rst b/docs/drools/pdpdEngine.rst index 22e5cbeb..d943d561 100644 --- a/docs/drools/pdpdEngine.rst +++ b/docs/drools/pdpdEngine.rst @@ -40,11 +40,11 @@ Docker Image ~~~~~~~~~~~~ Check the *drools-pdp* `released versions <https://wiki.onap.org/display/DW/Policy+Framework+Project%3A+Component+Versions>`__ page for the latest versions. -At the time of this writing *1.8.2* is the latest version. +At the time of this writing *3.0.0* is the latest version. .. code-block:: bash - docker pull onap/policy-drools:1.8.2 + docker pull onap/policy-drools:3.0.0 A container instantiated from this image will run under the non-priviledged *policy* account. @@ -60,7 +60,7 @@ The following command can be used to explore the directory layout. .. code-block:: bash - docker run --rm -it nexus3.onap.org:10001/onap/policy-drools:1.8.2 -- bash + docker run --rm -it nexus3.onap.org:10001/onap/policy-drools:3.0.0 -- bash Communication Endpoints ======================= @@ -674,16 +674,6 @@ A feature is packaged in a *feature-<name>.zip* and has this internal layout: # of pdp-d that are necessary for <feature-name> to operate # correctly. # lib/feature the single feature jar that implements the feature. - # [db] database directory, if the feature contains sql. - # [db]/<db-name> database to which underlying sql scripts should be applied. - # ideally, <db-name> = <feature-name> so it is easily to associate - # the db data with a feature itself. In addition, since a feature is - # a somewhat independent isolated unit of functionality,the <db-name> - # database ideally isolates all its data. - # [db]/<db-name>/sql directory with all the sql scripts. - # [db]/<db-name>/sql/<sql-scripts> for this feature, sql - # upgrade scripts should be suffixed with ".upgrade.sql" - # and downgrade scripts should be suffixed with ".downgrade.sql" # [artifacts] maven artifacts to be deployed in a maven repository. # [artifacts]/<artifact> maven artifact with identifiable maven coordinates embedded # in the artifact. @@ -788,7 +778,7 @@ Data Migration ============== PDP-D data is migrated across releases with the -`db-migrator <https://git.onap.org/policy/drools-pdp/tree/policy-management/src/main/server-gen/bin/db-migrator>`__. +`db-migrator <https://git.onap.org/policy/docker/tree/policy-db-migrator/src/main/docker/db-migrator>`__. The migration occurs when different release data is detected. *db-migrator* will look under the *$POLICY_HOME/etc/db/migration* for databases and SQL scripts to migrate. @@ -832,44 +822,16 @@ The db-migrator tool syntax is ok: is the migration status valid See the -`feature-distributed-locking sql directory <https://git.onap.org/policy/drools-pdp/tree/feature-distributed-locking/src/main/feature/db/pooling/sql>`__ +`feature-distributed-locking sql directory <https://git.onap.org/policy/docker/tree/policy-db-migrator/src/main/docker/config/pooling/sql>`__ for an example of upgrade/downgrade scripts. -The following command will provide a report on the upgrade or downgrade activies: - -.. code-block:: bash - - db-migrator -s ALL -o report - -For example in the official guilin delivery: - -.. code-block:: bash - - policy@dev-drools-0:/tmp/policy-install$ db-migrator -s ALL -o report - +---------+---------+ - | name | version | - +---------+---------+ - | pooling | 1811 | - +---------+---------+ - +-------------------------------------+-----------+---------+---------------------+ - | script | operation | success | atTime | - +-------------------------------------+-----------+---------+---------------------+ - | 1804-distributedlocking.upgrade.sql | upgrade | 1 | 2020-05-22 19:33:09 | - | 1811-distributedlocking.upgrade.sql | upgrade | 1 | 2020-05-22 19:33:09 | - +-------------------------------------+-----------+---------+---------------------+ - -In order to use the *db-migrator* tool, the system must be configured with a database. - -.. code-block:: bash - - SQL_HOST=mariadb Maven Repositories ================== The drools libraries in the PDP-D uses maven to fetch rules artifacts and software dependencies. -The default *settings.xml* file specifies the repositories to search. This configuration +The default *settings.xml* file specifies the repositories to search. This configuration can be overriden with a custom copy that would sit in a mounted configuration directory. See an example of the OOM override `settings.xml <https://github.com/onap/oom/blob/master/kubernetes/policy/components/policy-drools-pdp/resources/configmaps/settings.xml>`_. @@ -920,19 +882,6 @@ in a container. -s|--settings: custom settings.xml -a|--artifact: file artifact (jar or pom) to deploy and/or install -AAF -=== - -Policy can talk to AAF for authorization requests. To enable AAF set -the following environment variables: - -.. code-block:: bash - - AAF=true - AAF_NAMESPACE=org.onap.policy - AAF_HOST=aaf-locate.onap - -By default AAF is disabled. Policy Tool =========== @@ -969,15 +918,14 @@ It contains 3 sections: - *PDP-D* running status - *features* applied -- Data migration status on a per database basis. The *start* and *stop* commands are useful for developers testing functionality on a docker container instance. Telemetry Shell =============== -*PDP-D* offers an ample set of REST APIs to debug, introspect, and change state on a running PDP-D. This is known as the -*telemetry* API. The *telemetry* shell wraps these APIs for shell-like access using +*PDP-D* offers an ample set of REST APIs to debug, introspect, and change state on a running PDP-D. This is known as the +*telemetry* API. The *telemetry* shell wraps these APIs for shell-like access using `http-prompt <http://http-prompt.com/>`__. .. code-block:: bash @@ -1040,7 +988,6 @@ These are the configuration items that can reside externally and override the de - ***.post.sh** scripts that will be executed after the PDP-D starts. - **policy-keystore** to override the default PDP-D java keystore. - **policy-truststore** to override the default PDP-D java truststore. -- **aaf-cadi.keyfile** to override the default AAF CADI Key generated by AAF. - ***.properties** to override or add any properties file for the PDP-D, this includes *controller*, *endpoint*, *engine* or *system* configurations. - **logback*.xml** to override the default logging configuration. @@ -1109,9 +1056,6 @@ First create an environment file (in this example *env.conf*) to configure the P POLICY_PDP_PAP_API_KEY= POLICY_PDP_PAP_API_SECRET= - # DMaaP - - DMAAP_SERVERS=localhost Note that *SQL_HOST*, and *REPOSITORY* are empty, so the PDP-D does not attempt to integrate with those components. @@ -1119,18 +1063,6 @@ to integrate with those components. Configuration ~~~~~~~~~~~~~ -In order to avoid the noise in the logs that relate to dmaap configuration, a startup script (*noop.pre.sh*) is added -to convert *dmaap* endpoints to *noop* in the host directory to be mounted. - -noop.pre.sh -""""""""""" - -.. code-block:: bash - - #!/bin/bash -x - - sed -i "s/^dmaap/noop/g" $POLICY_HOME/config/*.properties - active.post.sh """""""""""""" @@ -1171,7 +1103,6 @@ To run the *telemetry shell* and other tools from the host: docker exec -it PDPD bash -c "/opt/app/policy/bin/telemetry" docker exec -it PDPD bash -c "/opt/app/policy/bin/policy status" - docker exec -it PDPD bash -c "/opt/app/policy/bin/db-migrator -s ALL -o report" Controlled instantiation of the PDP-D ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1332,23 +1263,6 @@ and the *mariadb* database: POLICY_PDP_PAP_API_KEY= POLICY_PDP_PAP_API_SECRET= - # DMaaP - - DMAAP_SERVERS=localhost - -prepare.pre.sh -~~~~~~~~~~~~~~ - -A pre-start script *config/prepare.pres.sh"can be added the custom config directory -to prepare the PDP-D to activate the distributed-locking feature (using the database) -and to use "noop" topics instead of *dmaap* topics: - -.. code-block:: bash - - #!/bin/bash - - bash -c "/opt/app/policy/bin/features enable distributed-locking" - sed -i "s/^dmaap/noop/g" $POLICY_HOME/config/*.properties active.post.sh ~~~~~~~~~~~~~~ @@ -1381,7 +1295,7 @@ The reader can also look at the `policy/docker repository <https://github.com/on More specifically, these directories have examples of other PDP-D configurations: * `plans <https://github.com/onap/policy-docker/tree/master/compose>`__: startup & teardown scripts. -* `scripts <https://github.com/onap/policy-docker/blob/master/compose/docker-compose.yml>`__: docker-compose file. +* `scripts <https://github.com/onap/policy-docker/blob/master/compose/compose.yaml>`__: docker-compose file. * `tests <https://github.com/onap/policy-docker/blob/master/csit/resources/tests/drools-pdp-test.robot>`__: test plan. Configuring the PDP-D in an OOM Kubernetes installation diff --git a/docs/index.rst b/docs/index.rst index 8dcfef33..7922c08e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -22,6 +22,5 @@ Policy Framework Architecture apex/apex distribution/distribution clamp/clamp - ui/ui system-attributes/system-attributes release-notes diff --git a/docs/installation/docker.rst b/docs/installation/docker.rst index 95957a02..5a3baca5 100644 --- a/docs/installation/docker.rst +++ b/docs/installation/docker.rst @@ -35,7 +35,6 @@ After cloning the docker repository, the scripts and compose files are under the compose config -- all the components configurations metrics -- configuration for Prometheus server and Grafana dashboards - docker-compose.gui.yml -- compose file with gui services docker-compose.yml -- compose file with policy components services, including simulator, prometheus and grafana export-ports.sh -- script to export the http ports for all components and where the images are collected from get-versions.sh -- script to get the latest SNAPSHOT version of images based on branch (master is default) @@ -48,18 +47,12 @@ Start the containers automatically ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Assuming all the scripts are being executed from the compose folder. -To start all components without Policy GUI: +To start all components: .. code-block:: bash ./start-compose.sh -To start all components with Policy GUI: - -.. code-block:: bash - - ./start-compose.sh --gui - To start all components with Grafana dashboards and Prometheus server: .. code-block:: bash @@ -148,10 +141,10 @@ Start the containers manually **Step 1:** Set the containers location and project. -For *local* images, set CONTAINER_LOCATION="", located at the `export-ports.sh` script +For *local* images, set `LOCAL_IMAGES=true`, located at the `get-versions.sh` script *You will need to build locally all the images using the steps in the previous section* -For *remote* images set CONTAINER_LOCATION="nexus3.onap.org:10001/" +Remote images are downloaded by default from "nexus3.onap.org:10001" **Step 2:** Set gerrit branch @@ -174,7 +167,7 @@ Use the script get-versions.sh .. code-block:: bash - ./start-compose.sh <component> [--grafana] [--gui] + ./start-compose.sh <component> [--grafana] The <component> input is any of the policy components available: @@ -214,7 +207,7 @@ Before the `-jar /app/pap.jar \ ` line, add the following block: -Dcom.sun.management.jmxremote.authenticate=false \ -Dcom.sun.management.jmxremote.local.only=false \ -On `docker-compose.yml` compose file, add to the port section the mapping 5005. +On `compose.yml` file, add to the port section the mapping 5005. .. code-block:: yaml @@ -222,7 +215,6 @@ On `docker-compose.yml` compose file, add to the port section the mapping 5005. image: ${CONTAINER_LOCATION}onap/policy-pap:${POLICY_PAP_VERSION} container_name: policy-pap depends_on: - - mariadb - simulator - api hostname: policy-pap diff --git a/docs/installation/oom.rst b/docs/installation/oom.rst index d1dca3d9..d975e752 100644 --- a/docs/installation/oom.rst +++ b/docs/installation/oom.rst @@ -16,14 +16,15 @@ Notes Cluster Used in this Guide ************************** -* Ubuntu-based cluster using Ubuntu 20.04.1 LTS -* 3 nodes - each having 8GB RAM and 4CPU +* Ubuntu-based VM using Ubuntu 22.04.1 LTS +* VM has 16GB RAM and 150 GB HDD and 4CPU +* microk8s-based cluster is used Prerequisites ************* -* K8s Cluster capable of running kubectl commands -* Both kubectl client and the server use v1.22.4 -* Helm version v3.6.3 is installed +* Microk8s Cluster capable of running kubectl commands +* Both kubectl client and the server use v1.30.4 +* Helm version v3.15.4 is installed * There should be a running chart repo called "local" * Chartmuseum used to create the chart repo @@ -60,19 +61,19 @@ Once this is completed, we should be able to see all of the charts in the local helm search repo local - local/policy 12.0.0 ONAP Policy - local/policy-apex-pdp 12.0.0 ONAP Policy APEX PDP - local/policy-api 12.0.0 ONAP Policy Design API - local/policy-clamp-ac-a1pms-ppnt 12.0.0 ONAP Policy Clamp A1PMS Participant - local/policy-clamp-ac-http-ppnt 12.0.0 ONAP Policy Clamp Controlloop Http Participant - local/policy-clamp-ac-k8s-ppnt 12.0.0 ONAP Policy Clamp Controlloop K8s Participant - local/policy-clamp-ac-kserve-ppnt 12.0.0 ONAP Policy Clamp Kserve Participant - local/policy-clamp-ac-pf-ppnt 12.0.0 ONAP Policy Clamp Controlloop Policy Participant - local/policy-clamp-runtime-acm 12.0.0 ONAP Policy Clamp Controlloop Runtime - local/policy-distribution 12.0.0 ONAP Policy Distribution - local/policy-drools-pdp 12.0.0 ONAP Drools Policy Engine (PDP-D) - local/policy-pap 12.0.0 ONAP Policy Administration (PAP) - local/policy-xacml-pdp 12.0.0 ONAP Policy XACML PDP (PDP-X) + local/policy 14.0.5 ONAP Policy + local/policy-apex-pdp 14.0.1 ONAP Policy APEX PDP + local/policy-api 14.0.2 ONAP Policy Design API + local/policy-clamp-ac-a1pms-ppnt 14.0.1 ONAP Policy Clamp A1PMS Participant + local/policy-clamp-ac-http-ppnt 14.0.1 ONAP Policy Clamp Controlloop Http Participant + local/policy-clamp-ac-k8s-ppnt 14.0.1 ONAP Policy Clamp Controlloop K8s Participant + local/policy-clamp-ac-kserve-ppnt 14.0.1 ONAP Policy Clamp Kserve Participant + local/policy-clamp-ac-pf-ppnt 14.0.1 ONAP Policy Clamp Controlloop Policy Participant + local/policy-clamp-runtime-acm 14.0.2 ONAP Policy Clamp Controlloop Runtime + local/policy-distribution 14.0.1 ONAP Policy Distribution + local/policy-drools-pdp 14.0.2 ONAP Drools Policy Engine (PDP-D) + local/policy-pap 14.0.2 ONAP Policy Administration (PAP) + local/policy-xacml-pdp 14.0.3 ONAP Policy XACML PDP (PDP-X) .. note:: Only the policy/acm charts are shown above - there will be many others. @@ -101,7 +102,7 @@ Install Strimzi Kafka Operator .. code-block:: bash helm repo add strimzi https://strimzi.io/charts/ - helm install strimzi-kafka-operator strimzi/strimzi-kafka-operator --namespace strimzi-system --version 0.32.0 --set watchAnyNamespace=true --create-namespace + helm install strimzi-kafka-operator strimzi/strimzi-kafka-operator --namespace strimzi-system --version 0.43.0 --set watchAnyNamespace=true --create-namespace Once these are installed and running, we can move on to the installation of the policy and related helm charts @@ -113,9 +114,9 @@ At this stage, we have all the required charts that we need for either Policy Fr helm deploy dev local/onap --namespace onap -f ~/override.yaml --create-namespace -In the above **helm deploy** command we provide an override file called **override.yaml**. In this file, we can turn on/off different parts of the onap installation. we have provided 2 different override files below in the collapsable code. One is for just the policy components and requirements. One is for the ACM components and requirements. These are provided just as examples - you can adjust any way you see fit. +In the above **helm deploy** command we provide an override file called **override.yaml**. In this file, we can turn on/off different parts of the onap installation. we have provided an file below in the collapsable code. This is provided just as examples - you can adjust any way you see fit. The choice between postgres and mariadb is controlled by **global.mariadbGalera.localCluster & global.mariadbGalera.useInPolicy** for mariadb and **global.postgres.localCluster & global.postgres.useInPolicy** for postgres -.. collapse:: Policy Chart Override +.. collapse:: Policy/ACM Chart Override .. code-block:: yaml @@ -127,6 +128,35 @@ In the above **helm deploy** command we provide an override file called **overri enabled: false cmpv2Enabled: false addTestingComponents: false + useStrimziKafka: true + useStrimziKafkaPf: false + mariadbGalera: + # flag to enable the DB creation via mariadb-operator + useOperator: false + # if useOperator set to "true", set "enableServiceAccount to "false" + # as the SA is created by the Operator + enableServiceAccount: true + localCluster: true + # '&mariadbConfig' means we "store" the values for later use in the file + # with '*mariadbConfig' pointer. + config: &mariadbConfig + mysqlDatabase: policyadmin + service: &mariadbService policy-mariadb + internalPort: 3306 + nameOverride: *mariadbService + # (optional) if localCluster=false and an external secret is used set this variable + #userRootSecret: <secretName> + useInPolicy: true + prometheusEnabled: false + postgres: + localCluster: false + service: + name: pgset + name2: policy-pg-primary + name3: policy-pg-replica + container: + name: postgres + useInPolicy: false robot: enabled: false so: @@ -134,145 +164,8 @@ In the above **helm deploy** command we provide an override file called **overri cassandra: enabled: false mariadb-galera: - enabled: true - replicaCount: 1 - appc: - enabled: false - sdnc: enabled: false replicaCount: 1 - config: - enableClustering: false - aaf: - enabled: false - aai: - enabled: false - clamp: - enabled: false - cli: - enabled: false - cds: - enabled: false - consul: - enabled: false - contrib: - enabled: false - awx: - enabled: false - netbox: - enabled: false - dcaegen2: - enabled: false - pnda: - enabled: false - dmaap: - enabled: true - message-router: - enabled: true - dmaap-bc: - enabled: false - dmaap-dr-prov: - enabled: false - dmaap-dr-node: - enabled: false - dmaap-strimzi: - enabled: false - esr: - enabled: false - log: - enabled: false - sniro-emulator: - enabled: false - oof: - enabled: false - msb: - enabled: false - multicloud: - enabled: false - nbi: - enabled: false - pomba: - enabled: false - portal: - enabled: false - platform: - enabled: false - sdc: - enabled: false - uui: - enabled: false - vfc: - enabled: false - vid: - enabled: false - modeling: - enabled: false - cps: - enabled: false - vnfsdk: - enabled: false - vvp: - enabled: false - strimzi: - enabled: true - replicaCount: 1 - persistence: - kafka: - size: 1Gi - zookeeper: - size: 256Mi - strimzi-kafka-bridge: - enabled: false - policy: - enabled: true - policy-clamp-ac-a1pms-ppnt: - enabled: false - policy-clamp-ac-k8s-ppnt: - enabled: false - policy-clamp-ac-http-ppnt: - enabled: false - policy-clamp-ac-pf-ppnt: - enabled: false - policy-clamp-runtime-acm: - enabled: false - policy-gui: - enabled: false - policy-apex-pdp: - enabled: true - policy-nexus: - enabled: false - policy-api: - enabled: true - policy-pap: - enabled: true - policy-xacml-pdp: - enabled: true - policy-drools-pdp: - enabled: true - policy-distribution: - enabled: true - -.. collapse:: ACM Chart Override - - .. code-block:: yaml - - global: - repository: nexus3.onap.org:10001 - pullPolicy: IfNotPresent - masterPassword: password - serviceMesh: - enabled: false - cmpv2Enabled: false - addTestingComponents: false - robot: - enabled: false - so: - enabled: false - cassandra: - enabled: false - mariadb-galera: - enabled: true - replicaCount: 1 appc: enabled: false sdnc: @@ -303,9 +196,9 @@ In the above **helm deploy** command we provide an override file called **overri pnda: enabled: false dmaap: - enabled: true + enabled: false message-router: - enabled: true + enabled: false dmaap-bc: enabled: false dmaap-dr-prov: @@ -364,6 +257,8 @@ In the above **helm deploy** command we provide an override file called **overri enabled: true policy-clamp-ac-a1pms-ppnt: enabled: true + policy-clamp-ac-kserve-ppnt: + enabled: true policy-clamp-ac-k8s-ppnt: enabled: true policy-clamp-ac-http-ppnt: @@ -375,7 +270,7 @@ In the above **helm deploy** command we provide an override file called **overri policy-gui: enabled: false policy-apex-pdp: - enabled: false + enabled: true policy-nexus: enabled: false policy-api: @@ -383,9 +278,9 @@ In the above **helm deploy** command we provide an override file called **overri policy-pap: enabled: true policy-xacml-pdp: - enabled: false + enabled: true policy-drools-pdp: - enabled: false + enabled: true policy-distribution: enabled: false @@ -428,8 +323,8 @@ The assumption is you have cloned the charts from the OOM repository into a loca From your local copy, edit any of the values.yaml files in the policy tree to make desired changes. -The policy schema will be installed automatically as part of the database configuration using ``db-migrator``. -By default the policy schema is upgraded to the latest version. +The policy/acm schemas will be installed automatically as part of the database configuration using ``db-migrator``. +By default the policy/acm schemas is upgraded to the latest version. For more information on how to change the ``db-migrator`` setup please see :ref:`Using Policy DB Migrator <policy-db-migrator-label>`. @@ -448,8 +343,8 @@ After undeploying policy, loop on monitoring the policy pods until they go away. .. code-block:: bash - helm undeploy dev-policy - kubectl get pods -n onap | grep dev-policy + helm undeploy dev + kubectl get pods -n onap | grep dev **Step 4** Re-Deploy Policy pods @@ -458,8 +353,8 @@ After deploying policy, loop on monitoring the policy pods until they come up. .. code-block:: bash - helm deploy dev-policy local/onap --namespace onap - kubectl get pods -n onap | grep dev-policy + helm deploy dev local/onap --namespace onap -f override.yaml + kubectl get pods -n onap | grep dev .. note:: If you want to purge the existing data and start with a clean install, diff --git a/docs/pap/InternalPapPdp.rst b/docs/pap/InternalPapPdp.rst index 132e0df1..77395f5b 100644 --- a/docs/pap/InternalPapPdp.rst +++ b/docs/pap/InternalPapPdp.rst @@ -10,20 +10,19 @@ The Internal Policy Framework PAP-PDP API .. contents:: :depth: 3 -This page describes the API between the PAP and PDPs. The APIs in this section are implemented using `DMaaP -API <https://wiki.onap.org/display/DW/DMaaP+API>`__ messaging. The APIs in this section are used for internal -communication in the Policy Framework. The APIs are NOT supported for use by components outside the Policy Framework and -are subject to revision and change at any time. +This page describes the API between the PAP and PDPs. The APIs in this section are used for internal +communication in the Policy Framework, using Kafka as messaging system. The APIs are NOT supported for +use by components outside the Policy Framework and are subject to revision and change at any time. There are three messages on the API: 1. PDP_STATUS: PDP→PAP, used by PDPs to report to the PAP -2. PDP_UPDATE: PAP→PDP, used by the PAP to update the policies running on PDPs, triggers a PDP_STATUS message with - the result of the PDP_UPDATE operation +2. PDP_UPDATE: PAP→PDP, used by the PAP to update the policies running on PDPs, triggers a PDP_STATUS + message with the result of the PDP_UPDATE operation -3. PDP_STATE_CHANGE: PAP→PDP, used by the PAP to change the state of PDPs, triggers a PDP_STATUS message with the result - of the PDP_STATE_CHANGE operation +3. PDP_STATE_CHANGE: PAP→PDP, used by the PAP to change the state of PDPs, triggers a PDP_STATUS message + with the result of the PDP_STATE_CHANGE operation The fields in the table below are valid on API calls: @@ -57,7 +56,7 @@ policiesToBeUndeployed N/A M N/A The list of policies ->(name) O M N/A The name of a TOSCA policy running on the PDP ->policy_type O M N/A The TOSCA policy type of the policyWhen a PDP starts, it commences periodic sending of *PDP_STATUS* - messages on DMaaP. The PAP receives these messages + messages. The PAP receives these messages and acts in whatever manner is appropriate. ->policy_type_version O M N/A The version of the TOSCA policy type of the policy ->properties O M N/A The properties of the policy for the XACML, Drools, @@ -95,9 +94,9 @@ type in the implementation of this API. ================== The purpose of this API is for PDPs to provide heartbeat, status, health, and statistical information to Policy Administration. There is a single *PDP_STATUS* message on this API. PDPs send this message to the PAP using the -*POLICY_PDP_PAP* DMaaP topic. The PAP listens on this topic for messages. +*POLICY_PDP_PAP* topic. The PAP listens on this topic for messages. -When a PDP starts, it commences periodic sending of *PDP_STATUS* messages on DMaaP. The PAP receives these messages and +When a PDP starts, it commences periodic sending of *PDP_STATUS* messages. The PAP receives these messages and acts in whatever manner is appropriate. *PDP_UPDATE* and *PDP_STATE_CHANGE* operations trigger a *PDP_STATUS* message as a response. @@ -133,13 +132,6 @@ sent to the PAP in a *PDP_STATUS* message is unknown to the PAP, the PAP locks t name: xacml-23d33c2a-8715-43a8-ade5-5923fc0f185c pdpGroup: defaultGroup pdpSubgroup: xacml - statistics: - policyDeployCount: 0 - policyDeploySuccessCount: 0 - policyDeployFailCount: 0 - policyExecutedCount: 123 - policyExecutedSuccessCount: 122 - policyExecutedFailCount: 1 .. code-block:: yaml @@ -160,16 +152,6 @@ sent to the PAP in a *PDP_STATUS* message is unknown to the PAP, the PAP locks t deployment_instance_info: node_address: drools_2_pod # Other deployment instance info - statistics: - policyDeployCount: 3 - policyDeploySuccessCount: 3 - policyDeployFailCount: 0 - policyExecutedCount: 123 - policyExecutedSuccessCount: 122 - policyExecutedFailCount: 1 - policyUndeployCount: 0 - policyUndeploySuccessCount: 0 - policyUndeployFailCount: 0 response: responseTo: 52117e25-f416-45c7-a955-83ed929d557f responseStatus: SUCCESSSS @@ -191,16 +173,6 @@ sent to the PAP in a *PDP_STATUS* message is unknown to the PAP, the PAP locks t policies: - name: onap.controllloop.operational.apex.bbs.EastRegion version: 1.0.0 - statistics: - policyExecutedCount: 0 - policyExecutedSuccessCount: 0 - policyExecutedFailCount: 0 - policyDeployCount: 1 - policyDeploySuccessCount: 1 - policyDeployFailCount: 0 - policyUndeployCount: 0 - policyUndeploySuccessCount: 0 - policyUndeployFailCount: 0 response: responseTo: 679fad9b-abbf-4b9b-971c-96a8372ec8af responseStatus: SUCCESS @@ -235,20 +207,13 @@ sent to the PAP in a *PDP_STATUS* message is unknown to the PAP, the PAP locks t name: xacml-23d33c2a-8715-43a8-ade5-5923fc0f185c pdpGroup: onap.pdpgroup.Monitoring pdpSubgroup: xacml - statistics: - policyDeployCount: 0 - policyDeploySuccessCount: 0 - policyDeployFailCount: 0 - policyExecutedCount: 123 - policyExecutedSuccessCount: 122 - policyExecutedFailCount: 1 2 PDP API for PAPs ================== The purpose of this API is for the PAP to load and update policies on PDPs and to change the state of PDPs. -The PAP sends *PDP_UPDATE* and *PDP_STATE_CHANGE* messages to PDPs using the *POLICY_PAP_PDP* DMaaP topic. +The PAP sends *PDP_UPDATE* and *PDP_STATE_CHANGE* messages to PDPs using the *POLICY_PAP_PDP* topic. PDPs listen on this topic for messages. The PAP can set the scope of *PDP_STATE_CHANGE* message: diff --git a/docs/release-notes.rst b/docs/release-notes.rst index ce932362..b021a06b 100644 --- a/docs/release-notes.rst +++ b/docs/release-notes.rst @@ -14,6 +14,192 @@ Policy Framework Release Notes .. * Except the date and the version number, all the other sections are optional but there must be at least .. * one section describing the purpose of this new release. + +.. ========================== +.. * * * NEWDELHI * * * +.. ========================== + +Version: 14.0.0 +--------------- + +:Release Date: 2024-06-13 (Newdelhi Release) + +Artifacts released: + +.. list-table:: + :widths: 15 10 10 + :header-rows: 1 + + * - Repository + - Java Artifact + - Docker Image (if applicable) + * - policy/parent + - 4.1.4 + - N/A + * - policy/docker + - 3.1.3 + - | policy-jre-alpine + | policy-jdk-alpine + | policy-db-migrator + * - policy/common + - 2.1.3 + - N/A + * - policy/models + - 3.1.3 + - N/A + * - policy/api + - 3.1.3 + - policy-api + * - policy/pap + - 3.1.3 + - policy-pap + * - policy/apex-pdp + - 3.1.3 + - policy-apex-pdp + * - policy/drools-pdp + - 2.1.3 + - policy-drools + * - policy/xacml-pdp + - 3.1.3 + - policy-xacml-pdp + * - policy/distribution + - 3.1.3 + - policy-distribution + * - policy/clamp + - 7.1.3 + - | policy-clamp-ac-pf-ppnt + | policy-clamp-ac-k8s-ppnt + | policy-clamp-ac-http-ppnt + | policy-clamp-runtime-acm' + * - policy/gui + - 3.1.3 + - policy-gui + * - policy/drools-applications + - 2.1.3 + - policy-pdpd-cl + +Key Updates +=========== + +* Improvements to CLAMP Automation Composition Management (ACM) + + CLAMP ACM is improved with various new capabilities in newdelhi release. ACM supports tracing feature with the integration of openTelemetry for http and kafka tracing. + This provides a more efficient way of diagnosing bottlenecks and performance issues in the system. + Participant's outProperties are now retained during the restart and redeployment scenario that can be consumed by the participants. + New Regression test suite has been added to test the ACM workflow with various combinations of ACM-R and participant versions. + ACM element versions can now be upgraded during Migration. + + See: + - `POLICY-4865 <https://jira.onap.org/browse/POLICY-4865>`_ - R14: Improvements specific to clamp + +* Backward compatibility support in ACM + + From Newdelhi release, Users can deploy a newer version of ACM-R against an older participant version maintaining the backward compatibility. + Participant intermediary provides flexibility for the users to maintain the older version participant when ACM-R is upgraded. + + See: + - `POLICY-4952 <https://jira.onap.org/browse/POLICY-4952>`_ - R14: Backward compatibility between ACM-R and participants + +* Oparent dependency removed + + From newdelhi onwards, Policy framework can be installed without oparent maven dependency. policy-parent provides all the required dependencies and design rule configurations + for the policy components. + + See: + - `POLICY-4960 <https://jira.onap.org/browse/POLICY-4960>`_ - R14: Remove oparent dependency from PF + +* Tracing support in clamp + + Distributed tracing of messages between acm, participants, databases, rest is available in policy clamp that helps to diagnose the bottlenecks and performance issues in the system. + A combination of OpenTelemetry and Micrometer is used to achieve this. + + See: + - `POLICY-4875 <https://jira.onap.org/browse/POLICY-4875>`_ - R14: Add support for Open Telemetry in ACM. + +Known Limitations, Issues and Workarounds +========================================= + +System Limitations +~~~~~~~~~~~~~~~~~~ +N/A + +Known Vulnerabilities +~~~~~~~~~~~~~~~~~~~~~ +N/A + +Workarounds +~~~~~~~~~~~ +N/A + +Security Notes +============== +N/A + +Functional Improvements +======================= +| `POLICY-4865 <https://jira.onap.org/browse/POLICY-4865>`_ - R14: Improvements specific to clamp +| `POLICY-4875 <https://jira.onap.org/browse/POLICY-4875>`_ - Add support for Open Telemetry in ACM +| `POLICY-4908 <https://jira.onap.org/browse/POLICY-4908>`_ - Add support for outProperties retention in restart/redeploy scenario +| `POLICY-4952 <https://jira.onap.org/browse/POLICY-4952>`_ - Support backward compatibility between ACM and participants +| `POLICY-4915 <https://jira.onap.org/browse/POLICY-4915>`_ - Allow element version update in Migration +| `POLICY-4869 <https://jira.onap.org/browse/POLICY-4869>`_ - Allow semantic versioning in ACM templates and instances +| `POLICY-4934 <https://jira.onap.org/browse/POLICY-4934>`_ - Add db migrator support for clamp database + +| `POLICY-4960 <https://jira.onap.org/browse/POLICY-4960>`_ - Remove oparent dependency in Policy framework + + +Necessary Improvements and Bug Fixes +==================================== + +Necessary Improvements +~~~~~~~~~~~~~~~~~~~~~~ +| `POLICY-4867 <https://jira.onap.org/browse/POLICY-4867>`_ - R14: Refactoring and removal of unused code +| `POLICY-4855 <https://jira.onap.org/browse/POLICY-4855>`_ - Remove AAF from Policy common repository +| `POLICY-4868 <https://jira.onap.org/browse/POLICY-4868>`_ - R14: Software (non functional) improvements +| `POLICY-4960 <https://jira.onap.org/browse/POLICY-4960>`_ - Remove oparent dependency in Policy framework +| `POLICY-4654 <https://jira.onap.org/browse/POLICY-4654>`_ - Add metrics for ACM-R and participants +| `POLICY-4893 <https://jira.onap.org/browse/POLICY-4893>`_ - Update Security dependencies +| `POLICY-4895 <https://jira.onap.org/browse/POLICY-4895>`_ - Update SLAs dashboards with spring actuator changes +| `POLICY-4987 <https://jira.onap.org/browse/POLICY-4987>`_ - Improve CSIT scripts and dependencies updates to CSIT docker images +| `POLICY-5002 <https://jira.onap.org/browse/POLICY-5002>`_ - Alter release scripts to include checkstyle update +| `POLICY-4865 <https://jira.onap.org/browse/POLICY-4865>`_ - R14: Improvements specific to CLAMP +| `POLICY-4806 <https://jira.onap.org/browse/POLICY-4806>`_ - Support stress testing of ACM with multiple compositions +| `POLICY-4870 <https://jira.onap.org/browse/POLICY-4870>`_ - Improve descriptiveness of error messages in clamp +| `POLICY-4900 <https://jira.onap.org/browse/POLICY-4900>`_ - Add validation in ACM for unique element Ids +| `POLICY-4918 <https://jira.onap.org/browse/POLICY-4918>`_ - Support recursive update of properties in participant Intermediary +| `POLICY-4635 <https://jira.onap.org/browse/POLICY-4635>`_ - R14: Enhance Policy Framework Documentation +| `POLICY-4644 <https://jira.onap.org/browse/POLICY-4644>`_ - Development documentation for Apex +| `POLICY-4584 <https://jira.onap.org/browse/POLICY-4584>`_ - Update property configuration mechanism documentation +| `POLICY-4585 <https://jira.onap.org/browse/POLICY-4585>`_ - Update PAP architecture documentation +| `POLICY-4629 <https://jira.onap.org/browse/POLICY-4629>`_ - Update policy framework upgrade documentation + +Bug Fixes +~~~~~~~~~ +| `POLICY-4946 <https://jira.onap.org/browse/POLICY-4946>`_ - Authorization issue in jenkins merge job for policy clamp regression module +| `POLICY-4953 <https://jira.onap.org/browse/POLICY-4953>`_ - Missing properties from participant cache during migration +| `POLICY-4961 <https://jira.onap.org/browse/POLICY-4961>`_ - Fix AutomationComposition copy constructor +| `POLICY-4968 <https://jira.onap.org/browse/POLICY-4968>`_ - K8s Participant gets out of sync with ChartMuseum + + +References +========== + +For more information on the ONAP London release, please see: + +#. `ONAP Home Page`_ +#. `ONAP Documentation`_ +#. `ONAP Release Downloads`_ +#. `ONAP Wiki Page`_ + +.. _`ONAP Home Page`: https://www.onap.org +.. _`ONAP Wiki Page`: https://wiki.onap.org +.. _`ONAP Documentation`: https://docs.onap.org +.. _`ONAP Release Downloads`: https://git.onap.org + +Quick Links: + - `POLICY project page`_ + - `Passing Badge information for POLICY`_ + .. ========================== .. * * * MONTREAL * * * .. ========================== diff --git a/docs/system-attributes/policy-db-migrator.rst b/docs/system-attributes/policy-db-migrator.rst index 81019efe..351f4852 100644 --- a/docs/system-attributes/policy-db-migrator.rst +++ b/docs/system-attributes/policy-db-migrator.rst @@ -53,13 +53,13 @@ These script can take up to four parameters: - upgrade/downgrade/report * - schema - -s - - policyadmin/clampacm + - schema_name * - to - -t - - 0800/0900 + - target_version (latest is 1600) * - from - -f - - 0800/0900 + - origin_version (earliest is 0800) The container also consists of several sql files which are used to upgrade/downgrade the policy database. @@ -76,7 +76,7 @@ to run and connect to the database. * - SQL_HOST - mariadb * - SQL_DB - - policyadmin/clampacm + - policyadmin clampacm etc [one or more schema separated by space] * - SQL_USER - policy_user * - SQL_PASSWORD @@ -98,7 +98,7 @@ to run and connect to the database. * - SQL_HOST - postgres * - SQL_DB - - policyadmin/clampacm + - policyadmin clampacm etc [one or more schema separated by space] * - SQL_USER - policy_user * - SQL_PASSWORD @@ -369,6 +369,6 @@ current schema version is set to 1300 and only sql scripts from later versions a .. note:: It is advisable to take a backup of your database prior to running this utility. - Please refer to the mariadb documentation on how to do this. + Please refer to the mariadb or postgres documentation on how to do this. End of Document diff --git a/docs/ui/designtime-ui/apex-policy-editor.rst b/docs/ui/designtime-ui/apex-policy-editor.rst deleted file mode 100644 index 6a5ecb95..00000000 --- a/docs/ui/designtime-ui/apex-policy-editor.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. - -.. _apex-policy-editor-label: - -The Policy Framework Apex Policy Editor -####################################### - -.. contents:: - :depth: 4 - -The Apex Policy Editor allows a user to create and edit an Apex policy. It's UI is shown in the image below. - -.. image:: ../images/ApexPolicyEditorUI.png - -See the :ref:`My-First-Policy Example <apex-myFirstExample>` for an example of using the Apex policy editor. - diff --git a/docs/ui/designtime-ui/designtime-ui.rst b/docs/ui/designtime-ui/designtime-ui.rst deleted file mode 100644 index da9e6d98..00000000 --- a/docs/ui/designtime-ui/designtime-ui.rst +++ /dev/null @@ -1,17 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. - -.. _designtime-ui-label: - -The Policy Framework Designtime User Interface -############################################## - -The Policy Framework Designtime UI is shown in the image below. It is, at present, a plain HTML page. - -.. image:: ../images/DesigntimeUI.png - -The pages below describe the elements of the Policy Framework Designtime UI. - -.. toctree:: - :maxdepth: 2 - - apex-policy-editor diff --git a/docs/ui/images/ApexPolicyEditorUI.png b/docs/ui/images/ApexPolicyEditorUI.png Binary files differdeleted file mode 100644 index 54c3b86f..00000000 --- a/docs/ui/images/ApexPolicyEditorUI.png +++ /dev/null diff --git a/docs/ui/images/DesigntimeUI.png b/docs/ui/images/DesigntimeUI.png Binary files differdeleted file mode 100644 index 16cacf10..00000000 --- a/docs/ui/images/DesigntimeUI.png +++ /dev/null diff --git a/docs/ui/images/MainUI.png b/docs/ui/images/MainUI.png Binary files differdeleted file mode 100644 index b9337834..00000000 --- a/docs/ui/images/MainUI.png +++ /dev/null diff --git a/docs/ui/images/RuntimeUI.png b/docs/ui/images/RuntimeUI.png Binary files differdeleted file mode 100644 index 1214f538..00000000 --- a/docs/ui/images/RuntimeUI.png +++ /dev/null diff --git a/docs/ui/images/UIArchitecture.drawio b/docs/ui/images/UIArchitecture.drawio deleted file mode 100644 index b715fb72..00000000 --- a/docs/ui/images/UIArchitecture.drawio +++ /dev/null @@ -1 +0,0 @@ -<mxfile host="Electron" modified="2022-11-07T16:58:18.463Z" agent="5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/19.0.2 Chrome/102.0.5005.63 Electron/19.0.3 Safari/537.36" etag="YSBAXs5JROLyrZci8Pr5" version="19.0.2" type="device"><diagram id="4LS_t8i9Lp9fYecXpLbe" name="Page-1">7Vtbb+I4FP41PLbyJddHetsZ7a3azmg7fVmZxIDVJEbGFJhfvw4xkNih0EISWk2lqvFx7MTf99nn+MTt4et08Zsgk/GfPKZJD4F40cM3PYSgEyL1J7cstQUBp7CMBIu1bWt4YD+pNgJtnbGYTis3Ss4TySZVY8SzjEayYiNC8Hn1tiFPqk+dkBG1DA8RSWzrvyyW48KKMPa2FV8oG43Xj/ZcPcCUrO/WQ5mOScznJRO+7eFrwbksrtLFNU1y+NbAFO3udtRu3kzQTB7S4K9Ykqeb78nkP9oPBk8/+0/s6wXSb/tCkpke8j1PWLRUtjtBUjrn4lldf/+a95TlqKrfqxxYKvS45HKNluCzLKb580APX83HTNKHCYny2rkSiLKNZZqoElSXQ55JTTgMVfmFCskU8v2EjTJllDxvMGRJcs0TLlZPwMPhEEWRsk+l4M+0VBN7A8/1VI0ekOqNLnZCBTcEKO1SnlIp8iHrBjjQnGnZbuQ432rAxbrbcYl+5GtdEK270abvLTPqQpPzFqKwRdTvswEVGZVqfjRKxIBLyVObCwpjl/p1XISej8mJuIAAVsmAoU0GdoFNBsagITKgxcUNneZgIfCNpfQ4OnbDX+LJs+mICQ2GtVPDiwI6GJ5oaoTg0q1ODtfmA7k1kwPCpvhAFh//zDL5yZnwAdzLw2auVBYp0NQiZa9Ra2fiJerhVwPlMrxRfnUbM8nFCReuOhpcGsROHQ0BGmDvROuTAwxf4SGbBlhDg9vUbHAtFvozpVsiGc9sJq55OuFTVl/ZBk3DIfV2uHQ/HABwGppc9E6a/KZo8iya7pjCF4GH5VTS1MJcxY+T/DJaJkyBL/B+5AcFTX8MNgYSPY9W5P09k6obqu1TTY9bQ9d5hQMuNP3Phtkyk0HduoeaotK3qNzNHhHx26eM5geBrlY516lOH9ezQa/zNRA0hXnQIeYtLVmugbnfNebh59e5Z2AedI352id9ZqH7Bug1O7yWQbd3eLsi2VKWxKzqK8c5JJG046ePPkuM/IgHOifM3gJaoNMs7ucpwRz3hEynLKrCXA1qTdDpgsnHvO7S1aUful1+fbPQzVaFpS4Ur0BjK8doAK1ek89ERF8bYHGfJGJE5b6o0iaunLh6ZS8iaKK2CS/V160jSz/hnjM1kI0uQqe6JfU9Y6dZDFO3QqVcpdlRaHQEjY4KHKyOVtrZDPsIOdk72cbk5IGgJCjwqqCUbMTysVz4sZVkXtw2W5WWpU7uqWAKFypOL07vQHGiLsXpGPkSx0yDHCpOx/EvQVj6qXYbgEvsWLVtCdfO509WjuuCTJgl4a1E4QfJtkCEjX08Ruv9YHn/h2p05DXmfOyMiwZ9okD8hKDjcwDdzp+QKL0QexO/x6PeTlRsoe6cA+p2qmM0YxdTKl5e/R54Aqm3klSH4BylfkCuozYamSpvI48JUo4INx5L0XHRCq0D5+aDZf/AgKRwl52Fy8a+1/f8tdbeGpNAYOS3fWj11XTocUB26AOo9AxF6nYpUgiNlBh2369SZKSRkY9aVul6mnxwlfpnKNNOUw8QGospPmIxRUbmHQWty9ROQL4m04znn/KuYjIdb8KtkjJz+z2Rau+frSwI4E0gtT7WhvYq+HBR7U8EdJoJgNDIXzrmR96DlWL2pFa0tpWCLKV8+fbt3s5Gc2Hb8jsfLGGp8FlWBVSNubXaygG6NhH9jThSisgTTdbH45TFcf6Y2s3AIfI7LrqH5sSGddG9VyO9xs6SITt58BEdUmv+CB3qjvxfUdPpFhk72fKp3FGnWgkNqTjhO72R2ZF14KVpldjJoV+uaIcrCs08NujaD9lJpl2fvPtxyjKmiNBHCg3OPt4ZTt/4bnn44UCnKTbsZMq7D3G2SFc7mXGTLlx38vlEdKni9l90ioVy+69O+PZ/</diagram></mxfile>
\ No newline at end of file diff --git a/docs/ui/images/UIArchitecture.png b/docs/ui/images/UIArchitecture.png Binary files differdeleted file mode 100644 index e60dd5a6..00000000 --- a/docs/ui/images/UIArchitecture.png +++ /dev/null diff --git a/docs/ui/runtime-ui/gui-server.rst b/docs/ui/runtime-ui/gui-server.rst deleted file mode 100644 index ffb0f9f9..00000000 --- a/docs/ui/runtime-ui/gui-server.rst +++ /dev/null @@ -1,143 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. - -.. _gui-server-label: - -The Policy Framework GUI Server -############################### - -The **gui-server** microservice serves the GUI code to the browser for Policy Framework UI. In addition, it acts as -a single point of reference for the REST interfaces provided by **policy-api**, **policy-pap**, and **acm-runtime**. -It can also be used as a HTTPS gatewy for REST references into a Policy Framework deployment in a Kubernetes cluster. - -.. contents:: - :depth: 2 - -The **gui-server** is a regular microservice, and it is packaged, delivered and configured as a docker image. It is -a Spring application and therefore uses a normal Spring-style *applciation.yaml* approach to configuration. - -Definitive example configurations are available in the codebase: - -- `application_http.yaml <https://github.com/onap/policy-gui/blob/master/gui-server/src/test/resources/application_http.yaml>`_ - showing how to configure gui-server for HTTP access -- `application_https.yaml <https://github.com/onap/policy-gui/blob/master/gui-server/src/test/resources/application_https.yaml>`_ - showing how to configure gui-server for HTTPS access - -The configuration parameters are explained in the sections below - -Server Configuration --------------------- - -Configuration for HTTP access to gui-server:: - - server: - port: 2443 - ssl: - enabled: false - -Start gui-server on port 2443 and disable SSL. - -Configuration for HTTPS access to gui-server:: - - server: - port: 2443 - ssl: - enabled: true - enabled-protocols: TLSv1.2 - client-auth: want - key-store: file:./src/test/resources/helloworld-keystore.jks - key-store-password: changeit - trust-store: file:./src/test/resources/helloworld-truststore.jks - trust-store-password: changeit - -Start gui-server on port 2443 and enable SSL with the parameters specified above - -Note that other standard Spring **server** configuraiton parameters as -documented -`on the Spring website <https://docs.spring.io/spring-boot/docs/current/reference/html/application-properties.html>`_ -are supported. - -Runtime Adaptation Configuration --------------------------------- - -You can configure the adaptation for **policy-api**, **policy-pap**, and **runtime-acm**. In other words, you can map -the URL that the GUI produced or that you want to use in a REST tool such as *postman* or *curl* in the **runtime-ui** -part of the aaplication.yaml file:: - - runtime-ui: - policy-api: - mapping-path: "/runtime-ui/policy-api/restservices/" - url: http://localhost:30440 - disable-ssl-validation: true - disable-ssl-hostname-check: true - policy-pap: - mapping-path: "/runtime-ui/policy-pap/restservices/" - url: http://localhost:30442 - disable-ssl-validation: true - disable-ssl-hostname-check: true - acm: - mapping-path: "/runtime-ui/acm/restservices/" - url: http://localhost:30258 - disable-ssl-validation: true - disable-ssl-hostname-check: true - -The parameters under the **policy-api**, **policy-pap**, and **acm** sections are identical. - -mapping-path and url -++++++++++++++++++++ - -The **mapping-path** is the root part of the path that will be replaced by the **url**, the **url** replaces the -**mapping-path**. - -Therefore, using the configuration above for policy-api, the following mapping occurs:: - - http://localhost:2443/runtime-ui/policy-api/restservices/policy/api/v1/healthcheck - - maps to - - http://localhost:30440/policy/api/v1/healthcheck - -and:: - - https://localhost:2443/runtime-ui/acm/restservices/onap/policy/clamp/acm/v2/commission - - maps to - - http://localhost:30258/onap/policy/clamp/acm/v2/commission - -disable-ssl-validation and disable-ssl-hostname-check -+++++++++++++++++++++++++++++++++++++++++++++++++++++ - -The **disable-ssl-validation** **disable-ssl-hostname-check** are boolean values. If the target server (policy-api, -policy-pap, or runtime-acm) is using http, these values should be set to **false**. If the target server is using -HTTPS, set the values as **true** so that the **gui-server** transfers and forwards certificates to target servers. - -Spring Boot Acuator Monitoring ------------------------------- - -The **gui-server** supports regular -`Spring Boot Actuator monitoring <https://docs.spring.io/spring-boot/docs/1.4.0.M2/reference/html/production-ready-monitoring.html>`_ -and monitoring over `prometheus <https://prometheus.io/>`_. - -The following section of the *application.yaml** file is an example of how to enable monitoring:: - - management: - endpoints: - web: - base-path: / - exposure: - include: health,metrics,prometheus - path-mapping.metrics: plain-metrics - path-mapping.prometheus: metrics - -The configuration above enables the following URLs:: - - # Health Check - http://localhost:2443/health - - # Plain Metrics - http://localhost:2443/plain-metrics - - # Prometheus Metrics - http://localhost:2443/metrics - - diff --git a/docs/ui/runtime-ui/runtime-ui.rst b/docs/ui/runtime-ui/runtime-ui.rst deleted file mode 100644 index b77607dc..00000000 --- a/docs/ui/runtime-ui/runtime-ui.rst +++ /dev/null @@ -1,17 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. - -.. _runtime-ui-label: - -The Policy Framework Runtime User Interface -########################################### - -The Policy Framework Runtime UI is shown in the image below. It is, at present, a plain HTML page. - -.. image:: ../images/RuntimeUI.png - -The pages below describe the elements of the Policy Framework Runtime UI. - -.. toctree:: - :maxdepth: 2 - - gui-server diff --git a/docs/ui/ui.rst b/docs/ui/ui.rst deleted file mode 100644 index b4b2d33f..00000000 --- a/docs/ui/ui.rst +++ /dev/null @@ -1,43 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. - -.. _ui-label: - -The Policy Framework User Interfaces -#################################### - -The Policy Framework has a demonstration user interface that supports design time and runtime activities for the Policy -Framework. - -Design time activities are offline activities such as policy editing and ACM composition preparation. The design time UI -works with offline files, producing artifacts that can be consumed by the runtime Policy Framework APIs. - -Runtime operations include creating and updating policy types and policies, deploying policies as well as working with -Automation Compositions. The runtime UI works towards the REST APIs published by the Policy Framework. - -.. image:: images/UIArchitecture.png - -.. note:: - The policy framework UI is developed for use in demonstrations. It is a work in progress. As such, it does not cover - all the features and functions that are avaiable on the Policy Framework REST APIs. - -A Policy Framework installation in Kubernetes is shown in the figure above. The **policy-api**, **policy-pap** and -**acm-runtime** microservices publish REST interfaces. In a Service Mesh installation, these interfaces are exposed -over HTTP and are available inside the Service Mesh. Alternatively, the interfaces may be exposed publicly over HTTPS. - -The **gui-server** microservice serves the GUI code to the browser for Policy Framework UI. In addition, it acts as -a single point of reference for the REST interfaces provided by **policy-api**, **policy-pap**, and **acm-runtime**. -It can also be used as a HTTPS gatewy for REST references into a Policy Framework deployment in a Kubernetes cluster. - -The Policy Framework UI runs in a browser as a Web application. It has a **designtime** and a **runtime** part. - -.. image:: images/MainUI.png - -The Policy Framework main UI is shown in the image above. It is, at present, a plain HTML page. - -The pages below describe the elements of the Policy Framework UI. - -.. toctree:: - :maxdepth: 4 - - designtime-ui/designtime-ui - runtime-ui/runtime-ui |
