Skip to end of metadata
Go to start of metadata

Discover the Microservice Bus

Microservice Bus provides a service registration/discovery and routing mechanism to simply the communications between services, The service consumers only need to talk with Microservice Bus without any address information of individual service providers. However, all the service consumers/providers must know the IP and service port of Microservice Bus. MSB suggests the following approach to discover the Microservice Bus.
Each service provider/consumer implementation can get the address of the Microservice Bus from a local config file via the key 'msb.address', the default value consists of a hostname and a service port. The hostname is 'msb.onap.org', which can be resolved by a DNS server in the local network, and the default port is 80. If a DNS server is not available in some deployments, an IP should be used instead.

Examples:

  • Default config when a DNS server is available
msb.address: msb.onap.org:80
  • An IP if a DNS server is not available
msb.address: 10.74.205.123:80

API Definition and Swagger-UI

ONAP intends to be a microservices-based architecture and every individual service is exposed as a restful API. Microservice Bus provide mechanisms to collect and display the API description(swagger UI) and metrics of services centrally.
The services should provide the information to Microservice Bus by the below approaches:

Swagger

  1. REST APIs should be described in a swagger.json file according to Open API Initiative.
  2. The swagger.json file should be put at the root path of the service url, such as: http(s)://[hostname][:port]/[ServiceType]/[ServiceName]/[Service Version]/Swagger.json
  3. The swagger.json can be automatically generated by JAVA notation, more information can be find at Swagger Annotations.

For example, the swagger description and UI of the services provided by Microservice Bus:
Service: /api/microservices/v1/
Swagger: /api/microservices/v1/swagger.json

Register service to the Microservice Bus

OperationRegister service to the Microservice Bus
URL/api/microservices/v1/services
VerbPOST
Request



ParameterMandatoryParameter typeData TypeDefaultexampleDescription
BodyYBodyJSON String
{
  "serviceName": "aai",
  "version": "v8",
  "url": "/aai/v8",
  "protocol": "REST",
  "visualRange": "1",
"path":"/aai/v8"
"nodes": [
    {
      "ip": "10.74.56.36",
      "port": "8988",
      "ttl": 0
    }
  ]
}
Described in the below table
createOrUpdateNQuerybooleantrue
true: create new instances or replace the old instances if the instance with the same service name, ipandportexist 

false: create new instances and remove all the old instances with the same service name

ParameterMandatoryData TypeDefaultDescription
serviceNameYString
Service Name, must comply with RFC 1123, only allowsthe ASCII letters 'a' through 'z' , the digits '0' through '9', and the minus sign ('-'). 
versionYString
Service Version
urlY if protocol is 'REST' or 'UI' or 'HTTP'String
the actual URL of the service to be registered
protocolYString
supported protocols: 'REST', 'UI', 'HTTP','TCP'
visualRangeNString1Visibility of the service. 
External(can be accessed by external systems):0 
Internal(can only be accessed by ONAP microservices):1

path

NString

Thecustomizedpublish path of this service.

If path parameter is specified when registering the service, the service will be published to apigateway under this path. Otherwise, the service will be published to apigateway using a fixed format: api/{serviceName}/{version}.

The customized publish path should only be used for back-compatible. 

enable_sslNbooleanFalse

True if the registered service is based on https.

False if the registered service is based on http.

nodesYList
ip: the ipoftheservice instance node, it could also be a hostname like catalog.onap.org
port: the port of the service instance node
ttl: time to live, this parameter is reserved for later use



Response
exampleDescription
{
  "serviceName": "catalog",
  "version": "v1",
  "url": "/api/catalog/v1",
  "protocol": "REST",
  "visualRange": "1",
"lb_policy":"ip_hash",
  "nodes": [
    {
      "ip": "10.74.55.66",
      "port": "6666",
      "ttl": 0
    },
    {
      "ip": "10.74.56.37",
      "port": "8989",
      "ttl": 0  
    },
    {
      "ip": "10.74.56.36",
      "port": "8988",
      "ttl": 0
    }
  ]
}

