docs/clamp/acm/defining-acms.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2
   3 .. _defining-acms-label:
   4
   5 Defining Automation Compositions in TOSCA for CLAMP
   6 ###################################################
   7
   8
   9 .. contents::
  10     :depth: 4
  11
  12 - **Automation Composition:** A set of elements working together to deliver a feature or function.
  13 - **Automation Composition Type Definition:** A formal definition of a type of an Automation Composition in the TOSCA modelling language (described in JSON or YAML), which specifies the type and properties of elements that make up an Automation Composition and the types of participants that host those elements
  14 - **Automation Composition Type:** An Automation Composition type, which has been created (commissioned) in the ACM runtime server
  15 - **Automation Composition Instance:** An instance of an Automation Composition Type, which as been created in the ACM runtime server. The elements of an Automation Composition Instance run on participants. The collection of all the Automation Composition Element Instances make up an Automation Composition Instance.
  16
  17 A Automation Composition Type is defined in a TOSCA service template. A TOSCA Service Template has
  18 two parts: a definition part in the service template itself, which contains the definitions
  19 of concepts that can be used to define the types of concepts that can appear on a Toplogy
  20 Template and a Topology Template that defines a topology. See the `Oasis Open TOSCA
  21 <https://docs.oasis-open.org/tosca/TOSCA-Simple-Profile-YAML/v1.3/>`_ web page
  22 for more details on TOSCA.
  23
  24 Unsurprisingly, to define a Automation Composition Type in TOSCA, of Automation Composition related concepts
  25 that we can use in all automation compositions exist. They are described in Section 1. Section 2
  26 describes how properties are managed. Properties are the configuration parameters that are
  27 provided to Automation Compositions and the Automation Composition Elements they use. Section 3 describes how to
  28 define a Automation Composition using the predefined Automation Composition concepts.
  29
  30
  31 1 Standard TOSCA Service Template Concepts for Automation Compositions
  32 ======================================================================
  33
  34 These concepts are the base concepts available to users who write definitions for automation
  35 compositions in TOSCA. TOSCA automation composition definitions are written using these concepts.
  36
  37 1.1 Fundamental TOSCA Concepts for Automation Compositions
  38 ----------------------------------------------------------
  39
  40 The following TOSCA concepts are the fundamental concepts in a TOSCA Service Template for
  41 defining automation compositions.
  42
  43 .. image:: images/defining-acms/fundamental-concepts.png
  44
  45 The TOSCA concepts above may be declared in the TOSCA Service Template of a automation composition.
  46 If the concepts already exist in the Design Time Catalogue or the Runtime Inventory, they
  47 may be omitted from a TOSCA service template that defines a automation composition type.
  48
  49 The *start_phase* is a value indicating the start phase in which this automation composition element
  50 will be started, the first start phase is zero. Automation Composition Elements are started in their
  51 start_phase order and stopped in reverse start phase order. Automation Composition Elements with the
  52 same start phase are started and stopped simultaneously.
  53
  54 The Yaml file that holds the Definition of `TOSCA fundamental Automation Composition Types is available in Github
  55 <https://github.com/onap/policy-clamp/blob/master/common/src/main/resources/tosca/AutomationCompositionTOSCAServiceTemplateTypes.yaml>`_
  56 and is the canonical definition of the Automation Composition concepts.
  57
  58 1.2 TOSCA Concepts for Automation Composition Elements delivered by ONAP
  59 ------------------------------------------------------------------------
  60
  61 TOSCA Standard Automation Composition Elements
  62
  63 .. image:: images/defining-acms/standard-acme.png
  64   :width: 600
  65
  66 - **Automation Composition Element Type Definition:** A formal definition of a type of an Automation Composition element in an Automation Composition Type Definition.
  67 - **Automation Composition Element Type:** An Automation Composition element type in an Automation Composition type, which has been created (commissioned) in the ACM runtime server
  68 - **Automation Composition Element Instance:** An instance of an Automation Composition Element, which can run on an Participant
  69 - **Participant:** A component that agrees to run elements of Automation Compositions. Therefore, participants agree to be part of Automation Composition Instances. Participants of a particular type can run Automation Composition Elements of specific types.
  70
  71
  72 1.2.1 Policy Automation Composition Element
  73 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  74
  75 The Policy Participant runs Policy Automation Composition Elements. Each Policy Automation Composition Element
  76 manages the deployment of the policy specified in the Policy Automation Composition Element definition.
  77 The Yaml file that holds the `Policy Automation Composition Element Type definition is available in Github
  78 <https://github.com/onap/policy-clamp/blob/master/common/src/main/resources/tosca/PolicyAutomationCompositionElementType.yaml>`_
  79 and is the canonical definition of the Policy Automation Composition Element type. For a description of
  80 the Policy Automation Composition Element and Policy Participant, please see `The CLAMP Policy Framework
  81 Participant <#>`_ page.
  82
  83 1.2.2 HTTP Automation Composition Element
  84 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  85
  86 The HTTP Participant runs HTTP Automation Composition Elements. Each HTTP Automation Composition Element manages
  87 REST communication towards a REST endpoint using the REST calls a user has specified in the
  88 configuration of the HTTP Automation Composition Element. The Yaml file that holds the
  89 `HTTP Automation Composition Element Type definition is available in Github
  90 <https://github.com/onap/policy-clamp/blob/master/common/src/main/resources/tosca/PolicyAutomationCompositionElementType.yaml>`_
  91 and is the canonical definition of the HTTP Automation Composition Element type. For a description of
  92 the HTTP Automation Composition Element and HTTP Participant, please see `The CLAMP HTTP Participant <#>`_ page.
  93
  94 .. _kubernetes-acm-element:
  95
  96 1.2.3 Kubernetes Automation Composition Element
  97 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  98
  99 The Kubernetes Participant runs Kubernetes Automation Composition Elements. Each Kubernetes Automation Composition
 100 Element manages a Kubernetes microservice using Helm. The user defines the Helm chart for the
 101 Kubernetes microservice as well as other properties that the microservice requires in order to
 102 execute. The Yaml file that holds the
 103 `Kubernetes Automation Composition Element Type defintion is available in Github
 104 <https://github.com/onap/policy-clamp/blob/master/common/src/main/resources/tosca/KubernetesAutomationCompositionElementType.yaml>`_
 105 and is the canonical definition of the Kubernetes Automation Composition Element type. For a description
 106 of the Kubernetes Automation Composition Element and Kubernetes Participant,please see
 107 `The CLAMP Kubernetes Participant <#>`_ page.
 108
 109
 110 2 Common and Instance Specific Properties
 111 =========================================
 112
 113 Properties are used to define the configuration for Automation Compositions and Automation Composition Elements.
 114 At design time, the types, constraints, and descriptions of the properties are specified.
 115 The values for properties are specified in Automation Composition Instance. TOSCA provides support
 116 for defining properties, see `Section 3.6.10: TOSCA Property Definition
 117 <https://docs.oasis-open.org/tosca/TOSCA-Simple-Profile-YAML/v1.3/os/TOSCA-Simple-Profile-YAML-v1.3-os.html#DEFN_ELEMENT_PROPERTY_DEFN>`_
 118 in the TOSCA documentation.
 119
 120 2.1 Terminology for Properties
 121 ------------------------------
 122
 123 **Property:** Metadata defined in TOSCA that is associated with a Automation Composition, a Automation
 124 Composition Element, or a Participant.
 125
 126 **TOSCA Property Type:** The TOSCA definition of the type of a property. A property can have
 127 a generic type such as string or integer or can have a user defined TOSCA data type.
 128
 129 **TOSCA Property Value:** The value of a Property Type.
 130
 131 **Common Property Type:** Property Types that apply to all instances of a Automation Composition Type.
 132
 133 **Common Property Value:** The value of a Property Type. It is assigned in Automation Composition Definition once for
 134 all instances of a Automation Composition Type.
 135
 136 **Instance Specific Property Type:** Property Types that apply to all instances of a specific Automation Composition Type.
 137
 138 **Instance Specific Property Value:** The value of a Property Type that applies to an
 139 individual instance of a Instance Specific Property Type. The value is assigned in Automation Composition Instance.
 140
 141 Automation Composition Properties can be *common* or *instance specific*. See Section 2 of
 142 :ref:`TOSCA Defined Automation Compositions: Architecture and Design <acm-capabilities>`
 143 for a detailed description of the usage of common and instance specific properties.
 144
 145 2.2 Common Properties
 146 ---------------------
 147
 148 Common properties apply to all instances of a automation composition. Common properties are identified
 149 by a special metadata flag in Automation Composition and Automation Composition Element definitions. For example,
 150 the startPhase parameter on any Automation Composition Element has the same value for any instance of
 151 that automation composition element, so it is defined as shown below in the
 152 `Definition of TOSCA fundamental Automation Composition Types
 153 <https://github.com/onap/policy-clamp/blob/master/common/src/main/resources/tosca/AutomationCompositionTOSCAServiceTemplateTypes.yaml>`_
 154 yaml file.
 155
 156 .. code-block:: yaml
 157
 158     startPhase:
 159       type: integer
 160       required: false
 161       constraints:
 162       - greater-or-equal: 0
 163       description: A value indicating the start phase in which this automation composition element will be started, the
 164                   first start phase is zero. Automation Composition Elements are started in their start_phase order and stopped
 165                   in reverse start phase order. Automation Composition Elements with the same start phase are started and
 166                   stopped simultaneously
 167       metadata:
 168         common: true
 169
 170 The "common: true" value in the metadata of the startPhase property identifies that property
 171 as being a common property. This property will be set on the CLAMP GUI during automation composition
 172 commissioning.
 173
 174 2.3 Instance Specific Properties
 175 --------------------------------
 176
 177 Instance Specific  properties apply to individual instances of a Automation Composition and/or Automation
 178 Composition Element and must be set individually for Automation Composition and Automation Composition Element instance.
 179 Properties are instance specific by default, but can be identified by a special metadata flag
 180 in Automation Composition and Automation Composition Element definitions. For example, the chart parameter on a
 181 Kubernetes Automation Composition Element has a different value for every instance of a Kubernetes Automation
 182 Composition Element, so it can be defined as shown below in the :ref:`Kubernetes Automation Composition Type definition
 183 <kubernetes-acm-element>` yaml file.
 184
 185
 186 .. code-block:: yaml
 187
 188     # Definition that omits the common flag metadata
 189     chart:
 190       type: org.onap.datatypes.policy.clamp.acm.kubernetesAutomationCompositionElement.Chart
 191       typeVersion: 1.0.0
 192       description: The helm chart for the microservice
 193       required: true
 194
 195     # Definition that specifies the common flag metadata
 196     chart:
 197       type: org.onap.datatypes.policy.clamp.acm.kubernetesAutomationCompositionElement.Chart
 198       typeVersion: 1.0.0
 199       description: The helm chart for the microservice
 200       required: true
 201       metadata:
 202         common: false
 203
 204 The "common: false" value in the metadata of the chart property identifies that property as
 205 being an instance specific property. This property will be set on the CLAMP GUI during automation
 206 composition instantiation.
 207
 208
 209 3 Writing a Automation Composition Type Definition
 210 ==================================================
 211
 212 The TOSCA definition of a automation composition contains a TOSCA Node Template for the automation composition
 213 itself, which contains TOSCA Node Templates for each Automation Composition Element that makes up the
 214 Automation Composition.
 215
 216 .. image:: images/defining-acms/acm-node-template.png
 217   :width: 600
 218
 219 To create a automation composition, a user creates a TOSCA Topology Template. In the Topology Template,
 220 the user creates a TOSCA Node Template for each Automation Composition Element that will be in the
 221 Automation Composition Definition. Finally, the user creates the Node Template that defines the Automation
 222 Composition itself, and references the Automation Composition Element definitions that make up the Automation Composition
 223 Definition.
 224
 225 3.1 The Gentle Guidance Automation Composition
 226 ----------------------------------------------
 227
 228 The best way to explain how to create a Automation Composition Definition is by example.
 229
 230 .. image:: images/defining-acms/gentle-guidance-acm.png
 231
 232 The example Gentle Guidance automation composition is illustrated in the diagram above. The domain logic for the automation composition is
 233 implemented in a microservice running in Kubernetes, a policy, and some configuration that is passed to the microservice
 234 over a REST endpoint. We want to manage the life cycle of the domain logic for our Gentle Guidance automation composition using
 235 our TOSCA based Automation Composition Life Cycle Management approach. To do this we create four Automation Composition Element definitions,
 236 one for the Kubernetes microservice, one for the policy and one or the REST configuration.
 237
 238 3.2 The TOSCA Automation Composition Definition
 239 -----------------------------------------------
 240
 241 We use a TOSCA Topology Template to specify a Automation Composition definition and the definitions of
 242 its Automation Composition Elements. Optionally, we can specify default parameter values in the TOSCA
 243 Topology Template. The actual values of Automation Composition common and instance specific parameters
 244 are set in Automation Composition Instance.
 245
 246 In the case of the Gentle Guidance automation composition, we define a Automation Composition Element Node Template
 247 for each part of the domain logic we are managing. We then define the Automation Composition Node Template
 248 for the automation composition itself.
 249
 250 Please refer to the `No Properties yaml file in Github
 251 <https://github.com/onap/policy-clamp/blob/cbd4d5dbe88928d5765e9749987f6b93f2b347e9/examples/src/main/resources/clamp/acm/gentleguidance/GentleGuidanceNoProperties.yaml>`_
 252 for the definitive Yaml specification for the TOSCA Topology Template for the Gentle Guidance
 253 domain when no parameters are defined.
 254
 255 Please refer to the `Default Properties yaml file in Github
 256 <https://github.com/onap/policy-clamp/blob/cbd4d5dbe88928d5765e9749987f6b93f2b347e9/examples/src/main/resources/clamp/acm/gentleguidance/GentleGuidanceDefaultProperties.yaml>`_
 257 for the definitive Yaml specification for the TOSCA Topology Template for the Gentle Guidance
 258 domain when the default values of parameters are defined.
 259
 260
 261 4 Creating Custom Automation Composition Elements
 262 =================================================
 263
 264 Any organization can include their own component in the framework and use the framework and have
 265 the Policy Framework CLAMP manage the lifecycle of domain logic in their component as part of a
 266 Automation Composition. To do this, a participant for the component must be developed that allows Automation
 267 Composition Elements for that component to be run. To develop a participant, the participant must comply
 268 with the `CLAMP Participants <#>`_
 269 framework and in particular comply with `The CLAMP Automation Composition Participant Protocol <#>`_.
 270 The organization must also specify a new Automation Composition Element type definition in TOSCA similar to
 271 those supplied in ONAP and described in Section 1.2. This Automation Composition Element type tells the
 272 CLAMP Automation Composition Lifecycle management that the Automation Composition Element exists and can be included
 273 in automation compositions. It also specifies the properties that can be specified for the Automation Composition Element.
 274
 275 An organization can supply the code for the Participant (for example as a Java jar file) and a
 276 TOSCA artifact with the Automation Composition Element definition and it can be added to the platform. In
 277 future releases, support will be provided to include participants and their Automation Composition Element
 278 definitions as packaged plugins that can be installed on the platform.
 279
 280 End of document