diff options
13 files changed, 480 insertions, 13 deletions
diff --git a/docs/clamp/clamp.rst b/docs/clamp/clamp.rst index 9fe6190f..6f20de25 100644 --- a/docs/clamp/clamp.rst +++ b/docs/clamp/clamp.rst @@ -14,4 +14,4 @@ CLAMP handles control loops in two ways, either using built in ONAP Control Loop controlloop/controlloop controlloop/system-level-dialogues controlloop/defining-controlloops - + controlloop/controlloop-participant-protocol diff --git a/docs/clamp/controlloop/controlloop-participant-protocol.rst b/docs/clamp/controlloop/controlloop-participant-protocol.rst new file mode 100644 index 00000000..208c5659 --- /dev/null +++ b/docs/clamp/controlloop/controlloop-participant-protocol.rst @@ -0,0 +1,472 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. + +.. _controlloop-participant-protocol-label: + +The CLAMP Control Loop Participant Protocol +########################################### + +The CLAMP Control Loop Participant protocol is an asynchronous protocol that is used by the +CLAMP runtime to coordinate life cycle management of Control Loop instances. The protocol +supports the functions described in the sections below. + + +Protocol Dialogues +================== + +The protocol supports the dialogues described below. + +Participant Registration and De-Registration +-------------------------------------------- + +Registration when a participant comes up and update of participant with control loop type +information and common parameter values for its control loop types. + +.. image:: images/clamp-cl-participants/participant-registering.png + + +De-registration is executed as a participant goes down. + +.. image:: images/clamp-cl-participants/participant-deregistration.png + + +Control Loop Priming and De-Priming +----------------------------------- + +When a control loop is primed, the portion of the Control Loop Type Definition and Common +Property values for the participants of each participant type mentioned in the Control Loop +Definition are sent to the participants. + +.. image:: images/clamp-cl-participants/controlloop-priming.png + +When a control loop is de-primed, the portion of the Control Loop Type Definition and Common +Property values for the participants of each participant type mentioned in the Control Loop +Definition are deleted on participants. + +.. image:: images/clamp-cl-participants/controlloop-depriming.png + + +Control Loop Update +------------------- + +Control Loop Update handles creation, change, and deletion of control loops on participants. +Change of control loops uses a semantic versioning approach and follow the semantics described +on the page `4.1 Management of Control Loop Instance Configurations <management-cl-instance-configs>`. + +.. image:: images/clamp-cl-participants/controlloop-update.png + +The handling of a ControlLoopUpdate message in each participant is as shown below. + +.. image:: images/clamp-cl-participants/controlloop-update-msg.png + +Control Loop State Change +------------------------- + +This dialogue is used to change the state of Control Loops and their Control Loop Elements. The +CLAMP Runtime sends a Control Loop State Change message on the control loop to all participants. +Participants that have Control Loop Elements in that Control Loop attempt an update on the state +of the control loop elements they have for that control loop, and report the result back. + +The *startPhase* in the `Definition of TOSCA fundamental Control Loop Types +<https://github.com/onap/policy-clamp/blob/master/common/src/main/resources/tosca/ControlLoopTOSCAServiceTemplateTypes.yaml>`_ +is particularly important in control loop state changes because sometime the user wishes to control +the order in which the state changes in Control Loop Elements in a control loop. In state changes +from *UNITITIALISED* → *PASSIVE* and from *PASSIVE* → *RUNNING*, control loop elements are started in +increasing order of their *startPhase*. In state changes from *RUNNING* → *PASSIVE* and from *PASSIVE* +→ *UNITITIALISED*, control loop elements are started in decreasing order of their *startPhase*. + +The CLAMP runtime controls the state change process described in the diagram below. The CLAMP runtime +sends a Control Loop State Change message on DMaaP to all participants in a particular Start Phase so, +in each state change multiple Control Loop State Change messages are sent, one for each Start Phase in +the control loop. If more than one Control Loop Element has the same Start Phase, those Control Loop +Elements receive the same Control Loop State Change message from DMaaP and start in parallel. + +The Participant reads each State Change Message it sees on DMaaP. If the Start Phase on the Control +Loop State Change message matches the Start Phase of the Control Loop Element, the participant processes +the State Change message. Otherwise the participant ignores the message. + +.. image:: images/clamp-cl-participants/controlloop-state-change.png + +The handling of a ControlLoopStateChange message in each participant is as shown below. + +.. image:: images/clamp-cl-participants/controlloop-state-change-msg.png + +Control Loop Monitoring and Reporting +------------------------------------- + +This dialogue is used as a heartbeat mechanism for participants, to monitor the status of Control Loop +Elements, and to gather statistics on control loops. The ParticipantStatus message is sent periodically +by each participant. The reporting interval for sending the message is configurable. + +.. image:: images/clamp-cl-participants/controlloop-monitoring.png + + +Messages +======== + +The CLAMP Control Loop Participant Protocol uses the following messages. The descriptions below give +an overview of each message. For the precise definition of the messages, see the `CLAMP code at Github +<https://github.com/onap/policy-clamp/tree/master/models/src/main/java/org/onap/policy/clamp/controlloop/models/messages/dmaap/participant>`_ +. All messages are carried on DMaaP. + + +.. list-table:: + :widths: 15 10 10 15 15 35 + :header-rows: 1 + + * - Message + - Source + - Target + - Purpose + - Important Fields + - Field Descriptions + * - ParticipantRegister + - Participant + - CLAMP Runtime + - Participant registers with the CLAMP runtime + - ParticipantId + - The ID of this participant + * - + - + - + - + - ParticipantType + - The type of the participant, maps to the capabilities of the participant in Control Loop Type + Definitions + * - ParticipantRegisterAck + - CLAMP Runtime + - Participant + - Acknowledgement of Participant Registration + - ParticipantId + - The ID of this participant + * - + - + - + - + - ParticipantType + - The type of the participant, maps to the capabilities of the participant in Control Loop Type + Definitions + * - + - + - + - + - Result + - Success/Fail + * - + - + - + - + - Message + - Message indicating reason for failure + * - ParticipantUpdate + - CLAMP Runtime + - Participant + - CLAMP Runtime sends Control Loop Element Definitions and Common Parameter Values to Participants + - ParticipantDefinitionUpdateMap + - Map with Participant ID as its key, each value on the map is a ControlLoopElementDefintionMap + * - + - + - + - + - ControlLoopElementDefintionMap + - List of ControlLoopElementDefinition values for a particular participant, keyed by its Control + Loop Element Definition ID + * - + - + - + - + - ControlLoopElementDefinition + - A ControlLoopElementToscaServiceTemplate containing the definition of the Control Loop Element + and a CommonPropertiesMap with the values of the common property values for Control Loop Elements + of this type + * - + - + - + - + - ControlLoopElementToscaServiceTemplate + - The definition of the Control Loop Element in TOSCA + * - + - + - + - + - CommonPropertiesMap + - A <String, String> map indexed by the property name. Each map entry is the serialized value of + the property, which can be deserialized into an instance of the type of the property. + * - ParticipantUpdateAck + - Participant + - CLAMP Runtime + - Acknowledgement of Participant Update + - ParticipantId + - The ID of this participant + * - + - + - + - + - ParticipantType + - The type of the participant, maps to the capabilities of the participant in Control Loop Type + Definitions + * - + - + - + - + - Result + - Success/Fail + * - + - + - + - + - Message + - Message indicating reason for failure + * - ParticipantDeregister + - Participant + - CLAMP Runtime + - Participant deregisters with the CLAMP runtime + - ParticipantId + - The ID of this participant + * - + - + - + - + - ParticipantType + - The type of the participant, maps to the capabilities of the participant in Control Loop Type + Definitions + * - ParticipantDeregisterAck + - CLAMP Runtime + - Participant + - Acknowledgement of Participant Deegistration + - ParticipantId + - The ID of this participant + * - + - + - + - + - ParticipantType + - The type of the participant, maps to the capabilities of the participant in Control Loop Type + Definitions + * - + - + - + - + - Result + - Success/Fail + * - + - + - + - + - Message + - Message indicating reason for failure + * - ControlLoopUpdate + - CLAMP Runtime + - Participant + - CLAMP Runtime sends Control Loop Element instances and Instance Specific Parameter Values for + a Control Loop Instance to Participants + - ControlLoopId + - The name and version of the Control Loop + * - + - + - + - + - ParticipantUpdateMap + - Map with Participant ID as its key, each value on the map is a ControlLoopElementList + * - + - + - + - + - ControlLoopElementList + - List of ControlLoopElement values for the Control Loop + * - + - + - + - + - ControlLoopElement + - A ControlLoopElement, which contains among other things a PropertiesMap with the values of the + property values for this Control Loop Element instance and a ToscaServiceTemplateFragment with + extra concept definitions and instances that a participant may need. + * - + - + - + - + - PropertiesMap + - A <String, String> map indexed by the property name. Each map entry is the serialized value of + the property, which can be deserialized into an instance of the type of the property. + * - + - + - + - + - ToscaServiceTemplateFragment + - A well-formed TOSCA service template containing extra concept definitions and instances that a + participant may need. For example, the Policy Participant may need policy type definitions or + policy instances to be provided if they are not already stored in the Policy Framework. + * - ControlLoopUpdateAck + - Participant + - CLAMP Runtime + - Acknowledgement of Control Loop Update + - ParticipantId + - The ID of this participant + * - + - + - + - + - ParticipantType + - The type of the participant, maps to the capabilities of the participant in Control Loop Type + Definitions + * - + - + - + - + - ControlLoopId + - The name and version of the Control Loop + * - + - + - + - + - ControlLoopResult + - Holds a Result and Message for the overall operation on the participant and a map of Result + and Message fields for each Control Loop Element of the control loop on this participant + * - + - + - + - + - Result + - Success/Fail + * - + - + - + - + - Message + - Message indicating reason for failure + * - ControlLoopStateChange + - CLAMP Runtime + - Participant + - CLAMP Runtime asks Participants to change the state of a Control Loop + - ControlLoopId + - The name and version of the Control Loop + * - + - + - + - + - currentState + - The current state of the Control Loop + * - + - + - + - + - orderedState + - The state that the Control Loop should transition to + * - + - + - + - + - startPhase + - The start phase to which this ControLoopStateChange message applies + * - ControlLoopStateChangeAck + - Participant + - CLAMP Runtime + - Acknowledgement of Control Loop State Change + - ParticipantId + - The ID of this participant + * - + - + - + - + - ParticipantType + - The type of the participant, maps to the capabilities of the participant in Control Loop Type + Definitions + * - + - + - + - + - ControlLoopId + - The name and version of the Control Loop + * - + - + - + - + - startPhase + - The start phase to which this ControLoopStateChangeAck message applies + * - + - + - + - + - ControlLoopResult + - Holds a Result and Message for the overall operation on the participant and a map of Result and + Message fields for each Control Loop Element of the control loop on this participant + * - + - + - + - + - Result + - Success/Fail + * - + - + - + - + - Message + - Message indicating reason for failure + * - ParticipantStatusReq + - CLAMP Runtime + - Participant + - Request that the specified participants return a ParticipantStatus message immediately + - ParticipantId + - The ID of this participant, if not specified, all participants respond. + * - ParticipantStatus + - Participant + - CLAMP Runtime + - Periodic or on-demand report for heartbeat, Participant Status, Control Loop Status, and Control + Loop Statistics + - ParticipantId + - The ID of this participant + * - + - + - + - + - ParticipantType + - The type of the participant, maps to the capabilities of the participant in Control Loop + Type Definitions + * - + - + - + - + - ParticipantDefinitionUpdateMap (returned in repsonse to ParticipantStatusReq only) + - See ParticipantUpdate message above for definition of this field + * - + - + - + - + - ParticipantStatus + - The current status of the participant for monitoring + * - + - + - + - + - ParticipantStatistics + - Statistics on the participant such as up time, or messages processed. Can include participant + specific data in a string blob that is opaque to CLAMP + * - + - + - + - + - ControlLoopInfoMap + - A map of ControlLoopInfo types indexed by ControlLoopId, one entry for each control loop + running on the participant + * - + - + - + - + - ControlLoopInfo + - The ControlLoopStatus and ControlLoopStatistics for a given control loop + * - + - + - + - + - ControlLoopStatus + - The current status of the control loop for monitoring + * - + - + - + - + - ControlLoopStatistics + - Statistics on the control loop such as up time, or messages processed. Can include participant + specific data in a string blob that is opaque to CLAMP + + +End of Document diff --git a/docs/clamp/controlloop/controlloop.rst b/docs/clamp/controlloop/controlloop.rst index a505abfe..752e3370 100644 --- a/docs/clamp/controlloop/controlloop.rst +++ b/docs/clamp/controlloop/controlloop.rst @@ -454,7 +454,7 @@ The APIs and Protocols used by CLAMP for Control Loops are described on the page #. :ref:`System Level Dialogues <system-level-label>` #. :ref:`Defining Control Loops in TOSCA for CLAMP <defining-controlloops-label>` #. REST APIs for CLAMP Control Loops -#. The CLAMP Control Loop Participant Protocol +#. :ref:`The CLAMP Control Loop Participant Protocol <controlloop-participant-protocol-label>` 6 Design and Implementation diff --git a/docs/clamp/controlloop/defining-controlloops.rst b/docs/clamp/controlloop/defining-controlloops.rst index 66a67cec..dad5ff1a 100644 --- a/docs/clamp/controlloop/defining-controlloops.rst +++ b/docs/clamp/controlloop/defining-controlloops.rst @@ -261,21 +261,16 @@ In the case of the Gentle Guidance control loop, we define a Control Loop Elemen 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 +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. +for the definitive Yaml specification for the TOSCA Topology Template for the Gentle Guidance +domain when no parameters are defined. -.. 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 +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. +for the definitive Yaml specification for the TOSCA Topology Template for the Gentle Guidance +domain when the default values of parameters are defined. -.. literalinclude:: files/gentle-cl-definiftion-default-example.yaml - :language: yaml 4 Creating Custom Control Loop Elements ======================================== diff --git a/docs/clamp/controlloop/images/clamp-cl-participants/controlloop-depriming.png b/docs/clamp/controlloop/images/clamp-cl-participants/controlloop-depriming.png Binary files differnew file mode 100644 index 00000000..16a923b1 --- /dev/null +++ b/docs/clamp/controlloop/images/clamp-cl-participants/controlloop-depriming.png diff --git a/docs/clamp/controlloop/images/clamp-cl-participants/controlloop-monitoring.png b/docs/clamp/controlloop/images/clamp-cl-participants/controlloop-monitoring.png Binary files differnew file mode 100644 index 00000000..f64fcd2e --- /dev/null +++ b/docs/clamp/controlloop/images/clamp-cl-participants/controlloop-monitoring.png diff --git a/docs/clamp/controlloop/images/clamp-cl-participants/controlloop-priming.png b/docs/clamp/controlloop/images/clamp-cl-participants/controlloop-priming.png Binary files differnew file mode 100644 index 00000000..fa17429d --- /dev/null +++ b/docs/clamp/controlloop/images/clamp-cl-participants/controlloop-priming.png diff --git a/docs/clamp/controlloop/images/clamp-cl-participants/controlloop-state-change-msg.png b/docs/clamp/controlloop/images/clamp-cl-participants/controlloop-state-change-msg.png Binary files differnew file mode 100644 index 00000000..dfcfe882 --- /dev/null +++ b/docs/clamp/controlloop/images/clamp-cl-participants/controlloop-state-change-msg.png diff --git a/docs/clamp/controlloop/images/clamp-cl-participants/controlloop-state-change.png b/docs/clamp/controlloop/images/clamp-cl-participants/controlloop-state-change.png Binary files differnew file mode 100644 index 00000000..9ce9e490 --- /dev/null +++ b/docs/clamp/controlloop/images/clamp-cl-participants/controlloop-state-change.png diff --git a/docs/clamp/controlloop/images/clamp-cl-participants/controlloop-update-msg.png b/docs/clamp/controlloop/images/clamp-cl-participants/controlloop-update-msg.png Binary files differnew file mode 100644 index 00000000..e4c8ce84 --- /dev/null +++ b/docs/clamp/controlloop/images/clamp-cl-participants/controlloop-update-msg.png diff --git a/docs/clamp/controlloop/images/clamp-cl-participants/controlloop-update.png b/docs/clamp/controlloop/images/clamp-cl-participants/controlloop-update.png Binary files differnew file mode 100644 index 00000000..be968dc7 --- /dev/null +++ b/docs/clamp/controlloop/images/clamp-cl-participants/controlloop-update.png diff --git a/docs/clamp/controlloop/images/clamp-cl-participants/participant-deregistration.png b/docs/clamp/controlloop/images/clamp-cl-participants/participant-deregistration.png Binary files differnew file mode 100644 index 00000000..bb2ec9a3 --- /dev/null +++ b/docs/clamp/controlloop/images/clamp-cl-participants/participant-deregistration.png diff --git a/docs/clamp/controlloop/images/clamp-cl-participants/participant-registering.png b/docs/clamp/controlloop/images/clamp-cl-participants/participant-registering.png Binary files differnew file mode 100644 index 00000000..eeae2e02 --- /dev/null +++ b/docs/clamp/controlloop/images/clamp-cl-participants/participant-registering.png |