serviceName: service name
version: version
url: url of the created service instance
protocol: supported protocols: 'REST', 'UI','HTTP','TCP'
nodes: the service instance nodes list to register
lb_policy: Load balancing method, Currently two LB methods are supported, round-robin and ip-hash.
ip: the ip of the service instance node, it could also be a hostname like catalog.onap.org
port: the port of the service instance node
ttl: time to live, this parameter is reserved for later use


Success Code201
Error Code

422 Invalid Parameters
500 Internal Server Error

Unregister service from the Microservice Bus

OperationUnregister service from the Microservice Bus
URL/api/microservices/v1/services/{serviceName}/version/{version}/nodes/{ip}/{port}
VerbDELETE
Request
ParameterMandatoryParameter typeData TypeDefaultexampleDescription
serviceNameYPathString

Service Name
versionNPathString

Service Version
ipNPathString

the IP address of the service instance, it could also be a hostname like catalog.onap.org
portNPathString

the port of the service instance
Response
Success Code204
Error Code

404 Can't find the service instance
422 Invalid Parameters
500 Internal Server Error

Query service from the Microservice Bus

You can access service by two ways:

First is Point to Point, service consumer can query service instances address from MSB by the following API,and access the service provider directly; - Not recommended, we will lose centralized control capabilities if chose this approach, for example, service call logging, service load balancing policy, etc.

Second is API Gateway, service consumer do not care ip and port of the service provider, it just access the API-Gateway ,and the API-Gateway will route the service call to the appropriate service provider; in this approach, service consumers only need to know the ip and port of API Gateway, it can be stored in a configuration file or an environment property of the service consumer implementation.

MSB support the following access methods:

if the service provider version property is provided when registration, you can use the version before or behind the service name.

/api/[servicename]/v1

/api/v1/[servicename]

if the service did not have version property, you can use the url without version.

/api/[servicename]/


OperationQuery service from the Microservice Bus
URL/api/microservices/v1/services/{serviceName}/version/{version}
VerbGET
Request
ParameterMandatoryParameter typeData TypeDefaultexampleDescription
serviceNameNPathString

Service Name
versionNPathString

Service Version
Response
exampleDescription
{
  "serviceName": "catalog",
  "version": "v1",
  "url": "/api/catalog/v1",
  "protocol": "REST",
  "visualRange": "1",
  "nodes": [
    {
      "ip": "10.74.55.66",
      "port": "6666",
      "ttl": 0
    },
    {
      "ip": "10.74.56.37",
      "port": "8989",
      "ttl": 0
    },
    {
      "ip": "10.74.56.36",
      "port": "8988",
      "ttl": 0
    }
  ]
}

serviceName: service name
version: version
url: url of the created service instance
protocol: supported protocols: 'REST', 'UI', 'HTTP','TCP'
nodes: the service instance nodes list to register
ip: the ip of the service instance node, it could also be a hostname like catalog.onap.org
port: the port of the service instance node
ttl: time to live, this parameter is reserved for later use

Success Code200
Error Code

404 Can't find the service instance
422 Invalid Parameters
500 Internal Server Error

MSB Client SDK

MSBServiceClient :  JAVA SDK for MSB service discovery

RestServiceCreater: JAVA SDK for REST service invocation

MSB Client SDK Example

https://gerrit.onap.org/r/gitweb?p=msb/java-sdk.git;a=tree;f=example;h=1c331f86cbcbdb8cc2935d8ac41169da1a523ec5;hb=refs/heads/master


    String MSB_IP="127.0.0.1";
    int MSB_Port=10081;
    
    MSBServiceClient msbClient = new MSBServiceClient(MSB_IP, MSB_Port);
    
    RestServiceCreater restServiceCreater =
        new RestServiceCreater(msbClient);

    AnimalServiceClient implProxy =
        restServiceCreater.createService(AnimalServiceClient.class);
    
    Animal animal = implProxy.queryAnimal("panda").execute().body();
    System.out.println("animal:" + animal);

