Code Review / policy / parent.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | review | tree
raw | inline | side by side
Uplift tomcat-embed-core and commons-lang
[policy/parent.git] / docs / clamp / acm / acm-user-guide.rst
diff --git a/docs/clamp/acm/acm-user-guide.rst b/docs/clamp/acm/acm-user-guide.rst
old mode 100755 (executable)
new mode 100644 (file)
index 0a033b5..7f9078c
--- a/docs/clamp/acm/acm-user-guide.rst
+++ b/docs/clamp/acm/acm-user-guide.rst
@@ -33,6 +33,23 @@ An example scenario is considered where we have a microservice that can be insta
 configured via REST api to perform some operation.This functionality can be realised as a composition in Tosca standard.
 The various sections of the composition definition includes:
 
 configured via REST api to perform some operation.This functionality can be realised as a composition in Tosca standard.
 The various sections of the composition definition includes:
 
+Metadata:
+---------
+The user can define 'TIMEOUT' for Prime and Deprime:
+
+primeTimeoutMs:
+  Denotes the maximum wait time during prime operation by the runtime to receive the state change update from participant
+
+deprimeTimeoutMs:
+  Denotes the maximum wait time during deprime operation by the runtime to receive the state change update from participant
+
+.. code-block:: yaml
+
+  metadata:
+    primeTimeoutMs: 200000
+    deprimeTimeoutMs: 100000
+
+
 Data Types:
 -----------
 The user can define their own data types to be used in the composition definition. In this use case, we are defining three data types as follows.
 Data Types:
 -----------
 The user can define their own data types to be used in the composition definition. In this use case, we are defining three data types as follows.
@@ -75,7 +92,9 @@ org.onap.policy.clamp.acm.AutomationCompositionElement:
   the ACM elements.
   Here we are defining various timeout properties and startPhase parameter that are common for all the AC elements.
 
   the ACM elements.
   Here we are defining various timeout properties and startPhase parameter that are common for all the AC elements.
 
-  Note: This node type value should not be changed as the ACM framework identifies the AC elements based on this type.
+  Note:
+    This node type value can be customised if the user wants to change the default name. Please refer the "Configure custom namings for TOSCA node types"
+    section of the Automation Composition Runtime design and implementation.
 
 org.onap.policy.clamp.acm.K8SMicroserviceAutomationCompositionElement:
   This node type is used to define AC elements that are associated with kubernetes operations. It is further derived from the
 
 org.onap.policy.clamp.acm.K8SMicroserviceAutomationCompositionElement:
   This node type is used to define AC elements that are associated with kubernetes operations. It is further derived from the
@@ -92,7 +111,9 @@ org.onap.policy.clamp.acm.AutomationComposition:
   Primitive node type for defining Automation composition definitions that comprises one or more AC elements in it.
   The AC definition of this type will be created under the Node templates.
 
   Primitive node type for defining Automation composition definitions that comprises one or more AC elements in it.
   The AC definition of this type will be created under the Node templates.
 
-  Note: This node type value should not be changed as the ACM framework identifies the AC definitions based on this type.
+  Note:
+    This node type value can be customised if the user wants to change the default name. Please refer the "Configure custom namings for TOSCA node types"
+    section of the Automation Composition Runtime design and implementation.
 
 .. literalinclude:: files/acm-nodetypes.yaml
    :language: yaml
 
 .. literalinclude:: files/acm-nodetypes.yaml
    :language: yaml
@@ -146,7 +167,7 @@ operations on a high level before proceeding with the workflow.
 
 
 Prerequisites:
 
 
 Prerequisites:
