########################################## HLO Frontend Engine ########################################## .. contents:: :local: :depth: 1 The HLO Frontend Engine is the Component of the HLO responsible for exposing an HLO REST API to the management portal. It exposes Exposes endpoints for cross-domain service LCM. It receives a TOSCA modeled service deployment request and initiates a service orchestration across aerOS domains. Upon a create request, TOSCA yaml is parsed and its nodes are converted to NGSI-LD entities. These entities are created and pushed to domain CB. The Service entity id is pushed to HLO data aggregator. Upon an update request, TOSCA yaml is parsed and its nodes are converted to NGSI-LD entities. Old/new entities are created/updated and pushed to domain CB. The Service entity id is pushed to HLO data aggregator. Upon a delete request, entities are updated for service deallocation. Service id is pushed to HLO data aggregator. .. image:: HLO-FE-Engine.png :alt: HLO Frontend Engine Prerequisities ============== This component requires make, helm and docker for building and installation. Installation ============ Note that this component is part of HLO common deployment and used in aerOS domain installation. You can install as part of this standard installation. For development installation : * .. code-block:: bash git clone https://gitlab.aeros-project.eu/wp3/t3.3/hlo-frontend.git * .. code-block:: bash cd hlo-frontend * .. code-block:: bash python3 -m venv venv * .. code-block:: bash pip install -r requirments * .. code-block:: bash source venv/bin/activate * .. code-block:: bash uvicorn main:app --reload * test APIs using the FastAPI swagger page, example Tosca included .. image:: hlo-fe-yaml-example.png :alt: HLO-FE-EP swagger * or test APIs using POSTMAN collection included (`HLO-FE-Engine.postman_collection.json `_) * for testing APIs either connect with MVP RedPanda broker or disable broker registration and message publishing For isolated component installation in aerOS domain, you can use the Makefile in the repository : Edit variables, if needed, and : * Build and tag docker image .. code-block:: bash make build * Push to aerOS repository .. code-block:: bash make push * Package and upload helm chart .. code-block:: bash make helm-upload * Deploy against cluster chosen as current k8s context .. code-block:: bash make deploy * All the above .. code-block:: bash make all * Removes docker image .. code-block:: bash make clean-build * Removes the helm deployment from the cluster .. code-block:: bash make clean-deploy * Removes all the above .. code-block:: bash make clean-all Configuration options ===================== The component can be configured from docker container environment variables : - CB_URL : Context Broker URL. - CB_PORT : Context Broker Port. - BOOTSTRAP_SERVERS : Redpanda bootstrap servers. - GROUP_ID : Redpanda group id. - AUTO_OFFSET_RESET : Auto Offset Reset option for Redpanda. - CONSUMER_TOPIC : The Redpanda topic used to publish to the data aggregator. Developer guide =============== Communications and Interactions ------------------------------- As introduced before, The HLO FE EP exposes a REST API and send a trigger message to the Data Aggregator. In what follows, the concerned data definitions : .. list-table:: OpenAPI EP, Messages exchanged and Primitives definition :header-rows: 1 * - HLO FE EP openAPI - Messages exchanged - Primitives definition * - .. code-block:: yaml openapi: 3.1.0 info: version: "1.0.0" title: HLO Domain Frontend API contact: email: info@aeros-project.com license: name: Apache 2.0 url: 'http://www.apache.org/licenses/LICENSE-2.0.html' servers: - description: HLO Domain Frontend endpoint url: '{protocol}://{hostname}:{port}' variables: protocol: enum: - http - https default: https hostname: default: localhost port: default: '443' tags: - name: hlo_fe paths: /hlo_fe/services/{service_id}: post: tags: - hlo_fe description: Allocate a new service across domains operationId: allocateService parameters: - $ref: '#/components/parameters/serviceIdParameter' requestBody: description: The service TOSCA definition content: "application/x-yaml": schema: type: string description: "service TOSCA" responses: '200': description: "service allocation initiated" '400': description: "invalid service parameters" delete: tags: - hlo_fe description: Deallocate an existing service across domains operationId: deallocateService parameters: - $ref: '#/components/parameters/serviceIdParameter' responses: '200': description: "service deallocation initated" '404': $ref: "#/components/responses/ServiceNotFound" put: tags: - hlo_fe operationId: changeServiceAllocationParamters requestBody: description: The service TOSCA definition content: "application/x-yaml": schema: type: string description: "service TOSCA" parameters: - $ref: '#/components/parameters/serviceIdParameter' responses: '200': description: "service allocation parameters change initiated" '404': $ref: "#/components/responses/ServiceNotFound" components: parameters: serviceIdParameter: name: 'service_id' in: query schema: type: string responses: ServiceNotFound: description: "service not found" - .. code-block:: protobuf syntax = "proto3"; import "hlo.proto"; message HLODataAggregatorOutput { Service service = 1; } - .. code-block:: protobuf syntax = "proto3"; message Domain { string id = 1; } message Service { string id = 1; } message LowLevelOrchestrator { string id = 1; string orchestration_type = 3; Domain domain = 2; } message InfrastructureElement { string id = 1; float total_ram = 2; float cpu_cores = 3; float avg_power_consumption = 4; bool real_time_capable = 5; float current_ram = 6; float current_cpu_usage = 7; float current_power_consumption = 8; Domain domain = 9; LowLevelOrchestrator low_level_orchestrator = 10; } message Port { int32 number = 1; } message ServiceComponent { string id = 1; string image = 2; repeated Port ports = 3; Service service = 4; ServiceComponentConstraints service_component_constraints = 5; optional InfrastructureElement infrastructure_element = 6; } message ServiceComponentConstraints { map constraints = 1; } Authors ======= The authors are: - Pitsilis, Vasilis (vpitsilis@dat.demokritos.gr). - Benmerar, Tarik Zakaria (tarik.benmerar@ictficial.com).