• 1: Getting started
• 1.1: Install Eclipse Kanto
• 1.2: Explore via Eclipse Hono
• 2: Concepts
• 2.1: AWS Connector
• 2.2: Container management
• 2.3: Software update
• 2.4: Update manager
• 2.5: Suite connector
• 2.6: Local digital twins
• 2.7: File upload
• 3: How-to guides
• 3.1: Update software
• 3.2: Upload files
• 3.3: Back up and restore files
• 3.4: Create and update the containers `Desired State`
• 3.5: Monitor system metrics
• 3.6: Verify signed container images
• 3.7: Offline explore edge device
• 3.8: Build Yocto Image for Raspberry Pi
• 4: References
• 4.1: Remote connectivity configuration
• 4.1.1: AWS Connector configuration
• 4.1.2: Azure Connector configuration
• 4.1.3: Suite connector configuration
• 4.1.4: Local digital twins configuration
• 4.2: Container management configuration
• 4.2.1: Manager configuration
• 4.2.2: Container configuration
• 4.2.3: API Reference
• 4.2.3.1: Container Factory API
• 4.2.3.2: Container API
• 4.2.3.3: Metrics API
• 4.2.3.4: Software Updatable API
• 4.2.4: Container configuration as Desired State component
• 4.3: Software Updatable
• 4.3.1: Software update configuration
• 4.3.2: Software Updatable API
• 4.4: File Upload
• 4.4.1: File upload configuration
• 4.4.2: File Upload API
• 4.5: File Backup
• 4.5.1: File backup configuration
• 4.5.2: File Backup API
• 4.6: System Metrics
• 4.6.1: System metrics configuration
• 4.6.2: System Metrics API
• 4.7: Update Manager
• 4.7.1: Update Manager API
• 4.7.2: Update manager configuration

1 - Getting started

1.1 - Install Eclipse Kanto

Before you begin

The containerd Debian package is required. You can install it manually or run:

curl -fsSL https://github.com/eclipse-kanto/kanto/raw/main/quickstart/install_ctrd.sh | sh

Install Eclipse Kanto

Choose the Eclipse Kanto Debian package for your target device architecture from the ones available at the project’s GitHub Releases page. Download and install it via executing the following (adjusted to your package name):

wget https://github.com/eclipse-kanto/kanto/releases/download/v1.0.0/kanto_1.0.0_linux_x86_64.deb && \
sudo apt install ./kanto_1.0.0_linux_x86_64.deb

Verify

It’s important to check if all the services provided by the Eclipse Kanto package are up and running successfully. You can quickly do that via executing:

systemctl status \
suite-connector.service \
container-management.service \
software-update.service \
file-upload.service \
file-backup.service \
system-metrics.service \
kanto-update-manager.service

All listed services must be in an active running state.

What’s next

Explore via Eclipse Hono

1.2 - Explore via Eclipse Hono

By following the steps below you will connect your first device to a publicly available Eclipse Hono sandbox using Eclipse Kanto. A couple of simple Eclipse Hono northbound business applications written in Python are provided to explore the capabilities for remotely managing and monitoring your edge device.

Before you begin

The location where the Python applications and utility shell scripts will run does not have to be your edge device as they communicate remotely with Eclipse Hono only. To run them, you need:

• Python 3 and pip3

• The quickstart applications and provisioning scripts

  You can execute the script below to download them automatically:

  mkdir quickstart && cd quickstart && \
  wget https://github.com/eclipse-kanto/kanto/raw/main/quickstart/hono_commands.py && \
  wget https://github.com/eclipse-kanto/kanto/raw/main/quickstart/hono_events.py && \
  wget https://github.com/eclipse-kanto/kanto/raw/main/quickstart/requirements.txt && \
  wget https://github.com/eclipse-kanto/kanto/raw/main/quickstart/hono_provisioning.sh
  

• OpenSSL and the following SSL and SASL related libraries: pkg-config, swig, libsasl2-dev, libsasl2-2 libsasl2-modules-gssapi-mit and libssl-dev, e.g.:

  sudo apt install openssl pkg-config swig libsasl2-dev libsasl2-2 libsasl2-modules-gssapi-mit libssl-dev
  

• Required Python dependencies to run the scripts

  You can install them by using the downloaded requirements.txt file via executing:

  pip3 install -r requirements.txt
  

Provision the Eclipse Hono tenant and device

In order to be able to connect your device to Eclipse Hono, you need to have a dedicated tenant and a device instance provisioned for it. Fill in the required empty environmental variables definitions in the hono_provisioning.sh, e.g.:

# The Hono tenant to be created
export TENANT=demo
# The identifier of the device on the tenant
# Note! It's important for the ID to follow the convention namespace:name (e.g. demo:device)
export DEVICE_ID=demo:device
# The authentication identifier of the device
export AUTH_ID=demo_device
# A password for the device to authenticate with
export PWD=secret

Run the provisioning script and you will have your Eclipse Hono tenant and device ready to be connected:

./hono_provisioning.sh

Configure Eclipse Kanto

Eclipse Kanto uses the /etc/suite-connector/config.json to acquire all the remote communication, identification and authentication data to establish the remote connection. Update it with the following:

{
  "caCert": "/etc/suite-connector/iothub.crt",
  "logFile": "/var/log/suite-connector/suite-connector.log",
  "address": "mqtts://hono.eclipseprojects.io:8883",
  "tenantId": "demo",
  "deviceId": "demo:device",
  "authId": "demo_device",
  "password": "secret"
}

Restart the Suite Connector service for the changes to take effect:

sudo systemctl restart suite-connector.service

Verify

To explore remote containerized applications management, we will use the two Python scripts to run, monitor and remove a simple InfluxDB container using its public container image available at Docker Hub.

First, start the monitoring application that requires the configured Eclipse Hono tenant (-t) and will print all received events triggered by the device:

python3 hono_events.py -t demo

In another terminal, we are ready to spin up an InfluxDB container instance at the edge via executing the second application that requires the command to execute (run), the Eclipse Hono tenant (-t), device identifier (-d) and the full container image reference to use (--img):

python3 hono_commands.py run -t demo -d demo:device --img docker.io/library/influxdb:1.8.4

After the script exits with success, you can check out the new container running on your edge device via executing:

sudo kanto-cm list

Looking at the terminal where the monitoring application is running, you will be able to see all the events triggered by the operation.

To remove the newly created container, execute the same application script only this time with the rm command and the identifier of the container to remove (--id), e.g.:

python3 hono_commands.py rm -t demo -d demo:device --id e6f7fbea-0e95-433c-acc7-16ef21b9c033

2 - Concepts

2.1 - AWS Connector

AWS Connector enables the remote connectivity to an AWS IoT cloud ecosystem. It provides the following use cases:

• Enriched remote connection
  • Optimized - to pass the messages via a single underlying connection
  • Secured - to protect the edge identity and data via TLS with basic and certificate-based authentication
  • Maintained - with a reconnect exponential backoff algorithm
  • Synchronized - on a connectivity recovering via a message buffering
• Application protection - AWS Connector is the only one component with a remote connectivity i.e. all local applications are protected from exposure to the public network
• Offline mode - local applications don’t need to care about the status of the remote connection, they can stay fully operable in offline mode
• Device Shadow - messages sent to the Twin Channel are converted to messages more suitable for AWS Device Shadow service and sent to it.

How it works

The AWS Connector plays a key role in two communication aspects - local and remote.

Cloud connectivity

To initiate its connection, the edge has to be manually or automatically provisioned. The result of this operation is different parameters and identifiers. Currently, AWS Connector supports MQTT transport as a connection-oriented and requiring less resources in comparison to AMQP. Once established, the connection is used as a channel to pass the edge telemetry and event messages. The IoT cloud can control the edge via commands and responses.

In case of a connection interruption, the AWS Connector will switch to offline mode. The message buffer mechanism will be activated to ensure that there is no data loss. Reconnect exponential backoff algorithm will be started to guarantee that no excessive load will be generated to the IoT cloud. All local applications are not affected and can continue to operate as normal. Once the remote connection is restored, all buffered messages will be sent and the edge will be fully restored to online mode.

Local communication

Ensuring that local applications are loosely coupled, Eclipse Hono™ MQTT definitions are in use. The event-driven local messages exchange is done via a MQTT message broker - Eclipse Mosquitto™. The AWS Connector takes the responsibility to forward these messages to the IoT cloud and vice versa.

