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