docs/sections/design-components/requirements-guidelines.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3
   4 Onboarding Pre-requisite
   5 ========================
   6
   7 Before a component is onboarded into DCAE, the component developer must ensure it
   8 is compliant with ONAP & DCAE goals and requirement in order to correctly be deployed and be managed. This
   9 page will discuss the changes which are grouped into the following
  10 categories:
  11
  12 -  :any:`Configuration management via ConfigBindingService <configuration_management>`
  13 -  :any:`Docker images <docker_images>`
  14 -  :any:`Policy Reconfiguration flow support <policy_reconfiguration>`
  15 -  :any:`Operational Requirement <operation_requirement>`
  16
  17
  18 .. _configuration_management:
  19
  20 Configuration Management
  21 ------------------------
  22
  23 All configuration for a component is stored in CONSUL under the
  24 components uniquely generated name which is provided by the environment
  25 variable ``HOSTNAME`` as well as ``SERVICE_NAME``. It is then made
  26 available to the component via a remote HTTP service call to CONFIG
  27 BINDING SERVICE.
  28
  29 The main entry in CONSUL for the component contains its
  30 **generated application configuration**. This is based on the submitted
  31 component specification, and consists of the *interfaces* (streams and
  32 services/calls) and *parameters* sections. Other entries may exist as
  33 well, under specific keys, such as :dmaap . Each key represents a
  34 specific type of information and is also available to the component by
  35 calling CONFIG BINDING SERVICE. More on this below.
  36
  37 Components are required to pull their
  38 **generated application configuration** at application startup using the environment
  39 setting exposed during deployment.
  40
  41
  42 Envs
  43 ~~~~
  44
  45 The platform provides a set of environment variables into each Docker
  46 container:
  47
  48 +----------------------------+--------------+----------------------------------------+
  49 | Name                       | Type         | Description                            |
  50 +============================+==============+========================================+
  51 | ``HOSTNAME``               | string       | Unique name of the component instance  |
  52 |                            |              | that is generated                      |
  53 +----------------------------+--------------+----------------------------------------+
  54 | ``CONSUL_HOST``            | string       | Hostname of the platform's Consul      |
  55 |                            |              | instance                               |
  56 +----------------------------+--------------+----------------------------------------+
  57 | ``CONFIG_BINDING_SERVICE`` | string       | Hostname of the platform's config      |
  58 |                            |              | binding service instance               |
  59 |                            |              |                                        |
  60 +----------------------------+--------------+----------------------------------------+
  61 | ``DOCKER_HOST``            | string       | Host of the target platform Docker     |
  62 |                            |              | host to run the container on           |
  63 +----------------------------+--------------+----------------------------------------+
  64 | ``CBS_CONFIG_URL``         | string       | Fully resolved URL to query config     |
  65 |                            |              | from CONSUL via CBS                    |
  66 +----------------------------+--------------+----------------------------------------+
  67
  68
  69 .. _config_binding_service:
  70
  71 Config Binding Service
  72 ~~~~~~~~~~~~~~~~~~~~~~
  73
  74 The config binding service is a platform HTTP service that is
  75 responsible for providing clients with its fully resolve configuration
  76 JSON at startup, and also other configurations objects
  77 when requested.
  78
  79 At runtime, components should make an HTTP GET on:
  80
  81 ::
  82
  83   <config binding service hostname>:<port>/service_component/NAME
  84
  85 For Docker components, NAME should be set to ``HOSTNAME``, which is
  86 provided as an ENV variable to the container.
  87
  88 The binding service integrates with the streams and services section of
  89 the component specification. For example, if you specify that you call a
  90 service:
  91
  92 ::
  93
  94     "services": {
  95         "calls": [{
  96             "config_key": "vnf-db",
  97             "request": {
  98                 "format": "dcae.vnf.meta",
  99                 "version": "1.0.0"
 100                 },
 101             "response": {
 102                 "format": "dcae.vnf.kpi",
 103                 "version": "1.0.0"
 104                 }
 105         }],
 106     ...
 107     }
 108
 109 Then the config binding service will find all available IP addresses of
 110 services meeting the containers needs, and provide them to the container
 111 under your ``config_key``:
 112
 113 ::
 114
 115     // your configuration
 116     {
 117         "vbf-db" :                 // see above
 118             [IP:Port1, IP:Port2,…] // all of these meet your needs, choose one.
 119     }
 120
 121 Regarding ``<config binding service hostname>:<port>``, there is DNS
 122 work going on to make this resolvable in a convenient way inside of your
 123 container.
 124
 125 For all Kubernetes deployments since El-Alto, an environment variable ``CBS_CONFIG_URL`` will be exposed
 126 by platform (k8s plugins) providing the exact URL to be used for configuration retrieval.
 127 Application can use this URL directly instead of constructing URL from HOSTNAME (which refers to ServiceComponentName)
 128 and CONFIG_BINDING_SERVICE env's.  By default, this URL will use HTTPS CBS interface
 129
 130 If you are integrating with CBS SDK, then the DNS resolution and configuration fetch
 131 are handled via library functions.
 132
 133 Generated Application Configuration
 134 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 135
 136 The DCAE platform uses the component specification to generate the
 137 component’s application configuration provided at deployment time. The
 138 component developer should expect to use this configuration JSON in the
 139 component.
 140
 141
 142 The following component spec snippet (from String Matching):
 143
 144 ::
 145
 146     "streams":{
 147         "subscribes": [{
 148           "format": "VES_specification",
 149           "version": "4.27.2",
 150           "type": "message_router",
 151           "config_key" : "mr_input"
 152         }],
 153         "publishes": [{
 154           "format": "VES_specification",
 155           "version": "4.27.2",
 156           "config_key": "mr_output",
 157           "type": "message_router"
 158          }]
 159       },
 160       "services":{
 161         "calls": [{
 162           "config_key" : "aai_broker_handle",
 163           "verb": "GET",
 164           "request": {
 165             "format": "get_with_query_params",
 166             "version": "1.0.0"
 167           },
 168           "response": {
 169             "format": "aai_broker_response",
 170             "version": "3.0.0"
 171           }
 172         }],
 173         "provides": []
 174       },
 175
 176 Will result in the following top level keys in the configuration
 177
 178 ::
 179
 180        "streams_publishes":{
 181           "mr_output":{                // notice the config key above
 182              "aaf_password":"XXX",
 183              "type":"message_router",
 184              "dmaap_info":{
 185                 "client_role": null,
 186                 "client_id": null,
 187                 "location": null,
 188                 "topic_url":"https://YOUR_HOST:3905/events/com.att.dcae.dmaap.FTL2.DCAE-CL-EVENT" // just an example
 189              },
 190              "aaf_username":"XXX"
 191           }
 192        },
 193        "streams_subscribes":{
 194           "mr_input":{                 // notice the config key above
 195              "aaf_password":"XXX",
 196              "type":"message_router",
 197              "dmaap_info":{
 198                 "client_role": null,
 199                 "client_id": null,
 200                 "location": null,
 201                 "topic_url":"https://YOUR_HOST:3905/events/com.att.dcae.dmaap.FTL2.TerrysStringMatchingTest" // just an example
 202              },
 203              "aaf_username":"XXX"
 204           }
 205        },
 206        "services_calls":{
 207           "aai_broker_handle":[        // notice the config key above
 208              "135.205.226.128:32768"   // based on deployment time, just an example
 209           ]
 210        }
 211
 212 These keys will always be populated whether they are empty or not. So
 213 the minimum configuration you will get, (in the case of a component that
 214 provides an HTTP service, doesn’t call any services, and has no streams,
 215 is:
 216
 217 ::
 218
 219         "streams_publishes":{},
 220         "streams_subscribes":{},
 221         "services_calls":{}
 222
 223 Thus your component should expect these well-known top level keys.
 224
 225 DCAE SDK
 226 ~~~~~~~~
 227
 228 DCAE has SDK/libraries which can be used for service components for easy integration.
 229
 230 - `Java Library <https://docs.onap.org/projects/onap-dcaegen2/en/latest/sections/sdk/architecture.html>`__
 231 - `Python Modules <https://git.onap.org/dcaegen2/utils/tree/onap-dcae-cbs-docker-client>`__
 232
 233
 234
 235 .. _policy_reconfiguration:
 236
 237 Policy Reconfiguration
 238 ----------------------
 239
 240 Components must provide a way to receive policy reconfiguration, that
 241 is, configuration parameters that have been updated via the Policy UI.
 242 The component developer must either periodically poll the ConfigBindingService API
 243 to retrieve/refresh the new configuration or provides a script (defined in the :any:`Docker
 244 auxiliary specification <docker-auxiliary-details>`)
 245 that will be triggered when policy update is detected by the platform.
 246
 247
 248 .. _docker_images:
 249
 250 Docker Images
 251 -------------
 252
 253 Docker images must be pushed to the environment specific Nexus
 254 repository. This requires tagging your build with the full name of you
 255 image which includes the Nexus repository name.
 256
 257 For ONAP microservices, the components images are expected to pushed into ONAP nexus
 258 part of `ONAP CI jobs <https://wiki.onap.org/display/DW/Using+Standard+Jenkins+Job+%28JJB%29+Templates>`__
 259
 260
 261 .. _operation_requirement:
 262
 263 Operational Requirement
 264 -----------------------
 265
 266 Logging
 267 ~~~~~~~
 268
 269 All ONAP MS logging should follow logging specification defined by `logging project <https://wiki.onap.org/pages/viewpage.action?pageId=71831691>`__
 270
 271 The application log configuration must enable operation to choose if to be written into file or stdout or both during deployment.
 272
 273
 274 S3P
 275 ~~~
 276 ONAP S3P (all scaling/resiliency/security/maintainability) goals should meet at the minimum level defined for DCAE project for the targeted release
 277
 278 If the component is stateful, it should persist its state on external store (eg. pg, redis) to allow support for scaling and resiliency. This should be important design criteria for the component. If the components either publish/subscribe into DMAAP topic, then secure connection to DMAAP must be supported (platform will provide aaf_username/aaf_password for each topic as configuration).
 279