Monitoring of the remote connection status is also enabled locally as well, along with details like the last known state of the connection, timestamp and a predefined connect/disconnect reason.

2.2 - Container management

Container management enables a lightweight standard runtime which is capable to run containerized applications with all advantages of the technology: isolation, portability and efficiency. The deployment and management are available both locally and remotely via an IoT cloud ecosystem of choice. The following use cases are provided:

• Standardized approach - with OCI (Open Container Initiative) compliant container images and runtime
• Lightweight runtime - with a default integration of containerd and a possibility for another container technology of choice like podman, LXC and more
• Isolation - with a default isolation from other containerized applications and the host system
• Portability - with an option to run one and the same containerized application on different platforms
• Pluggable architecture - with extension points on different levels

How it works

A container image packs the application executable along with all its needed dependencies into a single artifact that can be built by a tooling of choice. The built image is made available for usage by being pushed to a container image registry where the runtime can refer it to.

To create a new container instance, the container management uses such an image reference and a configuration for it to produce a fully functional container. The container lifecycle (start, update, stop, remove) and environment (memory constraints, restart policy, etc.) are also handled by the runtime. The container management continuously ensures the applications availability via state awareness and restart policies, provides monitoring via flexible logging and fine-grained resources management. All of that is achieved on top of an underlying runtime of choice (containerd by default) that takes care of the low-level isolation mechanisms.

2.3 - Software update

Software update enables the deployment and management of various software artifacts, both locally and remotely via an IoT cloud ecosystem of choice. It provides the following use cases:

• Robust download - with a retry and resume mechanism when the network connection is interrupted
• Artifact validation - with an integrity validation of every downloaded artifact
• Universal installation - with customizable install scripts to handle any kind of software
• Operation monitoring - with a status reporting of the download and install operations

How it works

When the install operation is received at the edge, the download process is initiated. Retrieving the artifacts will continue until they are stored at the edge or their size threshold is reached. If successful, the artifacts are validated for integrity and further processed by the configured script. It is responsible to apply the new software and finish the operation. A status report is announced on each step of the process enabling its transparent monitoring.

On start up, if there have been any ongoing operations, they will be automatically resumed as the operation state is persistently stored.

What’s next

How to update software

2.4 - Update manager

Update manager enables a lightweight core component which is capable to easily perform complex OTA update scenarios on a target device. The following capabilities are provided:

• Lightweight - consists of a single core component which orchestrates the update process
• Flexible deployment - supports different deployment models - natively, as an executable or container
• Unified API - all domain agents utilize a unified Update Agent API for interacting with the Update Manager
• MQTT Connectivity - the connectivity and communication between the Update Manager and domain agent is MQTT-based
• Multi-domain integration - easily integrates, scales and performs complex update operations across multiple domains
• Default update agents - integrates with the Kanto provided out-of-the box domain update agent implementation for deployment of container into the Kanto container management
• Pluggable architecture - provides an extensible model for plug-in custom orchestration logic
• Asynchronous updates - asynchronous and independent update process across the different domains
• Multi-staged updates - the update process is organized into different stages
• Configurable - offers a variety of configuration options for connectivity, supported domains, message reporting and etc

How it works

The update process is initiated by sending the desired state specification as an MQTT message towards the device, which is handled by the Update Manager component.

The desired state specification in the scope of the Update Manager is a JSON-based document, which consists of multiple component definitions per domain, representing the desired state to be applied on the target device. A component in the same context means a single, atomic and updatable unit, for example, OCI-compliant container, software application or firmware image.

Each domain agent is a separate and independent software component, which implements the Update Agent API for interaction with the Update Manager and manages the update logic for concrete domain. For example - container management.

The Update Manager, operating as a coordinator, is responsible for processing the desired state specification, distributing the split specification across the different domain agents, orchestrating the update process via MQTT-based commands, collecting and consolidating the feedback responses from the domain update agents, and reporting the final result of the update campaign to the backend.

As extra features and capabilities, the Update Manager enables reboot of the host after the update process is completed and reporting of the current state of the system to the backend.

2.5 - Suite connector

Suite connector enables the remote connectivity to an IoT cloud ecosystem of choice, powered by Eclipse Hono™ (e.g. Eclipse Cloud2Edge and Bosch IoT Suite). It provides the following use cases:

• Enriched remote connection
  • Optimized - to pass the messages via a single underlying connection
  • Secured - to protect the edge identity and data via TLS with basic and certificate-based authentication
  • Maintained - with a reconnect exponential backoff algorithm
  • Synchronized - on a connectivity recovering via a message buffering
• Application protection - suite connector is the only one component with a remote connectivity i.e. all local applications are protected from exposure to the public network
• Offline mode - local applications don’t need to care about the status of the remote connection, they can stay fully operable in offline mode

How it works

The suite connector plays a key role in two communication aspects - local and remote.

Cloud connectivity

To initiate its connection, the edge has to be manually or automatically provisioned. The result of this operation is different parameters and identifiers. Currently, suite connector supports MQTT transport as a connection-oriented and requiring less resources in comparison to AMQP. Once established, the connection is used as a channel to pass the edge telemetry and event messages. The IoT cloud can control the edge via commands and responses.

In case of a connection interruption, the suite connector will switch to offline mode. The message buffer mechanism will be activated to ensure that there is no data loss. Reconnect exponential backoff algorithm will be started to guarantee that no excessive load will be generated to the IoT cloud. All local applications are not affected and can continue to operate as normal. Once the remote connection is restored, all buffered messages will be sent and the edge will be fully restored to online mode.

Local communication

Ensuring that local applications are loosely coupled, Eclipse Hono™ MQTT definitions are in use. The event-driven local messages exchange is done via a MQTT message broker - Eclipse Mosquitto™. The suite connector takes the responsibility to forward these messages to the IoT cloud and vice versa.

The provisioning information used to establish the remote communication is available locally both on request via a predefined message and on update populated via an announcement. Applications that would like to extend the edge functionality can further use it in Eclipse Hono™ and Eclipse Ditto™ definitions.

Monitoring of the remote connection status is also enabled locally as well, along with details like the last known state of the connection, timestamp and a predefined connect/disconnect reason.

2.6 - Local digital twins

Local digital twins enables the digital twin state on a local level even in offline scenarios. It provides the following use cases:

• Mirrors the applications
• Persistency - digital twins are stored locally
• Cloud connectivity - provide connectivity to the cloud (similar to Suite connector)
• Offline scenarios - local applications stay fully operable as if the connection with the cloud is not interrupted Synchronization - when connection to the cloud is established the last known digital twin state is synchronized

How it works

Similar to the Suite connector service the local digital twins service needs to establish a connection to the cloud. To do this this the edge has to be manually or automatically provisioned. This connection is then used as a channel to pass the edge telemetry and event messages. Once a connection is established the device can be operated via commands.

To ensure that the digital twin state is available on a local level even in offline mode (no matter of the connection state) the local digital twins service persist all changes locally. Such capabilities were implemented to support offline scenarios and advanced edge computing involving synchronization with the cloud after disruptions or outages. The synchronization mechanisms were also designed in a way to significantly reduce data traffic, and efficiently prevent data loss due to long-lasting disruptions.

Upon reconnection, the local digital twins will notify the cloud of any changes during the offline mode and synchronize the digital twins state.

The synchronization works in both directions:

• Cloud -> Local digital twins - desired properties are updated if such changes are requested from the cloud.
• Local digital twins -> Cloud - local digital twins state is sent to the cloud (e.g. all current features, their reported properties values, and any removed features while there was no connection).

What’s next

How to receive offline the structure of your edge device.

2.7 - File upload

File upload enables sending of files to a backend storage of choice. It can be used both locally and remotely via a desired IoT cloud ecosystem. The following use cases are provided:

• Storage diversity - with ready to use integrations with Azure Blob Storage, Amazon S3 and standard HTTP upload
• Automatic uploads - with periodically triggered uploads at a specified interval in a given time frame
• Data integrity - with an option to calculate and send the integrity check required information
• Operation monitoring - with a status reporting of the upload operation

How it works

It’s not always possible to inline all the data into exchanged messages. For example, large log files or large diagnostic files cannot be sent as a telemetry message. In such scenarios, file upload can assist enabling massive amount of data to be stored to the backend storage.

