Defining Control Loops documentation.

Issue-ID: POLICY-3363
Change-Id: I11cc75800a78c67295d7286804158786ffd4e651
Signed-off-by: adheli.tavares <adheli.tavares@est.tech>

7 files changed, 305 insertions, 2 deletions

diff --git a/docs/clamp/clamp.rst b/docs/clamp/clamp.rst
index 7d9452e6..9fe6190f 100644
--- a/docs/clamp/clamp.rst
+++ b/docs/clamp/clamp.rst
@@ -13,4 +13,5 @@ CLAMP handles control loops in two ways, either using built in ONAP Control Loop
    clamp/clamp
    controlloop/controlloop
    controlloop/system-level-dialogues
+   controlloop/defining-controlloops
 
diff --git a/docs/clamp/controlloop/controlloop.rst b/docs/clamp/controlloop/controlloop.rst
index aa6bbedc..a505abfe 100644
--- a/docs/clamp/controlloop/controlloop.rst
+++ b/docs/clamp/controlloop/controlloop.rst
@@ -222,6 +222,7 @@ At Run Time, the following Control Loop Life Cycle management capabilities are s
     The system dialogues for run time capabilities are described in detail on the
     :ref:`System Level Dialogues <system-level-label>` page.
 
+.. _controlloop-instance-states:
 
 2.1 Control Loop Instance States
 --------------------------------
@@ -312,6 +313,8 @@ partake in control loops.
 4. Other Considerations
 =======================
 
+.. _management-cl-instance-configs:
+
 4.1 Management of Control Loop Instance Configurations
 ------------------------------------------------------
 
@@ -395,7 +398,7 @@ of many types across themselves using a mechanism such as a Kubernetes cluster.
 At runtime, interaction between ONAP platform services and application microservices are
 relatively unconstrained, so interactions between Control Loop Elements for a given Control
 Loop Instance remain relatively unconstrained. A
-`proposal to support access-controlled accessto and between ONAP services
+`proposal to support access-controlled access to and between ONAP services
 <https://wiki.onap.org/pages/viewpage.action?pageId=103417456>`_
 will improve this. This can be complemented by intercepting and controlling services
 accesses between Control Loop Elements for Control Loop Instances for some/all Control
@@ -449,7 +452,7 @@ in isolated namespaces or in dedicated workers/clusters; etc..
 The APIs and Protocols used by CLAMP for Control Loops are described on the pages below:
 
 #. :ref:`System Level Dialogues <system-level-label>`
-#. Defining Control Loops in TOSCA for CLAMP
+#. :ref:`Defining Control Loops in TOSCA for CLAMP <defining-controlloops-label>`
 #. REST APIs for CLAMP Control Loops
 #. The CLAMP Control Loop Participant Protocol
 
