##########################################
LLO Docker
##########################################

.. contents::
  :local:
  :depth: 1

Introduction
==============
K8s Operator developed using the `Operator SDK <https://sdk.operatorframework.io/>`__ toolkit for Infrastructure Elements use Docker as its container management framework.

.. note::
    A new version of the LLO Docker is under development, with a renewed architecture based on NATS broker pub/sub.
    When ready, the installation guide will be updated accordingly.


Features
========
This project aims to follow the Kubernetes `Operator pattern <https://kubernetes.io/docs/concepts/extend-kubernetes/operator/>`_.
It uses `Controllers <https://kubernetes.io/docs/concepts/architecture/controller/>`_,
which provide a reconcile function responsible for synchronizing resources until the desired state is reached on the cluster.
More information can be found via the `Kubebuilder Documentation <https://book.kubebuilder.io/introduction.html>`_.


The LLO Docker Operator watches for two different K8s custom resources:

- **DockerInfrastructureElement**: this custom resource is used to manage the underlyging Docker API of the IEs, which actually manages the containers (creation and deletion) in the IE.
- **ServiceComponentDocker**: sends a request to the custom Docker API of the selected IE to run or delete a Docker container.

It is important to clarify that, although the LLO Docker is developed as a K8s Operator, it just aims to manage Docker containers by calling the Docker API 
installed in the Docker IEs of the same aerOS domain. Therefore, this Operator only manages the K8s Custom Resources described above in the K8s cluster in 
which is installed, without creating any additional resources (nor containers) in the K8s cluster.

This operator also updates the *status* attribute of the *ServiceComponent* entity in Orion-LD to be compliant with the aerOS lifecycle management 
of deployed services in the continuum.

User guide
=====================

.. TODO include info about Docker API

.. warning:: 

  A *DockerInfrastructureElement* must be successfully deployed previously in the cluster, with an annotation *apiReady=true*, to be able to deploy a *ServiceComponentDocker* in a Docker IE. This means that the Docker API has been installed in this target IE and it's accessible by this Operator.


Deploy a K8s Custom Resource of kind **ServiceComponentDocker** in your K8s cluster:

.. code-block:: bash

  kubectl apply -f your-scdocker-cr.yaml
  

This is an example of a **ServiceComponentDocker**:

.. code-block:: yaml

  apiVersion: llo.aeros-project.eu/v1alpha1
  kind: ServiceComponentDocker
  metadata:
    labels:
      app.kubernetes.io/name: component-1-of-the-service-1
      app.kubernetes.io/instance: urn_ngsi-ld_Service_1_Component_1
      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-1-orion-ld
  spec:
    selectedIE:
      id: urn:ngsi-ld:InfrastructureElement:CloudFerro:4073c6a5a93b
      hostname: docker-machine-2
    image: fiware/orion-ld:1.7.0
    ports:
      - number: 1026
        protocol: TCP
    cliArgs:
      - key: -brokerId
        value: test-broker
      - key: -dbhost
        value: service-1-mongo
      - key: -t
        value: 0-255
      - key: -logLevel
        value: DEBUG
      - key: -forwarding
      - key: -experimental
      - key: -wip
        value: entityMaps

To delete the previously created **ServiceComponentDocker** in the K8s cluster:

.. code-block:: bash

  kubectl delete -f your-scdocker-cr.yaml

  
Prerequisities
==============

A K8s cluster is required. The controller will automatically use the current context in your kubeconfig file (i.e. whatever cluster `kubectl cluster-info` shows).

In addition, a machine with Docker and the aerOS Docker API installed is also needed as this Operator is in charge of managing the Docker containers in the underlying machine.


Installation
============
All the needed K8s manifests have been packaged into a single YAML file, which is available in the repository.

.. code-block:: bash

  kubectl apply -f operator-deployment.yaml


You can also create these manifests by running the below command, but some modifications may be needed.