There are different triggers which can initiate the upload operation: periodic or explicit. Once initiated, the request will be sent to the IoT cloud for confirmation or cancellation transferred back to the edge. If starting is confirmed, the files to upload will be selected according to the specified configuration, their integrity check information can be calculated and the transfer of the binary content will begin. A status report is announced on each step of the upload process enabling its transparent monitoring.

What’s next

How to upload files

3 - How-to guides

3.1 - Update software

By following the steps below you will install ahello Debian package via a publicly available Eclipse Hono sandbox using Eclipse Kanto. A couple of simple Eclipse Hono northbound business applications written in Python are provided to explore the capabilities for remotely installing and monitoring. On the edge side, a basic install_hello.sh script will be downloaded and executed.

Before you begin

To ensure that your edge device is capable to execute the steps in this guide, you need:

• Debian-based linux distribution and the apt command line tool

• If you don’t have an installed and running Eclipse Kanto, follow Install Eclipse Kanto

• If you don’t have a connected Eclipse Kanto to Eclipse Hono sandbox, follow Explore via Eclipse Hono

• The software update application

  Navigate to the quickstart folder where the resources from the Explore via Eclipse Hono guide are located and execute the following script:

  wget https://github.com/eclipse-kanto/kanto/raw/main/quickstart/hono_commands_su.py
  

• Executing hello in the terminal will return that the command is not found

Install Debian package

To explore the software management, we will use two Python scripts to install and monitor the hello Debian package. The location where the Python applications will run does not have to be your edge device as they communicate remotely with Eclipse Hono only.

First, start the monitoring application that requires the configured Eclipse Hono tenant (-t) and will print all received events triggered by the device:

python3 hono_events.py -t demo

In another terminal, we are ready to spin up a hello Debian package at the edge via executing the second application that requires the Eclipse Hono tenant (-t) and the device identifier (-d):

python3 hono_commands_su.py -t demo -d demo:device

Verify

You can check out that the new package is installed on your edge device via executing:

hello

The command now displays: Hello, world!

Clean up

The installed hello Debian package can be removed via executing:

sudo apt remove hello

3.2 - Upload files

By following the steps below you will upload an example log file to your HTTP file server via a publicly available Eclipse Hono sandbox using Eclipse Kanto. A simple Eclipse Hono northbound business application written in Python is provided to explore the capabilities for remotely uploading and monitoring.

Before you begin

To ensure that all steps in this guide can be executed, you need:

• servefile installed

  This is a small Python HTTP server used in the example to serve the uploads. It does not have to be running on your edge device but it has to be accessible from there. You can install it by executing:

  pip3 install servefile
  

• If you don’t have an installed and running Eclipse Kanto on your edge device, follow Install Eclipse Kanto

• If you don’t have a connected Eclipse Kanto to Eclipse Hono sandbox, follow Explore via Eclipse Hono

• The file upload application

  Navigate to the quickstart folder where the resources from the Explore via Eclipse Hono guide are located and execute the following script:

  wget https://github.com/eclipse-kanto/kanto/raw/main/quickstart/hono_commands_fu.py
  

Upload log file

By default, all files in /var/tmp/file-upload/ directory can be uploaded. For example, grab the suite connector log file and place it in the directory via executing:

mkdir -p /var/tmp/file-upload/ && sudo cp /var/log/suite-connector/suite-connector.log /var/tmp/file-upload/

Choose a directory where the log file will be uploaded, open a new terminal there and run servefile:

servefile -u .

To explore the file upload, we will use a Python script to request and monitor the operation. The location where the Python application will run does not have to be your edge device as it communicates remotely with Eclipse Hono only.

Now we are ready to request the log file upload from the edge via executing the application that requires the Eclipse Hono tenant (-t) and the device identifier (-d):

python3 hono_commands_fu.py -t demo -d demo:device

Verify

You can check out that the log file is on your HTTP file server by listing the content of servefile working directory.

Clean up

Stop servefile and clean up its working directory.

3.3 - Back up and restore files

By following the steps below you will back up a simple text file to an HTTP file server and then restore it back via a publicly available Eclipse Hono sandbox using Eclipse Kanto. A simple Eclipse Hono northbound business application written in Python is provided to explore the capabilities for remotely backing up and restoring files.

Before you begin

To ensure that all steps in this guide can be executed, you need:

• servefile installed

  This is a small Python HTTP server used in the example to serve the uploads and downloads. It does not have to be running on your edge device, but it has to be accessible from there. You can install it by executing:

  pip3 install servefile
  

• If you don’t have an installed and running Eclipse Kanto on your edge device, follow Install Eclipse Kanto

• If you don’t have a connected Eclipse Kanto to Eclipse Hono sandbox, follow Explore via Eclipse Hono

• The file backup and restore application

  Navigate to the quickstart folder where the resources from the Explore via Eclipse Hono guide are located and execute the following script:

  wget https://github.com/eclipse-kanto/kanto/raw/main/quickstart/hono_commands_fb.py
  

Back up

By default, all directories in /var/tmp/file-backup/ or the directory itself can be backed up. For this example, create a file data.txt which will be later backed up:

sudo mkdir -p /var/tmp/file-backup && sudo echo "This is the first line in the file!" >> /var/tmp/file-backup/data.txt

You can verify that the file was successfully created by executing the following command:

cat /var/tmp/file-backup/data.txt

This should produce This is the first line in the file! as an output.

Choose a directory where the text file will be uploaded, open a new terminal there and run servefile with the flag -u to enable a file upload:

servefile -u .

To explore the file backup, we will use a Python script to request and monitor the operation. The location where the Python application will run does not have to be your edge device as it communicates remotely with Eclipse Hono only.

Now we are ready to request the text file backup from the edge via executing the application that requires the command to execute (backup), Eclipse Hono tenant (-t), the device identifier (-d) and the host where the backup will be uploaded to:

python3 hono_commands_fb.py backup -t demo -d demo:device -h localhost

You can check out that the backup file data.zip is on your HTTP file server by listing the content of the servefile working directory.

Restore

To explore the restore capabilities you will first modify the data.txt file, and then you will restore it to the version before the changes by using the backup, that was created earlier.

You can modify the data.txt file with the following command:

sudo echo "This is the second line in the file!" >> /var/tmp/file-backup/data.txt

You can verify that the file was successfully updated by executing the following command:

cat /var/tmp/file-backup/data.txt

This output should be:

This is the first line in the file!
This is the second line in the file!

Navigate to the terminal where servefile was started and terminate it. Start it again with the flag -l to enable a file download:

servefile -l .

To explore the file restore, we will use a Python script to request and monitor the operation. The location where the Python application will run does not have to be your edge device as it communicates remotely with Eclipse Hono only.

Now we are ready to request the text file restore from the edge via executing the application that requires the command to execute (restore), Eclipse Hono tenant (-t), the device identifier (-d) and the host where the backup file will be downloaded from:

python3 hono_commands_fb.py restore -t demo -d demo:device -h localhost

Verify

You can check out that the original file is restored by executing the following command:

cat /var/tmp/file-backup/data.txt

This should produce This is the first line in the file! as an output.

Clean up

Stop servefile and clean up its working directory. Remove the data.txt file from the /var/tmp/file-backup directory.

3.4 - Create and update the containers `Desired State`

By following the steps below you will publish a simple Desired State specification via a publicly available Eclipse Hono sandbox and then the specification will be handled by the Eclipse Kanto Update Manager, which will trigger an OTA update on the edge device.

A simple monitoring application will track the progress and the status of the update process.

Before you begin

To ensure that all steps in this guide can be executed, you need:

• Debian-based linux distribution and the apt command line tool

• If you don’t have an installed and running Eclipse Kanto, follow Install Eclipse Kanto

• If you don’t have a connected Eclipse Kanto to Eclipse Hono sandbox, follow Explore via Eclipse Hono

• The update manager application

  Navigate to the quickstart folder where the resources from the Explore via Eclipse Hono guide are located and execute the following script:

  wget https://github.com/eclipse-kanto/kanto/raw/main/quickstart/hono_commands_um.py
  

• Enable the containers update agent service of the Container Management by adding the "update_agent": {"enable": true} property to the container-management service configuration (by default located at /etc/container-management/config.json) and restart the service:

  systemctl restart container-management
  

Publish the Desired State specification

First, start the monitoring application that requires the configured Eclipse Hono tenant (-t) and an optional filter parameter (-f). It will print all received feedback events triggered by the device:

python3 hono_events.py -t demo -f demo/device/things/live/messages/feedback

The starting point of the OTA update process is to publish the example Desired State specification:

