--- /dev/null
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. _master_index:
+
+MSB(Microservices Bus)
+------------------------------------------------
+
+Microservices Bus(MSB) provides a reliable, resilient and scalable communication and governance infrastructure to support ONAP Microservice Architecture including service registration/discovery, external API gateway, internal API gateway, client SDK, Swagger SDK, etc. It's a pluggable architecture, plugins can be added to MSB to provide whatever functionalities you need, such as an auth plugin can be used to provide centralized authentication & authorization. MSB also provides a service portal to manage the REST APIs.
+
+MSB is platform independent, while it is integrated with Kubernetes(OOM) to provide transparent service registration for ONAP microservices, MSB also supports OpenStack(Heat) and bare metal deployment.
+
+This document is aimed to give the users some brief introductions on MSB from different aspects. The users could find useful information, e.g. the architecuture, the APIs and the installation steps, etc. as well as the release notes of MSB in this document.
+
+
+.. toctree::
+ :maxdepth: 1
+
+ platform/index.rst
+ release-notes.rst
+
--- /dev/null
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. _architecture:
+
+
+Architecture
+------------
+Microservices Bus(MSB) provides a reliable, resilient and scalable communication and governance infrastructure to support ONAP Microservice Architecture including service registration/discovery, external API gateway, internal API gateway, client SDK, Swagger SDK, etc. It's a pluggable architecture, plugins can be added to MSB to provide whatever functionalities you need, such as an auth plugin can be used to provide centralized authentication & authorization. MSB also provides a service portal to manage the REST APIs.
+
+MSB is platform independent, while it is integrated with Kubernetes(OOM) to provide transparent service registration for ONAP microservices, MSB also supports OpenStack(Heat) and bare metal deployment.
+
+
+
+MSB is mainly comprised of three parts: Discovery, API Gateway and MSB Client SDK. MSB also provide a swagger SDK which could generate swagger REST service description files..
+
+.. image:: images/msb-architecture.png
+
+Registry is the storage of service information, MSB leverage Consul as the service registry.
+
+MSB Discovery provides REST APIs for service discovery and registration.
+
+API Gateway provides service request routing, load balancing and service governance. It can be deployed as external Gateway or Internal Gateway.
+
+MSB SDK is a client-side Java SDK which can be used for point to point communication of microservices.
--- /dev/null
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+
+Configuration
+-------------
+
+No machanism for customized configurtions is provided in this release. Such functionalities will be provided in the future if necessary.
+
--- /dev/null
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+Consumed APIs
+-------------
+
+In the Amsterdam release, MSB does not consume any APIs provided by other ONAP components.
--- /dev/null
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+
+Delivery
+--------
+
+Describe how functions are packaged into run-time components. For some components a block diagram may be useful.
+
+:Docker:
+
+- MSB Discovery
+- MSB API Gateway
+
+Docker containers can be downloaded from ONAP docker repository.
+
+:jar:
+
+- MSB Client SDK
+- Swagger SDK
+
+Jars can be downloaded from ONAP docker repository.
--- /dev/null
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+Human Interfaces
+----------------
+MSB provides a Web GUI Portal for users.
+Users can register services and browse all the registered services. If the registered service support swagger, user can see the REST API documentation and test the registered services via the swagger UI integrated in MSB.
+
+Target Users
+^^^^^^^^^^^^
+ONAP Administrator.
+
+Interface Type
+^^^^^^^^^^^^^^
+Web GUI.
+
+Access
+^^^^^^
+``http://MSB_API_GATEWAY_IP:80/msb``
\ No newline at end of file
--- /dev/null
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+Platform
+--------
+
+Microservices Bus provide key infrastructure functionalities to support ONAP microservice architecture including service registration/discovery, service gateway, service load balancer and service governance. It's a pluggable architecture so it can be extended with plugins to provide value added services such as centralized authentication for APIs. Microservices Platform also provides a GUI portal for service management.
+
+.. toctree::
+ :maxdepth: 1
+
+ architecture.rst
+ offeredapis.rst
+ consumedapis.rst
+ delivery.rst
+ log-and-diagnostic-info.rst
+ installation.rst
+ configuration.rst
+ human-interfaces.rst
+ user-guide.rst
--- /dev/null
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+Installation
+------------
+MSB can run as docker, it's very handy to try it at your laptop. For production, MSB supports to be deployed as a cluster to provide a scalable microservice communication infrastructure with kubernetes.
+
+Run MSB on the a single host using host network
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This deployment approach is only for testing. MSB is consist of multiple microservices, for testing, the easiest way is to run them in the same host by using host network.
+
+- Run the Consul dockers
+
+::
+
+ sudo docker run -d --net=host --name msb_consul consul:0.9.3
+
+- Run the MSB dockers
+
+Login the ONAP docker registry first:
+
+::
+
+ docker login -u docker -p docker nexus3.onap.org:10001
+
+Run MSB dockers
+
+::
+
+ docker run -d --net=host --name msb_discovery nexus3.onap.org:10001/onap/msb/msb_discovery
+ docker run -d --net=host -e "ROUTE_LABELS=visualRange:1" --name msb_internal_apigateway nexus3.onap.org:10001/onap/msb/msb_apigateway
+
+- Register your REST service to MSB via curl
+
+For testing, we can register the services via curl.
+
+::
+
+ curl -X POST \
+ -H "Content-Type: application/json" \
+ -d '{"serviceName": "aai", "version": "v8", "url": "/aai/v8","protocol": "REST", "path": "/aai/v8", "nodes": [ {"ip": "10.74.215.65","port": "8443"}]}' \
+ "http://127.0.0.1:10081/api/microservices/v1/services”
+
+- Access the rest service via api gateway
+
+::
+
+ curl http://127.0.0.1/api/aai/v8/cloud-infrastructure/cloud-regions
+
+- Browse the registered services
+
+ Open MSB Web GUI portal in your browser: ``http://127.0.0.1/msb`` , you can see all the registered services. If the registered service support swagger, you can see the REST API documentation and test the registered services via the swagger UI integrated in MSB.
+
+Run MSB using default docker network
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In case that you don't want to use host network to set up the MSB dockers, you need to export the port and specify the environment variables to let msb components know each other.
+
+- Run the Consul dockers
+
+::
+
+ sudo docker run -d -p 8500:8500 --name msb_consul consul:0.9.3
+ CONSUL_IP=`sudo docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' msb_consul`
+
+
+- Run the MSB dockers
+
+Login the ONAP docker registry first:
+
+::
+
+ docker login -u docker -p docker nexus3.onap.org:10001
+
+Run MSB dockers
+
+::
+
+ sudo docker run -d -p 10081:10081 -e CONSUL_IP=$CONSUL_IP --name msb_discovery nexus3.onap.org:10001/onap/msb/msb_discovery
+ DISCOVERY_IP=`sudo docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' msb_discovery`
+ sudo docker run -d -p 80:80 -e CONSUL_IP=$CONSUL_IP -e SDCLIENT_IP=$DISCOVERY_IP -e "ROUTE_LABELS=visualRange:1" --name msb_internal_apigateway nexus3.onap.org:10001/onap/msb/msb_apigateway
+
+Deploy MSB with kubernetes
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The chart for MSB running in kubernetes cluster is available here:
+
+https://gerrit.onap.org/r/gitweb?p=oom.git;a=tree;f=kubernetes/msb;h=17f8fd89791b81f1e981716dcffdb3e2e90299ae;hb=refs/heads/master
--- /dev/null
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+Logging & Diagnostic Information
+---------------------------------
+
+Description of how to interact with and diagnose problems with the components as delivered.
+
+Where to Access Information
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+You can use docker command such as docker exec or docker logs to interact with and diagnose problems of MSB.
+
+
+Error / Warning Messages
+^^^^^^^^^^^^^^^^^^^^^^^^
--- /dev/null
+Offered APIs
+------------
+.. _offeredapis:
+
+The MSB provides the following APIs.
+
+- `Service Registration <https://wiki.onap.org/display/DW/Microservice+Bus+API+Documentation#MicroserviceBusAPIDocumentation-RegisterservicetotheMicroserviceBus>`_.
+- `Service Unregistration <https://wiki.onap.org/display/DW/Microservice+Bus+API+Documentation#MicroserviceBusAPIDocumentation-UnregisterservicefromtheMicroserviceBus>`_.
+- `Service Discovery <https://wiki.onap.org/display/DW/Microservice+Bus+API+Documentation#MicroserviceBusAPIDocumentation-QueryservicefromtheMicroserviceBus>`_.
+- `MSB Java SDK :ref: https://wiki.onap.org/display/DW/Microservice+Bus+API+Documentation#MicroserviceBusAPIDocumentation-MSBClientSDK>`.
+- `Swagger SDK <https://wiki.onap.org/display/DW/swagger-sdk>`_.
+
+Discover more about.
+
+- `MSB API & User Guide <https://wiki.onap.org/pages/viewpage.action?pageId=20873883>`_.
--- /dev/null
+.. 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'
Code Review / msb / apigateway.git / commitdiff
