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: This node type value should not be changed as the ACM framework identifies the AC elements based on this type.
  79
  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.
  85
  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.
  90
  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.
  94
  95   Note: This node type value should not be changed as the ACM framework identifies the AC definitions based on this type.
  96
  97 .. literalinclude:: files/acm-nodetypes.yaml
  98    :language: yaml
  99
 100 Node Templates:
 101 ---------------
 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.
 106
 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"
 110
 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.
 115
 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"
 119
 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.
 124
 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"
 128
 129 .. literalinclude:: files/acm-nodetemplates.yaml
 130    :language: yaml
 131
 132 Completed tosca template :download:`click here <files/acm-tosca.yaml>`
 133
 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.
 136
 137 ACM workflow
 138 ============
 139
 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
 142 the same.
 143
 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.
 146
 147
 148 Prerequisites:
 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>`_.)
 153
 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.
 156
 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.
 160
 161 .. code-block:: bash
 162
 163   Invoke a POST request 'http://policy_runtime_ip:port/onap/policy/clamp/acm/v2/compositions'
 164
 165 This returns a 202 response on the successful creation of the composition definition.
 166
 167 Note:
 168   The rest response returns the compositionId on a successful creation that requires to be used in the subsequent requests.
 169
 170 Prime AC definitions
 171 --------------------
 172 Priming associates the AC elements with suitable participants and sends the corresponding AC element information to the participants.
 173
 174 .. code-block:: bash
 175
 176   Invoke a PUT request 'http://policy_runtime_ip:port/onap/policy/clamp/acm/v2/compositions/${compositionId}'
 177
 178 Request payload
 179
 180 .. literalinclude:: files/AC-priming.json
 181    :language: json
 182
 183 This returns a 202 response on a successful priming.
 184
 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.
 191
 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.
 194
 195 Note:
 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.
 199
 200 .. code-block:: bash
 201
 202   Invoke a POST request
 203   'http://policy_runtime_ip:port/onap/policy/clamp/acm/v2/compositions/${compositionId}/instances'
 204
 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.
 207
 208 Request payload
 209
 210 .. literalinclude:: files/AC-instantiation.json
 211    :language: json
 212
 213 Deploy AC instance
 214 ------------------
 215 Once the AC instance is created, the user can deploy the instance which in turn activates the corresponding participants to execute the intended operations.
 216 In this case, the kubernetes participant will be installing the test microservice helm chart on the kubernetes cluster and the http participant will be
 217 executing the REST requests on the microservice endpoints.
 218
 219 .. code-block:: bash
 220
 221   Invoke a PUT request
 222   'http://policy_runtime_ip:port/onap/policy/clamp/acm/v2/compositions/${compositionId}/instances/${instanceId}'
 223
 224 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
 225 the elements are updated to "DEPLOYED"
 226 The current status of the deployment can be fetched through the following endpoint.
 227
 228 .. code-block:: bash
 229
 230   Invoke a GET request
 231   'http://policy_runtime_ip:port/onap/policy/clamp/acm/v2/compositions/${compositionId}/instances/${instanceId}'
 232
 233 Request payload
 234
 235 .. literalinclude:: files/AC-deploy.json
 236    :language: json
 237
 238 Note:
 239   The user can further implement the admin states 'LOCK' and 'UNLOCK' on the participants to further cascade the deployment operations.
 240   If these states are implemented, then a subsequent request to LOCK and UNLOCK requires to be triggered following the deployment.
 241
 242 Once all the AC elements are deployed, there should be a test microservice pod running on the kubernetes cluster which is
 243 configured to send events on the kafka by the http participant. This can be verified on the test microservice application logs.
 244 The AC instances can also be undeployed and deleted by the user.
 245
 246 UnDeploy AutomationComposition
 247 ------------------------------
 248 The AC instances can be undeployed from the system by the participants.
 249
 250 .. code-block:: bash
 251
 252   Invoke a PUT request
 253   'http://policy_runtime_ip:port/onap/policy/clamp/acm/v2/compositions/${compositionId}/instances/${instanceId}'
 254
 255 This returns a 202 response on successful deploy order request.
 256
 257 Request payload
 258
 259 .. literalinclude:: files/AC-undeploy.json
 260    :language: json
 261
 262 Uninstantiate AC instance
 263 -------------------------
 264 This deletes the AC instance from the database including all the element properties that are initialised.
 265
 266 .. code-block:: bash
 267
 268   Invoke a DELETE request
 269   'http://policy_runtime_ip:port/onap/policy/clamp/acm/v2/compositions/${compositionId}/instances/${instanceId}'
 270
 271 This returns a 202 response on successful delete order request.
 272
 273 Deprime Ac defintions
 274 ---------------------
 275 Once the AC instance is deleted, it can be deprimed from the participants to be safely deleted from the database.
 276
 277 .. code-block:: bash
 278
 279   Invoke a PUT request 'http://policy_runtime_ip:port/onap/policy/clamp/acm/v2/compositions/${compositionId}'
 280
 281 This returns a 202 response on a successful operation.
 282
 283 Request payload
 284
 285 .. literalinclude:: files/AC-depriming.json
 286    :language: json
 287
 288 Delete AC defintion
 289 -------------------
 290 The AC definitions can be deleted if there are no instances are running and it is not primed to the participants.
 291
 292 .. code-block:: bash
 293
 294   Invoke a DELETE request 'http://policy_runtime_ip:port/onap/policy/clamp/acm/v2/compositions/${compositionId}'
 295
 296 This return a 200 response on a successful deletion operation.