docs/clamp/acm/acm-participant-guide.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3 .. Copyright (c) Nordix Foundation.  All rights reserved.
   4
   5 .. _acm-participant-guide-label:
   6
   7 Participant developer guide
   8 ###########################
   9
  10 .. contents::
  11     :depth: 4
  12
  13 The ACM runtime delegates the user requests to the participants for performing the actual operations.
  14 Hence the participant module in ACM is implemented adhering to a list of ACM protocols along with their own functional logic.
  15 It works in a contract with the Participant Intermediary module for communicating with ACM-R.
  16 This guide explains the design considerations for a new participant implementation in ACM.
  17
  18 Please refer the following section for a detailed understanding of Inbound and outbound messages a participant interacts with.
  19
  20 .. toctree::
  21    :maxdepth: 2
  22
  23    design-impl/participants/participants
  24
  25 Design considerations for a participant
  26 ---------------------------------------
  27
  28 In ONAP, the ACM-runtime and participant modules are implemented in Java spring boot. The participant Intermediary module
  29 which is added as a maven dependency to the participants has the default implementations available for listening the kafka
  30 events coming in from the ACM-runtime, process them and delegate them to the appropriate handler class. Similarly the
  31 Intermediary module also has the publisher class implementations for publishing events back from the participants to the ACM-runtime.
  32
  33 Hence the new participants has to have this Participant Intermediary module as a dependency and should implement the following
  34 interfaces from the Participant Intermediary. It should also be provided with the following mandatory properties in order to make the participant
  35 work in synchronisation with ACM-runtime.
  36
  37 The participant application should be provided with the following Intermediary parameter values in the application properties
  38 and the same is configured for the 'ParticipantIntermediaryParameters' object in the code.
  39
  40 1. participantId - A unique participant UUID that is used by the runtime to identify the participant.
  41 2. ReportingTimeIntervalMs - Time inertval the participant should report the status/heartbeat to the runtime.
  42 3. clampAutomationCompositionTopics - This property takes in the kafka topic names and servers for the intermediary module to use.
  43    These values should be provided for both source and sink configs. The following example shows the topic parameters set for using DMaap.
  44
  45 .. code-block:: bash
  46
  47     clampAutomationCompositionTopics:
  48           topicSources:
  49             -
  50               topic: POLICY-ACRUNTIME-PARTICIPANT
  51               servers:
  52                 - ${topicServer:localhost}
  53               topicCommInfrastructure: dmaap
  54               fetchTimeout: 15000
  55           topicSinks:
  56             -
  57               topic: POLICY-ACRUNTIME-PARTICIPANT
  58               servers:
  59                 - ${topicServer:localhost}
  60               topicCommInfrastructure: dmaap
  61
  62 4. participantSupportedElementTypes - This property takes a list of typeName and typeVersion fields to define the types of AC elements the participant deals with.
  63    These are user defined name and version and the same should be defined for the AC elements that are included in the TOSCA based AC definitions.
  64
  65 .. code-block:: bash
  66
  67     participantSupportedElementTypes:
  68       -
  69         typeName: org.onap.policy.clamp.acm.PolicyAutomationCompositionElement
  70         typeVersion: 1.0.0
  71
  72 Interfaces to Implement
  73 -----------------------
  74 AutomationCompositionElementListener:
  75   Every participant should implement a handler class that implements the AutomationCompositionElementListener interface
  76   from the Participant Intermediary. The intermediary listener class listens for the incoming events from the ACM-runtime
  77   and invoke the handler class implementations for various operations. This class implements the methods for deploying,
  78   undeploying, locking, unlocking , updating, getting UseState, getting OperationalState requests that are coming from the ACM-runtime.
  79   The methods are as follows.
  80
  81 .. code-block:: bash
  82
  83   1. void undeploy(UUID automationCompositionId, UUID automationCompositionElementId) throws PfModelException;
  84   2. void deploy(UUID automationCompositionId, AcElementDeploy element, Map<String, Object> properties) throws PfModelException;
  85   3. default void lock(UUID automationCompositionId, UUID automationCompositionElementId) throws PfModelException;
  86   4. default void unlock(UUID automationCompositionId, UUID automationCompositionElementId) throws PfModelException;
  87   5. default void update(UUID automationCompositionId, AcElementDeploy element, Map<String, Object> properties) throws PfModelException;
  88
  89 These method from the interface are implemented independently as per the user requirement. These methods after handling the
  90 appropriate requests should also invoke the intermediary's publisher apis to notify the ACM-runtime with the acknowledgement events.
  91
  92 APIs to invoke
  93 --------------
  94 ParticipantIntermediaryApi:
  95   The participant intermediary api has the following methods that can be invoked from the participant for the following purposes.
  96   1. The requested operations are completed in the handler class and the ACM-runtime needs to be notified.
  97   2. To register the participant with the ACM-runtime during the startup.
  98
  99   The methods are as follows:
 100
 101   This following method is invoked to register the handler class that is implemented specific to the participant.
 102
 103 .. code-block:: bash
 104
 105   void registerAutomationCompositionElementListener(AutomationCompositionElementListener automationCompositionElementListener);
 106
 107 This following method is invoked to update the AC element state after each operation is completed in the participant.
 108
 109 .. code-block:: bash
 110
 111   void updateAutomationCompositionElementState(UUID automationCompositionId, UUID id, DeployState newState,LockState lockState);
 112
 113
 114 In ONAP, the following participants are already implemented in java spring boot for various requirements. The maven modules
 115 can be referred here
 116
 117   `HTTP participant <https://github.com/onap/policy-clamp/tree/master/participant/participant-impl/participant-impl-http>`_.
 118   `Kubernetes participant <https://github.com/onap/policy-clamp/tree/master/participant/participant-impl/participant-impl-kubernetes>`_.
 119   `Policy participant <https://github.com/onap/policy-clamp/tree/master/participant/participant-impl/participant-impl-policy>`_.
 120   `A1PMS participant <https://github.com/onap/policy-clamp/tree/master/participant/participant-impl/participant-impl-a1pms>`_.
 121   `Kserve participant <https://github.com/onap/policy-clamp/tree/master/participant/participant-impl/participant-impl-kserve>`_.
 122
 123
 124
 125
 126
 127