From 7ae1f0b9c56ea4d443e0d3a8898ca8dc49aa3d51 Mon Sep 17 00:00:00 2001 From: brunomilitzer Date: Fri, 1 Apr 2022 12:52:30 +0100 Subject: Removed Control Loop from definition-controlloops Issue-ID: POLICY-4059 Change-Id: I81489e379dc505fd5b148f8ab422177f9461cc20 Signed-off-by: brunomilitzer --- docs/clamp/acm/defining-acms.rst | 273 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 273 insertions(+) create mode 100644 docs/clamp/acm/defining-acms.rst (limited to 'docs/clamp/acm/defining-acms.rst') diff --git a/docs/clamp/acm/defining-acms.rst b/docs/clamp/acm/defining-acms.rst new file mode 100644 index 00000000..185f53a8 --- /dev/null +++ b/docs/clamp/acm/defining-acms.rst @@ -0,0 +1,273 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. + +.. _defining-acms-label: + +Defining Automation Compositions in TOSCA for CLAMP +################################################### + + +.. contents:: + :depth: 4 + + +A Automation Composition Type is defined in a TOSCA service template. A TOSCA Service Template has +two parts: a definition part in the service template itself, which contains the definitions +of concepts that can be used to define the types of concepts that can appear on a Toplogy +Template and a Topology Template that defines a topology. See the `Oasis Open TOSCA +`_ web page +for more details on TOSCA. + +Unsurprisingly, to define a Automation Composition Type in TOSCA, of Automation Composition related concepts +that we can use in all automation compositions exist. They are described in Section 1. Section 2 +describes how properties are managed. Properties are the configuration parameters that are +provided to Automation Compositions and the Automation Composition Elements they use. Section 3 describes how to +define a Automation Composition using the predefined Automation Composition concepts. + + +1 Standard TOSCA Service Template Concepts for Automation Compositions +====================================================================== + +These concepts are the base concepts available to users who write definitions for automation +compositions in TOSCA. TOSCA automation composition definitions are written using these concepts. + +1.1 Fundamental TOSCA Concepts for Automation Compositions +---------------------------------------------------------- + +The following TOSCA concepts are the fundamental concepts in a TOSCA Service Template for +defining automation compositions. + +.. image:: images/defining-acms/fundamental-concepts.png + +The TOSCA concepts above may be declared in the TOSCA Service Template of a automation composition. +If the concepts already exist in the Design Time Catalogue or the Runtime Inventory, they +may be omitted from a TOSCA service template that defines a automation composition type. + +The *start_phase* is a value indicating the start phase in which this automation composition element +will be started, the first start phase is zero. Automation Composition Elements are started in their +start_phase order and stopped in reverse start phase order. Automation Composition Elements with the +same start phase are started and stopped simultaneously. + +The Yaml file that holds the Definition of `TOSCA fundamental Automation Composition Types is available in Github +`_ +and is the canonical definition of the Automation Composition concepts. + +1.2 TOSCA Concepts for Automation Composition Elements delivered by ONAP +------------------------------------------------------------------------ + +TOSCA Standard Automation Composition Elements + +.. image:: images/defining-acms/standard-acme.png + :width: 600 + +1.2.1 Policy Automation Composition Element +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The Policy Participant runs Policy Automation Composition Elements. Each Policy Automation Composition Element +manages the deployment of the policy specified in the Policy Automation Composition Element definition. +The Yaml file that holds the `Policy Automation Composition Element Type definition is available in Github +`_ +and is the canonical definition of the Policy Automation Composition Element type. For a description of +the Policy Automation Composition Element and Policy Participant, please see `The CLAMP Policy Framework +Participant <#>`_ page. + +1.2.2 HTTP Automation Composition Element +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The HTTP Participant runs HTTP Automation Composition Elements. Each HTTP Automation Composition Element manages +REST communication towards a REST endpoint using the REST calls a user has specified in the +configuration of the HTTP Automation Composition Element. The Yaml file that holds the +`HTTP Automation Composition Element Type definition is available in Github +`_ +and is the canonical definition of the HTTP Automation Composition Element type. For a description of +the HTTP Automation Composition Element and HTTP Participant, please see `The CLAMP HTTP Participant <#>`_ page. + +.. _kubernetes-acm-element: + +1.2.3 Kubernetes Automation Composition Element +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The Kubernetes Participant runs Kubernetes Automation Composition Elements. Each Kubernetes Automation Composition +Element manages a Kubernetes microservice using Helm. The user defines the Helm chart for the +Kubernetes microservice as well as other properties that the microservice requires in order to +execute. The Yaml file that holds the +`Kubernetes Automation Composition Element Type defintion is available in Github +`_ +and is the canonical definition of the Kubernetes Automation Composition Element type. For a description +of the Kubernetes Automation Composition Element and Kubernetes Participant,please see +`The CLAMP Kubernetes Participant <#>`_ page. + + +2 Common and Instance Specific Properties +========================================= + +Properties are used to define the configuration for Automation Compositions and Automation Composition Elements. +At design time, the types, constraints, and descriptions of the properties are specified. +The values for properties are specified in the CLAMP GUI at runtime. TOSCA provides support +for defining properties, see `Section 3.6.10: TOSCA Property Definition +`_ +in the TOSCA documentation. + +2.1 Terminology for Properties +------------------------------ + +**Property:** Metadata defined in TOSCA that is associated with a Automation Composition, a Automation +Composition Element, or a Participant. + +**TOSCA Property Type:** The TOSCA definition of the type of a property. A property can have +a generic type such as string or integer or can have a user defined TOSCA data type. + +**TOSCA Property Value:** The value of a Property Type. Property values are assigned at run +time in CLAMP. + +**Common Property Type:** Property Types that apply to all instances of a Automation Composition Type. + +**Common Property Value:** The value of a Property Type. It is assigned at run time once for +all instances of a Automation Composition Type. + +**Instance Specific Property Type:** Property Types that apply to an individual instance of +a Automation Composition Type. + +**Instance Specific Property Value:** The value of a Property Type that applies to an +individual instance of a Automation Composition Type. The value is assigned at run time for each +automation composition instance. + +Automation Composition Properties can be *common* or *instance specific*. See Section 2 of +:ref:`TOSCA Defined Automation Compositions: Architecture and Design ` +for a detailed description of the usage of common and instance specific properties. + +2.2 Common Properties +--------------------- + +Common properties apply to all instances of a automation composition. Common properties are identified +by a special metadata flag in Automation Composition and Automation Composition Element definitions. For example, +the startPhase parameter on any Automation Composition Element has the same value for any instance of +that automation composition element, so it is defined as shown below in the +`Definition of TOSCA fundamental Automation Composition Types +`_ +yaml file. + +.. code-block:: yaml + + startPhase: + type: integer + required: false + constraints: + - greater-or-equal: 0 + description: A value indicating the start phase in which this automation composition element will be started, the + first start phase is zero. Automation Composition Elements are started in their start_phase order and stopped + in reverse start phase order. Automation Composition Elements with the same start phase are started and + stopped simultaneously + metadata: + common: true + +The "common: true" value in the metadata of the startPhase property identifies that property +as being a common property. This property will be set on the CLAMP GUI during automation composition +commissioning. + +2.3 Instance Specific Properties +-------------------------------- + +Instance Specific properties apply to individual instances of a Automation Composition and/or Automation +Composition Element and must be set individually for Automation Composition and Automation Composition Element instance. +Properties are instance specific by default, but can be identified by a special metadata flag +in Automation Composition and Automation Composition Element definitions. For example, the chart parameter on a +Kubernetes Automation Composition Element has a different value for every instance of a Kubernetes Automation +Composition Element, so it can be defined as shown below in the :ref:`Kubernetes Automation Composition Type definition +` yaml file. + + +.. code-block:: yaml + + # Definition that omits the common flag metadata + chart: + type: org.onap.datatypes.policy.clamp.acm.kubernetesAutomationCompositionElement.Chart + typeVersion: 1.0.0 + description: The helm chart for the microservice + required: true + + # Definition that specifies the common flag metadata + chart: + type: org.onap.datatypes.policy.clamp.acm.kubernetesAutomationCompositionElement.Chart + typeVersion: 1.0.0 + description: The helm chart for the microservice + required: true + metadata: + common: false + +The "common: false" value in the metadata of the chart property identifies that property as +being an instance specific property. This property will be set on the CLAMP GUI during automation +composition instantiation. + + +3 Writing a Automation Composition Type Definition +================================================== + +The TOSCA definition of a automation composition contains a TOSCA Node Template for the automation composition +itself, which contains TOSCA Node Templates for each Automation Composition Element that makes up the +Automation Composition. + +.. image:: images/defining-acms/acm-node-template.png + :width: 600 + +To create a automation composition, a user creates a TOSCA Topology Template. In the Topology Template, +the user creates a TOSCA Node Template for each Automation Composition Element that will be in the +Automation Composition Definition. Finally, the user creates the Node Template that defines the Automation +Composition itself, and references the Automation Composition Element definitions that make up the Automation Composition +Definition. + +3.1 The Gentle Guidance Automation Composition +---------------------------------------------- + +The best way to explain how to create a Automation Composition Definition is by example. + +.. image:: images/defining-acms/gentle-guidance-acm.png + +The example Gentle Guidance automation composition is illustrated in the diagram above. The domain logic for the automation composition is +implemented in a microservice running in Kubernetes, a policy, and some configuration that is passed to the microservice +over a REST endpoint. We want to manage the life cycle of the domain logic for our Gentle Guidance automation composition using +our TOSCA based Automation Composition Life Cycle Management approach. To do this we create four Automation Composition Element definitions, +one for the Kubernetes microservice, one for the policy and one or the REST configuration. + +3.2 The TOSCA Automation Composition Definition +----------------------------------------------- + +We use a TOSCA Topology Template to specify a Automation Composition definition and the definitions of +its Automation Composition Elements. Optionally, we can specify default parameter values in the TOSCA +Topology Template. The actual values of Automation Composition common and instance specific parameters +are set at run time in the CLAMP GUI. + +In the case of the Gentle Guidance automation composition, we define a Automation Composition Element Node Template +for each part of the domain logic we are managing. We then define the Automation Composition Node Template +for the automation composition itself. + +Please refer to the `No Properties yaml file in Github +`_ +for the definitive Yaml specification for the TOSCA Topology Template for the Gentle Guidance +domain when no parameters are defined. + +Please refer to the `Default Properties yaml file in Github +`_ +for the definitive Yaml specification for the TOSCA Topology Template for the Gentle Guidance +domain when the default values of parameters are defined. + + +4 Creating Custom Automation Composition Elements +================================================= + +Any organization can include their own component in the framework and use the framework and have +the Policy Framework CLAMP manage the lifecycle of domain logic in their component as part of a +Automation Composition. To do this, a participant for the component must be developed that allows Automation +Composition Elements for that component to be run. To develop a participant, the participant must comply +with the `CLAMP Participants <#>`_ +framework and in particular comply with `The CLAMP Automation Composition Participant Protocol <#>`_. +The organization must also specify a new Automation Composition Element type definition in TOSCA similar to +those supplied in ONAP and described in Section 1.2. This Automation Composition Element type tells the +CLAMP Automation Composition Lifecycle management that the Automation Composition Element exists and can be included +in automation compositions. It also specifies the properties that can be specified for the Automation Composition Element. + +An organization can supply the code for the Participant (for example as a Java jar file) and a +TOSCA artifact with the Automation Composition Element definition and it can be added to the platform. In +future releases, support will be provided to include participants and their Automation Composition Element +definitions as packaged plugins that can be installed on the platform. + +End of document -- cgit 1.2.3-korg