docs/clamp/acm/design-impl/participants/http-participant.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2
   3 .. _clamp-acm-http-participant:
   4
   5 HTTP Participant
   6 ################
   7
   8 The CLAMP HTTP participant receives configuration information from the CLAMP runtime,
   9 maps the configuration information to a REST URL, and makes a REST call on the URL.
  10 Typically the HTTP Participant is used with another participant such as the
  11 :ref:`Kubernetes Participant <clamp-acm-k8s-participant>`, which brings up
  12 the microservice that runs a REST server. Once the microservice is up, the HTTP
  13 participant can be used to configure the microservice over its REST interface.Of course,
  14 the HTTP participant works towards any REST service, it is not restricted to REST
  15 services started by participants.
  16 Supported message Broker are DMaap and Strimzi-Kafka.
  17
  18 .. image:: ../../images/participants/http-participant.png
  19
  20
  21 The HTTP participant runs a Automation Composition Element to handle the REST dialogues for a
  22 particular application domain. The REST dialogues are whatever REST calls that are
  23 required to implement the functionality for the application domain.
  24
  25 The HTTP participant allows the REST dialogues for a Automation Composition to be managed. A
  26 particular Automation Composition may require many *things* to be configured and managed and this
  27 may require many REST dialogues to achieve.
  28
  29 When a automation composition is initialized, the HTTP participant starts a HTTP Automation Composition
  30 element for the automation composition. It reads the configuration information sent from the
  31 Automation Composition Runtime runs a HTTP client to talk to the REST endpoint that is receiving
  32 the REST requests. A HTTP participant can simultaneously manage HTTP Automation Composition
  33 Elements towards multiple REST endpoints, as shown in the diagram above where the HTTP
  34 participant is running two HTTP Automation Composition Elements, one for Automation Composition A and one for
  35 Automation Composition B.
  36
  37 Supported Element Types
  38 -----------------------
  39 Supported Element Types for Http participant will be used to define the HTTP participant Element Definition Types in tosca template.
  40 Participant Supported Element Types is defined in Http participant application.yaml.
  41
  42 .. code-block:: YAML
  43
  44     participantSupportedElementTypes:
  45       -
  46         typeName: org.onap.policy.clamp.acm.HttpAutomationCompositionElement
  47         typeVersion: 1.0.0
  48
  49
  50 Configuring an Automation Composition Definition and Instance for the HTTP participant
  51 --------------------------------------------------------------------------------------
  52 A *Configuration Entity* describes a concept that is managed by the HTTP participant. A
  53 Configuration Entity can be created, Read, Updated, and Deleted (CRUD). The user defines
  54 the Configuration Entities that it wants its HTTP Automation Composition Element to manage and
  55 provides a sequence of parameterized REST commands to Create, Read, Update, and Delete
  56 each Configuration Entity.
  57
  58 Sample tosca template defining a http participant and a AC element definition. :download:`click here <tosca/tosca-http-participant.yml>`
  59
  60 The user defines the following properties in the TOSCA for the HTTP participant:
  61
  62 .. list-table::
  63    :widths: 15 10 50
  64    :header-rows: 1
  65
  66    * - Property
  67      - Type
  68      - Description
  69    * - baseUrl
  70      - URL
  71      - A well formed URL pointing at the REST server that is processing the REST requests
  72    * - httpHeaders
  73      - map
  74      - A map of *<String, String>* defining the HTTP headers to send on all REST calls
  75    * - configurationEntitiies
  76      - map
  77      - A map of *<String, ConfigurationEntity>* describing the names and definitions of
  78        configuration entities that are managed by this HTTP Automation Composition Element
  79
  80 The *ConfigurationEntity* type is described in the following table:
  81
  82 .. list-table::
  83    :widths: 15 10 50
  84    :header-rows: 1
  85
  86    * - Field
  87      - Type
  88      - Description
  89    * - ID
  90      - ToscaConceptIdentifier
  91      - The name and version of the Configuration Entity
  92    * - restSequence
  93      - List<RestRequest>
  94      - A list of REST requests to give manage the Configuration Entity
  95
  96 The *RestRequest* type is described in the following table:
  97
  98 .. list-table::
  99    :widths: 15 10 50
 100    :header-rows: 1
 101
 102    * - Field
 103      - Type
 104      - Description
 105    * - httpMethod
 106      - HttpMethod
 107      - An enum for the HTTP method {GET, PUT, POST, DELETE}
 108    * - path
 109      - String
 110      - The path of the REST endpoint relative to the baseUrl
 111    * - body
 112      - String
 113      - The body of the request for POST and PUT methods
 114    * - expectedResponse
 115      - HttpStatus
 116      - The expected HTTP response code fo the REST request
 117
 118 Sample Automation Composition instances.
 119 In that example the user fills the properties defined in the TOSCA for the HTTP participant :download:`click here <tosca/automation-composition-http.yml>`
 120
 121 Http participant Interactions:
 122 ------------------------------
 123 The http participant interacts with Automation Composition Runtime on the northbound via Message Broker. It interacts with any microservice on the southbound over http for configuration.
 124
 125 The communication for the Automation Composition updates and state change requests are sent from the Automation Composition Runtime to the participant via Message Broker.
 126 The participant invokes the appropriate http endpoint of the microservice based on the received messages from the Automation Composition Runtime.
 127
 128
 129 startPhase:
 130 -----------
 131 The http participant is often used along with :ref:`Kubernetes Participant <clamp-acm-k8s-participant>` to configure the microservice after the deployment.
 132 This requires the Automation Composition Element of http participant to be started after the completion of deployment of the microservice. This can be achieved by adding the property `startPhase`
 133 in the Automation Composition Element of http participant. Automation Composition Runtime starts the elements based on the `startPhase` value defined in the Tosca. The default value of startPhase is taken as '0'
 134 which takes precedence over the Automation Composition Elements with the startPhase value '1'. Http Automation Composition Elements are defined with value '1' in order to start the Automation Composition Element in the second phase.
 135
 136 Http participant Workflow:
 137 --------------------------
 138 Once the participant is started, it sends a "REGISTER" event to the Message Broker topic which is then consumed by the Automation Composition Runtime to register this participant on the runtime database.
 139 The user can commission the tosca definitions from the Policy Gui to the Automation Composition Runtime.
 140 Once the automation composition definitions are available in the runtime database the user can prime them and further updates the participant with these definitions via Message Broker.
 141 After primed, the Automation Composition can be instantiated with the default state "UNDEPLOYED" from the Policy Gui.
 142
 143 When the state of the Automation Composition is changed from "UNDEPLOYED" to "DEPLOYED" from the Policy Gui, the http participant receives the automation composition state change event from the runtime and
 144 configures the microservice of the corresponding Automation Composition Element over http.
 145 The configuration entity for a microservice is associated with each Automation Composition Element for the http participant.
 146 The http participant holds the executed http requests information along with the responses received.
 147
 148 The participant is used in a generic way to configure any entity over http and it does not hold the information about the microservice to unconfigure/revert the configurations when the
 149 state of Automation Composition changes from "DEPLOYED" to "UNDEPLOYED".
 150