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

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2
   3 .. _acm-participant-protocol-label:
   4
   5 The ACM Automation Composition Participant Protocol
   6 ###################################################
   7
   8 The ACM Automation Composition protocol is an asynchronous protocol that is used by the ACM
   9 runtime to coordinate lifecycle management of Automation Composition 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 Participant Registration is performed by a Participant when it starts up. It registers its ID and the ACM Element Types it supports with the ACM runtime.
  22
  23 .. image:: ../images/system-dialogues/RegisterParticipant.png
  24
  25
  26 Participant Deregistration is performed by a Participant when it shuts down. It deregisters its ID and type with the ACM runtime. The participant should already have cleared down all its' ACM Element instances and set their states to “Not In Service”.
  27
  28 .. image:: ../images/system-dialogues/DeregisterParticipant.png
  29
  30
  31 Automation Composition Priming and De-Priming
  32 ---------------------------------------------
  33
  34 The Priming operation sends Automation Composition Types and common property values to participants for each Automation Composition Element Type in the Automation Composition Type. The ParticipantPrime message type is sent to trigger priming and depriming in participants in participants
  35
  36 .. image:: ../images/system-dialogues/PrimeAcTypeOnPpnts.png
  37
  38 A participant should respond for each Automation Composition Element Type, thus causing the full Automation Composition Type to become primed. Note that if more than one participant can support an Automation Composition Element Type the ACM Runtime uses the participant in the first response it receives for that Automation Composition Element Type.
  39
  40 .. image:: ../images/system-dialogues/PrimeAcTypeMultiplePpnts.png
  41
  42 The ACM Runtime updates the priming information in the database.
  43
  44 .. image:: ../images/system-dialogues/PrimeInfoUpdatedInDb.png
  45
  46 The Depriming operation removes Automation Composition Types and common property values on participants for each Automation Composition Element Type in the Automation Composition Type.
  47
  48 .. image:: ../images/system-dialogues/DeprimeOnParticipants.png
  49
  50 A participant should respond for each Automation Composition Element Type, thus causing the full Automation Composition Type to become deprimed.
  51
  52 .. image:: ../images/system-dialogues/DeprimeElements.png
  53
  54 The ACM Runtime updates the priming information in the database.
  55
  56 .. image:: ../images/system-dialogues/UpdateDeprimeInDb.png
  57
  58 Automation Composition Update
  59 -----------------------------
  60
  61 Automation Composition Update handles creation, change, and deletion of Automation Compositions on
  62 participants. Change of Automation Compositions uses a semantic versioning approach and follows the
  63 semantics described on the page :ref:`4.1 Management of Automation Composition Instance
  64 Configurations <management-acm-instance-configs>`.
  65
  66 .. image:: ../images/acm-participants-protocol/acm-update.png
  67
  68 The handling of an *ACMUpdate* message in each participant is as shown below.
  69
  70 .. image:: ../images/acm-participants-protocol/acm-update-msg.png
  71
  72 Automation Composition State Change
  73 -----------------------------------
  74
  75 This dialogue is used to change the state of Automation Compositions and their Automation
  76 Composition Elements. The CLAMP Runtime sends an Automation Composition State Change message on the
  77 Automation Composition to all participants. Participants that have Automation Composition Elements
  78 in that Automation Composition attempt an update on the state of the Automation Composition
  79 elements they have for that Automation Composition, and report the result back.
  80
  81 The *startPhase* in the `Definition of TOSCA fundamental Automation Composition Types
  82 <https://github.com/onap/policy-clamp/blob/master/common/src/main/resources/tosca/AutomationCompositionTOSCAServiceTemplateTypes.yaml>`_
  83 is particularly important in Automation Composition state changes because sometimes the user wishes
  84 to control the order in which the state changes in Automation Composition Elements in an Automation
  85 Composition. In-state changes from *UNDEPLOYED → DEPLOYED*,
  86 Automation Composition elements are started in increasing order of their startPhase. In-state
  87 changes from *DEPLOYED → UNDEPLOYED*, Automation Composition
  88 elements are started in decreasing order of their *startPhase*.
  89
  90 The ACM runtime controls the state change process described in the diagram below. The ACM
  91 runtime sends an Automation Composition state change message on the messaging system (e.g. Kafka) to all participants in a
  92 particular start phase so, in each state change multiple Automation Composition State Change
  93 messages are sent, one for each start phase in the Automation Composition. If more than one
  94 Automation Composition Element has the same start phase, those Automation Composition Elements
  95 receive the same Automation Composition State Change message from Kafka and start in parallel.
  96
  97 The Participant reads each State Change Message it sees on Kafka. If the start phase on the
  98 Automation Composition State Change message matches the Start Phase of the Automation Composition
  99 Element, the participant processes the state change message. Otherwise, the participant ignores the
 100 message.
 101
 102 .. image:: ../images/acm-participants-protocol/acm-state-change.png
 103
 104 The flow of the DEPLOY/UNDEPLOY state change messages are shown below. But the same flow is true for LOCK/UNLOCK
 105
 106 .. note:: More details of the state machine are available on :ref:`ACM States <acm-states-label>`
 107
 108 .. image:: ../images/acm-participants-protocol/acm-state-change-msg.png
 109
 110 Automation Composition Monitoring and Reporting
 111 -----------------------------------------------
 112
 113 This dialogue is used as a heartbeat mechanism for participants, to monitor the status of
 114 Automation Composition Elements, and to gather statistics on Automation Compositions. The
 115 *ParticipantStatus* message is sent periodically by each participant. The reporting interval for
 116 sending the message is configurable.
 117
 118 .. image:: ../images/acm-participants-protocol/acm-monitoring.png
 119
 120
 121 Messages
 122 ========
 123
 124 The CLAMP Automation Composition Participant Protocol uses the following messages. The
 125 descriptions below give an overview of each message. For the precise definition of the messages,
 126 see the `CLAMP code at Github
 127 <https://github.com/onap/policy-clamp/tree/master/models/src/main/java/org/onap/policy/clamp/models/acm/messages/dmaap/participant>`_
 128 . All messages are carried on DMaaP.
 129
 130 .. csv-table:: ACM Messages
 131   :file: ../files/ACM-Message-Table.csv
 132   :header-rows: 1
 133
 134
 135 End of Document