Services

Proxy

Proxy service is responsible for providing microservices functionalities through HTTP(S) protocol ensuring high availability and security mechanisms.

Each microservice is identified by JLupin Edge Balancer by its context:

  • defined by contextName parameter in case of servlet microservice configuration (servlet_configuration.yml file)
  • automatically assigned basing on microservice name, in case of native microservice

and is made available on particular virtual server basing on externalPort parameter provided in its configuration.

If the externalPort of a servlet microservice that provides its services under contextName context matches listen parameter one of the virtual server, it is accessible on that virtual server through the following URL:

http://<address_IP>:<externalPort>:/<contextName>

In case of native microservice, the additional parameters must be taken into consideration - the name of ELASTIC HTTP entry point, through which user would like to invoke service, as well as a service and method name that are involved in the request processing:

http://<address_IP>:<externalPort>:/_eapi/ELASTIC_HTTP/<microservice_name>/<serviceName>/<methodName>

Figure 2. JLupin Edge Balancer - proxy service.

The health checking mechanism comes along with the proxy service. Health checking URIs differs depending on the type of checked component:

  • /_healthcheck - reflect the state of the node
  • /_healthcheck/<context_name> - show the state of <context_name> context provided by SERVLET microservices
  • /_eapi/<elastic_api_name>/_healthcheck/<context_name> - show the state of <context_name> context provided by NATIVE microservices on <elastic_api_name>

If the component (node / context) is available the health check responds with 200 OK (we use curl to prepare examples and patterns):

Request:

GET /_healthcheck HTTP/1.1
User-Agent: curl/7.29.0
Host: localhost:8000
Accept: */*

Response:

HTTP/1.1 200 OK
Server: nginx
Date: Mon, 30 Jul 2018 07:00:28 GMT
Content-Type: text/plain
Connection: close
Content-Length: 2

in other cases, the response will be 503 Service Temporarily Unavailable:

Request:

GET /_healthcheck HTTP/1.1
User-Agent: curl/7.29.0
Host: localhost:8000
Accept: */*

Response:

HTTP/1.1 200 OK
Server: nginx
Date: Mon, 30 Jul 2018 07:00:28 GMT
Content-Type: text/plain
Connection: close
Content-Length: 2

We support 3 content types of response from health check mechanisms:

  • plain - plain text, the default type of content, where none of formatting if provided.
  • json - the JSON response is provided, suitable for load balancers that prefer this type of messages
  • html - the web page is generated, suitable for web browsers and users.

You can change the health check content type in two ways:

  • by modifying Content-type header in the request or
  • by modifying Accept header in the request

The Content-type has higher priority and will overwrite settings coming from Accept. Here are some examples:

JSON

curl -X GET -v -H "Content-type: application/json" http://localhost:8000/_healthcheck

HTTP/1.1 200 OK
Server: nginx
Date: Mon, 30 Jul 2018 07:11:33 GMT
Content-Type: application/json
Connection: close
Content-Length: 53
{
        "responseMessage": "OK",
        "responseCode": "200"
}

HTML

curl -X GET -v -H "Content-type: text/html" http://localhost:8000/_healthcheck

HTTP/1.1 200 OK
Server: nginx
Date: Mon, 30 Jul 2018 07:18:17 GMT
Content-Type: text/html
Connection: close
Content-Length: 311
<!DOCTYPE html>
<html>
<head><title>200 OK</title></head>
<style>
    body {
        width: 35em;
        margin: 0 auto;
        font-family: Tahoma, Verdana, Arial, sans-serif;
    }
</style>
<body><h1>Response status: 200</h1>
<p>Response message: OK</p>
<p><em>JLupin Edge Balancer</em></p>
</body>
</html>

Status