Note: In order to test the example application, you need to run MSB following this guide MSB Test Environment Setup

  • No labels

4 Comments

  1. Hello, A very good documentation.

    I would suggere that we add design / pattern / registration recommendation for APIs in ONAP.


    1/ When using SO we found for instance that it's the root path that is registered in MSB and not the 3 different kind of APIs, for instance as you suggest "url": "/api/catalog/v1". Thus client needs to hardcode specific path, including version, instead of just the resource path like /serviceInstance. When new version has been out in casablanca those hardcoded full path are broken, it would have not occurred if client used the serviceInstance api v7  from MSB, instead of just so api.

    Should be

    serviceInstance
    /onap/so/infra/serviceInstantiation/v7/serviceInstances/

    orchestration
    /onap/so/infra/orchestrationRequests/v7

    e2e
    /onap/so/infra/e2eServiceInstances/v3


    instead of unique /


    2/ Some find request return 404 when list is empty, that's wrong because the URL is valid, but query parameters returns nothing. It's not an error, it's just an empty list with code 200 and json []. The 404 is ambiguous because it suggests that this url doesn't exist, and you MUST update your client code which is wrong..


    There are more to add (smile)

    1. Good points! We do have suggestion/recommendation for APIs here: RESTful API Design Specification and we encourage projects to follow these suggestions when designing their APIs.

      1. The recommendation is registering each microservices separately to MSB, however, some ONAP projects such as SO are not Microservice architecture when they are brought to ONAP, but the suggestion from TSC is every project should evolve towards that direction.
      2. Could you please elaborate on this issue, is it from MSB api gateway or form SO originally?  
  2. Thank you very much Huabing for pointing to this excellent document.

    My remark is not specific to SO, but it's a good example to illustrate why we need centralized service( or api ) repository.SO is not micro services oriented but we can guess 3 different APIs

    serviceInstance

    /onap/so/infra/serviceInstantiation/v7/serviceInstances/

    orchestration

    /onap/so/infra/orchestrationRequests/v7

    e2e

    /onap/so/infra/e2eServiceInstances/v3

    As SO registers only base hosts we had to hard code 3 paths in casablanca, and we faced with SO, while playing with first integration test to, a change, both in path and version. We had to look into the source code.As an improvement I guess SO might publish 3 different APIs or services with 3 different url parameter while registering to MSB.


    I have also seen that services are listed here, but it's still human documentation which doesn't reflect the source code, for instance SO is still v5 in the wiki. ( bad point for externalapi we didn't reference the service here by the way ! )

    ONAP Services List#SO

    2 options:

    1. maintain an official list and add that into the milestone checklist
    2. or maybe something cool get those information from the master instanciation, reflecting that way what are the referenced services, as a table with : serviceName, version, protocol, checkUrl and msb url to consume the service. It would facilitate integration  (smile)
    1. Loop Seshu Kumar M in

      I checked with OOM deployment yaml file, as Matthieu Geerebaert pointed out, only the infra URL is registered.

      We could register 3 different APIs as Matthieu suggested if SO project also think it's reasonable. 


      For the services list, MSB generates a list of service at http://$MSB_Address:80/msb, you could see all the registered services.

      annotations:
          msb.onap.org/service-info: '[
            {
                "serviceName": "{{ include "common.servicename" . }}",
                "version": "v1",
                "url": "/ecomp/mso/infra",
                "protocol": "REST"
                "port": "8080",
                "visualRange":"1"
            },
            {
                "serviceName": "so-deprecated",
                "version": "v1",
                "url": "/ecomp/mso/infra",
                "protocol": "REST"
                "port": "8080",
                "visualRange":"1",
                "path":"/ecomp/mso/infra"
            }
            ]'