.. code-block:: bash
  
  kustomize build config/default > operator-deployment.yaml


This file has also been uploaded to the `Common deployments repository <https://gitlab.aeros-project.eu/aeros-public/common-deployments/-/packages/102>`_. Therefore, you can install it just by running:

.. code-block:: bash

  curl --header "PRIVATE-TOKEN: <token-from-common-deployments>" https://gitlab.aeros-project.eu/api/v4/projects/65/packages/generic/llo/1.0.1/docker-operator-deployment.yaml | kubectl apply -f -


.. Configuration options
.. =====================

Developer guide
===============
As previously mentioned, this K8s Operator has been developed using the `Go-based Operator <https://sdk.operatorframework.io/docs/building-operators/golang/>`__ of the Operator SDK framework.
Please, check the official documentation for more information.

.. warning:: 

  - The golang version must be 1.21
  - The K8s cluster that is configured as the *current context* in the *kubeconfig* file must be reachable 


Install the Operator SDK CLI
----------------------------
The official installation guide is available `here <https://sdk.operatorframework.io/docs/installation/>`__, but a quick installation guide is included here.

- Set platform information as environment variables:

.. code-block:: bash

  export ARCH=$(case $(uname -m) in x86_64) echo -n amd64 ;; aarch64) echo -n arm64 ;; *) echo -n $(uname -m) ;; esac)
  export OS=$(uname | awk '{print tolower($0)}')

- Download the binary for your platform from the `Github releases <https://github.com/operator-framework/operator-sdk/releases/>`__. The latest version is 1.35.0:

.. code-block:: bash

  export OPERATOR_SDK_VERSION=v1.35.0
  export OPERATOR_SDK_DL_URL=https://github.com/operator-framework/operator-sdk/releases/download/${OPERATOR_SDK_VERSION}
  curl -LO ${OPERATOR_SDK_DL_URL}/operator-sdk_${OS}_${ARCH}

- Install the downloaded release binary in the PATH:

.. code-block:: bash

  chmod +x operator-sdk_${OS}_${ARCH} && sudo mv operator-sdk_${OS}_${ARCH} /usr/local/bin/operator-sdk


.. note::

  Run `make --help` for more information on all potential `make` targets


Run the Operator
----------------

1. Generate CRDs and other needed manifests

  .. code-block:: bash

    make manifests


2. Generate internal operator-sdk code

  .. code-block:: bash
    
    make generate


3. Install the CRDs into the cluster:

  .. code-block:: bash
  
    make install


4. Run the controller (this will run in the foreground, so switch to a new terminal if you want to leave it running):

  .. code-block:: bash
  
    make run


.. note::
   You can also run this in one step by running: `make install run`


5. Install example Instances of Custom Resources:

  .. code-block:: bash
  
    kubectl apply -f config/samples/


Generate and upload the Docker image
------------------------------------

1. Build and push your image to the location specified by `IMG`:

  .. code-block:: bash
  
    make docker-build docker-push IMG=<some-registry>/aeros-llo-docker:tag


To upload the image to the common deployments repo (Docker login is required):

  .. code-block:: bash
  
    make docker-build docker-push IMG=registry.gitlab.aeros-project.eu/aeros-public/common-deployments/llo/k8s-operator-sdk:1.0.1-mvp


2. Deploy the controller to the cluster with the image specified by `IMG`:

  .. code-block:: bash
  
    make deploy IMG=<some-registry>/aeros-llo-docker:tag


To deploy the image to the common deployments repo (Docker login is required):

  .. code-block:: bash
  
    make deploy IMG=registry.gitlab.aeros-project.eu/aeros-public/common-deployments/llo/docker:1.0.1-mvp

Uninstall the Operator
----------------------

First, undeploy the controller from the cluster:

  .. code-block:: bash
  
    make undeploy


Then, delete the CRDs from the cluster:

  .. code-block:: bash
  
    make uninstall

Authors
=======
Universitat Politècnica de València