##########################################
LLO K8s
##########################################

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


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

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 K8s Operator watches for a new *ServiceComponentK8s* (K8s Custom Resource) deployment in the K8s cluster and then deploys a K8s Deployment and a linked service 
in the same K8s cluster. When the *ServiceComponentK8s* is deleted, all the created K8s resources are also deleted.

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
=====================

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

.. code-block:: bash

  kubectl apply -f your-sck8s-cr.yaml


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

.. code-block:: yaml

  apiVersion: llo.aeros-project.eu/v1alpha1
  kind: ServiceComponentK8s
  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: continuum-cluster-worker-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: -mongocOnly
      - key: -wip
        value: entityMaps,distSubs
      - key: -disableFileLog
      - key: -noArrayReduction
      - key: -subordinateEndpoint
        value: http://192.168.1.25:1026/ngsi-ld/ex/v1
      - key: -socketService


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

.. code-block:: bash

  kubectl delete -f your-sck8s-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).

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.1.0/k8s-operator-sdk-deployment.yaml | kubectl apply -f -


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-k8s-operator-sdk: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.1.0


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

  .. code-block:: bash
  
    make deploy IMG=<some-registry>/aeros-llo-k8s-operator-sdk: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/k8s-operator-sdk:1.1.0


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