thin-edge.io container plugin to install, start, stop and monitor containers on a device. Cumulocity UI Plugin to monitor running containers in the UI.

The following thin-edge.io customization is included in the plugin.

The container monitoring requires a thin-edge.io feature (service monitoring) which is only available > 0.9.0. You can try the version by following the pre-release guide.

• A service called tedge-container-monitor. This provides the monitoring of the containers
• The following software management plugins which is called when installing and removing containers/container groups via Cumulocity IoT
  • container - Deploy a single container (docker run xxx equivalent)
  • container-group - Deploy one or more container as defined by a docker-compose.yaml file (docker compose up equivalent)

Note

Child device support does not make any sense with this plugin as it needs to install/remove/monitor containers running on the current device (where the container engine is running). Though I guess you could try modifying the DOCKER_HOST environment variable etc. Though PRs are welcome to extend/edit any of the features ;)

Technical summary

The following details the technical aspects of the plugin to get an idea what systems it supports.

The following linux package formats are provided on the releases page and also in the tedge-community repository:

Operating System	Repository link
Debian/Raspbian (deb)
Alpine Linux (apk)
RHEL/CentOS/Fedora (rpm)

The following features are supported by the plugin:

• Install/remove containers via the Cumulocity IoT software interface
• Install multiple containers as one group using a docker-compose.yaml file
• Monitor container states (e.g. up/down) via Cumulocity IoT Services (only supported from tedge >= 0.10.0)
• Download container images via Cumulocity IoT binaries if a URL is provided
• Support for multiple container engines (docker, podman, nerdctl)

Containers can be installed and removed via the Cumulocity IoT Software Management interface in the Device Management Application.

The software package is modeled so that each software name corresponds to one container instance. Upon installation of a software item, the container uses the version field as the source of the container image/tag which is used to create the container. The software package can include an optional url referring to an exported container image in the gzip (compressed tarball) format (e.g. the image that you get when running docker save <my_image> --output <my_image>.tar.gz).

The software package properties are also describe below:

A container-group is the name given to deploy a docker-compose.yaml file. A docker compose file allows use to deploy multiple containers/networks/volumes and allows you maximum control over how the container is started. This means you can create a complex setup of persisted volumes, isolated networks, and also facilitate communication between containers. Check out the docker compose documentation for more details on how to write your own service definition.

The software package properties are also describe below:

The container software management plugin can be configured with the following properties.

The configuration is managed from the following file, and an example of the contents are shown below.

File

/etc/tedge-container-plugin/env

Contents

# container sm-plugin settings
PRUNE_IMAGES=0
VALIDATE_TAR_CONTENTS=0
CONTAINER_RUN_OPTIONS="--cpus 1 --memory 64m"

The plugin also includes a service which monitors the running status of the containers and includes some runtime metrics such as memory, cpu and network io. Please note that access to the container monitoring might not be supported by your container engine. When in doubt, just manually do a docker stats and if the data is only showing zeros, then the plugin will also see zeros.

Checkout the TELEMETRY docs for details on what is included in the telemetry data.

The container software management plugin can be configured with the following properties.

The configuration is managed from the following file, and an example of the contents are shown below.

File

/etc/tedge-container-plugin/env

Contents

CONTAINER_CLI_OPTIONS="docker podman nerdctl"
CONTAINER_CLI=docker

# Interval in seconds
INTERVAL=60

# Enable/disable telemetry (1/0)
TELEMETRY=1

# Enable/disable meta info (1/0)
META_INFO=1

# Only used if tedge cli is not installed
MQTT_HOST=127.0.0.1
MQTT_PORT=1883

# Log levels: error, warn, info, debug, none
LOG_LEVEL=info
LOG_TIMESTAMPS=1

# Service type to be used for the containers and container groups
SERVICE_TYPE=container
GROUP_SERVICE_TYPE=container-group

Start

sudo systemctl start tedge-container-monitor

Stop

sudo systemctl stop tedge-container-monitor

Reload (configuration)

sudo systemctl reload tedge-container-monitor

Get Logs

sudo journalctl -u tedge-container-monitor -f

Start

sudo service tedge-container-monitor start

Stop

sudo service tedge-container-monitor stop

Reload (configuration)

sudo service tedge-container-monitor reload

Get Logs

tail -f /var/log/tedge-container-monitor.err

With the UI plugin, container monitoring can be added to the Cumulocity UI. The Ui plugin contains 3 components that add the following tabs to the UI:

The UI Plugin was developed for the Device Management application, but can also be added to the Cockpit if needed.

To use the UI-Plugin, download the tedge-container-plugin-ui.zip version that matches your Cumulocity UI version form the releases and upload it in the Cumulocity administration. Detailed instructions on how to install UI plugins can also be found here.

The tab will be enabled for all services of type container. Displays the container properties that are stored in the managed Object.

The tab will be enabled for all devices with a childAddition with serviceType=container. Lists all containers in a grid or list.The search can be used for the image name and the project id. The list can include/exclude the containers that are part of a container group.

The tab will be enabled for all devices with a childAddition with serviceType=container. Lists all containers that are part of a project. The filter/search can be used to search for project names or container images.

This section details everything you need to know about building the package yourself.

To build the linux packages use the following steps:

1. Checkout the project

2. Install nfpm

   Note Make sure you install it somewhere that is included in your PATH environment variable. Use which nfpm to check if your shell can find it after installation.

3. Build the packages

   ./ci/build.sh

   Ideally the SEMVER environment variable should be set to the git tag, however you can also use a manual version using:

   ./ci/build.sh 1.0.1

   The built packages are created under the ./dist folder.

To build the ui use the following steps:

1. Checkout the project

2. Install dependencies:

   npm install

3. (Optional) Run the UI locally. Add your tenant in the package.json file:

    "scripts": {
    "start": "c8ycli server -u https://{{add the url of your tenant here}} --shell devicemanagement",
    ...
    }

   Start the UI locally via:

   npm start

4. Build the Plugin

    npm run build

5. Deploy the Plugin

   npm run deploy