LLO Docker Controller

This component is the local controller that must be deployed in each Infrastructure Element that uses Docker as its container management framework to handle and execute the actions requested by the LLO Docker Operator, which is deployed in a K8s cluster.

It's important to highlight that without the installation of this component in a Docker IE, the aeriOS orchestration process cannot be performed.

The communications between the Controller (this component) and the LLO Docker (the K8s Operator) are performed through a NATS broker.

Developed using Go 1.22.5.

Architecture

Messages format

The messages exchanged among the aforedescribed components aim to follow the CloudEvents specification. In this case, the NATS Protocol Binding for CloudEvents is followed.

Configuration

The LLO Docker controller component must be configured through the use of a set of environment variables:

• APP_ENV: environment mode of the application (development or production).
• NATS_URL: URL to connect to the NATS broker. For instance: nats://192.168.250.236:4222
• LLO_ID: final part of ID of the LLO of type Docker that is in charge of the orchestration in this IE. This value must be obtained from Orion-LD before the installation of this component. For instance, if the entity ID is urn:ngsi-ld:LowLevelOrchestrator:CloudFerro:Docker, the value of this variable must be CloudFerro-Docker.
• IE_ID: final part (MAC address) of the ID of the IE (ID from its related NGSI-LD entity of type InfrastructureElement) in which is deployed the controller. This value must be obtained from Orion-LD before the installation of this component. For instance, if the entity ID is urn:ngsi-ld:InfrastructureElement:CloudFerro:2473d6a5a43b, the value of this variable must be 2473d6a5a43b.

Docker image

To build the image for the same CPU architecture of the developing/building machine:

docker build -t eclipseaerios/llo-docker-controller .

For being able to build multi-arch images, a compatible Docker builder must be used.

To build the multi-arch image:

docker buildx build --provenance=false --push --platform=<target-platforms> -t eclipseaerios/llo-docker-controller:<tag> .

To build the multi-arch image (for linux/arm64,linux/amd64 in this casse) and push it directly to the Common deployments repository, without storing it locally:

docker buildx build --provenance=false --push --platform=linux/arm64,linux/amd64 -t eclipseaerios/llo-docker-controller .

Deploy the LLO Docker controller

As a Go binary

1. Compile the application (see the developer guide for more details):

go build cmd

2. Give execution permissions to the binary:

chmod +x llo-docker-controller

3. Run the binary:

./llo-docker-controller

As a container: using Docker run

First, you have to check the group of the Docker Socket on the Host (you may need root permissions):

ls -l /var/run/docker.sock

This command will display an output like this:

srw-rw---- 1 root docker 0 Jan 23 11:12 /var/run/docker.sock

Then, take the obtained value of the group (docker in this case, which it's the default and most common group for the Docker Socket), and get the group ID:

getent group docker | cut -d: -f3

Finally, this module can be installed as a Docker container with this command:

docker run -d --name llo-docker-controller -v "/var/run/docker.sock":"/var/run/docker.sock" --group-add <group-ID> -e APP_ENV=production -e NATS_URL="nats://192.168.1.39:4222" -e LLO_ID=Cluster-Docker -e IE_ID=2473d6a5a43b eclipseaerios/llo-docker-controller

The group ID can also be obtained dynamically in the docker run command:

docker run -d --name llo-docker-controller -v "/var/run/docker.sock":"/var/run/docker.sock" --group-add $(getent group docker | cut -d: -f3) e NATS_URL="nats://192.168.1.39:4222" -e LLO_ID=Cluster-Docker -e IE_ID=2473d6a5a43b eclipseaerios/llo-docker-controller

As a container: using Docker compose

1. Obtain the group of the Docker socket following the above steps.
2. Install the Docker compose file:

DOCKER_GID=$(getent group <group-name> | cut -d: -f3) docker compose up -d

For instance:

DOCKER_GID=$(getent group docker | cut -d: -f3) docker compose up -d

Developer guide

Build the application

The LLO Docker controller component has been developed using Golang, so it can be packaged as a binary executable, which is ready to be run in the same OS in which the go build command has been executed:

go build

Golang has the advantage that applications can be easily packaged for different OS and CPU architecrtues (the complete list can be obtained by running go tool dist list), so in Linux you can run this command to compile the federator for different platforms:

env GOOS=<target-OS> GOARCH=<target-architecture> go build

For instance, in case of Linux running on a ARM64 machine:

env GOOS=linux GOARCH=arm64 go build

License

Copyright 2025 Eclipse aeriOS project.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.