-  - ACM components including acm-runtime, required participants (http and kubernetes in this case) and Dmaap/kafka clients are deployed in docker or kubernetes environment.
+  - ACM components including acm-runtime, required participants (http and kubernetes in this case) and kafka clients are deployed in docker or kubernetes environment.
   - Kubernetes and Helm are installed.
   - Chartmuseum server is installed to host the acelement microservice helm chart. (`Procedure to install chartmuseum <https://wiki.onap.org/display/DW/Microk8s+and+helm+setup+in+Ubuntu>`_.)
   - The helm chart for ACM test microservice is available in the policy/clamp repository that can be cloned locally and uploaded to the chartmuseum using helm push.(`AC element helm chart <https://github.com/onap/policy-clamp/tree/master/examples/src/main/resources/clamp/acm/acelement-helm>`_.)
   - Kubernetes and Helm are installed.
   - Chartmuseum server is installed to host the acelement microservice helm chart. (`Procedure to install chartmuseum <https://wiki.onap.org/display/DW/Microk8s+and+helm+setup+in+Ubuntu>`_.)
   - The helm chart for ACM test microservice is available in the policy/clamp repository that can be cloned locally and uploaded to the chartmuseum using helm push.(`AC element helm chart <https://github.com/onap/policy-clamp/tree/master/examples/src/main/resources/clamp/acm/acelement-helm>`_.)
@@ -210,6 +231,24 @@ Request payload
 .. literalinclude:: files/AC-instantiation.json
    :language: json
 
 .. literalinclude:: files/AC-instantiation.json
    :language: json
 
+The following properties will be used by ACM-runtime:
+
+deployTimeoutMs:
+  Denotes the maximum wait time during deploy operation by the runtime to receive the state change update from participant
+
+undeployTimeoutMs:
+  Denotes the maximum wait time during undeploy operation by the runtime to receive the state change update from participant
+
+updateTimeoutMs:
+  Denotes the maximum wait time during update operation by the runtime to receive the state change update from participant
+
+migrateTimeoutMs:
+  Denotes the maximum wait time migrate deploy operation by the runtime to receive the state change update from participant
+
+deleteTimeoutMs:
+  Denotes the maximum wait time during delete operation by the runtime to receive the state change update from participant
+
+
 Update AC instance properties (Optional)
 ----------------------------------------
 Before the AC instance is deployed, the user is allowed to update the instance property values if needed. The runtime updates these new values
 Update AC instance properties (Optional)
 ----------------------------------------
 Before the AC instance is deployed, the user is allowed to update the instance property values if needed. The runtime updates these new values
@@ -228,6 +267,30 @@ Example payload to update the base url of the http request
    :language: json
 
 
    :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.
 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.
@@ -261,6 +324,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.
 
 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
 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
@@ -275,6 +361,66 @@ required operation.
 Note:
   Please refer the request payload section for updating the instance properties before deployment.
 
 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 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
+
+  Invoke a POST request
+  'http://policy_runtime_ip:port/onap/policy/clamp/acm/v2/compositions/${compositionId}/instances'
+
+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
+
+Rollback AC instance (Optional)
+-------------------------------
+
+In the event of a migration failure, the user can rollback to a previous state.
+
+.. code-block:: bash
+
+  Invoke a POST request
+  'http://policy_runtime_ip:port/onap/policy/clamp/acm/v2/compositions/${compositionId}/instances/${instanceId}/rollback'
+
+This returns a 202 response on a successful rollback request. The elements will be in "MIGRATION_REVERTING" deploy 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}'
+
 UnDeploy AutomationComposition
 ------------------------------
 The AC instances can be undeployed from the system by the participants.
 UnDeploy AutomationComposition
 ------------------------------
 The AC instances can be undeployed from the system by the participants.
@@ -302,8 +448,8 @@ This deletes the AC instance from the database including all the element propert
 
 This returns a 202 response on successful delete order request.
 
 
 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
 Once the AC instance is deleted, it can be deprimed from the participants to be safely deleted from the database.
 
 .. code-block:: bash
@@ -317,8 +463,8 @@ Request payload
 .. literalinclude:: files/AC-depriming.json
    :language: json
 
 .. 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
 The AC definitions can be deleted if there are no instances are running and it is not primed to the participants.
 
 .. code-block:: bash
@@ -337,10 +483,11 @@ Functionality covered:
 #. Set participantId and supportedElementType by properties file or by parameter environment.
 #. Set a delay for each operation at runtime by Rest-Api.
 #. Set success or fail for each operation at runtime by Rest-Api.
 #. Set participantId and supportedElementType by properties file or by parameter environment.
 #. Set a delay for each operation at runtime by Rest-Api.
 #. Set success or fail for each operation at runtime by Rest-Api.