python3 hono_commands_um.py -t demo -d demo:device -o apply

The Desired State specification in this case consists of single domain section definition for the containers domain and a three container components - influxdb, hello-world and alpine image.

Apply Desired State specification

The Update Manager receives the published Desired State to the local Mosquitto broker, splits the specification (in this case into single domain) and then distributes the processed specification to the domain agents which initiates the actual update process logic on the domain agents side.

The update process is organized into multiple phases, which are triggered by sending specific Desired State commands (DOWNLOAD/UPDATE/ACTIVATE).

In the example scenario, the three images for the three container components will be pulled (if not available in the cache locally), created as containers during the UPDATING phase and started in the ACTIVATING phase.

Monitor OTA update progress

During the OTA update, the progress can be tracked in the monitoring application fot the Desired State feedback messages, started in the prerequisite section above.

The Update Manager reports at a time interval of a second the status of the active update process. For example:

{
   "activityId":"e5c858cc-2057-41b0-bd5f-83aee0aad22e",
   "timestamp":1693201088401,
   "desiredStateFeedback":{
      "status":"RUNNING",
      "actions":[
         {
            "component":{
               "id":"containers:alpine",
               "version":"latest"
            },
            "status":"UPDATE_SUCCESS",
            "message":"New container instance is started."
         },
         {
            "component":{
               "id":"containers:hello-world",
               "version":"latest"
            },
            "status":"UPDATE_SUCCESS",
            "message":"New container instance is started."
         },
         {
            "component":{
               "id":"containers:influxdb",
               "version":"2.7.1"
            },
            "status":"UPDATING",
            "message":"New container created."
         }
      ]
   }
}

List containers

After the update process is completed, list the installed containers by executing the command kanto-cm list to verify if the Desired State is applied correctly.

The output of the command should display the info about the three containers, described in the Desired State specification. The influxdb is expected to be in RUNNING state and the other containers in status EXITED. For example :

ID                                    |Name         |Image                               |Status   |Finished At |Exit Code
|-------------------------------------|-------------|------------------------------------|----------------------|---------
7fe6b689-eb76-476d-a730-c2f422d6e8ea  |influxdb     |docker.io/library/influxdb:1.8.4    |Running  |            |0
c36523d7-8d17-4255-ae0c-37f11003f658  |hello-world  |docker.io/library/hello-world:latest|Exited   |            |0
9b99978b-2593-4736-bb52-7a07be4a7ed1  |alpine       |docker.io/library/alpine:latest     |Exited   |            |0

Update Desired State specification

To update the existing Desired State run the command below. The update changes affect two containers - alpine and influxdb. Being not present in the updated Desired State specification, the alpine container will be removed from the system. The influxdb will be updated to version 1.8.5. The last container - hello-world is not affected and any events will be not reported from the container update agent for this particular container.

python3 hono_commands_um.py -t demo -d demo:device -o update

List updated containers

After the update process of the existing Desired State is completed, list again the available containers to the verify the Desired State is updated correctly.

The output of the command should display the info about the two containers, described in the Desired State specification. The influxdb is expected to be updated with the version 1.8.5 and in RUNNING state and hello-world container to be status EXITED with version unchanged. The alpine container must be removed and not displayed.

ID                                    |Name         |Image                               |Status   |Finished At |Exit Code
|-------------------------------------|-------------|------------------------------------|----------------------|---------
7fe6b689-eb76-476d-a730-c2f422d6e8ea  |influxdb     |docker.io/library/influxdb:1.8.5    |Running  |            |0
c36523d7-8d17-4255-ae0c-37f11003f658  |hello-world  |docker.io/library/hello-world:latest|Exited   |            |0

Remove all containers

To remove all containers, publish an empty Desired State specification (with empty components section):

python3 hono_commands_um.py -t demo -d demo:device -o clean

As a final step, execute the command kanto-cm list to verify that the containers are actually removed from the Kanto container management. The expected output is No found containers..

3.5 - Monitor system metrics

By following the steps below you will be able to monitor the system metrics from your edge device via a publicly available Eclipse Hono sandbox using Eclipse Kanto. A simple Eclipse Hono northbound business application written in Python is provided to explore the capabilities for remotely monitoring the CPU and memory utilization.

Before you begin

To ensure that all steps in this guide can be executed, you need:

• Plotly and Dash installed

  Plotly is an open-source plotting library and Dash is a framework for building data application in Python. They are used in this example to run a simple HTTP server and visualize the incoming system metrics data in real time, and they do not have to be running on your edge device. You can install them by executing:

  pip3 install plotly dash
  

• If you don’t have an installed and running Eclipse Kanto on your edge device, follow Install Eclipse Kanto

• If you don’t have a connected Eclipse Kanto to Eclipse Hono sandbox, follow Explore via Eclipse Hono

• The system metrics application

  Navigate to the quickstart folder where the resources from the Explore via Eclipse Hono guide are located and execute the following script:

  wget https://github.com/eclipse-kanto/kanto/raw/main/quickstart/hono_commands_sm.py
  

Monitor system metrics

To explore the system metrics, we will use a Python script to request and monitor the CPU and memory utilization. The location where the Python application will run does not have to be your edge device as it communicates remotely with Eclipse Hono only.

Now we are ready to request the system metrics from the edge via executing the application that requires the Eclipse Hono tenant (-t) and the device identifier (-d):

python3 hono_commands_sm.py -t demo -d demo:device

Verify