It provides information about the state of the node, microservices and balancer as well. The following URIs are available:

  • /_status/components - the brief information about all components covered by Edge Balancer, provided in JSON format. Example:
{
    "host": "NODE_1",
    "createdOn": "2018-07-30 09:55:34",
    "componentsCount": 8,
    "components": [
        {
            "status": "AVAILABLE",
            "componentName": "queueMicroservice"
        },
        {
            "status": "AVAILABLE",
            "componentName": "exchange-rates"
        },
        {
            "status": "AVAILABLE",
            "componentName": "channelMicroservice"
        },
        {
            "status": "AVAILABLE",
            "componentName": "exchange"
        },
        {
            "status": "AVAILABLE",
            "componentName": "currency-converter-gbp"
        },
        {
            "status": "AVAILABLE",
            "componentName": "http-session-repository"
        },
        {
            "status": "AVAILABLE",
            "componentName": "currency-converter-chf"
        },
        {
            "status": "AVAILABLE",
            "componentName": "currency-converter-eur"
        }
    ]
}

Discovery

It provides information about microservices that are configured on the given node. It used by Edge Balance intra-zone routing mechanism, it could be used by external balancer to build its configuration dynamically (similarly to Edge Balnacer) and perform proper balancing.

The following URIs are available:

  • /_discover/microservices - the list of local microservices with theirs basic parameters (valuable for Edge Balancer), formatted in JSON. Example:
{
    "8000": [
        {
            "state": "AVAILABLE",
            "host": "127.0.0.1",
            "discoveryPort": "9098",
            "contextName": "exchange-rates",
            "httpStickySession": "false",
            "type": "NATIVE",
            "elasticApi": "ELASTIC_HTTP",
            "name": "exchange-rates",
            "directPort": "8082"
        },
        {
            "elasticApi": "NULL",
            "host": "127.0.0.1",
            "discoveryPort": "9098",
            "contextName": "exchange",
            "httpStickySession": "false",
            "type": "SERVLET",
            "directPort": 20032,
            "name": "exchange",
            "state": "AVAILABLE"
        },
        {
            "state": "AVAILABLE",
            "host": "127.0.0.1",
            "discoveryPort": "9098",
            "contextName": "currency-converter-gbp",
            "httpStickySession": "false",
            "type": "NATIVE",
            "elasticApi": "ELASTIC_HTTP",
            "name": "currency-converter-gbp",
            "directPort": "8082"
        },
        {
            "state": "AVAILABLE",
            "host": "127.0.0.1",
            "discoveryPort": "9098",
            "contextName": "http-session-repository",
            "httpStickySession": "false",
            "type": "NATIVE",
            "elasticApi": "ELASTIC_HTTP",
            "name": "http-session-repository",
            "directPort": "8082"
        },
        {
            "state": "AVAILABLE",
            "host": "127.0.0.1",
            "discoveryPort": "9098",
            "contextName": "currency-converter-chf",
            "httpStickySession": "false",
            "type": "NATIVE",
            "elasticApi": "ELASTIC_HTTP",
            "name": "currency-converter-chf",
            "directPort": "8082"
        },
        {
            "state": "AVAILABLE",
            "host": "127.0.0.1",
            "discoveryPort": "9098",
            "contextName": "currency-converter-eur",
            "httpStickySession": "false",
            "type": "NATIVE",
            "elasticApi": "ELASTIC_HTTP",
            "name": "currency-converter-eur",
            "directPort": "8082"
        }
    ],
    "8001": [
        {
            "state": "AVAILABLE",
            "host": "127.0.0.1",
            "discoveryPort": "9098",
            "contextName": "queueMicroservice",
            "httpStickySession": "false",
            "type": "NATIVE",
            "elasticApi": "ELASTIC_HTTP",
            "name": "queueMicroservice",
            "directPort": "8082"
        },
        {
            "state": "AVAILABLE",
            "host": "127.0.0.1",
            "discoveryPort": "9098",
            "contextName": "channelMicroservice",
            "httpStickySession": "false",
            "type": "NATIVE",
            "elasticApi": "ELASTIC_HTTP",
            "name": "channelMicroservice",
            "directPort": "8082"
        }
    ],
    "8888": {},
    "8889": {}
}
  • /_discover/contexts - the list of context, dynamically configured by Edge Balancer. Example:
{
    "8000": [
        {
            "contextName": "exchange-rates",
            "routes": [
                {
                    "host": "127.0.0.1",
                    "discoveryPort": "9098",
                    "state": "AVAILABLE",
                    "priority": 1,
                    "name": "exchange-rates",
                    "port": "8082"
                }
            ],
            "state": "AVAILABLE",
            "httpStickySession": "false",
            "elasticApi": "ELASTIC_HTTP",
            "apiType": "NATIVE"
        },
        {
            "contextName": "exchange",
            "routes": [
                {
                    "host": "127.0.0.1",
                    "discoveryPort": "9098",
                    "state": "AVAILABLE",
                    "priority": 1,
                    "name": "exchange",
                    "port": 20032
                }
            ],
            "state": "AVAILABLE",
            "httpStickySession": "false",
            "elasticApi": "NULL",
            "apiType": "SERVLET"
        },
        {
            "contextName": "currency-converter-gbp",
            "routes": [
                {
                    "host": "127.0.0.1",
                    "discoveryPort": "9098",
                    "state": "AVAILABLE",
                    "priority": 1,
                    "name": "currency-converter-gbp",
                    "port": "8082"
                }
            ],
            "state": "AVAILABLE",
            "httpStickySession": "false",
            "elasticApi": "ELASTIC_HTTP",
            "apiType": "NATIVE"
        },
        {
            "contextName": "http-session-repository",
            "routes": [
                {
                    "host": "127.0.0.1",
                    "discoveryPort": "9098",
                    "state": "AVAILABLE",
                    "priority": 1,
                    "name": "http-session-repository",
                    "port": "8082"
                }
            ],
            "state": "AVAILABLE",
            "httpStickySession": "false",
            "elasticApi": "ELASTIC_HTTP",
            "apiType": "NATIVE"
        },
        {
            "contextName": "currency-converter-chf",
            "routes": [
                {
                    "host": "127.0.0.1",
                    "discoveryPort": "9098",
                    "state": "AVAILABLE",
                    "priority": 1,
                    "name": "currency-converter-chf",
                    "port": "8082"
                }
            ],
            "state": "AVAILABLE",
            "httpStickySession": "false",
            "elasticApi": "ELASTIC_HTTP",
            "apiType": "NATIVE"
        },
        {
            "contextName": "currency-converter-eur",
            "routes": [
                {
                    "host": "127.0.0.1",
                    "discoveryPort": "9098",
                    "state": "AVAILABLE",
                    "priority": 1,
                    "name": "currency-converter-eur",
                    "port": "8082"
                }
            ],
            "state": "AVAILABLE",
            "httpStickySession": "false",
            "elasticApi": "ELASTIC_HTTP",
            "apiType": "NATIVE"
        }
    ],
    "8001": [
        {
            "contextName": "queueMicroservice",
            "routes": [
                {
                    "host": "127.0.0.1",
                    "discoveryPort": "9098",
                    "state": "AVAILABLE",
                    "priority": 1,
                    "name": "queueMicroservice",
                    "port": "8082"
                }
            ],
            "state": "AVAILABLE",
            "httpStickySession": "false",
            "elasticApi": "ELASTIC_HTTP",
            "apiType": "NATIVE"
        },
        {
            "contextName": "channelMicroservice",
            "routes": [
                {
                    "host": "127.0.0.1",
                    "discoveryPort": "9098",
                    "state": "AVAILABLE",
                    "priority": 1,
                    "name": "channelMicroservice",
                    "port": "8082"
                }
            ],
            "state": "AVAILABLE",
            "httpStickySession": "false",
            "elasticApi": "ELASTIC_HTTP",
            "apiType": "NATIVE"
        }
    ],
    "8888": {},
    "8889": {}
}
  • /_discover/routes - the list of available routes for each context, dynamically configured by Edge Balancer. This set of information is crucial for balancing mechanisms. Example:
{
    "NATIVE.channelMicroservice.8001.ELASTIC_HTTP": [
        {
            "state": "AVAILABLE",
            "priority": 1,
            "microserviceRouteKey": "channelMicroservice.127.0.0.1.9098.ELASTIC_HTTP"
        }
    ],
    "SERVLET.exchange.8000.NULL": [
        {
            "state": "AVAILABLE",
            "priority": 1,
            "microserviceRouteKey": "exchange.127.0.0.1.9098.NULL"
        }
    ],
    "NATIVE.http-session-repository.8000.ELASTIC_HTTP": [
        {
            "state": "AVAILABLE",
            "priority": 1,
            "microserviceRouteKey": "http-session-repository.127.0.0.1.9098.ELASTIC_HTTP"
        }
    ],
    "NATIVE.exchange-rates.8000.ELASTIC_HTTP": [
        {
            "state": "AVAILABLE",
            "priority": 1,
            "microserviceRouteKey": "exchange-rates.127.0.0.1.9098.ELASTIC_HTTP"
        }
    ],
    "NATIVE.currency-converter-gbp.8000.ELASTIC_HTTP": [
        {
            "state": "AVAILABLE",
            "priority": 1,
            "microserviceRouteKey": "currency-converter-gbp.127.0.0.1.9098.ELASTIC_HTTP"
        }
    ],
    "NATIVE.currency-converter-eur.8000.ELASTIC_HTTP": [
        {
            "state": "AVAILABLE",
            "priority": 1,
            "microserviceRouteKey": "currency-converter-eur.127.0.0.1.9098.ELASTIC_HTTP"
        }
    ],
    "NATIVE.currency-converter-chf.8000.ELASTIC_HTTP": [
        {
            "state": "AVAILABLE",
            "priority": 1,
            "microserviceRouteKey": "currency-converter-chf.127.0.0.1.9098.ELASTIC_HTTP"
        }
    ],
    "NATIVE.queueMicroservice.8001.ELASTIC_HTTP": [
        {
            "state": "AVAILABLE",
            "priority": 1,
            "microserviceRouteKey": "queueMicroservice.127.0.0.1.9098.ELASTIC_HTTP"
        }
    ]
}

