aboutsummaryrefslogtreecommitdiffstats
path: root/docs/platform/user-guide.rst
diff options
context:
space:
mode:
Diffstat (limited to 'docs/platform/user-guide.rst')
-rw-r--r--docs/platform/user-guide.rst286
1 files changed, 286 insertions, 0 deletions
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'