Overview

JLupin Edge Balancer is a NGINX instance with LUA module, which includes prepared by JLupin custom LUA module (called 'jlupin') to integrate it with Main Server. The basic assumption is that Main Server provides all necessary information for NGINX on HTTP_INFORMATION_PORT (/listMicroservices entry point), which is used by NGINX to perform auto-configuration process providing controlled access to servlet microservices in the environment.

By default JLupin Edge Balancer runs the following virtual servers (as a HTTP server):

• edge0 (port: 8000) - default 'data' type virtual server, where services from servlet microserivces are implicitly provided if it hasn't been defined differently in their configuration files. See next chapter to get to know more.
• edge1 (port: 8001) - additional 'data' type virtual servers, where services from servlet microservices might be provided, if it has been defined in their configuration files accordingly. See next chapter to get to know more.
• edge_adm (port: 8888) - default 'admin' type virtual server, where only administration services are provided. I the near future, the JLupin Local Web Console will be provided here (as webcontrol context). The SSL turned on this virtual server by default.

The type of virtual server determines what kind of services are provided and what is the scope of the informational entry points (ex. /_status):

• on 'data' virtual servers (interfaces) only user's servlet microservices are provided and the scope of informational entry points are limited to this particular virtual server.
• on 'admin' virtual servers (interfaces) none of user's servlet microserivces are provided (regardless their configuration), only administration tools provided by JLupin are available here. The scope of informational entry points covers all servlet microserivces.

Configuration

Configuration files

JLupin Edge Balancer consists of several NGINX configuration files:

Parameters

The following list consists only those parameters, that are important for the mechanisms and processes performed by JLupin Edge Balancer and might be modified by users.

nginx.conf

server.conf

edge.conf

Common parameters

Virtual servers parameters

Each virtual server that provides services from servlet microserivces is defined through server directive and configured by the following parameters

The additional generic NGINX parameters can be provided by the user to adjust Edge Balancer actions to services' specifics (offical documentation).

Accessing services

General rules

Each servlet microservice is identified by JLupin Edge Balancer by its context (contextName in its servlet_configuration.yml file) 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>

as shown on the below picture.

Built-in services

There couple of built-in services that support integration of JLupin node (jBrick) into the environment. There are available under predefined and reserved contexts (URIs) and presented below in the next chapters.

/_healthcheck

The health checking endpoint for external balancers allowing to properly set status of provided services. This endpoint is available on each virtual server defined in edge.conf.

Request: GET http(s)://<hostname>:<port>/_healthcheck/[<context_name>]

Answer :

If Content-Type was not specified or set to text/plain in the request:

HTTP/1.1 200 OK
Server: nginx
Date: ...
Content-Type: text/plain
Connection: keep-alive
Content-Length: 2

or

HTTP/1.1 503 Service Temporarily Unavailable
Server: nginx
Date: ...
Content-Type: text/plain
Connection: keep-alive
Content-Length: 19

depending on the availability of the <context_name>.

If Content-Type was set to application/json in the request:

Headers:

HTTP/1.1 200 OK
Server: nginx
Date: ...
Content-Type: application/json
Connection: keep-alive
Content-Length: 53

Body:

{
    "responseMessage": "OK",
    "responseCode": "200"
}

or

Header:

HTTP/1.1 503 Service Temporarily Unavailable
Server: nginx
Date: ...
Content-Type: application/json
Connection: keep-alive
Content-Length: 70

Body:

{
        "responseMessage": "Service Unavailable",
        "responseCode": "503"
}

depending on the availability of the <context_name>.

Node that when <context_name> is null then the response reflects status of the node.

/_status

The status endpoint summarizes status of each context configured on the particular virtual server. The scope of the response from admin type virtual server is extended by all contexts, configured on all virtual servers, including admin ones. This endpoint is available on each virtual server defined in edge.conf, where status.conf was included.

Request: GET http(s)://<hostname>:<port>/_status

Answer :

If Content-Type was not specified or set to text/plain in the request:

Pattern:

<context_name1>:<status>
<context_name2>:<status>
...

Example:

conA:AVAILABLE
conB:AVAILABLE
conC:AVAILABLE

If Content-Type was not specified or set to application/json in the request:

Pattern:

[
    {
        "contextName": "<context_name1>",
        "contextStatus": "<status>"
    },
    {
        "contextName": "<context_name2>",
        "contextStatus": "<status>"
    },

    ...
]

Example:

[
    {
        "contextName": "conA",
        "contextStatus": "AVAILABLE"
    },
    {
        "contextName": "conB",
        "contextStatus": "AVAILABLE"
    },
    {
        "contextName": "conC",
        "contextStatus": "AVAILABLE"
    }
]

/_discover

The discover endpoint provides the list of contexts configured on the particular data type virtual server. The scope of the response from admin type virtual server is extended by all data type virtual servers. This endpoint is available on each virtual server defined in edge.conf.

Note that service provided on admin type virtual server can be very useful in service discovery performed by external balancers in auto configuration process.

Request: GET http(s)://<hostname>:<port>/_discover

Answer :

If Content-Type was not specified or set to text/plain in the request:

Pattern:

<virtual_server_port1>:<context_name1>
<virtual_server_port1>:<context_name2>
...
<virtual_server_port2>:<context_name2>
<virtual_server_port2>:<context_name3>
...

Example (on 'data' type virtual server configured on 8000 port):

8000:conA
8000:conB

Example (on 'admin' type virtual server):

8000:conA
8000:conB
8001:
8002:conB
8002:conC

Note that in case when none of contexts are configured on the particular virtual server, this virtual server is followed with null value (as presented above in case of 8001 virtual server).

If Content-Type was not specified or set to application/json in the request:

Pattern:

[
    {
        "<virtual_server_port1>": [
            {
                "contextName": "<context_name1>"
            },
            {
                "contextName": "<context_name2>"
            }
            ...
        ]
    },
    {
        "<virtual_server_port2>": [
            {
                "contextName": "<context_name1>"
            },
            {
                "contextName": "<context_name2>"
            }
            ...
        ]
    },

    ...
]

Example (on 'data' type virtual server configured on 8000 port):

[
    {
        "8000": [
            {
                "contextName": "conA"
            },
            {
                "contextName": "conB"
            }
        ]
    }
]

Example (on 'admin' type virtual server):

[
    {
        "8000": [
            {
                "contextName": "conA"
            },
            {
                "contextName": "conB"
            }
        ]
    },
    {
        "8001": {}
    },
    {
        "8002": [
            {
                "contextName": "conB"
            },
            {
                "contextName": "conC"
            }
        ]
    }
]