docs/clamp/acm/acm-user-guide.rst

   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.
   4
   5 .. _acm-user-guide-label:
   6
   7 ACM user guide
   8 ##############
   9
  10 .. contents::
  11     :depth: 4
  12
  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.
  16
  17 Defining a composition
  18 ======================
  19
  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.
  22
  23
  24 .. toctree::
  25    :maxdepth: 2
  26
  27    defining-acms
  28
  29 HowTo: My First Automation Composition
  30 ======================================
  31
  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:
  35
  36 Data Types:
  37 -----------
  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.
  39
  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.
  44
  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
  48   the rest request.
  49
  50   Note that the "restRequestId" property which is of type "onap.datatypes.ToscaConceptIdentifier" that was defined in the
  51   previous step.
  52
  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"
  57
  58
  59 .. literalinclude:: files/acm-datatypes.yaml
  60    :language: yaml
  61
  62
  63 Node Types:
  64 -----------
  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:
  69
  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".
  72
  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
  75   the ACM elements.
  76   Here we are defining various timeout properties and startPhase parameter that are common for all the AC elements.
  77
  78   Note:
  79     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"
  80     section of the Automation Composition Runtime design and implementation.
  81
  82 org.onap.policy.clamp.acm.K8SMicroserviceAutomationCompositionElement:
  83   This node type is used to define AC elements that are associated with kubernetes operations. It is further derived from the
  84   "org.onap.policy.clamp.acm.AutomationCompositionElement" type and hence supports its common properties and also includes
  85   additional properties related to helm charts.
  86   We are going to create kubernetes AC elements of this type, under the Node templates.
  87
  88 org.onap.policy.clamp.acm.HttpAutomationCompositionElement:
  89   Node type for AC elements associated with REST operations. It is derived from the "org.onap.policy.clamp.acm.AutomationCompositionElement"
  90   type and hence supports its common properties and also supports additional properties for REST operation.
  91   We are going to create a REST AC element of this type, under the Node templates.
  92
  93 org.onap.policy.clamp.acm.AutomationComposition:
  94   Primitive node type for defining Automation composition definitions that comprises one or more AC elements in it.
  95   The AC definition of this type will be created under the Node templates.
  96
  97   Note:
  98     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"
  99     section of the Automation Composition Runtime design and implementation.
 100
 101 .. literalinclude:: files/acm-nodetypes.yaml
 102    :language: yaml
 103
 104 Node Templates:
 105 ---------------
 106 A Node Template specifies the occurrence of a manageable software component as part of an application's topology model
 107 which is defined in a TOSCA Service Template. We create the actual participants and AC elements involved in this use case
 108 under the node templates.
 109 There are no element properties supplied at this point since it will be provided by the user during the instantiation.
 110
 111 org.onap.k8s.acm.K8SAutomationCompositionParticipant:
 112   A kubernetes participant element that processes the kubernetes AC elements in the composition.
 113   This element is of node type "org.onap.policy.clamp.acm.Participant"
 114
 115 onap.policy.clamp.ac.element.K8S_AutomationCompositionElement:
 116   An AC element for kubernetes helm chart installation of the microservice derived from the node type
 117   "org.onap.policy.clamp.acm.K8SMicroserviceAutomationCompositionElement".
 118   The common element properties are provided with values as part of commissioning the definition.
 119
 120 org.onap.policy.clamp.acm.HttpParticipant:
 121   A http participant element that processes the REST AC elements in the composition.
 122   This element is of type "org.onap.policy.clamp.acm.Participant"
 123
 124 onap.policy.clamp.ac.element.Http_AutomationCompositionElement:
 125  An AC element for REST operation in the microservice derived from the node type
 126  "org.onap.policy.clamp.acm.HttpAutomationCompositionElement".
 127  The common element properties startPhase and timeout are provided with values as part of commissioning the definition.
 128
 129 onap.policy.clamp.ac.element.AutomationCompositionDefinition:
 130  The actual Automation Composition definition that comprises the list of AC elements mapped to it.
 131  This element is of node type "org.onap.policy.clamp.acm.AutomationComposition"
 132
 133 .. literalinclude:: files/acm-nodetemplates.yaml
 134    :language: yaml
 135
 136 Completed tosca template :download:`click here <files/acm-tosca.yaml>`
 137
 138 Once the Tosca template definition is created, the ACM workflow can be executed to create and deploy the compositions.
 139 Please refer the following section for running ACM workflow.
 140
 141 ACM workflow
 142 ============
 143
 144 ACM framework exposes REST interfaces for creating and deploying the user defined compositions. In this section, the
 145 TOSCA template created in the previous step can be commissioned, and then AC instances can be created and deployed for
 146 the same.
 147
 148 This section assumes that the user has read about the ACM APIs and Protocols documentation and understands the ACM
 149 operations on a high level before proceeding with the workflow.
 150
 151
 152 Prerequisites:
 153   - ACM components including acm-runtime, required participants (http and kubernetes in this case) and Dmaap/kafka clients are deployed in docker or kubernetes environment.
 154   - Kubernetes and Helm are installed.
 155   - 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>`_.)
 156   - 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>`_.)
 157
 158 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.
 159 This section guides through the various steps involved in executing the ACM workflow for deploying the test microservice element.
 160
 161 Commissioning the AC definition
 162 -------------------------------
 163 Commissioning refers to storing the composition definition on the ACM database. The created tosca template is posted as a request payload.
 164
 165 .. code-block:: bash
 166
 167   Invoke a POST request 'http://policy_runtime_ip:port/onap/policy/clamp/acm/v2/compositions'
 168
 169 This returns a 202 response on the successful creation of the composition definition.
 170
 171 Note:
 172   The rest response returns the compositionId on a successful creation that requires to be used in the subsequent requests.
 173
 174 Prime AC definitions
 175 --------------------
 176 Priming associates the AC elements with suitable participants and sends the corresponding AC element information to the participants.
 177
 178 .. code-block:: bash
 179
 180   Invoke a PUT request 'http://policy_runtime_ip:port/onap/policy/clamp/acm/v2/compositions/${compositionId}'
 181
 182 Request payload
 183
 184 .. literalinclude:: files/AC-priming.json
 185    :language: json
 186
 187 This returns a 202 response on a successful priming.
 188
 189 Instantiate AutomationComposition
 190 ---------------------------------
 191 Instantiation refers to creating an AC instance on the database by initialising the element properties for each element in the composition.
 192 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
 193 of the test microservice for the Ac element "onap.policy.clamp.ac.element.K8S_AutomationCompositionElement" which will be processed and installed
 194 by the kubernetes participant on a deployment request.
 195
 196 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"
 197 which will be executed by the http participant. Please refer to the properties of the elements in the json payload.
 198
 199 Note:
 200   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.
 201   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.
 202   Each element in the request payload is assigned with a uniques UUID which will be automatically generated by the GUI in the upcoming releases.
 203
 204 .. code-block:: bash
 205
 206   Invoke a POST request
 207   'http://policy_runtime_ip:port/onap/policy/clamp/acm/v2/compositions/${compositionId}/instances'
 208
 209 The compositionId retrieved from the previous step should be updated in the request body. This returns a 201 response on a successful instantiation.
 210 This also returns the instanceId in the response that can be used in the subsequent requests.
 211
 212 Request payload
 213
 214 .. literalinclude:: files/AC-instantiation.json
 215    :language: json
 216
 217 Update AC instance properties (Optional)
 218 ----------------------------------------
 219 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 in the database.
 221
 222 .. code-block:: bash
 223
 224   Invoke a POST request
 225   'http://policy_runtime_ip:port/onap/policy/clamp/acm/v2/compositions/${compositionId}/instances'
 226
 227 Request Payload
 228
 229 Example payload to update the base url of the http request
 230
 231 .. literalinclude:: files/AC-update.json
 232    :language: json
 233
 234
 235 Deploy AC instance
 236 ------------------
 237 Once the AC instance is created, the user can deploy the instance which in turn activates the corresponding participants to execute the intended operations.
 238 In this case, the kubernetes participant will be installing the test microservice helm chart on the kubernetes cluster and the http participant will be
 239 executing the REST requests on the microservice endpoints.
 240
 241 .. code-block:: bash
 242
 243   Invoke a PUT request
 244   'http://policy_runtime_ip:port/onap/policy/clamp/acm/v2/compositions/${compositionId}/instances/${instanceId}'
 245
 246 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
 247 the elements are updated to "DEPLOYED"
 248 The current status of the deployment can be fetched through the following endpoint.
 249
 250 .. code-block:: bash
 251
 252   Invoke a GET request
 253   'http://policy_runtime_ip:port/onap/policy/clamp/acm/v2/compositions/${compositionId}/instances/${instanceId}'
 254
 255 Request payload
 256
 257 .. literalinclude:: files/AC-deploy.json
 258    :language: json
 259
 260 Note:
 261   The user can further implement the admin states 'LOCK' and 'UNLOCK' on the participants to further cascade the deployment operations.
 262   If these states are implemented, then a subsequent request to LOCK and UNLOCK requires to be triggered following the deployment.
 263
 264 Once all the AC elements are deployed, there should be a test microservice pod running on the kubernetes cluster which is
 265 configured to send events on the kafka by the http participant. This can be verified on the test microservice application logs.
 266 The AC instances can also be undeployed and deleted by the user.
 267
 268 Update AC instance properties after deployment (Optional)
 269 ---------------------------------------------------------
 270 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
 271 in the database and also sends an update event to the participants. The participants has to implement the update method to perform the
 272 required operation.
 273
 274 .. code-block:: bash
 275
 276   Invoke a POST request
 277   'http://policy_runtime_ip:port/onap/policy/clamp/acm/v2/compositions/${compositionId}/instances'
 278
 279 Note:
 280   Please refer the request payload section for updating the instance properties before deployment.
 281
 282 Migrate AC instance
 283 -------------------
 284 After the AC instance is deployed, the user can migrate it to other composition definition.
 285 The target composition have to be primed and have to contain the same element definitions present in the source composition.
 286 The user can update the instance property values if needed.
 287
 288 .. code-block:: bash
 289
 290   Invoke a POST request
 291   'http://policy_runtime_ip:port/onap/policy/clamp/acm/v2/compositions/${compositionId}/instances'
 292
 293 Request Payload
 294
 295 Example payload to migrate and update the base url of the http request
 296
 297 .. literalinclude:: files/AC-migrate.json
 298    :language: json
 299
 300 UnDeploy AutomationComposition
 301 ------------------------------
 302 The AC instances can be undeployed from the system by the participants.
 303
 304 .. code-block:: bash
 305
 306   Invoke a PUT request
 307   'http://policy_runtime_ip:port/onap/policy/clamp/acm/v2/compositions/${compositionId}/instances/${instanceId}'
 308
 309 This returns a 202 response on successful deploy order request.
 310
 311 Request payload
 312
 313 .. literalinclude:: files/AC-undeploy.json
 314    :language: json
 315
 316 Uninstantiate AC instance
 317 -------------------------
 318 This deletes the AC instance from the database including all the element properties that are initialised.
 319
 320 .. code-block:: bash
 321
 322   Invoke a DELETE request
 323   'http://policy_runtime_ip:port/onap/policy/clamp/acm/v2/compositions/${compositionId}/instances/${instanceId}'
 324
 325 This returns a 202 response on successful delete order request.
 326
 327 Deprime Ac defintions
 328 ---------------------
 329 Once the AC instance is deleted, it can be deprimed from the participants to be safely deleted from the database.
 330
 331 .. code-block:: bash
 332
 333   Invoke a PUT request 'http://policy_runtime_ip:port/onap/policy/clamp/acm/v2/compositions/${compositionId}'
 334
 335 This returns a 202 response on a successful operation.
 336
 337 Request payload
 338
 339 .. literalinclude:: files/AC-depriming.json
 340    :language: json
 341
 342 Delete AC defintion
 343 -------------------
 344 The AC definitions can be deleted if there are no instances are running and it is not primed to the participants.
 345
 346 .. code-block:: bash
 347
 348   Invoke a DELETE request 'http://policy_runtime_ip:port/onap/policy/clamp/acm/v2/compositions/${compositionId}'
 349
 350 This return a 200 response on a successful deletion operation.
 351
 352 Participant simulator
 353 =====================
 354 Participant simulator do not execute any particular functionality, and can be used to mock one or more participants in debug tests.
 355 It should be used to test ACM-runtime and Participant Intermediary in specific scenario that could be difficult to replay in real environment.
 356
 357 Functionality covered:
 358
 359 #. Set participantId and supportedElementType by properties file or by parameter environment.
 360 #. Set a delay for each operation at runtime by Rest-Api.
 361 #. Set success or fail for each operation at runtime by Rest-Api.
 362 #. update composition outProperties and send to ACM-runtime by Rest-Api.
 363 #. read all AC Definition inProperties/outProperties information by Rest-Api.
 364 #. update useState, operationalState and outProperties and send to ACM-runtime by Rest-Api.
 365 #. read all AC instance elements information by Rest-Api.
 366 #. log of all information for each operation.
 367
 368 Mock a participant using docker-compose
 369 ---------------------------------------
 370 The follow example show a docker-compose configuration to mock http Participant, where 'onap/policy-clamp-ac-sim-ppnt' is the Participant simulator image:
 371
 372 .. code-block:: yaml
 373
 374   http-participant:
 375     image: onap/policy-clamp-ac-sim-ppnt
 376     environment:
 377       - participantId=101c62b3-8918-41b9-a747-d21eb79c6c01
 378       - supportedElementTypeName=org.onap.policy.clamp.acm.HttpAutomationCompositionElement
 379       - SERVER_SSL_ENABLED=false
 380       - useHttps=false
 381       - SERVER_PORT=8084
 382     ports:
 383       - "8084:8084"
 384
 385 Set delay and success/fail
 386 --------------------------
 387 Parameters like delay and success/fail could be set any time using the following endpoint:
 388
 389 .. code-block:: bash
 390
 391   Invoke a PUT request 'http://participant_sim_ip:port/onap/policy/clamp/acm/simparticipant/v2/parameters'
 392
 393 The Json below is an example of configuration:
 394
 395 .. code-block:: json
 396
 397   {
 398     "deploySuccess": true,
 399     "undeploySuccess": true,
 400     "lockSuccess": true,
 401     "unlockSuccess": true,
 402     "deleteSuccess": true,
 403     "updateSuccess": true,
 404     "migrateSuccess": true,
 405     "primeSuccess": true,
 406     "deprimeSuccess": true,
 407     "deployTimerMs": 1000,
 408     "undeployTimerMs": 1000,
 409     "migrateTimerMs": 100,
 410     "lockTimerMs": 100,
 411     "unlockTimerMs": 100,
 412     "updateTimerMs": 100,
 413     "deleteTimerMs": 100,
 414     "primeTimerMs": 100,
 415     "deprimeTimerMs": 100
 416   }
 417
 418 Update and send composition outProperites
 419 -----------------------------------------
 420 Data like useState operationalState and outProperites could be updated any time using the following endpoint:
 421
 422 .. code-block:: bash
 423
 424   Invoke a PUT request 'http://participant_sim_ip:port/onap/policy/clamp/acm/simparticipant/v2/compositiondatas'
 425
 426 The Json below is an example of update, where {{compositionId}} is the UUID of the AC Definition
 427 and ("onap.policy.clamp.ac.element.Http_BridgeAutomationCompositionElement", "1.2.3") is the ToscaConceptIdentifier  of the AC Definition element:
 428
 429 .. code-block:: json
 430
 431   {
 432         "outProperties": {
 433             "list": [
 434                 {"id": 10 },
 435                 {"id": 20 }
 436             ]
 437         },
 438         "compositionId": "{{compositionId}}",
 439         "compositionDefinitionElementId": {
 440             "name": "onap.policy.clamp.ac.element.Http_BridgeAutomationCompositionElement",
 441             "version": "1.2.3"
 442         }
 443   }
 444
 445 Read all AC Definition elements information
 446 -------------------------------------------
 447 All AC Definition elements information like composition inProperties and outProperties
 448 could be read using the following endpoint:
 449
 450 .. code-block:: bash
 451
 452   Invoke a GET request 'http://participant_sim_ip:port/onap/policy/clamp/acm/simparticipant/v2/compositiondatas'
 453
 454 Update and send useState operationalState and instance outProperites
 455 --------------------------------------------------------------------
 456 Data like useState operationalState and outProperites could be updated any time using the following endpoint:
 457
 458 .. code-block:: bash
 459
 460   Invoke a PUT request 'http://participant_sim_ip:port/onap/policy/clamp/acm/simparticipant/v2/datas'
 461
 462 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:
 463
 464 .. code-block:: json
 465
 466   {
 467         "outProperties": {
 468             "Opresult": true,
 469             "list": [
 470                 {"id": 1 },
 471                 {"id": 2 }
 472             ]
 473         },
 474         "automationCompositionId": "{{instanceId}}",
 475         "automationCompositionElementId": "{{instanceElementId}}",
 476         "useState": "IDLE",
 477         "operationalState": "ENABLED"
 478   }
 479
 480 Read all AC instance elements information
 481 -----------------------------------------
 482 All AC instance elements information like deployState, lockState, useState, operationalState, inProperties and outProperties
 483 could be read using the following endpoint:
 484
 485 .. code-block:: bash
 486
 487   Invoke a GET request 'http://participant_sim_ip:port/onap/policy/clamp/acm/simparticipant/v2/instances'
 488
 489 Log of all information for each operation
 490 -----------------------------------------
 491 All information for each operation are logged, so the developer can monitoring what data are passed through the calls. Example of log during deploy.
 492
 493 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**
 494 **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={} **]**