diff --git a/docs/clamp/controlloop/defining-controlloops.rst b/docs/clamp/controlloop/defining-controlloops.rst
new file mode 100644
index 00000000..66a67cec
--- /dev/null
+++ b/docs/clamp/controlloop/defining-controlloops.rst
@@ -0,0 +1,299 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+.. _defining-controlloops-label:
+
+Defining Control Loops in TOSCA for CLAMP
+#########################################
+
+
+.. contents::
+    :depth: 4
+
+
+A Control Loop 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
+<https://docs.oasis-open.org/tosca/TOSCA-Simple-Profile-YAML/v1.3/>`_ web page
+for more details on TOSCA.
+
+Unsurprisingly, to define a Control Loop Type in TOSCA, of Control Loop related concepts
+that we can use in all control loops exist. They are described in Section 1. Section 2
+describes how properties are managed. Properties are the configuration parameters that are
+provided to Control Loops and the Control Loop Elements they use. Section 3 describes how to
+define a Control Loop using the predefined Control Loop concepts.
+
+
+1 Standard TOSCA Service Template Concepts for Control Loops
+============================================================
+
+These concepts are the base concepts available to users who write definitions for control
+loops in TOSCA. TOSCA control loop definitions are written using these concepts.
+
+1.1 Fundamental TOSCA Concepts for Control Loops
+------------------------------------------------
+
+The following TOSCA concepts are the fundamental concepts in a TOSCA Service Template for
+defining control loops.
+
+.. image:: images/defining-controlloops/fundamental-concepts.png
+
+The TOSCA concepts above may be declared in the TOSCA Service Template of a control loop.
+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 control loop type.
+
+The *start_phase* is a value indicating the start phase in which this control loop element
+will be started, the first start phase is zero. Control Loop Elements are started in their
+start_phase order and stopped in reverse start phase order. Control Loop Elements with the
+same start phase are started and stopped simultaneously.
+
+The Yaml file that holds the Definition of `TOSCA fundamental Control Loop Types is available in Github
+<https://github.com/onap/policy-clamp/blob/master/common/src/main/resources/tosca/ControlLoopTOSCAServiceTemplateTypes.yaml>`_
+and is the canonical definition of the Control Loop concepts.
+
+1.2 TOSCA Concepts for Control Loop Elements delivered by ONAP
+--------------------------------------------------------------
+
+TOSCA Standard Control Loop Elements
+
+.. image:: images/defining-controlloops/standard-cle.png
+
+1.2.1 Policy Control Loop Element
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The Policy Participant runs Policy Control Loop Elements. Each Policy Control Loop Element
+manages the deployment of the policy specified in the Policy Control Loop Element definition.
+The Yaml file that holds the `Policy Control Loop Element Type definition is available in Github
+<https://github.com/onap/policy-clamp/blob/master/common/src/main/resources/tosca/PolicyControlLoopElementType.yaml>`_
+and is the canonical definition of the Policy Control Loop Element type. For a description of
+the Policy Control Loop Element and Policy Participant, please see `The CLAMP Policy Framework
+Participant <#>`_ page.
+
+1.2.2 HTTP Control Loop Element
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The HTTP Participant runs HTTP Control Loop Elements. Each HTTP Control Loop Element manages
+REST communication towards a REST endpoint using the REST calls a user has specified in the
+configuration of the HTTP Control Loop Element. The Yaml file that holds the
+`HTTP Control Loop Element Type definition is available in Github
+<https://github.com/onap/policy-clamp/blob/master/common/src/main/resources/tosca/HttpControlLoopElementType.yaml>`_
+and is the canonical definition of the HTTP Control Loop Element type. For a description of
+the HTTP Control Loop Element and HTTP Participant, please see `The CLAMP HTTP Participant <#>`_ page.
+
+.. _kubernetes-cl-element:
+
+1.2.3 Kubernetes Control Loop Element
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The Kubernetes Participant runs Kubernetes Control Loop Elements. Each Kubernetes Control Loop
+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 Control Loop Element Type defintion is available in Github
+<https://github.com/onap/policy-clamp/blob/master/common/src/main/resources/tosca/KubernetesControlLoopElementType.yaml>`_
+and is the canonical definition of the Kubernetes Control Loop Element type. For a description
+of the Kubernetes Control Loop Element and Kubernetes Participant,please see
+`The CLAMP Kubernetes Participant <#>`_ page.
+
+1.2.4 CDS Control Loop Element
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The CDS Participant runs CDS Control Loop Elements. Each CDS Control Loop Element manages the
+deployment of the CDS blueprint specified in the CDS Control Loop Element definition. The Yaml
+file that holds the `CDS Control Loop Element Type definition is available in Github
+<https://github.com/onap/policy-clamp/blob/master/common/src/main/resources/tosca/CdsControlLoopElementType.yaml>`_
+and is the canonical definition of the CDS Control Loop Element type. For a description of the
+CDS Control Loop Element and CDS Participant, please see `The CLAMP CDS Participant page <#>`_.
+
+1.2.5 DCAE Participant
+~~~~~~~~~~~~~~~~~~~~~~
+
+The DCAE Participant runs DCAE Control Loop Elements. Each DCAE Control Loop Element manages
+a DCAE microservice on DCAE. The user defines the DCAE blueprint for the DCAE microservice as
+well as other properties that the microservice requires in order to execute. The Yaml file that
+holds the `DCAE Control Loop Type definition is available in Github
+<https://github.com/onap/policy-clamp/blob/master/common/src/main/resources/tosca/DcaeControlLoopElementType.yaml>`_
+and is the canonical definition of the DCAE Control Loop Element type. For a description of
+the DCAE Control Loop Element and DCAE Participant, please see `The CLAMP DCAE Participant <#>`_ page.
+
+
+2 Common and Instance Specific Properties
+=========================================
+
+Properties are used to define the configuration for Control Loops and Control Loop 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
+<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>`_
+in the TOSCA documentation.
+
+2.1 Terminology for Properties
+------------------------------
+
+**Property:** Metadata defined in TOSCA that is associated with a Control Loop, a Control
+Loop 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 Control Loop Type.
+
+**Common Property Value:** The value of a Property Type. It is assigned at run time once for
+all instances of a Control Loop Type.
+
+**Instance Specific Property Type:** Property Types that apply to an individual instance of
+a Control Loop Type.
+
+**Instance Specific Property Value:** The value of a Property Type that applies to an
+individual instance of a Control Loop Type. The value is assigned at run time for each
+control loop instance.
+
+Control Loop Properties can be *common* or *instance specific*. See Section 2 of
+:ref:`TOSCA Defined Control Loops: Architecture and Design <controlloop-capabilities>`
+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 control loop. Common properties are identified
+by a special metadata flag in Control Loop and Control Loop Element definitions. For example,
+the startPhase parameter on any Control Loop Element has the same value for any instance of
+that control loop element, so it is defined as shown below in the
+`Definition of TOSCA fundamental Control Loop Types
+<https://github.com/onap/policy-clamp/blob/master/common/src/main/resources/tosca/ControlLoopTOSCAServiceTemplateTypes.yaml>`_
+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 control loop element will be started, the
+                  first start phase is zero. Control Loop Elements are started in their start_phase order and stopped
+                  in reverse start phase order. Control Loop 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 control loop
+commissioning.
+
+2.3 Instance Specific Properties
+--------------------------------
+
+Instance Specific  properties apply to individual instances of a Control Loop and/or Control
+Loop Element and must be set individually for Control Loop and Control Loop Element instance.
+Properties are instance specific by default, but can be identified by a special metadata flag
+in Control Loop and Control Loop Element definitions. For example, the chart parameter on a
+Kubernetes Control Loop Element has a different value for every instance of a Kubernetes Control
+Loop Element, so it can be defined as shown below in the :ref:`Kubernetes Control Loop Type definition
+<_kubernetes-cl-element>` yaml file.
+
+
+.. code-block:: yaml
+
+    # Definition that omits the common flag metadata
+    chart:
+      type: org.onap.datatypes.policy.clamp.controlloop.kubernetesControlLoopElement.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.controlloop.kubernetesControlLoopElement.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 control
+loop instantiation.
+
+
+3 Writing a Control Loop Type Definition
+=========================================
+
+The TOSCA definition of a control loop contains a TOSCA Node Template for the control loop
+itself, which contains TOSCA Node Templates for each Control Loop Element that makes up the
+Control Loop.
+
+.. image:: images/defining-controlloops/controlloop-node-template.png
+
+To create a control loop, a user creates a TOSCA Topology Template. In the Topology Template,
+the user creates a TOSCA Node Template for each Control Loop Element that will be in the
+Control Loop Definition. Finally, the user creates the Node Template that defines the Control
+Loop itself, and references the Control Loop Element definitions that make up the Control Loop
+Definition.
+
+3.1 The Gentle Guidance Control Loop
+------------------------------------
+
+The best way to explain how to create a Control Loop Definition is by example.
+
+.. image:: images/defining-controlloops/gentle-guidance-controlloop.png
+
+The example Gentle Guidance control loop is illustrated in the diagram above. The domain logic
+for the control loop is implemented in a microservice running in Kubernetes, a policy, a CDS
+blueprint, 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 control loop using
+our TOSCA based Control Loop Life Cycle Management approach. To do this we create four Control
+Loop Element definitions, one for the Kubernetes microservice, one for the policy, one for the
+CDS blueprint and one or the REST configuration.
+
+3.2 The TOSCA Control Loop Definition
+-------------------------------------
+
+We use a TOSCA Topology Template to specify a Control Loop definition and the definitions of
+its Control Loop Elements. Optionally, we can specify default parameter values in the TOSCA
+Topology Template. The actual values of Control Loop common and instance specific parameters
+are set at run time in the CLAMP GUI.
+
+In the case of the Gentle Guidance control loop, we define a Control Loop Element Node Template
+for each part of the domain logic we are managing. We then define the Control Loop Node Template
+for the control loop itself.
+
+The code fragment below shows the TOSCA Topology Template for the Gentle Guidance domain when
+no parameters are defined. Please refer to the `No Properties yaml file in Github
+<https://github.com/onap/policy-clamp/blob/master/common/src/test/resources/gentleguidance/GentleGuidanceNoPropeties.yaml>`_
+for the definitive Yaml specification.
+
+.. literalinclude:: files/gentle-cl-definition-example.yaml
+    :language: yaml
+
+The code fragment below shows the TOSCA Topology Template for the Gentle Guidance domain when
+the default values of parameters are defined. Please refer to the `Default Properties yaml file in Github
+<https://github.com/onap/policy-clamp/blob/master/common/src/test/resources/gentleguidance/GentleGuidanceDefaultPropeties.yaml>`_
+for the definitive Yaml specification.
+
+.. literalinclude:: files/gentle-cl-definiftion-default-example.yaml
+    :language: yaml
+
+4 Creating Custom Control Loop 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
+Control Loop. To do this, a participant for the component must be developed that allows Control
+Loop 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 Control Loop Participant Protocol <#>`_.
+The organization must also specify a new Control Loop Element type definition in TOSCA similar to
+those supplied in ONAP and described in Section 1.2. This Control Loop Element type tells the
+CLAMP Control Loop Lifecycle management that the Control Loop Element exists and can be included
+in control loops. It also specifies the properties that can be specified for the Control Loop Element.
+
+An organization can supply the code for the Participant (for example as a Java jar file) and a
+TOSCA artifact with the Control Loop Element definition and it can be added to the platform. In
+future releases, support will be provided to include participants and their Control Loop Element
+definitions as packaged plugins that can be installed on the platform.
+
+End of document
diff --git a/docs/clamp/controlloop/images/defining-controlloops/controlloop-node-template.png b/docs/clamp/controlloop/images/defining-controlloops/controlloop-node-template.png
new file mode 100644
index 00000000..f8721299
--- /dev/null
+++ b/docs/clamp/controlloop/images/defining-controlloops/controlloop-node-template.png
diff --git a/docs/clamp/controlloop/images/defining-controlloops/fundamental-concepts.png b/docs/clamp/controlloop/images/defining-controlloops/fundamental-concepts.png
new file mode 100644
index 00000000..dc52a840
--- /dev/null
+++ b/docs/clamp/controlloop/images/defining-controlloops/fundamental-concepts.png
diff --git a/docs/clamp/controlloop/images/defining-controlloops/gentle-guidance-controlloop.png b/docs/clamp/controlloop/images/defining-controlloops/gentle-guidance-controlloop.png
new file mode 100644
index 00000000..3e0862fb
--- /dev/null
+++ b/docs/clamp/controlloop/images/defining-controlloops/gentle-guidance-controlloop.png
diff --git a/docs/clamp/controlloop/images/defining-controlloops/standard-cle.png b/docs/clamp/controlloop/images/defining-controlloops/standard-cle.png
new file mode 100644
index 00000000..038549e0
--- /dev/null
+++ b/docs/clamp/controlloop/images/defining-controlloops/standard-cle.png