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

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2
   3 .. _clamp-controlloop-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-controlloop-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
  17
  18 .. image:: ../../images/participants/http-participant.png
  19
  20
  21 The HTTP participant runs a Control Loop 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 Control Loop to be managed. A
  26 particular Control Loop may require many *things* to be configured and managed and this
  27 may require many REST dialogues to achieve.
  28
  29 When a control loop is initialized, the HTTP participant starts a HTTP Control Loop
  30 element for the control loop. It reads the configuration information sent from the
  31 Control Loop 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 Control Loop
  33 Elements towards multiple REST endpoints, as shown in the diagram above where the HTTP
  34 participant is running two HTTP Control Loop Elements, one for Control Loop A and one for
  35 Control Loop B.
  36
  37 Configuring a Control Loop Element on the HTTP participant for a Control Loop
  38 -----------------------------------------------------------------------------
  39 A *Configuration Entity* describes a concept that is managed by the HTTP participant. A
  40 Configuration Entity can be created, Read, Updated, and Deleted (CRUD). The user defines
  41 the Configuration Entities that it wants its HTTP Control Loop Element to manage and
  42 provides a sequence of parameterized REST commands to Create, Read, Update, and Delete
  43 each Configuration Entity.
  44
  45 Sample tosca template defining a http participant and a control loop element for a control loop. :download:`click here <tosca/tosca-http-participant.yml>`
  46
  47 The user configures the following properties in the TOSCA for the HTTP participant:
  48
  49 .. list-table::
  50    :widths: 15 10 50
  51    :header-rows: 1
  52
  53    * - Property
  54      - Type
  55      - Description
  56    * - baseUrl
  57      - URL
  58      - A well formed URL pointing at the REST server that is processing the REST requests
  59    * - httpHeaders
  60      - map
  61      - A map of *<String, String>* defining the HTTP headers to send on all REST calls
  62    * - configurationEntitiies
  63      - map
  64      - A map of *<String, ConfigurationEntity>* describing the names and definitions of
  65        configuration entities that are managed by this HTTP Control Loop Element
  66
  67 The *ConfigurationEntity* type is described in the following table:
  68
  69 .. list-table::
  70    :widths: 15 10 50
  71    :header-rows: 1
  72
  73    * - Field
  74      - Type
  75      - Description
  76    * - ID
  77      - ToscaConceptIdentifier
  78      - The name and version of the Configuration Entity
  79    * - restSequence
  80      - List<RestRequest>
  81      - A list of REST requests to give manage the Configuration Entity
  82
  83 The *RestRequest* type is described in the following table:
  84
  85 .. list-table::
  86    :widths: 15 10 50
  87    :header-rows: 1
  88
  89    * - Field
  90      - Type
  91      - Description
  92    * - httpMethod
  93      - HttpMethod
  94      - An enum for the HTTP method {GET, PUT, POST, DELETE}
  95    * - path
  96      - String
  97      - The path of the REST endpoint relative to the baseUrl
  98    * - body
  99      - String
 100      - The body of the request for POST and PUT methods
 101    * - expectedResponse
 102      - HttpStatus
 103      - The expected HTTP response code fo the REST request
 104
 105 Http participant Interactions:
 106 ------------------------------
 107 The http participant interacts with Control Loop Runtime on the northbound via DMaap. It interacts with any microservice on the southbound over http for configuration.
 108
 109 The communication for the Control loop updates and state change requests are sent from the Control Loop Runtime to the participant via DMaap.
 110 The participant invokes the appropriate http endpoint of the microservice based on the received messages from the Control Loop Runtime.
 111
 112
 113 startPhase:
 114 -----------
 115 The http participant is often used along with :ref:`Kubernetes Participant <clamp-controlloop-k8s-participant>` to configure the microservice after the deployment.
 116 This requires the Control Loop Element of http participant to be started after the completion of deployment of the microservice. This can be achieved by adding the property `startPhase`
 117 in the Control Loop Element of http participant. Control Loop Runtime starts the elements based on the `startPhase` value defined in the Tosca. The default value of startPhase is taken as '0'
 118 which takes precedence over the Control Loop Elements with the startPhase value '1'. Http Control Loop Elements are defined with value '1' in order to start the Control Loop Element in the second phase.
 119
 120 Http participant Workflow:
 121 --------------------------
 122 Once the participant is started, it sends a "REGISTER" event to the DMaap topic which is then consumed by the Control Loop Runtime to register this participant on the runtime database.
 123 The user can commission the tosca definitions from the Policy Gui to the Control Loop Runtime that further updates the participant with these definitions via DMaap.
 124 Once the control loop definitions are available in the runtime database, the Control Loop can be instantiated with the default state "UNINITIALISED" from the Policy Gui.
 125
 126 When the state of the Control Loop is changed from "UNINITIALISED" to "PASSIVE" from the Policy Gui, the http participant receives the control loop state change event from the runtime and
 127 configures the microservice of the corresponding Control Loop Element over http.
 128 The configuration entity for a microservice is associated with each Control Loop Element for the http participant.
 129 The http participant holds the executed http requests information along with the responses received.
 130
 131 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
 132 state of Control Loop changes from "PASSIVE" to "UNINITIALISED".
 133