You can check out that the CPU and memory utilization metrics are properly received and displayed by checking out the application dashboard (by default - http://127.0.0.1:8050).

3.6 - Verify signed container images

By following the steps below, you will sign a container image and push it to a local registry using anotation. Then a notation trust policy and the Kanto Container Management service will be configured in a way that running containers from the signed image via kanto-cm CLI will be successful, while running containers from unsigned images will fail.

Before you begin

To ensure that your edge device is capable to execute the steps in this guide, you need:

• If you don’t have an installed and running Eclipse Kanto, follow Install Eclipse Kanto
• Installed Notation CLI
• Installed and running Docker

Create an image and push it to a local registry using docker and than sign it with notation

Create and run a local container registry:

sudo kanto-cm create --ports 5000:5000 --e REGISTRY_STORAGE_DELETE_ENABLED=true --name registry docker.io/library/registry:latest
sudo kanto-cm start -n registry

Build a dummy hello world image and push it to the registry:

cat <<EOF | sudo docker build -t localhost:5000/dummy-hello:signed -
FROM busybox:latest
CMD [ "echo", "Hello World" ]
EOF
sudo docker push localhost:5000/dummy-hello:signed

export IMAGE=$(sudo docker inspect --format='{{index .RepoDigests 0}}' localhost:5000/dummy-hello:signed)
echo $IMAGE

Generate a key-pair with notation and add it as the default signing key:

notation cert generate-test --default "kanto"

Sign the image and store the signature in the registry:

notation sign $IMAGE

Configure notation truspolicy and container management verifier

Get the notation config directory and assign it to an environment variable to be used in the next steps of the guide:

export NOTATION_CONFIG=${XDG_CONFIG_HOME:-$HOME/.config}/notation
echo $NOTATION_CONFIG

Create a simple notation trustpolicy as a trustpolicy.json file in the notation config directory:

cat <<EOF | tee $NOTATION_CONFIG/trustpolicy.json
{
  "version": "1.0",
  "trustPolicies": [
    {
      "name": "kanto-images",
      "registryScopes": [ "*" ],
      "signatureVerification": {
        "level" : "strict"
      },
      "trustStores": [ "ca:kanto" ],
      "trustedIdentities": [ "*" ]
    }
  ]
}
EOF

Create a backup of the initial Kanto Container Management configuration that is found in /etc/container-management/config.json(the backup will be restored at the end of the guide):

sudo cp /etc/container-management/config.json /etc/container-management/config-backup.json

Configure the use of notation verifier, set its config directory, mark the local registry as an insecure one, and set the image expiry time to zero seconds, so the local cache of the images used in the how-to will be deleted upon container removal:

cat <<EOF | sudo tee /etc/container-management/config.json
{
  "log": {
    "log_file": "/var/log/container-management/container-management.log"
  },
  "containers": {
    "image_verifier_type": "notation",
    "image_verifier_config": {
      "configDir": "$NOTATION_CONFIG"
    },
    "insecure_registries": [ "localhost:5000" ],
    "image_expiry": "0s"
  }
}
EOF

Restart the Container Management service for the changes to take effect:

sudo systemctl restart container-management.service

Verify

Create and run a container from the signed image. The container prints Hello world to the console:

sudo kanto-cm create --name dummy-hello --rp no --t $IMAGE
sudo kanto-cm start --name dummy-hello --a

Make sure that a docker hub hello-world image is not cached locally, by removing any containers with this image, and verify that creating containers from it fails, as the image is not signed, and the signature verification fails:

sudo kanto-cm remove -f $(sudo kanto-cm list --quiet --filter image=docker.io/library/hello-world:latest)
sudo kanto-cm create --name dockerhub-hello --rp no --t docker.io/library/hello-world:latest

Clean up

Remove the created containers from the Kanto Container Management:

sudo kanto-cm remove -n dummy-hello
sudo kanto-cm remove -n registry -f

Restore the initial Kanto Container Management configuration and restart the service:

sudo mv -f /etc/container-management/config-backup.json /etc/container-management/config.json
sudo systemctl restart container-management.service

Remove the localy cached images from Docker:

sudo docker image rm localhost:5000/dummy-hello:signed registry:latest

Reset the notation configuration by removing the directory:

rm -r $NOTATION_CONFIG

Unset exported environment variables:

unset IMAGE NOTATION_CONFIG

3.7 - Offline explore edge device

By following the steps below, you will get the structure of the edge digital twins with all its features and properties using Eclipse Kanto. A simple Eclipse Hono northbound business application written in Python is provided to display the things’ and their features’ structure.

Before you begin

To ensure that your edge device is capable to execute the steps in this guide, you need:

• If you don’t have an installed and running Eclipse Kanto on your edge device, follow Install Eclipse Kanto

• If you don’t have a connected Eclipse Kanto to Eclipse Hono sandbox, follow Explore via Eclipse Hono

• Stop suite-connector.service. The local digital twins service is a replacement for the suite connector service, that is why either one of the services must be running.

  sudo systemctl stop suite-connector.service
  

• The offline explore application

  Navigate to the quickstart folder where the resources from the Explore via Eclipse Hono guide are located and execute the following script:

  wget https://github.com/eclipse-kanto/kanto/raw/main/quickstart/hono_commands_ldt.py
  

Configure Local digital twins

Open file /etc/suite-connector/config.json, copy tenantId, deviceId, authId and password.

{
    ...
    "tenantId": "demo",
    "deviceId": "demo:device",
    "authId": "demo_device",
    "password": "secret"
    ...
}

The local digital twins service uses the /etc/local-digital-twins/config.json to acquire all the remote communication, identification and authentication data to establish the remote connection. Update the configuration as shown below and replace tenantId, deviceId, authId and password with the settings that you copied in the previous step.

  {
    "logFile": "/var/log/local-digital-twins/local-digital-twins.log",
    "caCert": "/etc/local-digital-twins/iothub.crt",
    "thingsDb": "/var/lib/local-digital-twins/thing.db",
    "tenantId": "demo",
    "deviceId": "demo:device",
    "authId": "demo_device",
    "password": "secret"
  }

Save the configuration and start the local digital twins service using the following command:

sudo systemctl start local-digital-twins.service

Receive the structure of the edge device

Now we are ready to request the structure of the edge digital twins via executing the offline explore application that requires the local digital twins tenant (-t) and the device identifier (-d):

python3 hono_commands_ldt.py -t demo -d demo:device

Verify

On the shell there will be output of the structure of the edge digital twins with all its features and properties. Things with the following identifiers will be presented:

• demo:device
• demo:device:edge:containers

Clean up

Stop the local digital twins service and start suite connector service by executing:

sudo systemctl stop local-digital-twins.service && \
sudo systemctl restart suite-connector.service

3.8 - Build Yocto Image for Raspberry Pi

Building a Yocto Image for a Raspberry Pi involves several steps, including setting up the environment, download the necessary layers, configuring the build and compiling the image.

Before you begin

• Install the required packages required for the build on a Ubuntu/Debian system

  sudo apt-get update
  sudo apt install -y gawk wget git-core diffstat unzip texinfo gcc-multilib \
  build-essential chrpath socat cpio python3 python3-pip python3-pexpect \
  xz-utils debianutils iputils-ping libsdl1.2-dev xterm zstd liblz4-tool \
  

Clone the Yocto/Poky Repository

• Verify the Yocto Version of Kanto availabe in meta-kanto layer, https://github.com/eclipse-kanto/meta-kanto, this example provides information for kirkstone branch.

• Create a Source folder

  mkdir sources
  cd sources
  

• If it is kirkstone branch then, clone poky for kirkstone version in source directory

  git clone https://github.com/yoctoproject/poky.git
  cd poky
  git checkout kirkstone
  

  Note : Change branch based on meta-kanto layer.

Add Meta Layers to the source directory

• Based on the yocto version, clone the meta layers in the source directory meta-raspberrypi meta-openembedded meta-virtualization meta-lts-mixins

• Clone meta-raspberry pi layer to sources directory

  cd ..
  git clone git://git.yoctoproject.org/meta-raspberrypi
  cd meta-raspberrypi
  git checkout kirkstone
  

• Clone meta-openembedded layer to sources directory

  cd ..
  git clone https://github.com/openembedded/meta-openembedded.git
  cd meta-openembedded
  git checkout kirkstone
  

• Clone meta-virtualization layer to sources directory

  cd ..
  git clone https://git.yoctoproject.org/git/meta-virtualization
  cd meta-virtualization
  git checkout kirkstone
  

• Clone meta-lts-mixins layers to source directory

  cd ..
  git clone https://git.yoctoproject.org/git/meta-lts-mixins
  cd meta-lts-mixins
  git checkout kirkstone/go
  

  Note : The above layer is required to get the updated go version to be added in the yocto build, since kanto requires go version 1.19 and above.

Add meta-kanto layer to the sources directory

• Clone meta-kanto layer to the sources directory

  cd ..
  git clone https://github.com/eclipse-kanto/meta-kanto.git
  cd meta-kanto
  git checkout kirkstone
  

  Note : Make sure all the layers cloned are of same yocto version ( kirkstone in this case)

Create Build Directory

• After cloning all the required meta layers, move out of source directory to create build directory

  cd ../..
  source sources/poky/oe-init-build-env
  

• Run the below command to view the layers present in bblayers.conf file

  bitbake-layers show-layers
  

  Note : Resolve any dependendencies if occured while running bitbake command.

Configure bblayer.conf file

• By Default in the bblayer.conf file some of the layers will be added

• Add all the layers to the bblayers.conf file with below command

  bitbake-layers add-layer /home/path/to/meta/layer/directory
  

  The following layers should be added in the bblayer.conf file

  meta-raspberrypi
  meta-openembedded
  meta-virtualization
  meta-lts-mixins
  meta-openembedded/meta-oe
  meta-openembedded/meta-python
  meta-opemembedded/meta-networking
  meta-openembedded/meta-filesystems
  meta-kanto
  

• Example to add layers to bblayers.conf file

  while adding layers bitbake might have dependencies, add the dependent layers first. Example,

  To add meta-kanto layer to bblayer.conf file which is kept at /home/yocto/sources/meta-kanto

  bitbake-layers add-layers /home/yocto/sources/meta-kanto

• After adding all the required layers in bblayer.conf file, verify again by running the below command

  bitbake-layers show-layers
  

Configure local.conf file

• Open local.conf file which is placed at the below location in build directory

  vi conf/local.conf
  

• Change the machine variable in local.conf file to raspberry pi machine

  MACHINE ??= "raspberrypi4" 
  

  Note: Check the sources/meta-raspberrypi/conf/machine for the availabe machines for raspberry pi.

• Add required variables in local.conf file as shown and provided in the link below,

  https://github.com/eclipse-kanto/meta-kanto

    # Add the required DISTRO_FEATURES
    DISTRO_FEATURES:append = " virtualization systemd"
  
    # Configure the kernel modules required to be included
    MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-modules"
  
    # System initialization manager setup
    VIRTUAL-RUNTIME_init_manager = "systemd"
    DISTRO_FEATURES_BACKFILL_CONSIDERED = "sysvinit"
    VIRTUAL-RUNTIME_initscripts = "systemd-compat-units"
  
    # Add the Eclipse Kanto components
    IMAGE_INSTALL:append = " mosquitto"
    IMAGE_INSTALL:append = " suite-connector"
    IMAGE_INSTALL:append = " aws-connector"
    IMAGE_INSTALL:append = " azure-connector"
    IMAGE_INSTALL:append = " software-updates"
    IMAGE_INSTALL:append = " file-upload"
    IMAGE_INSTALL:append = " file-backup"
    IMAGE_INSTALL:append = " update-manager"
    IMAGE_INSTALL:append = " container-management"
    IMAGE_INSTALL:append = " local-digital-twins"
  

• Run bitbake `target-name’ availabe as shown below,

    Common targets are:
    core-image-minimal
    core-image-full-cmdline
    core-image-sato
    core-image-weston
    meta-toolchain
    meta-ide-support
  

  Note : If any build issues comes up, resolve the issue and run the bitbake `target-name’ command again for the build.

Final Build Image Repository Location

• After the successful build, the image will be availabe at the below location.

  build/tmp/deploy/images/`machine_name`/
  

Run & Test the image with QEMU (Quick Emulator)

• If RaspberryPi device is not availabe, the image can be run and tested on QEMU. Make the below changes to run on QEMU.

  In `build/conf/local.conf’ file

• Change the machine variable name to relevant qemu arch as shown below by changing the MACHINE varilabe from raspberrypi4 to ‘qemux86_64`

  # You need to select a specific machine to target the build with. There are a selection
  # of emulated machines available which can boot and run in the QEMU emulator:
  #
  #MACHINE ?= "qemuarm"
  #MACHINE ?= "qemuarm64"
  #MACHINE ?= "qemux86"
  #MACHINE ?= "qemux86-64"
  
  # This sets the default machine to be qemux86-64 if no other machine is selected:
  MACHINE ??= "qemuarm64"
  

• Run bitbake target-name command by sourcing the oe-init-build-env script

• In the same build directory run the below command to run qemu

   runqemu qemuarm64
  

  

  

• The above command will open a window which boots as “YOCTO PROJECT” and it enters to command line window. Enter login as `root’, and check for kanto components with the below commands.

  systemctl status \
  suite-connector.service \
  container-management.service \
  software-update.service \
  file-upload.service \
  file-backup.service \
  system-metrics.service \
  kanto-update-manager.service
  

  All listed services must be in an active running state.

  

Flash the image on Raspberry Pi

• The build image will be availabe at build/tmp/deploy/images/raspberrypi4/

• Identify the SD Card Device with the below command to find the device name of your SD card

  lsblk
  

• Flash the image to sd card

  sudo dd if=/path/to/image.wic of=/dev/sdX bs=4M status=progress
  

• Boot the Raspberry Pi,

  Insert the SD card into your Raspberry Pi and power it on. The Pi should boot from the Yocto image.Login to your device and run the below command to verify the kanto components.

  systemctl status \
  suite-connector.service \
  container-management.service \
  software-update.service \
  file-upload.service \
  file-backup.service \
  system-metrics.service \
  kanto-update-manager.service
  

4 - References

4.1 - Remote connectivity configuration

4.1.1 - AWS Connector configuration

Properties

To control all aspects of the aws connector behavior.

Example

The minimal required configuration to connect.

{
    "address": "tls://<AWS-endpoint-address>:8883",
    "caCert": "AmazonRootCA1.pem",
    "cert": "example-device.crt",
    "key": "example-device.key",
    "clientId": "org.eclipse.kanto:exampleDevice",
    "logFile": "/var/log/aws-connector/aws-connector.log"
}

Template

The configuration can be further adjusted according to the use case. The following template illustrates all possible properties with their default values.

{
    "topicFilter": "",
    "payloadFilters": [],
    "address": "",
    "tenantId": "default-tenant-id",
    "clientId": "",
    "alpn" : [],
    "caCert": "aws.crt",
    "cert": "",
    "key": "",
    "tpmDevice": "",
    "tpmHandle": 0,
    "tpmKeyPub": "",
    "tpmKey": "",
    "localAddress": "tcp://localhost:1883",
    "localUsername": "",
    "localPassword": "",
    "localCACert": "",
    "localCert": "",
    "localKey": "",
    "logFile": "logs/aws-connector.log",
    "logLevel": "INFO",
    "logFileCount": 5,
    "logFileMaxAge": 28,
    "logFileSize": 2
}

4.1.2 - Azure Connector configuration

Properties

To control all aspects of the azure connector behavior.

Example

The minimal required configuration to connect.

{
    "connectionString": "HostName=hostName.azure-devices.net;DeviceId=deviceId;SharedAccessKey=cGFzc3AvcKQ=",
    "caCert": "/etc/azure-connector/iothub.crt",
    "logFile": "/var/log/azure-connector/azure-connector.log"
}

Template

The configuration can be further adjusted according to the use case. The following template illustrates all possible properties with their default values.

{
    "tenantId": "defaultTenant",
    "connectionString": "",
    "sasTokenValidity": "1h",
    "idScope": "",
    "alpn" : [],
    "caCert": "iothub.crt",
    "cert": "",
    "key": "",
    "tpmDevice": "",
    "tpmHandle": 0,
    "tpmKeyPub": "",
    "tpmKey": "",
    "localAddress": "tcp://localhost:1883",
    "localUsername": "",
    "localPassword": "",
    "localCACert": "",
    "localCert": "",
    "localKey": "",
    "logFile": "logs/azure-connector.log",
    "logLevel": "INFO",
    "logFileCount": 5,
    "logFileMaxAge": 28,
    "logFileSize": 2
}

4.1.3 - Suite connector configuration

Properties

To control all aspects of the suite connector behavior.

Example

The minimal required configuration to connect the publicly available Eclipse Hono sandbox.

{
    "address": "hono.eclipseprojects.io:1883",
    "caCert": "/etc/suite-connector/iothub.crt",
    "tenantId": "org.eclipse.kanto",
    "deviceId": "org.eclipse.kanto:exampleDevice",
    "authId": "org.eclipse.kanto_example",
    "password": "secret",
    "logFile": "/var/log/suite-connector/suite-connector.log"
}

Template

The configuration can be further adjusted according to the use case. The following template illustrates all possible properties with their default values.

{
    "address": "mqtts://mqtt.bosch-iot-hub.com:8883",
    "deviceId": "",
    "authId": "",
    "tenantId": "",
    "username": "",
    "password": "",
    "clientId": "",
    "policyId": "",
    "generic": false,
    "alpn" : [],
    "caCert": "iothub.crt",
    "cert": "",
    "key": "",
    "deviceIdPattern": "",
    "tpmDevice": "",
    "tpmHandle": 0,
    "tpmKeyPub": "",
    "tpmKey": "",
    "localAddress": "tcp://localhost:1883",
    "localUsername": "",
    "localPassword": "",
    "localCACert": "",
    "localCert": "",
    "localKey": "",
    "logFile": "log/suite-connector.log",
    "logLevel": "INFO",
    "logFileCount": 5,
    "logFileMaxAge": 28,
    "logFileSize": 2
}

4.1.4 - Local digital twins configuration

Properties

To control all aspects of the local digital twins behavior.

Example

The minimal required configuration to enable the local digital twins and their synchronization with the publicly available Eclipse Hono sandbox.

{
    "address": "hono.eclipseprojects.io:1883",
    "caCert": "/etc/local-digital-twins/iothub.crt",
    "tenantId": "org.eclipse.kanto",
    "deviceId": "org.eclipse.kanto:exampleDevice",
    "authId": "org.eclipse.kanto_example",
    "password": "secret",
    "thingsDb": "/var/lib/local-digital-twins/thing.db",
    "logFile": "/var/log/local-digital-twins/local-digital-twins.log"
}

Template

The configuration can be further adjusted according to the use case. The following template illustrates all possible properties with their default values.

{
    "thingsDb": "things.db",
    "address": "mqtts://mqtt.bosch-iot-hub.com:8883",
    "deviceId": "",
    "authId": "",
    "tenantId": "",
    "password": "",
    "clientId": "",
    "policyId": "",
    "caCert": "iothub.crt",
    "cert": "",
    "key": "",
    "deviceIdPattern": "",
    "tpmDevice": "",
    "tpmHandle": 0,
    "tpmKeyPub": "",
    "tpmKey": "",
    "localAddress": "tcp://localhost:1883",
    "localUsername": "",
    "localPassword": "",
    "localCACert": "",
    "localCert": "",
    "localKey": "",
    "logFile": "log/local-digital-twins.log",
    "logLevel": "INFO",
    "logFileCount": 5,
    "logFileMaxAge": 28,
    "logFileSize": 2
}

4.2 - Container management configuration

4.2.1 - Manager configuration

Properties

To control all aspects of the container manager behavior.

Example

The minimal required configuration that sets a timeout period of 5 seconds for the managed containers to stop gracefully.

{
    "manager": {
        "default_ctrs_stop_timeout": 5
    },
    "log": {
        "log_file": "/var/log/container-management/container-management.log"
    }
}

Template

The configuration can be further adjusted according to the use case. The following template illustrates all possible properties with their default values.

{
    "manager": {
        "home_dir": "/var/lib/container-management",
        "exec_root_dir": "/var/run/container-management",
        "container_client_sid": "container-management.service.local.v1.service-containerd-client",
        "network_manager_sid": "container-management.service.local.v1.service-libnetwork-manager",
        "default_ctrs_stop_timeout": 30
    },
    "containers": {
        "default_ns": "kanto-cm",
        "address_path": "/run/containerd/containerd.sock",
        "exec_root_dir": "/var/run/container-management",
        "home_dir": "/var/lib/container-management",
        "image_dec_keys": [],
        "image_dec_recipients": [],
        "runc_runtime": "io.containerd.runc.v2",
        "image_expiry": "744h",
        "image_expiry_disable": false,
        "image_verifier_type": "notation",
        "image_verifier_config": {
            "configDir": "/home/user/.config/notation"
        },
        "lease_id": "kanto-cm.lease",
        "registry_configurations": {
            "": {
                "credentials": {
                    "user_id": "",
                    "password": ""
                },
                "transport": {
                    "root_ca": "",
                    "client_cert": "",
                    "client_key": ""
                }
            }
        },
        "insecure_registries": [
            "localhost"
        ]
    },
    "network": {
        "home_dir": "/var/lib/container-management",
        "exec_root_dir": "/var/run/container-management",
        "default_bridge": {
            "name": "kanto-cm0",
            "ip4": "",
            "fcidr4": "",
            "enable_ip6": false,
            "mtu": 1500,
            "icc": true,
            "ip_tables": true,
            "ip_forward": true,
            "ip_masq": true,
            "userland_proxy": false
        }
    },
    "grpc_server": {
        "protocol": "unix",
        "address_path": "/run/container-management/container-management.sock"
    },
    "things": {
        "enable": true,
        "home_dir": "/var/lib/container-management",
        "features": [
            "ContainerFactory",
            "SoftwareUpdatable",
            "Metrics"
        ],
    "update_agent": {
         "enable": true,
         "domain": "containers",
         "system_containers": [
             "my-core-container-that-is-auto-deployed-and-updatable-only-through-firmware-update"
         ],
         "verbose_inventory_report": false,
     },
     "connection": {
         "broker_url": "tcp://localhost:1883",
         "keep_alive": "20s",
         "disconnect_timeout": "250ms",
         "client_username": "",
         "client_password": "",
         "connect_timeout": "30s",
         "acknowledge_timeout": "15s",
         "subscribe_timeout": "15s",
         "unsubscribe_timeout": "5s",
         "transport": {
             "root_ca": "",
             "client_cert": "",
             "client_key": ""
         }
     },
    "log": {
        "log_file": "log/container-management.log",
        "log_level": "INFO",
        "log_file_count": 5,
        "log_file_size": 2,
        "log_file_max_age": 28,
        "syslog": false
    },
    "deployment": {
        "enable": true,
        "mode": "update",
        "home_dir": "/var/lib/container-management",
        "ctr_dir": "/etc/container-management/containers"
    }
}

4.2.2 - Container configuration

Properties

To control all aspects of the container instance behavior.

Example

The minimal required configuration to spin up an InfluxDB container instance.

{
  "image": {
    "name": "docker.io/library/influxdb:1.8.4"
  }
}

Template

The configuration can be further adjusted according to the use case. The following template illustrates all possible properties with their default values.

{
    "container_name": "",
    "image": {
        "name": "",
        "decrypt_config": {
            "keys": [],
            "recipients": []
        }
    },
    "domain_name": "",
    "host_name": "",
    "mount_points": [
        {
            "destination": "",
            "source": "",
            "propagation_mode": "rprivate"
        }
    ],
    "config": {
        "env": [],
        "cmd": []
    },
    "io_config": {
        "open_stdin": false,
        "tty": false
    },
    "host_config": {
        "devices": [
            {
                "path_on_host": "",
                "path_in_container": "",
                "cgroup_permissions": "rwm"
            }
        ],
        "network_mode": "bridge",
        "privileged": false,
        "extra_hosts": [],
        "extra_capabilities": [],
        "port_mappings": [
            {
                "proto": "tcp",
                "container_port": 0,
                "host_ip": "0.0.0.0",
                "host_port": 0,
                "host_port_end": 0
            }
        ],
        "resources": {
            "memory": "",
            "memory_reservation": "",
            "memory_swap": ""
        },
        "restart_policy": {
            "type": "unless-stopped",
            "maximum_retry_count": 0,
            "retry_timeout": 0
        },
        "log_config": {
            "driver_config": {
                "type": "json-file",
                "max_files": 2,
                "max_size": "100M",
                "root_dir": ""
            },
            "mode_config": {
                "mode": "blocking",
                "max_buffer_size": "1M"
            }
        }
    }
}

4.2.3 - API Reference

4.2.3.1 - Container Factory API

Create

Create a container from a single container image reference with an option to start it.

{
	"topic":"edge/device:edge:containers/things/live/messages/create",
	"headers":{
		"response-required":true,
		"content-type":"application/json",
		"correlation-id":"<UUID>"
	},
	"path":"/features/ContainerFactory/inbox/messages/create",
	"value":{
		"imageRef":"docker.io/library/hello-world:latest",
		"start":true
	}
}

{
	"topic":"edge/device:edge:containers/things/live/messages/create",
	"headers":{
		"content-type":"application/json",
		"correlation-id":"<UUID>"
	},
	"path":"/features/ContainerFactory/outbox/messages/create",
	"value":"<Container UUID>"
}

Create with config

Create a container with a specified container configuration.

{
	"topic":"edge/device:edge:containers/things/live/messages/createWithConfig",
	"headers":{
		"response-required":true,
		"content-type":"application/json",
		"correlation-id":"<UUID>"
	},
	"path":"/features/ContainerFactory/inbox/messages/createWithConfig",
	"value":{
		"imageRef":"docker.io/library/influxdb:1.8.4",
		"start":true,
		"config":{
			"domainName": "",
			"hostName": "",
			"env": [],
			"cmd": [],
			"privileged": false,
			"extraHosts": ["ctrhost:host_ip"],
			"extraCapabilities": [],
			"networkMode": "bridge",
			"openStdin": false,
			"tty": false,
			"mountPoints": [
				{
					"source": "",
					"destination": "",
					"propagationMode": "rprivate"
				}
			],
			"decryption": {
				"keys": [],
				"recipients": []
			},
			"devices": [
				{
					"pathOnHost": "",
					"pathInContainer": "",
					"cgroupPermissions": "rwm"
				}
			],
			"restartPolicy": {
				"type": "unless-stopped",
				"maxRetryCount": 0,
				"retryTimeout": 0
			},
			"portMappings":[
				{
					"proto": "tcp",
					"containerPort": 80,
					"hostIP": "0.0.0.0",
					"hostPort": 5000,
					"hostPortEnd": 5005,
				}
			],
			"log": {
				"type": "json-file",
				"maxFiles": 2,
				"maxSize": "100M",
				"rootDir": "",
				"mode": "blocking",
				"maxBufferSize": "1M"
			},
			"resources": {
				"memory": "",
				"memoryReservation": "",
				"memorySwap": ""
			},
		}
    }
}

{
	"topic":"edge/device:edge:containers/things/live/messages/createWithConfig",
	"headers":{
		"content-type":"application/json",
		"correlation-id":"<UUID>"
	},
	"path":"/features/ContainerFactory/outbox/messages/createWithConfig",
	"value":"<Container UUID>"
}

4.2.3.2 - Container API

Start

Start an existing container.

{
	"topic":"edge/device:edge:containers/things/live/messages/start",
	"headers":{
		"response-required":true,
		"content-type":"application/json",
		"correlation-id":"<UUID>"
	},
	"path":"/features/Container:<UUID>/inbox/messages/start",
	"value":{}
}

{
	"topic":"edge/device:edge:containers/things/live/messages/start",
	"headers":{
		"content-type":"application/json",
		"correlation-id":"<UUID>"
	},
	"path":"/features/Container:<UUID>/outbox/messages/start",
	"status": 204
}

Stop

Stop an existing and running container.

{
	"topic":"edge/device:edge:containers/things/live/messages/stop",
	"headers":{
		"response-required":true,
		"content-type":"application/json",
		"correlation-id":"<UUID>"
	},
	"path":"/features/Container:<UUID>/inbox/messages/stop",
	"value":{}
}

{
	"topic":"edge/device:edge:containers/things/live/messages/stop",
	"headers":{
		"content-type":"application/json",
		"correlation-id":"<UUID>"
	},
	"path":"/features/Container:<UUID>/outbox/messages/stop",
	"status":204
}

Stop with options

Stop an existing and running container with given options.

{
	"topic":"edge/device:edge:containers/things/live/messages/stopWithOptions",
	"headers":{
		"response-required":true,
		"content-type":"application/json",
		"correlation-id":"<UUID>"
	},
	"path":"/features/Container:<UUID>/inbox/messages/stopWithOptions",
	"value":{
		"signal":"SIGINT",
		"timeout": 30,
		"force": true
	}
}

{
	"topic":"edge/device:edge:containers/things/live/messages/stopWithOptions",
	"headers":{
		"content-type":"application/json",
		"correlation-id":"<UUID>"
	},
	"path":"/features/Container:<UUID>/outbox/messages/stopWithOptions",
	"status":204
}

Rename

Change the name of an existing container to the specified new name.

{
	"topic":"edge/device:edge:containers/things/live/messages/rename",
	"headers":{
		"response-required":true,
		"content-type":"application/json",
		"correlation-id":"<UUID>"
	},
	"path":"/features/Container:<UUID>/inbox/messages/rename",
	"value":"new_container_name"
}

{
	"topic":"edge/device:edge:containers/things/live/messages/rename",
	"headers":{
		"content-type":"application/json",
		"correlation-id":"<UUID>"
	},
	"path":"/features/Container:<UUID>/outbox/messages/rename",
	"status":204
}

Update

Update an existing container without recreating it. The provided configurations will be merged with the current one.

{
	"topic":"edge/device:edge:containers/things/live/messages/update",
	"headers":{
		"response-required":true,
		"content-type":"application/json",
		"correlation-id":"<UUID>"
	},
	"path":"/features/Container:<UUID>/inbox/messages/update",
	"value":{
		"restartPolicy":{
			"type":"on-failure",
			"maxRetryCount":3,
			"timeout":10
		},
		"resources":{
			"memory":"500M",
			"memoryReservation":"300M",
			"memorySwap":"1G",
		}
	}
}

{
	"topic":"edge/device:edge:containers/things/live/messages/update",
	"headers":{
		"content-type":"application/json",
		"correlation-id":"<UUID>"
	},
	"path":"/features/Container:<UUID>/outbox/messages/update",
	"status":204
}

Remove

Remove an existing container.

{
	"topic":"edge/device:edge:containers/things/live/messages/remove",
	"headers":{
		"response-required":true,
		"content-type":"application/json",
		"correlation-id":"<UUID>"
	},
	"path":"/features/Container:<UUID>/inbox/messages/remove",
	"value":true
}

{
	"topic":"edge/device:edge:containers/things/live/messages/remove",
	"headers":{
		"content-type":"application/json",
		"correlation-id":"<UUID>"
	},
	"path":"/features/Container:<UUID>/outbox/messages/remove",
	"status":204
}

4.2.3.3 - Metrics API

Request

Request to receive data from the container.

{
	"topic":"edge/device:edge:containers/things/live/messages/request",
	"headers":{
		"response-required":true,
		"content-type":"application/json",
		"correlation-id":"<UUID>"
	},
	"path":"/features/Metrics/inbox/messages/request",
	"value":{
		"filter":[
			{
				"id":null,
				"originator":"SYSTEM"
			}
		],
		"frequency":"2s"
	}
}

{
	"topic":"edge/device:edge:containers/things/live/messages/request",
	"headers":{
		"content-type":"application/json",
		"correlation-id":"<UUID>"
	},
	"path":"/features/Metrics/outbox/messages/request",
	"status": 204
}

Data

Metrics data from a container based on the frequency specified in the request.

{
	"topic":"edge/device:edge:containers/things/live/messages/data",
	"headers":{
		"content-type":"application/json",
	},
	"path":"/features/Metrics/outbox/messages/data",
	"value":{
		"snapshot":[
			{
				"originator":"Container:test",
				"measurements":[
					{
						"id":"memory.total",
						"value":10371616768
					},
					{
						"id":"memory.used",
						"value":1396736
					},
					{
						"id":"memory.utilization",
						"value":0.01346690714903206
					},
					{
						"id":"net.readBytes",
						"value":180
					},
					{
						"id":"net.writeBytes",
						"value":0
					},
					{
						"id":"pids",
						"value":6
					}
				]
			},
			{
				"originator":"Container:test2",
				"measurements":[
					{
						"id":"cpu.utilization",
						"value":8.751566666666667
					},
					{
						"id":"memory.total",
						"value":10371616768
					},
					{
						"id":"memory.used",
						"value":4759552
					},
					{
						"id":"memory.utilization",
						"value":0.04589016453717083
					},
					{
						"id":"io.readBytes",
						"value":0
					},
					{
						"id":"io.writeBytes",
						"value":4096
					},
					{
						"id":"net.readBytes",
						"value":610
					},
					{
						"id":"net.writeBytes",
						"value":202
					},
					{
						"id":"pids",
						"value":14
					}
				]
			}
		],
		"timestamp":1234567890
	}
}

4.2.3.4 - Software Updatable API

Install

You can install a specified list of containers (software modules).

{
	"topic":"edge/device:edge:containers/things/live/messages/install",
	"headers":{
		"response-required":true,
		"content-type":"application/json",
		"correlation-id":"<UUID>"
	},
	"path":"/features/SoftwareUpdatable/inbox/messages/install",
	"value":{
		"correlationId":"other_correlation_id",
		"forced":true,
		"softwareModules":[
			{
				"softwareModule":{
					"name":"influxdb",
					"version":"1.8.4"
				},
				"artifacts":[
					{
						"filename":"valid.json",
						"download":{
							"HTTPS":{
								"url":"https://raw.githubusercontent.com/eclipse-kanto/container-management/main/containerm/pkg/testutil/config/container/valid.json",
								"md5url":"https://raw.githubusercontent.com/eclipse-kanto/container-management/main/containerm/pkg/testutil/config/container/valid.json"
							}
						},
						"checksums":{
							"MD5":"8c5a0fa2c01e218262d672bf643652fd",
							"SHA1":"7539b451d818d94bcd97d401a5467b3e1c0b8981",
							"SHA256":"be8f5def8e6a61caab078be0995826ae65f5993b1a35c18ed6045c3db37c4a3a"
						},
						"size":100
					}
				]
			}
		]
	}
}

{
	"topic":"edge/device:edge:containers/things/live/messages/install",
	"headers":{
		"content-type":"application/json",
		"correlation-id":"<UUID>"
	},
	"path":"/features/SoftwareUpdatable/outbox/messages/install",
	"status": 204
}

Remove

Remove of an installed software module.

{
	"topic":"edge/device:edge:containers/things/live/messages/remove",
	"headers":{
		"response-required":true,
		"content-type":"application/json",
		"correlation-id":"<UUID>"
	},
	"path":"/features/SoftwareUpdatable/inbox/messages/remove",
	"value": {
		"correlationId":"other_correlation_id",
		"forced":true,
		"software":[
			{
				"name":"influxdb",
				"version":""
			}
		]
	}
}

{
	"topic":"edge/device:edge:containers/things/live/messages/remove",
	"headers":{
		"correlation-id":"<UUID>"
	},
	"path":"/features/SoftwareUpdatable/outbox/messages/remove",
	"status":204
}

4.2.4 - Container configuration as Desired State component

Domain Identifier

The default domain identifier for the Containers Update Agent is containers. This can be modified within the update agent section in the container management JSON config file.

Containers Update Agent Properties

To control the container update agent behavior through desired state specification. As defined in the Desired State Specification, all properties are of type string.

Container Properties

To control all aspects of the container instance behavior. As defined in the Desired State Specification, all properties are of type string.