docs/docs/platform/user-guide.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0
   2    International License.
   3 .. http://creativecommons.org/licenses/by/4.0
   4
   5 MSB User-guide
   6 ==============
   7
   8
   9 Overview
  10 --------
  11
  12 Micro-Service Bus (MSB) provides a facility to register and
  13 expose ONAP Rest API.
  14
  15 It is particulary usefull to expose some API endpoints
  16 that are not published by default when installing ONAP with OOM installer.
  17
  18 There are two methods to register an API in MSB:
  19
  20 - via MSB Portal/GUI
  21 - via MSB Rest API
  22
  23
  24 Using MSB portal
  25 ----------------
  26
  27 MSB Portal/GUI is available on the following URL
  28 (adapt to your ONAP installation)
  29
  30 ..
  31
  32     ``http://msb.api.discovery.simpledemo.onap.org:30282/iui/microservices/default.html``
  33
  34
  35 The following screen should appears
  36
  37 .. figure:: images/home.png
  38    :align: center
  39
  40
  41 click on the "Service Discover" icon to get the list of
  42 registred API (it will take several seconds to get the next screen)
  43
  44 .. figure:: images/service-list-2.png
  45    :align: center
  46
  47 Note: majority of Registred API have been declared using MSB API and
  48 they can not be modified/deleted via MSB Portal/GUI.
  49
  50
  51 click on "view" icon in "Control" column to have a more
  52 detailed description of the registred API
  53
  54 .. figure:: images/service-detail.png
  55    :align: center
  56
  57 click on "Service Register" icon to start the register process for a new API
  58
  59 .. figure:: images/service-register.png
  60    :align: center
  61
  62 "Service Name" will be the new API name in MSB and will be used
  63 to build the URL that will be exposed.
  64
  65 "Url" is the url of the existing ONAP API that we are registering
  66
  67 "Protocol" must be selected in the list (usualy REST)
  68
  69 "Version" will be part of the exposed URL
  70
  71 "Visual Range" must be selected (usualy inSystem)
  72
  73 click on "Add Host" to provide information about IP address and
  74 port of the API that we are registering.
  75
  76 Tips: from an ONAP platform installed via OOM, to know about the IP/port,
  77 use Kubctl commands
  78
  79 example: to know about IP addresses used by ONAP Policy components
  80
  81 ::
  82
  83     kubectl get svc -n onap | grep policy
  84
  85
  86 Here after an example of Registered API for ONAP SO:
  87
  88
  89 .. figure:: images/service-edit.png
  90    :align: center
  91
  92
  93
  94 Using MSB API
  95 -------------
  96
  97 Get the list of registred API in MSB
  98
  99
 100 ::
 101
 102     curl -X GET \
 103     http://msb.api.discovery.simpledemo.onap.org:30280/api/microservices/v1/services \
 104     -H 'Content-Type: application/json' \
 105     -H 'cache-control: no-cache'
 106
 107
 108 response (small extract only):
 109
 110 ::
 111
 112         ],
 113         "metadata": [],
 114         "labels": [],
 115         "status": "1",
 116         "is_manual": false
 117     },
 118     {
 119         "serviceName": "aai-business",
 120         "version": "v16",
 121         "url": "/aai/v16/business",
 122         "protocol": "REST",
 123         "visualRange": "1",
 124         "lb_policy": "ip_hash",
 125         "publish_port": "",
 126         "namespace": "",
 127         "network_plane_type": "",
 128         "host": "",
 129         "path": "",
 130         "enable_ssl": true,
 131         "nodes": [
 132             {
 133                 "ip": "10.233.69.5",
 134                 "port": "8447",
 135                 "checkType": "",
 136                 "checkUrl": "",
 137                 "tls_skip_verify": true,
 138                 "ha_role": "",
 139                 "nodeId": "_v16_aai-business_10.233.69.5_8447",
 140                 "status": "passing"
 141             }
 142         ],
 143         "metadata": [],
 144         "labels": [],
 145         "status": "1",
 146         "is_manual": false
 147     },
 148
 149
 150
 151 Register a new API (example for ONAP policy-pap API)
 152
 153 "Service Name" will be the new API name in MSB and will be used
 154 to build the URL that will be exposed.
 155
 156 "Url" is the url of the existing ONAP API that we are registering
 157
 158 "Protocol" must be selected in the list (usualy REST)
 159
 160 "Version" will be part of the exposed URL
 161
 162 "Visual Range" must be selected (usualy inSystem)
 163
 164 "enable_ssl" must be set to "true" is using
 165 https between MSB and API service that we are registering.
 166
 167 "nodes" is a list  of IP addresses and port of the API that we are registering.
 168
 169 Tips: from an ONAP platform installed via OOM, to know about the IP/port,
 170 use Kubctl commands
 171 "enable_ssl" must be set to "true" is using
 172 https between MSB and API service that we are registering.
 173
 174
 175 ::
 176
 177     curl -X POST \
 178     http://msb.api.discovery.simpledemo.onap.org:30280/api/microservices/v1/services \
 179     -H 'Content-Type: application/json' \
 180     -H 'cache-control: no-cache' \
 181     -d '{
 182     "serviceName": "policy-api",
 183     "version": "v1",
 184     "url": "/policy/api/v1",
 185     "protocol": "REST",
 186     "visualRange": "1",
 187     "enable_ssl": true,
 188     "nodes": [
 189
 190         {
 191         "ip": "10.233.35.125",
 192         "port": "6969",
 193         "ttl": 0
 194         }
 195     ]
 196     }
 197     '
 198
 199 Delete an API from MSB (=unregister an API):
 200
 201 ::
 202
 203     curl -X DELETE \
 204     http://msb.api.discovery.simpledemo.onap.org:30280/api/microservices/v1/services/policy-pap/version/v1/nodes/10.233.15.213/6969 \
 205     -H 'Content-Type: application/json' \
 206     -H 'cache-control: no-cache' \
 207     -d '{
 208     "serviceName": "policy-pdp-legacy",
 209     "version": "v1",
 210     "url": "/pdp/api",
 211     "protocol": "REST",
 212     "visualRange": "1",
 213     "enable_ssl": true,
 214     "nodes": [
 215
 216         {
 217         "ip": "10.233.77.14",
 218         "port": "8081",
 219         "ttl": 0
 220         }
 221     ]
 222     }
 223     '
 224
 225
 226 Using a registred API
 227 ---------------------
 228
 229
 230 Once registered, the API can then be accessible using
 231 the following URL/Port
 232
 233 ``http://msb.api.discovery.simpledemo.onap.org:30280/api/{{Service Name}}/{{Version}}/{{resource}}``
 234
 235 where {{Service Name}} and {{Version}} are mapped to what have been registered
 236
 237 {{resource}} is to be replace by the object that the API is able to manage
 238
 239
 240 some examples:
 241
 242 to get the service model list from SDC via MSB
 243 (this API is pre-registred by default in ONAP):
 244
 245
 246 ::
 247
 248     curl -X GET \
 249     http://msb.api.discovery.simpledemo.onap.org:30280/api/sdc/v1/catalog/services \
 250     -H 'Accept: application/json' \
 251     -H 'Authorization: Basic YWFpOktwOGJKNFNYc3pNMFdYbGhhazNlSGxjc2UyZ0F3ODR2YW9HR21KdlV5MlU=' \
 252     -H 'Content-Type: application/json' \
 253     -H 'USER_ID: cs0008' \
 254     -H 'X-FromAppId: ONAP-Test' \
 255     -H 'X-TransactionId: ONAP-Test' \
 256     -H 'cache-control: no-cache' \
 257     -H 'x-ecomp-instanceid: ONAP-Test'
 258
 259
 260
 261 to get the customer list from AAI via MSB
 262 (this API is pre-registred by default in ONAP):
 263
 264
 265 ::
 266
 267     curl -X GET \
 268     http://msb.api.discovery.simpledemo.onap.org:30280/api/aai-business/v16/customers \
 269     -H 'Accept: application/json' \
 270     -H 'Authorization: Basic QUFJOkFBSQ==' \
 271     -H 'Content-Type: application/json' \
 272     -H 'X-FromAppId: AAI' \
 273     -H 'X-TransactionId: 808b54e3-e563-4144-a1b9-e24e2ed93d4f' \
 274     -H 'cache-control: no-cache'
 275
 276
 277 to get the list of policy models from Policy via MSB
 278 (this policy API needs to be registred):
 279
 280 ::
 281
 282     curl -X GET \
 283     http://msb.api.discovery.simpledemo.onap.org:30280/api/policy-api/v1/policytypes \
 284     -H 'Authorization: Basic aGVhbHRoY2hlY2s6emIhWHp0RzM0' \
 285     -H 'X-ONAP-RequestID: 9ac7ce8e-a867-4269-bc52-c8236b7fdad6' \
 286     -H 'cache-control: no-cache'