*************************
Low-Level Orchestrator
*************************


Introduction
==============
The aerOS Low-level Orchestrator receives formal services implementation blueprints from the HLO and translates this blueprints into running services in 
the selected IEs.


Features
========
In aerOS, the LLOs are based on the `K8s Operator Pattern <https://kubernetes.io/docs/concepts/extend-kubernetes/operator/>`__, 
which provide a framework to automatically control the lifecycle management of resources. This does not mean that LLOs only support the 
management of K8s workloads, but that actually leverage this widely used and tested resource management framework to finally reflect the desired 
state of services (to be deployed in a certain IE), with a common way to express the Implementation Blueprints (custom K8s Custom Resources) 
that is independent on the container management framework used in the selected IE, so that agnostic for the HLO. Moreover, using K8s Operators
allows to easily extend the aerOS LLO to cover more container management frameworks without being decoupled from the entire orchestration solution.

It is important to highligh that several LLOs may exist in a domain, one for each container management framework that run the IEs of the domain.
Therefore, the LLO Operator developed to interact with an specific container management framework (Docker for instance) contains the needed logic to run 
and delete the containerized workload in the selected IE of the same domain.

Custom Resource Definition
--------------------------
In K8s, `Custom Resources <https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/>`__ (CR) are extensions to the Kubernetes API.
In aerOS, a common structure for all the Custom Resources used by the LLO Operators has been defined to cover all the Implementation Blueprint regardless 
of the underlying container management framework of the selected IE to deploy a service. This means that the only field of the CR that will change depending
on the container management framework is the **kind**. For instance, for Docker it will be *ServiceComponentDocker* and for K8s it will be *ServiceComponentK8s*.

As an example, when a K8s CR of type *ServiceComponentK8s* is deployed in the K8s cluster in which has been installed the LLO Operators, the LLO Operator for IEs with 
K8s as container management framework is triggered to deploy the container in the selected IE, which in this case is a K8s node. The same process occurs
when the selected IE is a standalone Docker machine.

This is an example of a LLO Custom Resource:

.. code-block:: yaml

  apiVersion: llo.aeros-project.eu/v1alpha1
  kind: <It_Depends_On_The_Container_Management_Framework>
  metadata:
    labels:
      app.kubernetes.io/name: component-3-of-the-service-1
      app.kubernetes.io/instance: urn_ngsi-ld_Service_1_Component_3
      app.kubernetes.io/part-of: urn_ngsi-ld_Service_1
      app.kubernetes.io/managed-by: aeros-project.eu
      app.kubernetes.io/created-by: urn_ngsi-ld_LowLevelOrchestrator_2
    name: service-component-sample
  spec:
    selectedIE: urn:ngsi-ld:IE:continuum-cluster-worker-2
    image: your_public_container_image:tag
    cliArgs:
      - key: -test
      - key: -testValue
        value: id3
    envVars:
      - key: SAMPLE_ENV_VAR
        value: sampleValue
    ports:
      - number: 80
        protocol: TCP
      - number: 3000
        protocol: UDP


LLO types
==============
According to the aerOS architecture and as mentioned in the above section, the IEs of the continuum can run different types of container management frameworks, 
such as K8s, Docker or containerd. Thus, a different K8s Operator must be developed to support the required containerization technologies run by the IEs. 
Currently, aerOS provides support for these container management frameworks:

.. toctree::
    :maxdepth: 1
  
    k8s.rst
    docker.rst
.. containerd.rst

In the future, a guide will be provided in order to assist on the development of new LLO types.

.. image:: ./multiple-llos.png
  :alt: multiple LLOs
  :align: center

|

LLO Operator API
================
A custom REST API has been developed to help end users to manage the aerOS K8s Custom Resources deployed in the K8s clusters.

+--------+---------------------------------+-----------------------------------------------+---------------------------------------+------------+----------------------------------------------------------------+
| Method | Endpoint                        | Description                                   | Query parameters                      | Payload    | Response format                                                |
+========+=================================+===============================================+=======================================+============+================================================================+
| GET    | /version                        | Returns the API version                       |                                       |            | {"version": "1.0.1-mvp","supportedCRs": list of supported CRs} |
+--------+---------------------------------+-----------------------------------------------+---------------------------------------+------------+----------------------------------------------------------------+
| GET    | /health                         | Returns the health status                     |                                       |            | {"message": "Health status"}                                   |
+--------+---------------------------------+-----------------------------------------------+---------------------------------------+------------+----------------------------------------------------------------+
| GET    | /v1/service-components          | Retrieves all the deployed Service Components | type: type of the LLO (docker or k8s) |            |                                                                |
+--------+---------------------------------+-----------------------------------------------+---------------------------------------+------------+----------------------------------------------------------------+
| POST   | /v1/service-components          | Deploys a Service Component                   | type: type of the LLO (docker or k8s) | CR in YAML |                                                                |
+--------+---------------------------------+-----------------------------------------------+---------------------------------------+------------+----------------------------------------------------------------+
| GET    | /v1/service-components/{scName} | Retrieves a deployed Service Component        | type: type of the LLO (docker or k8s) |            |                                                                |
+--------+---------------------------------+-----------------------------------------------+---------------------------------------+------------+----------------------------------------------------------------+
| DELETE | /v1/service-components/{scName} | Deletes a deployed Service Component          | type: type of the LLO (docker or k8s) |            |                                                                |
+--------+---------------------------------+-----------------------------------------------+---------------------------------------+------------+----------------------------------------------------------------+