##########################################
LLO K8s
##########################################
.. contents::
:local:
:depth: 1
Introduction
==============
K8s Operator developed using the `Operator SDK `__ toolkit for Infrastructure Elements that use Kubernetes as its container management framework.
Features
========
This project aims to follow the Kubernetes `Operator pattern `_.
It uses `Controllers `_,
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 `_.
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: urn:ngsi-ld:InfrastructureElement:continuum-cluster-worker-2
image: fiware/orion-ld:1.5.1
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 **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 `_. Therefore, you can install it just by running:
.. code-block:: bash
curl --header "PRIVATE-TOKEN: " https://gitlab.aeros-project.eu/api/v4/projects/65/packages/generic/llo/1.0.1/k8s-operator-sdk-deployment.yaml | kubectl apply -f -
Developer guide
===============
As previously mentioned, this K8s Operator has been developed using the `Go-based Operator `__ 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 `__, 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 `__. 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=/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.0.1-mvp
2. Deploy the controller to the cluster with the image specified by `IMG`:
.. code-block:: bash
make deploy IMG=/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.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