SSL

SSL service is a set of NGINX generic parameters that can be associated with any data or admin type virtual service (except discovery). In contains the following parameters:

ssl on;
ssl_session_cache  builtin:1000  shared:SSL:10m;
ssl_protocols  TLSv1 TLSv1.1 TLSv1.2;
ssl_ciphers HIGH:!aNULL:!eNULL:!EXPORT:!CAMELLIA:!DES:!MD5:!PSK:!RC4;
ssl_prefer_server_ciphers on;
ssl_certificate edge_ssl/edge_admin.crt;
ssl_certificate_key edge_ssl/edge_admin.key;

If you want to turn SSL on, include ssl.conf in your virtual server definition and optionally overwrite / add parameters (probable you will need to change certificate's and key's file names at least.)

Debug

This service helps to track Edge Balancer operations and state by providing access to its internal registers. It is good starting point for troubleshooting, before switching log severity do debug level.

The following URIs are available:

  • /_regdump/<registry_name>/[<registry_key>] - it dumps <registry_name> registry, in JSON format, optionally limited to the given <registry_key> key. example

The current state of the balancer (https://localhost:8888/_regdump/contextRoutes)

[
    {
        "key": "NATIVE.currency-converter-eur.8000.ELASTIC_HTTP",
        "value": "currency-converter-eur.127.0.0.1.9098.ELASTIC_HTTP"
    },
    {
        "key": "SERVLET.exchange.8000.NULL",
        "value": "exchange.127.0.0.1.9098.NULL"
    },
    {
        "key": "NATIVE.exchange-rates.8000.ELASTIC_HTTP",
        "value": "exchange-rates.127.0.0.1.9098.ELASTIC_HTTP"
    }
]

Addons

This is a set of additional services included in Edge Balancer which might be helpful in development and/or maintenance.

The following addons are available:

  • SwaggerUI - an offline version of Swagger UI available at /_swaggerUI URI. Additionally, you can automatically provide API specification to this instance of swagger UI by using /_swagger/<microservice_name>. In that way the swagger.json file located in <microservice_name> directory ($JLUPIN_HOME/platform/application/<microservice_name>) is automatically loaded by SwaggerUI.

Do you have any other ideas what could be useful here ? Please share this idea with us.