LLO Docker
Introduction
K8s Operator developed using the Operator SDK toolkit for Infrastructure Elements use Docker 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 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
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:
kubectl apply -f your-scdocker-cr.yaml
This is an example of a ServiceComponentDocker:
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: urn:ngsi-ld:InfrastructureElement:docker-machine-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 ServiceComponentDocker in the K8s cluster:
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.
kubectl apply -f operator-deployment.yaml
You can also create these manifests by running the below command, but some modifications may be needed.
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:
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 -
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:
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:
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:
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
Generate CRDs and other needed manifests
make manifests
Generate internal operator-sdk code
make generate
Install the CRDs into the cluster:
make install
Run the controller (this will run in the foreground, so switch to a new terminal if you want to leave it running):
make run
Note
You can also run this in one step by running: make install run
Install example Instances of Custom Resources:
kubectl apply -f config/samples/
Generate and upload the Docker image
Build and push your image to the location specified by IMG:
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):
make docker-build docker-push IMG=registry.gitlab.aeros-project.eu/aeros-public/common-deployments/llo/k8s-operator-sdk:1.0.1-mvp
Deploy the controller to the cluster with the image specified by IMG:
make deploy IMG=<some-registry>/aeros-llo-docker:tag
To deploy the image to the common deployments repo (Docker login is required):
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:
make undeploy
Then, delete the CRDs from the cluster:
make uninstall