docs/clamp/acm/api-protocol/controlloop-participant-protocol.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2
   3 .. _controlloop-participant-protocol-label:
   4
   5 The CLAMP Control Loop Participant Protocol
   6 ###########################################
   7
   8 The CLAMP Control Loop Participant protocol is an asynchronous protocol that is used by the
   9 CLAMP runtime to coordinate life cycle management of Control Loop instances. The protocol
  10 supports the functions described in the sections below.
  11
  12
  13 Protocol Dialogues
  14 ==================
  15
  16 The protocol supports the dialogues described below.
  17
  18 Participant Registration and De-Registration
  19 --------------------------------------------
  20
  21 Registration when a participant comes up and update of participant with control loop type
  22 information and common parameter values for its control loop types.
  23
  24 .. image:: ../images/clamp-cl-participants/participant-registering.png
  25
  26
  27 De-registration is executed as a participant goes down.
  28
  29 .. image:: ../images/clamp-cl-participants/participant-deregistration.png
  30
  31
  32 Control Loop Priming and De-Priming
  33 -----------------------------------
  34
  35 When a control loop is primed, the portion of the Control Loop Type Definition and Common
  36 Property values for the participants of each participant type mentioned in the Control Loop
  37 Definition are sent to the participants.
  38
  39 .. image:: ../images/clamp-cl-participants/controlloop-priming.png
  40
  41 When a control loop is de-primed, the portion of the Control Loop Type Definition and Common
  42 Property values for the participants of each participant type mentioned in the Control Loop
  43 Definition are deleted on participants.
  44
  45 .. image:: ../images/clamp-cl-participants/controlloop-depriming.png
  46
  47
  48 Control Loop Update
  49 -------------------
  50
  51 Control Loop Update handles creation, change, and deletion of control loops on participants.
  52 Change of control loops uses a semantic versioning approach and follow the semantics described
  53 on the page `4.1 Management of Control Loop Instance Configurations <management-cl-instance-configs>`.
  54
  55 .. image:: ../images/clamp-cl-participants/controlloop-update.png
  56
  57 The handling of a ControlLoopUpdate message in each participant is as shown below.
  58
  59 .. image:: ../images/clamp-cl-participants/controlloop-update-msg.png
  60
  61 Control Loop State Change
  62 -------------------------
  63
  64 This dialogue is used to change the state of Control Loops and their Control Loop Elements. The
  65 CLAMP Runtime sends a Control Loop State Change message on the control loop to all participants.
  66 Participants that have Control Loop Elements in that Control Loop attempt an update on the state
  67 of the control loop elements they have for that control loop, and report the result back.
  68
  69 The *startPhase* in the `Definition of TOSCA fundamental Control Loop Types
  70 <https://github.com/onap/policy-clamp/blob/master/common/src/main/resources/tosca/ControlLoopTOSCAServiceTemplateTypes.yaml>`_
  71 is particularly important in control loop state changes because sometime the user wishes to control
  72 the order in which the state changes in Control Loop Elements in a control loop. In state changes
  73 from *UNITITIALISED* → *PASSIVE* and from *PASSIVE* → *RUNNING*, control loop elements are started in
  74 increasing order of their *startPhase*. In state changes from *RUNNING* → *PASSIVE* and from *PASSIVE*
  75 → *UNITITIALISED*, control loop elements are started in decreasing order of their *startPhase*.
  76
  77 The CLAMP runtime controls the state change process described in the diagram below. The CLAMP runtime
  78 sends a Control Loop State Change message on DMaaP to all participants in a particular Start Phase so,
  79 in each state change multiple Control Loop State Change messages are sent, one for each Start Phase in
  80 the control loop. If more than one Control Loop Element has the same Start Phase, those Control Loop
  81 Elements receive the same Control Loop State Change message from DMaaP and start in parallel.
  82
  83 The Participant reads each State Change Message it sees on DMaaP. If the Start Phase on the Control
  84 Loop State Change message matches the Start Phase of the Control Loop Element, the participant processes
  85 the State Change message. Otherwise the participant ignores the message.
  86
  87 .. image:: ../images/clamp-cl-participants/controlloop-state-change.png
  88
  89 The handling of a ControlLoopStateChange message in each participant is as shown below.
  90
  91 .. image:: ../images/clamp-cl-participants/controlloop-state-change-msg.png
  92
  93 Control Loop Monitoring and Reporting
  94 -------------------------------------
  95
  96 This dialogue is used as a heartbeat mechanism for participants, to monitor the status of Control Loop
  97 Elements, and to gather statistics on control loops. The ParticipantStatus message is sent periodically
  98 by each participant. The reporting interval for sending the message is configurable.
  99
 100 .. image:: ../images/clamp-cl-participants/controlloop-monitoring.png
 101
 102
 103 Messages
 104 ========
 105
 106 The CLAMP Control Loop Participant Protocol uses the following messages. The descriptions below give
 107 an overview of each message. For the precise definition of the messages, see the `CLAMP code at Github
 108 <https://github.com/onap/policy-clamp/tree/master/models/src/main/java/org/onap/policy/clamp/controlloop/models/messages/dmaap/participant>`_
 109 . All messages are carried on DMaaP.
 110
 111
 112 .. list-table::
 113    :widths: 15 10 10 15 15 35
 114    :header-rows: 1
 115
 116    * - Message
 117      - Source
 118      - Target
 119      - Purpose
 120      - Important Fields
 121      - Field Descriptions
 122    * - ParticipantRegister
 123      - Participant
 124      - CLAMP Runtime
 125      - Participant registers with the CLAMP runtime
 126      - ParticipantId
 127      - The ID of this participant
 128    * -
 129      -
 130      -
 131      -
 132      - ParticipantType
 133      - The type of the participant, maps to the capabilities of the participant in Control Loop Type
 134        Definitions
 135    * - ParticipantRegisterAck
 136      - CLAMP Runtime
 137      - Participant
 138      - Acknowledgement of Participant Registration
 139      - ParticipantId
 140      - The ID of this participant
 141    * -
 142      -
 143      -
 144      -
 145      - ParticipantType
 146      - The type of the participant, maps to the capabilities of the participant in Control Loop Type
 147        Definitions
 148    * -
 149      -
 150      -
 151      -
 152      - Result
 153      - Success/Fail
 154    * -
 155      -
 156      -
 157      -
 158      - Message
 159      - Message indicating reason for failure
 160    * - ParticipantUpdate
 161      - CLAMP Runtime
 162      - Participant
 163      - CLAMP Runtime sends Control Loop Element Definitions and Common Parameter Values to Participants
 164      - ParticipantDefinitionUpdateMap
 165      - Map with Participant ID as its key, each value on the map is a ControlLoopElementDefintionMap
 166    * -
 167      -
 168      -
 169      -
 170      - ControlLoopElementDefintionMap
 171      - List of ControlLoopElementDefinition values for a particular participant, keyed by its Control
 172        Loop Element Definition ID
 173    * -
 174      -
 175      -
 176      -
 177      - ControlLoopElementDefinition
 178      - A ControlLoopElementToscaServiceTemplate containing the definition of the Control Loop Element
 179        and a CommonPropertiesMap with the values of the common property values for Control Loop Elements
 180        of this type
 181    * -
 182      -
 183      -
 184      -
 185      - ControlLoopElementToscaServiceTemplate
 186      - The definition of the Control Loop Element in TOSCA
 187    * -
 188      -
 189      -
 190      -
 191      - CommonPropertiesMap
 192      - A <String, String> map indexed by the property name. Each map entry is the serialized value of
 193        the property, which can be deserialized into an instance of the type of the property.
 194    * - ParticipantUpdateAck
 195      - Participant
 196      - CLAMP Runtime
 197      - Acknowledgement of Participant Update
 198      - ParticipantId
 199      - The ID of this participant
 200    * -
 201      -
 202      -
 203      -
 204      - ParticipantType
 205      - The type of the participant, maps to the capabilities of the participant in Control Loop Type
 206        Definitions
 207    * -
 208      -
 209      -
 210      -
 211      - Result
 212      - Success/Fail
 213    * -
 214      -
 215      -
 216      -
 217      - Message
 218      - Message indicating reason for failure
 219    * - ParticipantDeregister
 220      - Participant
 221      - CLAMP Runtime
 222      - Participant deregisters with the CLAMP runtime
 223      - ParticipantId
 224      - The ID of this participant
 225    * -
 226      -
 227      -
 228      -
 229      - ParticipantType
 230      - The type of the participant, maps to the capabilities of the participant in Control Loop Type
 231        Definitions
 232    * - ParticipantDeregisterAck
 233      - CLAMP Runtime
 234      - Participant
 235      - Acknowledgement of Participant Deegistration
 236      - ParticipantId
 237      - The ID of this participant
 238    * -
 239      -
 240      -
 241      -
 242      - ParticipantType
 243      - The type of the participant, maps to the capabilities of the participant in Control Loop Type
 244        Definitions
 245    * -
 246      -
 247      -
 248      -
 249      - Result
 250      - Success/Fail
 251    * -
 252      -
 253      -
 254      -
 255      - Message
 256      - Message indicating reason for failure
 257    * - ControlLoopUpdate
 258      - CLAMP Runtime
 259      - Participant
 260      - CLAMP Runtime sends Control Loop Element instances and Instance Specific Parameter Values for
 261        a Control Loop Instance to Participants
 262      - ControlLoopId
 263      - The name and version of the Control Loop
 264    * -
 265      -
 266      -
 267      -
 268      - ParticipantUpdateMap
 269      - Map with Participant ID as its key, each value on the map is a ControlLoopElementList
 270    * -
 271      -
 272      -
 273      -
 274      - ControlLoopElementList
 275      - List of ControlLoopElement values for the Control Loop
 276    * -
 277      -
 278      -
 279      -
 280      - ControlLoopElement
 281      - A ControlLoopElement, which contains among other things a PropertiesMap with the values of the
 282        property values for this Control Loop Element instance and a ToscaServiceTemplateFragment with
 283        extra concept definitions and instances that a participant may need.
 284    * -
 285      -
 286      -
 287      -
 288      - PropertiesMap
 289      - A <String, String> map indexed by the property name. Each map entry is the serialized value of
 290        the property, which can be deserialized into an instance of the type of the property.
 291    * -
 292      -
 293      -
 294      -
 295      - ToscaServiceTemplateFragment
 296      - A well-formed TOSCA service template containing extra concept definitions and instances that a
 297        participant may need. For example, the Policy Participant may need policy type definitions or
 298        policy instances to be provided if they are not already stored in the Policy Framework.
 299    * - ControlLoopUpdateAck
 300      - Participant
 301      - CLAMP Runtime
 302      - Acknowledgement of Control Loop Update
 303      - ParticipantId
 304      - The ID of this participant
 305    * -
 306      -
 307      -
 308      -
 309      - ParticipantType
 310      - The type of the participant, maps to the capabilities of the participant in Control Loop Type
 311        Definitions
 312    * -
 313      -
 314      -
 315      -
 316      - ControlLoopId
 317      - The name and version of the Control Loop
 318    * -
 319      -
 320      -
 321      -
 322      - ControlLoopResult
 323      - Holds a Result and Message for the overall operation on the participant and a map of Result
 324        and Message fields for each Control Loop Element of the control loop on this participant
 325    * -
 326      -
 327      -
 328      -
 329      - Result
 330      - Success/Fail
 331    * -
 332      -
 333      -
 334      -
 335      - Message
 336      - Message indicating reason for failure
 337    * - ControlLoopStateChange
 338      - CLAMP Runtime
 339      - Participant
 340      - CLAMP Runtime asks Participants to change the state of a Control Loop
 341      - ControlLoopId
 342      - The name and version of the Control Loop
 343    * -
 344      -
 345      -
 346      -
 347      - currentState
 348      - The current state of the Control Loop
 349    * -
 350      -
 351      -
 352      -
 353      - orderedState
 354      - The state that the Control Loop should transition to
 355    * -
 356      -
 357      -
 358      -
 359      - startPhase
 360      - The start phase to which this ControLoopStateChange message applies
 361    * - ControlLoopStateChangeAck
 362      - Participant
 363      - CLAMP Runtime
 364      - Acknowledgement of Control Loop State Change
 365      - ParticipantId
 366      - The ID of this participant
 367    * -
 368      -
 369      -
 370      -
 371      - ParticipantType
 372      - The type of the participant, maps to the capabilities of the participant in Control Loop Type
 373        Definitions
 374    * -
 375      -
 376      -
 377      -
 378      - ControlLoopId
 379      - The name and version of the Control Loop
 380    * -
 381      -
 382      -
 383      -
 384      - startPhase
 385      - The start phase to which this ControLoopStateChangeAck message applies
 386    * -
 387      -
 388      -
 389      -
 390      - ControlLoopResult
 391      - Holds a Result and Message for the overall operation on the participant and a map of Result and
 392        Message fields for each Control Loop Element of the control loop on this participant
 393    * -
 394      -
 395      -
 396      -
 397      - Result
 398      - Success/Fail
 399    * -
 400      -
 401      -
 402      -
 403      - Message
 404      - Message indicating reason for failure
 405    * - ParticipantStatusReq
 406      - CLAMP Runtime
 407      - Participant
 408      - Request that the specified participants return a ParticipantStatus message immediately
 409      - ParticipantId
 410      - The ID of this participant, if not specified, all participants respond.
 411    * - ParticipantStatus
 412      - Participant
 413      - CLAMP Runtime
 414      - Periodic or on-demand report for heartbeat, Participant Status, Control Loop Status, and Control
 415        Loop Statistics
 416      - ParticipantId
 417      - The ID of this participant
 418    * -
 419      -
 420      -
 421      -
 422      - ParticipantType
 423      - The type of the participant, maps to the capabilities of the participant in Control Loop
 424        Type Definitions
 425    * -
 426      -
 427      -
 428      -
 429      - ParticipantDefinitionUpdateMap (returned in repsonse to ParticipantStatusReq only)
 430      - See ParticipantUpdate message above for definition of this field
 431    * -
 432      -
 433      -
 434      -
 435      - ParticipantStatus
 436      - The current status of the participant for monitoring
 437    * -
 438      -
 439      -
 440      -
 441      - ParticipantStatistics
 442      - Statistics on the participant such as up time, or messages processed. Can include participant
 443        specific data in a string blob that is opaque to CLAMP
 444    * -
 445      -
 446      -
 447      -
 448      - ControlLoopInfoMap
 449      - A map of ControlLoopInfo types indexed by ControlLoopId, one entry for each control loop
 450        running on the participant
 451    * -
 452      -
 453      -
 454      -
 455      - ControlLoopInfo
 456      - The ControlLoopStatus and ControlLoopStatistics for a given control loop
 457    * -
 458      -
 459      -
 460      -
 461      - ControlLoopStatus
 462      - The current status of the control loop for monitoring
 463    * -
 464      -
 465      -
 466      -
 467      - ControlLoopStatistics
 468      - Statistics on the control loop such as up time, or messages processed. Can include participant
 469        specific data in a string blob that is opaque to CLAMP
 470
 471
 472 End of Document