1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
2 .. http://creativecommons.org/licenses/by/4.0
3 .. Copyright (c) Nordix Foundation. All rights reserved.
5 .. _acm-user-guide-label:
13 This guide helps the user to define their own composition definitions and explains the procedure to execute them via the
14 Clamp Automation Composition Management Framework. This guide briefly talks about the commissioning, instantiation and
15 deployment steps once the composition definitions are created.
17 Defining a composition
18 ======================
20 A composition can be created in yaml/json format as per the TOSCA standard. Please refer to the below section to understand
21 the Tosca fundamental concepts and how an Automation Composition definition can be realised in the TOSCA.
29 HowTo: My First Automation Composition
30 ======================================
32 An example scenario is considered where we have a microservice that can be installed with a helm chart in kubernetes and
33 configured via REST api to perform some operation.This functionality can be realised as a composition in Tosca standard.
34 The various sections of the composition definition includes:
38 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.
40 onap.datatypes.ToscaConceptIdentifier:
41 This is a composite data type that holds two key value pairs in it. This type is used as an identifier for automation
42 element types and participant types.This holds two string properties "name" and "version" and hence this data type can
43 be used for creating the other composition element ids.
45 onap.datatypes.clamp.acm.httpAutomationCompositionElement.RestRequest:
46 The rest api request for configuring the microservice can use the RestRequest datatype for defining the request in TOSCA.
47 This holds the string properties "httpMethod", "path", "body" and an integer property "expectedResponse" for defining
50 Note that the "restRequestId" property which is of type "onap.datatypes.ToscaConceptIdentifier" that was defined in the
53 onap.datatypes.clamp.acm.httpAutomationCompositionElement.ConfigurationEntity:
54 This data type holds a list of rest requests in case a microservice requires more than one rest request for configuration.
55 This holds the "configurationEntityId" which is of type "onap.datatypes.ToscaConceptIdentifier" and "restSequence" property
56 to hold the list of "onap.datatypes.clamp.acm.httpAutomationCompositionElement.RestRequest"
59 .. literalinclude:: files/acm-datatypes.yaml
65 A Node Type is a reusable entity that defines the type of one or more Node Templates.
66 An Interface Type is a reusable entity that describes a set of operations that can be used to interact with or manage a
67 node or relationship in a TOSCA topology. The actual acm elements will be created under the Node templates deriving from
68 these node types. We are going to define the following element types for ACM:
70 org.onap.policy.clamp.acm.Participant:
71 This is a participant element type to define various participants in ACM. It holds the string property "provider".
73 org.onap.policy.clamp.acm.AutomationCompositionElement:
74 This node type defines the primitive Automation composition element type that includes various common properties for all
76 Here we are defining various timeout properties and startPhase parameter that are common for all the AC elements.
78 Note: This node type value should not be changed as the ACM framework identifies the AC elements based on this type.
80 org.onap.policy.clamp.acm.K8SMicroserviceAutomationCompositionElement:
81 This node type is used to define AC elements that are associated with kubernetes operations. It is further derived from the
82 "org.onap.policy.clamp.acm.AutomationCompositionElement" type and hence supports its common properties and also includes
83 additional properties related to helm charts.
84 We are going to create kubernetes AC elements of this type, under the Node templates.
86 org.onap.policy.clamp.acm.HttpAutomationCompositionElement:
87 Node type for AC elements associated with REST operations. It is derived from the "org.onap.policy.clamp.acm.AutomationCompositionElement"
88 type and hence supports its common properties and also supports additional properties for REST operation.
89 We are going to create a REST AC element of this type, under the Node templates.
91 org.onap.policy.clamp.acm.AutomationComposition:
92 Primitive node type for defining Automation composition definitions that comprises one or more AC elements in it.
93 The AC definition of this type will be created under the Node templates.
95 Note: This node type value should not be changed as the ACM framework identifies the AC definitions based on this type.
97 .. literalinclude:: files/acm-nodetypes.yaml
102 A Node Template specifies the occurrence of a manageable software component as part of an application's topology model
103 which is defined in a TOSCA Service Template. We create the actual participants and AC elements involved in this use case
104 under the node templates.
105 There are no element properties supplied at this point since it will be provided by the user during the instantiation.
107 org.onap.k8s.acm.K8SAutomationCompositionParticipant:
108 A kubernetes participant element that processes the kubernetes AC elements in the composition.
109 This element is of node type "org.onap.policy.clamp.acm.Participant"
111 onap.policy.clamp.ac.element.K8S_AutomationCompositionElement:
112 An AC element for kubernetes helm chart installation of the microservice derived from the node type
113 "org.onap.policy.clamp.acm.K8SMicroserviceAutomationCompositionElement".
114 The common element properties are provided with values as part of commissioning the definition.
116 org.onap.policy.clamp.acm.HttpParticipant:
117 A http participant element that processes the REST AC elements in the composition.
118 This element is of type "org.onap.policy.clamp.acm.Participant"
120 onap.policy.clamp.ac.element.Http_AutomationCompositionElement:
121 An AC element for REST operation in the microservice derived from the node type
122 "org.onap.policy.clamp.acm.HttpAutomationCompositionElement".
123 The common element properties startPhase and timeout are provided with values as part of commissioning the definition.
125 onap.policy.clamp.ac.element.AutomationCompositionDefinition:
126 The actual Automation Composition definition that comprises the list of AC elements mapped to it.
127 This element is of node type "org.onap.policy.clamp.acm.AutomationComposition"
129 .. literalinclude:: files/acm-nodetemplates.yaml
132 Completed tosca template :download:`click here <files/acm-tosca.yaml>`
134 Once the Tosca template definition is created, the ACM workflow can be executed to create and deploy the compositions.
135 Please refer the following section for running ACM workflow.
140 ACM framework exposes REST interfaces for creating and deploying the user defined compositions. In this section, the
141 TOSCA template created in the previous step can be commissioned, and then AC instances can be created and deployed for
144 This section assumes that the user has read about the ACM APIs and Protocols documentation and understands the ACM
145 operations on a high level before proceeding with the workflow.
149 - ACM components including acm-runtime, required participants (http and kubernetes in this case) and Dmaap/kafka clients are deployed in docker or kubernetes environment.
150 - Kubernetes and Helm are installed.
151 - 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>`_.)
152 - 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>`_.)
154 Please refer the `ACM swagger document <https://raw.githubusercontent.com/onap/policy-clamp/master/runtime-acm/src/main/resources/openapi/openapi.yaml>`_. for REST API information for all the ACM operations.
155 This section guides through the various steps involved in executing the ACM workflow for deploying the test microservice element.
157 Commissioning the AC definition
158 -------------------------------
159 Commissioning refers to storing the composition definition on the ACM database. The created tosca template is posted as a request payload.
163 Invoke a POST request 'http://policy_runtime_ip:port/onap/policy/clamp/acm/v2/compositions'
165 This returns a 202 response on the successful creation of the composition definition.
168 The rest response returns the compositionId on a successful creation that requires to be used in the subsequent requests.
172 Priming associates the AC elements with suitable participants and sends the corresponding AC element information to the participants.
176 Invoke a PUT request 'http://policy_runtime_ip:port/onap/policy/clamp/acm/v2/compositions/${compositionId}'
180 .. literalinclude:: files/AC-priming.json
183 This returns a 202 response on a successful priming.
185 Instantiate AutomationComposition
186 ---------------------------------
187 Instantiation refers to creating an AC instance on the database by initialising the element properties for each element in the composition.
188 These values requires to be provided by the user as per their use case requirement. In this case, we are passing the helm chart information
189 of the test microservice for the Ac element "onap.policy.clamp.ac.element.K8S_AutomationCompositionElement" which will be processed and installed
190 by the kubernetes participant on a deployment request.
192 Similarly the REST request data that are to be executed on the microservice will be passed on for the http AC element "onap.policy.clamp.ac.element.Http_AutomationCompositionElement"
193 which will be executed by the http participant. Please refer to the properties of the elements in the json payload.
196 In this scenario, the kubernetes element requires to be invoked first to install the helm chart and then the http element needs to be invoked to configure the microservice.
197 This is achieved by using the "startPhase" property on the AC element properties. The elements with the startPhase value defined are executed on a sequence starting from the least value to the higher value.
198 Each element in the request payload is assigned with a uniques UUID which will be automatically generated by the GUI in the upcoming releases.
202 Invoke a POST request
203 'http://policy_runtime_ip:port/onap/policy/clamp/acm/v2/compositions/${compositionId}/instances'
205 The compositionId retrieved from the previous step should be updated in the request body. This returns a 201 response on a successful instantiation.
206 This also returns the instanceId in the response that can be used in the subsequent requests.
210 .. literalinclude:: files/AC-instantiation.json
213 Update AC instance properties (Optional)
214 ----------------------------------------
215 Before the AC instance is deployed, the user is allowed to update the instance property values if needed. The runtime updates these new values
220 Invoke a POST request
221 'http://policy_runtime_ip:port/onap/policy/clamp/acm/v2/compositions/${compositionId}/instances'
225 Example payload to update the base url of the http request
227 .. literalinclude:: files/AC-update.json
233 Once the AC instance is created, the user can deploy the instance which in turn activates the corresponding participants to execute the intended operations.
234 In this case, the kubernetes participant will be installing the test microservice helm chart on the kubernetes cluster and the http participant will be
235 executing the REST requests on the microservice endpoints.
240 'http://policy_runtime_ip:port/onap/policy/clamp/acm/v2/compositions/${compositionId}/instances/${instanceId}'
242 This returns a 202 response on a successful deploy order request. The elements will be in "DEPLOYING" state until the completion and then the state of
243 the elements are updated to "DEPLOYED"
244 The current status of the deployment can be fetched through the following endpoint.
249 'http://policy_runtime_ip:port/onap/policy/clamp/acm/v2/compositions/${compositionId}/instances/${instanceId}'
253 .. literalinclude:: files/AC-deploy.json
257 The user can further implement the admin states 'LOCK' and 'UNLOCK' on the participants to further cascade the deployment operations.
258 If these states are implemented, then a subsequent request to LOCK and UNLOCK requires to be triggered following the deployment.
260 Once all the AC elements are deployed, there should be a test microservice pod running on the kubernetes cluster which is
261 configured to send events on the kafka by the http participant. This can be verified on the test microservice application logs.
262 The AC instances can also be undeployed and deleted by the user.
264 Update AC instance properties after deployment (Optional)
265 ---------------------------------------------------------
266 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
267 in the database and also sends an update event to the participants. The participants has to implement the update method to perform the
272 Invoke a POST request
273 'http://policy_runtime_ip:port/onap/policy/clamp/acm/v2/compositions/${compositionId}/instances'
276 Please refer the request payload section for updating the instance properties before deployment.
278 UnDeploy AutomationComposition
279 ------------------------------
280 The AC instances can be undeployed from the system by the participants.
285 'http://policy_runtime_ip:port/onap/policy/clamp/acm/v2/compositions/${compositionId}/instances/${instanceId}'
287 This returns a 202 response on successful deploy order request.
291 .. literalinclude:: files/AC-undeploy.json
294 Uninstantiate AC instance
295 -------------------------
296 This deletes the AC instance from the database including all the element properties that are initialised.
300 Invoke a DELETE request
301 'http://policy_runtime_ip:port/onap/policy/clamp/acm/v2/compositions/${compositionId}/instances/${instanceId}'
303 This returns a 202 response on successful delete order request.
305 Deprime Ac defintions
306 ---------------------
307 Once the AC instance is deleted, it can be deprimed from the participants to be safely deleted from the database.
311 Invoke a PUT request 'http://policy_runtime_ip:port/onap/policy/clamp/acm/v2/compositions/${compositionId}'
313 This returns a 202 response on a successful operation.
317 .. literalinclude:: files/AC-depriming.json
322 The AC definitions can be deleted if there are no instances are running and it is not primed to the participants.
326 Invoke a DELETE request 'http://policy_runtime_ip:port/onap/policy/clamp/acm/v2/compositions/${compositionId}'
328 This return a 200 response on a successful deletion operation.
330 Participant simulator
331 =====================
332 Participant simulator do not execute any particular functionality, and can be used to mock one or more participants in debug tests.
333 It should be used to test ACM-runtime and Participant Intermediary in specific scenario that could be difficult to replay in real environment.
335 Functionality covered:
337 #. Set participantId and supportedElementType by properties file or by parameter environment.
338 #. Set a delay for each operation at runtime by Rest-Api.
339 #. Set success or fail for each operation at runtime by Rest-Api.
340 #. update composition outProperties and send to ACM-runtime by Rest-Api.
341 #. read all AC Definition inProperties/outProperties information by Rest-Api.
342 #. update useState, operationalState and outProperties and send to ACM-runtime by Rest-Api.
343 #. read all AC instance elements information by Rest-Api.
345 Mock a participant using docker-compose
346 ---------------------------------------
347 The follow example show a docker-compose configuration to mock http Participant, where 'onap/policy-clamp-ac-sim-ppnt' is the Participant simulator image:
352 image: onap/policy-clamp-ac-sim-ppnt
354 - participantId=101c62b3-8918-41b9-a747-d21eb79c6c01
355 - supportedElementTypeName=org.onap.policy.clamp.acm.HttpAutomationCompositionElement
356 - SERVER_SSL_ENABLED=false
362 Set delay and success/fail
363 --------------------------
364 Parameters like delay and success/fail could be set any time using the following endpoint:
368 Invoke a PUT request 'http://participant_sim_ip:port/onap/policy/clamp/acm/simparticipant/v2/parameters'
370 The Json below is an example of configuration:
375 "deploySuccess": true,
376 "undeploySuccess": true,
378 "unlockSuccess": true,
379 "deleteSuccess": true,
380 "updateSuccess": true,
381 "primeSuccess": true,
382 "deprimeSuccess": true,
383 "deployTimerMs": 1000,
384 "undeployTimerMs": 1000,
386 "unlockTimerMs": 100,
387 "updateTimerMs": 100,
388 "deleteTimerMs": 100,
390 "deprimeTimerMs": 100
393 Update and send composition outProperites
394 -----------------------------------------
395 Data like useState operationalState and outProperites could be updated any time using the following endpoint:
399 Invoke a PUT request 'http://participant_sim_ip:port/onap/policy/clamp/acm/simparticipant/v2/compositiondatas'
401 The Json below is an example of update, where {{compositionId}} is the UUID of the AC Definition
402 and ("onap.policy.clamp.ac.element.Http_BridgeAutomationCompositionElement", "1.2.3") is the ToscaConceptIdentifier of the AC Definition element:
413 "compositionId": "{{compositionId}}",
414 "compositionDefinitionElementId": {
415 "name": "onap.policy.clamp.ac.element.Http_BridgeAutomationCompositionElement",
420 Read all AC Definition elements information
421 -------------------------------------------
422 All AC Definition elements information like composition inProperties and outProperties
423 could be read using the following endpoint:
427 Invoke a GET request 'http://participant_sim_ip:port/onap/policy/clamp/acm/simparticipant/v2/compositiondatas'
429 Update and send useState operationalState and instance outProperites
430 --------------------------------------------------------------------
431 Data like useState operationalState and outProperites could be updated any time using the following endpoint:
435 Invoke a PUT request 'http://participant_sim_ip:port/onap/policy/clamp/acm/simparticipant/v2/datas'
437 The Json below is an example of update, where {{instanceId}} is the UUID of the AC instance and {{instanceElementId}} is the UUID of the AC instance element:
449 "automationCompositionId": "{{instanceId}}",
450 "automationCompositionElementId": "{{instanceElementId}}",
452 "operationalState": "ENABLED"
455 Read all AC instance elements information
456 -----------------------------------------
457 All AC instance elements information like deployState, lockState, useState, operationalState, inProperties and outProperties
458 could be read using the following endpoint:
462 Invoke a GET request 'http://participant_sim_ip:port/onap/policy/clamp/acm/simparticipant/v2/instances'