##################### Entrypoint balancer ##################### .. contents:: :local: :depth: 1 Introduction ============== The Entrypoint balancer is an important part of the aerOS management framework (stuck to the Management portal) to avoid the addition of an additional centralization point, so that it emphasises the decentralised nature of aerOS. After conducting a thorough review of the cutting-edge network load balancers, it has been determined that the most suitable LB algorithm in the case of the entrypoint balancer is the Least Connection type (or one of its modifications). This algorithm includes a straightforwardly updatable weighting function that is fed with metrics from the data fabric, such as the number of orchestration requests managed by each domain's HLO or IE capabilities. Features ======== The Entrypoint balancer offers the endpoint */entrypoint-balancer/distribute/{serviceId}*, which enables the Management Portal BE to send the upcoming service orchestration request that are to be distributed among the HLOs of the continuum domains. The endpoint accepts: - path variable *serviceId*, which is a unique identifier of the service that is to be deployed in one of the domains - JSON request body representing a valid TOSCA specification of the service - optional parameter *domainId* that can be used to pass an identifier of the domain to which the request is to be forwarded (used when the user explicitly selects the target domain) Moreover, the Entrypoint balancer supports online updates of its internal configuration by exposing the */entrypoint-balancer/configure* endpoint. It accepts a JSON body with a valid configuration specification, about which more details can be found in *Configuration options* section. Load balancing algorithm ------------------------ The algorithm implemented within Entrypoint balancer is based on the `Improved Weighted Least Connections `__. It works in the following way. The Entrypoint balancer assign to each of the domains registered in Orion-LD the flag **availability**, which indicates whether a given domain is going to be considered in the processing of next client request. Initially, all domains are marked as available. The information about the domains' availability is stored in the Entrypoint balancer's cache and is being updated in consecutive computations of the algorithm. Whenever the client request is received, the Entrypoint balancer begins by evaluating the scores of each available domain using the **weighting function**. By default, the **weighting function** computes the CPU usage of all IEs belonging to the given domain. However, its code can be easily modified (e.g. to take into account different properties such as RAM usage) depending on the high-level requirements. The domain's score is obtained by dividing the number of services running within a domain (services with *Running* status) by the weight computed using **weighting function**. Then the domain, which has a highest score is selected by the algorithm. To prevent the cases in which a single domain would be consecutively selected by the algorithm (e.g. when it was newly added to the continuum), the Entrypoint balancer uses a parameter *maxAssignments*. If a given domain is selected more than *maxAssignments* time, it is being temporarily blocked for the next *maxAssignments* - 1 selections (see `Improved Weighted Least Connections `__). After that, the domain is made, once again, available. This feature, is applicable only when there is more than 1 domain present in the continuum. Place in architecture ===================== The Entrypoint balancer aims to relax the centralised needs of a unique, 1:1, direct relation Management Portal -> HLO, towards a 1:N, fairly distributed approach. In fact, with this addition, the existence of an Entrypoint balancer emphasises the decentralised nature of aerOS orchestration. This way, regardless of the "Entrypoint domain" choice, the inception of orchestration (the HLO that will initiate the process) is balanced across domains. .. image:: ./images/decentralized-orchestration.png :alt: aerOS entrypoint balancer in orchestration :align: center Prerequisities ============== This aerOS Basic Services are needed to cover all the functionalities provided by the Entrypoint balancer: - Keycloak - Orion-LD - HLO Storage Engine .. Installation .. ============ Configuration options ===================== Currently, the Entrypoint balancer uses only one configurable option: - *maxAssignments*: maximum number of orchestration requests consecutively passed to a single domain. Developer guide =============== The Entrypoint Balancer has been developed a **Spring Framework 6** application, starting the project with **Spring Boot 3** and using some complementary libraries such as **Spring Security** or **OpenFeign**. Minimum prerequirements for the local development machine: - `Java JDK 21 `__ - `Apache Maven 3.8 `__ The recommended IDE to develop this component is `IntelliJ IDEA `__ but other alternatives such as Eclipse Java IDE and VSCode can be used as well. Now, the application can be run using the selected IDE. It will run by default in the port 8080. Finally, the Spring application can be configured through the modification of the *src/main/resources/application.yaml* file: .. code:: yaml spring: cloud: openfeign: client: config: orion-ld: url: "http://orion-ld-broker:1026/ngsi-ld/v1/" connect-timeout: 20000 read-timeout: 20000 logger-level: basic hlo-fe: url: "http://hlo-fe-service:8081" connect-timeout: 10000 read-timeout: 10000 logger-level: basic load-balancer: max-assignments: 10 Packaging into a JAR file ------------------------- In order to package the application into a JAR file (for instance, to be included into a Dockerfile), run: .. code:: bash mvn clean compile package Build a container image ----------------------- First, package the application into a JAR file. Then, use the included *Dockerfile* to build the container image: .. code:: bash docker build -t aerOS/entrypoint-balancer . Authors ======= SRIPAS