-#. update composition outProperties and send to ACM-runtime by Rest-Api.
-#. read all AC Definition inProperties/outProperties information by Rest-Api.
-#. update useState, operationalState and outProperties and send to ACM-runtime by Rest-Api.
-#. read all AC instance elements information by Rest-Api.
+#. Update composition outProperties and send to ACM-runtime by Rest-Api.
+#. Read all AC Definition inProperties/outProperties information by Rest-Api.
+#. Update useState, operationalState and outProperties and send to ACM-runtime by Rest-Api.
+#. Read all AC instance elements information by Rest-Api.
+#. Log of all information for each operation.
 
 Mock a participant using docker-compose
 ---------------------------------------
 
 Mock a participant using docker-compose
 ---------------------------------------
@@ -369,30 +516,12 @@ Parameters like delay and success/fail could be set any time using the following
 
 The Json below is an example of configuration:
 
 
 The Json below is an example of configuration:
 
-.. code-block:: json
-
-  {
-    "deploySuccess": true,
-    "undeploySuccess": true,
-    "lockSuccess": true,
-    "unlockSuccess": true,
-    "deleteSuccess": true,
-    "updateSuccess": true,
-    "primeSuccess": true,
-    "deprimeSuccess": true,
-    "deployTimerMs": 1000,
-    "undeployTimerMs": 1000,
-    "lockTimerMs": 100,
-    "unlockTimerMs": 100,
-    "updateTimerMs": 100,
-    "deleteTimerMs": 100,
-    "primeTimerMs": 100,
-    "deprimeTimerMs": 100
-  }
+.. literalinclude:: files/simparticipant-parameters.json
+   :language: json
 
 Update and send composition outProperites
 -----------------------------------------
 
 Update and send composition outProperites
 -----------------------------------------
-Data like useState operationalState and outProperites could be updated any time using the following endpoint:
+Composition Definition outProperites could be updated any time using the following endpoint:
 
 .. code-block:: bash
 
 
 .. code-block:: bash
 
@@ -428,7 +557,7 @@ could be read using the following endpoint:
 
 Update and send useState operationalState and instance outProperites
 --------------------------------------------------------------------
 
 Update and send useState operationalState and instance outProperites
 --------------------------------------------------------------------
-Data like useState operationalState and outProperites could be updated any time using the following endpoint:
+AC instance data like useState operationalState and outProperites could be updated any time using the following endpoint:
 
 .. code-block:: bash
 
 
 .. code-block:: bash
 
@@ -440,7 +569,7 @@ The Json below is an example of update, where {{instanceId}} is the UUID of the
 
   {
         "outProperties": {
 
   {
         "outProperties": {
-            "Opresult": true,
+            "result": true,
             "list": [
                 {"id": 1 },
                 {"id": 2 }
             "list": [
                 {"id": 1 },
                 {"id": 2 }
@@ -460,3 +589,11 @@ could be read using the following endpoint:
 .. code-block:: bash
 
   Invoke a GET request 'http://participant_sim_ip:port/onap/policy/clamp/acm/simparticipant/v2/instances'
 .. code-block:: bash
 
   Invoke a GET request 'http://participant_sim_ip:port/onap/policy/clamp/acm/simparticipant/v2/instances'
+
+Log of all information for each operation
+-----------------------------------------
+All information for each operation are logged, so the developer can monitoring what data are passed through the calls. Example of log during deploy.
+
+26-02-2024 09:55:38.547 [pool-4-thread-4] DEBUG  o.o.p.c.a.p.s.m.h.AutomationCompositionElementHandler.deploy **- deploy call**
+**compositionElement: CompositionElementDto[** compositionId=6502ba5e-1939-42b0-8bd2-bf89f0d51be6, elementDefinitionId=onap.policy.clamp.ac.element.Http_StarterAutomationCompositionElement 1.2.3, inProperties={ ... }, outProperties={} **], instanceElement: InstanceElementDto[** instanceId=022b3dee-a878-4b32-8544-de86e67e7335, elementId=2d614898-4945-41c7-9127-947b401aa753, toscaServiceTemplateFragment=ToscaServiceTemplate( ... ), inProperties={ ... }, outProperties={} **]**
+
Parent code that holds the pom.xml to build all the repos (Casablanca)