From: Rene_Robert Date: Mon, 19 Aug 2019 14:05:54 +0000 (+0200) Subject: Adding MSB user-guide X-Git-Tag: 1.2.6~15 X-Git-Url: https://gerrit.onap.org/r/gitweb?p=msb%2Fapigateway.git;a=commitdiff_plain;h=0d3d414b1e62c0c3b1423be9ccd46a720430db8c Adding MSB user-guide Issue-ID: MSB-362 Signed-off-by: Rene_Robert Change-Id: Ie3a9b01f6e7f4c36f8e860fb658ccb5c7a95f54f --- diff --git a/docs/platform/images/add-host.png b/docs/platform/images/add-host.png new file mode 100644 index 0000000..7c23852 Binary files /dev/null and b/docs/platform/images/add-host.png differ diff --git a/docs/platform/images/home.png b/docs/platform/images/home.png new file mode 100644 index 0000000..e9db9c1 Binary files /dev/null and b/docs/platform/images/home.png differ diff --git a/docs/platform/images/service-detail.png b/docs/platform/images/service-detail.png new file mode 100644 index 0000000..e546b7b Binary files /dev/null and b/docs/platform/images/service-detail.png differ diff --git a/docs/platform/images/service-edit.png b/docs/platform/images/service-edit.png new file mode 100644 index 0000000..2dbfade Binary files /dev/null and b/docs/platform/images/service-edit.png differ diff --git a/docs/platform/images/service-list-2.png b/docs/platform/images/service-list-2.png new file mode 100644 index 0000000..f88b493 Binary files /dev/null and b/docs/platform/images/service-list-2.png differ diff --git a/docs/platform/images/service-list.png b/docs/platform/images/service-list.png new file mode 100644 index 0000000..bca9af3 Binary files /dev/null and b/docs/platform/images/service-list.png differ diff --git a/docs/platform/images/service-register.png b/docs/platform/images/service-register.png new file mode 100644 index 0000000..745a100 Binary files /dev/null and b/docs/platform/images/service-register.png differ diff --git a/docs/platform/index.rst b/docs/platform/index.rst index 0d114ed..e918128 100644 --- a/docs/platform/index.rst +++ b/docs/platform/index.rst @@ -16,3 +16,4 @@ Microservices Bus provide key infrastructure functionalities to support ONAP mic installation.rst configuration.rst human-interfaces.rst + user-guide.rst diff --git a/docs/platform/user-guide.rst b/docs/platform/user-guide.rst new file mode 100644 index 0000000..3471275 --- /dev/null +++ b/docs/platform/user-guide.rst @@ -0,0 +1,286 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 + International License. +.. http://creativecommons.org/licenses/by/4.0 + +MSB User-guide +============== + + +Overview +-------- + +Micro-Service Bus (MSB) provides a facility to register and +expose ONAP Rest API. + +It is particulary usefull to expose some API endpoints +that are not published by default when installing ONAP with OOM installer. + +There are two methods to register an API in MSB: + +- via MSB Portal/GUI +- via MSB Rest API + + +Using MSB portal +---------------- + +MSB Portal/GUI is available on the following URL +(adapt to your ONAP installation) + +.. + + http://msb.api.discovery.simpledemo.onap.org:30282/iui/microservices/default.html + + +The following screen should appears + +.. figure:: images/home.png + :align: center + + +click on the "Service Discover" icon to get the list of +registred API (it will take several seconds to get the next screen) + +.. figure:: images/service-list-2.png + :align: center + +Note: majority of Registred API have been declared using MSB API and +they can not be modified/deleted via MSB Portal/GUI. + + +click on "view" icon in "Control" column to have a more +detailed description of the registred API + +.. figure:: images/service-detail.png + :align: center + +click on "Service Register" icon to start the register process for a new API + +.. figure:: images/service-register.png + :align: center + +"Service Name" will be the new API name in MSB and will be used +to build the URL that will be exposed. + +"Url" is the url of the existing ONAP API that we are registering + +"Protocol" must be selected in the list (usualy REST) + +"Version" will be part of the exposed URL + +"Visual Range" must be selected (usualy inSystem) + +click on "Add Host" to provide information about IP address and +port of the API that we are registering. + +Tips: from an ONAP platform installed via OOM, to know about the IP/port, +use Kubctl commands + +example: to know about IP addresses used by ONAP Policy components + +:: + + kubectl get svc -n onap | grep policy + + +Here after an example of Registered API for ONAP SO: + + +.. figure:: images/service-edit.png + :align: center + + + +Using MSB API +------------- + +Get the list of registred API in MSB + + +:: + + curl -X GET \ + http://msb.api.discovery.simpledemo.onap.org:30280/api/microservices/v1/services \ + -H 'Content-Type: application/json' \ + -H 'cache-control: no-cache' + + +response (small extract only): + +:: + + ], + "metadata": [], + "labels": [], + "status": "1", + "is_manual": false + }, + { + "serviceName": "aai-business", + "version": "v16", + "url": "/aai/v16/business", + "protocol": "REST", + "visualRange": "1", + "lb_policy": "ip_hash", + "publish_port": "", + "namespace": "", + "network_plane_type": "", + "host": "", + "path": "", + "enable_ssl": true, + "nodes": [ + { + "ip": "10.233.69.5", + "port": "8447", + "checkType": "", + "checkUrl": "", + "tls_skip_verify": true, + "ha_role": "", + "nodeId": "_v16_aai-business_10.233.69.5_8447", + "status": "passing" + } + ], + "metadata": [], + "labels": [], + "status": "1", + "is_manual": false + }, + + + +Register a new API (example for ONAP policy-pap API) + +"Service Name" will be the new API name in MSB and will be used +to build the URL that will be exposed. + +"Url" is the url of the existing ONAP API that we are registering + +"Protocol" must be selected in the list (usualy REST) + +"Version" will be part of the exposed URL + +"Visual Range" must be selected (usualy inSystem) + +"enable_ssl" must be set to "true" is using +https between MSB and API service that we are registering. + +"nodes" is a list of IP addresses and port of the API that we are registering. + +Tips: from an ONAP platform installed via OOM, to know about the IP/port, +use Kubctl commands +"enable_ssl" must be set to "true" is using +https between MSB and API service that we are registering. + + +:: + + curl -X POST \ + http://msb.api.discovery.simpledemo.onap.org:30280/api/microservices/v1/services \ + -H 'Content-Type: application/json' \ + -H 'cache-control: no-cache' \ + -d '{ + "serviceName": "policy-api", + "version": "v1", + "url": "/policy/api/v1", + "protocol": "REST", + "visualRange": "1", + "enable_ssl": true, + "nodes": [ + + { + "ip": "10.233.35.125", + "port": "6969", + "ttl": 0 + } + ] + } + ' + +Delete an API from MSB (=unregister an API): + +:: + + curl -X DELETE \ + http://msb.api.discovery.simpledemo.onap.org:30280/api/microservices/v1/services/policy-pap/version/v1/nodes/10.233.15.213/6969 \ + -H 'Content-Type: application/json' \ + -H 'cache-control: no-cache' \ + -d '{ + "serviceName": "policy-pdp-legacy", + "version": "v1", + "url": "/pdp/api", + "protocol": "REST", + "visualRange": "1", + "enable_ssl": true, + "nodes": [ + + { + "ip": "10.233.77.14", + "port": "8081", + "ttl": 0 + } + ] + } + ' + + +Using a registred API +--------------------- + + +Once registered, the API can then be accessible using +the following URL/Port + +http://msb.api.discovery.simpledemo.onap.org:30280/api/{{Service Name}}/{{Version}}/{{resource}} + +where {{Service Name}} and {{Version}} are mapped to what have been registered + +{{resource}} is to be replace by the object that the API is able to manage + + +some examples: + +to get the service model list from SDC via MSB +(this API is pre-registred by default in ONAP): + + +:: + + curl -X GET \ + http://msb.api.discovery.simpledemo.onap.org:30280/api/sdc/v1/catalog/services \ + -H 'Accept: application/json' \ + -H 'Authorization: Basic YWFpOktwOGJKNFNYc3pNMFdYbGhhazNlSGxjc2UyZ0F3ODR2YW9HR21KdlV5MlU=' \ + -H 'Content-Type: application/json' \ + -H 'USER_ID: cs0008' \ + -H 'X-FromAppId: ONAP-Test' \ + -H 'X-TransactionId: ONAP-Test' \ + -H 'cache-control: no-cache' \ + -H 'x-ecomp-instanceid: ONAP-Test' + + + +to get the customer list from AAI via MSB +(this API is pre-registred by default in ONAP): + + +:: + + curl -X GET \ + http://msb.api.discovery.simpledemo.onap.org:30280/api/aai-business/v16/customers \ + -H 'Accept: application/json' \ + -H 'Authorization: Basic QUFJOkFBSQ==' \ + -H 'Content-Type: application/json' \ + -H 'X-FromAppId: AAI' \ + -H 'X-TransactionId: 808b54e3-e563-4144-a1b9-e24e2ed93d4f' \ + -H 'cache-control: no-cache' + + +to get the list of policy models from Policy via MSB +(this policy API needs to be registred): + +:: + + curl -X GET \ + http://msb.api.discovery.simpledemo.onap.org:30280/api/policy-api/v1/policytypes \ + -H 'Authorization: Basic aGVhbHRoY2hlY2s6emIhWHp0RzM0' \ + -H 'X-ONAP-RequestID: 9ac7ce8e-a867-4269-bc52-c8236b7fdad6' \ + -H 'cache-control: no-cache'