This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

API Reference

API Reference for the Container Management Things service.

1: Container Factory API
2: Container API
3: Metrics API
4: Software Updatable API

1 - Container Factory API

The container factory service provides the ability to create new containers form a container image, or from a container configuration.

Create

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

Request

Hono Command: command//<name>:<namespace>:edge:containers/req//create

Ditto Message:

Name Value Description
topic <name>/<namespace>:edge:containers/things/live/messages/create Information about the affected Thing and the type of operation
path /features/ContainerFactory/inbox/messages/create A path to the ContainerFactory Feature, it’s message channel, and command
Headers Additional headers
response-required true/false If response is required
content-type application/json The content type
correlation-id container UUID The container UUID
Value
imageRef URL Fully qualified image reference, that follows the OCI Image Specification, the format is: host[:port]/[namespace/]name:tag
start true/false Start or only create the container

Name	Value	Description
topic	`<name>/<namespace>:edge:containers/things/live/messages/create`	Information about the affected Thing and the type of operation
path	`/features/ContainerFactory/inbox/messages/create`	A path to the `ContainerFactory` Feature, it’s message channel, and command
Headers		Additional headers
response-required	true/false	If response is required
content-type	`application/json`	The content type
correlation-id	container UUID	The container UUID
Value
imageRef	URL	Fully qualified image reference, that follows the OCI Image Specification, the format is: `host[:port]/[namespace/]name:tag`
start	true/false	Start or only create the container

Example : Create and automatically start a new Hello World container.

Topic: command//edge:device:edge:containers/req//create

{
	"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
	}
}

Response

Hono Command : command//<name>:<namespace>:edge:containers/res//create

Ditto Message:

Name Value Description
topic <name>/<namespace>:edge:containers/things/live/messages/create Information about the affected Thing and the type of operation
path /features/ContainerFactory/outbox/messages/create A path to the Feature, it’s message channel, and command
Headers Additional headers
content-type application/json The content type
correlation-id <UUID> The same correlation id as the request message
Value UUID of the created container

Name	Value	Description
topic	`<name>/<namespace>:edge:containers/things/live/messages/create`	Information about the affected Thing and the type of operation
path	`/features/ContainerFactory/outbox/messages/create`	A path to the Feature, it’s message channel, and command
Headers		Additional headers
content-type	application/json	The content type
correlation-id	<UUID>	The same correlation id as the request message
Value		UUID of the created container

Example : Response of a create operation.

Topic: `command//edge:device:edge:containers/res//create``

{
	"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.

Request

Hono Command: command//<name>:<namespace>:edge:containers/req//createWithConfig

Ditto Message:

Name Value Description
topic <name>/<namespace>:edge:containers/things/live/messages/createWithConfig Information about the affected Thing and the type of operation
path /features/ContainerFactory/inbox/messages/createWithConfig A path to the ContainerFactory Feature, it’s message channel, and command
Headers Additional headers
response-required true/false If response is required
content-type application/json The content type
correlation-id container UUID The container UUID
Value
imageRef URL Fully qualified image reference, that follows the OCI Image Specification, the format is: host[:port]/[namespace/]name:tag
start true/false Force to start created container
config json presentation of the configuration
domainName Domain name inside the container, if omitted the container’s domain name will be set to a system-defined value
hostName Host name for the container, if omitted the container’s hostname will be set to a system-defined value
env An array of environment variables that are set into the container
cmd An array of command with arguments that is executed upon the container’s start
privileged false Grant root capabilities to all devices on the host system
extraHosts An array of additional extra host names to IP address mappings added to the container network configuration, the format is: hostname:ip. If the IP of the host machine is to be added to the container’s hosts file the reserved host_ip[] must be provided. If only host_ip (the network-interface part is skipped) is used, by default it will be resolved to the host’s IP on the default bridge network interface for containerm (the default configuration is kanto-cm0) and add it to the container’s hosts file. If the IP of a container in the same bridge network is to be added to the hosts file the reserved container<container-host_name> must be provided.
extraCapabilities An array of additional capabilities for a container
networkMode The container’s networking capabilities type based on the desired communication mode. The possible options are: bridge or host
openStdin true/false Open the terminal’s standard input for an interaction with the current container
tty true/false Attach standard streams to a TTY
mountPoints An array of the mount points
source Path to the file or directory on the host that is referred from within the container
destination Path to the file or directory that is mounted inside the container
propagationMode Bind propagation for the mount, supported are: rprivate, private, rshared, shared, rslave or slave
decryption
keys A string array of private keys (GPG private key ring, JWE or PKCS7) used for decrypting the container’s image, the format is: filepath_private_key[:password]
recipients A string array of recipients (only for PKCS7 and must be an x509) used for decrypting the container’s image, the format is: pkcs7:filepath_x509_certificate
devices An array of accessible devices from the host
pathOnHost Path to the device on the host
pathInContainer Path to the device in the container
cgroupPermissions rwm Cgroup permissions for the device access, possible options are: r(read), w(write), m(mknod) and all combinations are possible
restartPolicy The container restart policy
type unless-stopped The container’s restart policy, the supported types are: always, no, on-failure and unless-stopped
maxRetryCount Maximum number of retries that are made to restart the container on exit with fail, if the type is on-failure
retryTimeout Timeout period in seconds for each retry that is made to restart the container on exit with fail, if the type is on-failure
portMappings An array of port mappings from the host to a container
proto tcp Protocol used for the port mapping from the container to the host, the possible options are: tcp and udp
containerPort Port number on the container that is mapped to the host port
hostIP 0.0.0.0 Host IP address
hostPort Beginning of the host ports range
hostPortEnd <host_port> Ending of the host ports range
log
type json-file Type in which the logs are produced, the possible options are: json-file or none
maxFiles 2 Maximum log files before getting rotated
maxSize 100M Maximum log file size before getting rotated as a number with a unit suffix of B, K, M and G
rootDir <meta_path>/containers/<container_id> Root directory where the container’s log messages are stored
mode blocking Messaging delivery mode from the container to the log driver, the supported modes are: blocking and non-blocking
maxBufferSize 1M Maximum size of the buffered container’s log messages in a non-blocking mode as a number with a unit suffix of B, K, M and G
resources
memory Hard memory limitation of the container as a number with a unit suffix of B, K, M and G, the minimum allowed value is 3M
memoryReservation Soft memory limitation of the container as a number with a unit suffix of B, K, M and G, if memory is specified, the memoryReservation must be smaller than it
memorySwap Total amount of memory and swap that the container can use as a number with a unit suffix of B, K, M and G, use -1 to allow the container to use unlimited swap

Name	Value	Description
topic	`<name>/<namespace>:edge:containers/things/live/messages/createWithConfig`	Information about the affected Thing and the type of operation
path	`/features/ContainerFactory/inbox/messages/createWithConfig`	A path to the `ContainerFactory` Feature, it’s message channel, and command
Headers		Additional headers
response-required	true/false	If response is required
content-type	`application/json`	The content type
correlation-id	container UUID	The container UUID
Value
imageRef	URL	Fully qualified image reference, that follows the OCI Image Specification, the format is: `host[:port]/[namespace/]name:tag`
start	true/false	Force to start created container
config		json presentation of the configuration
domainName		Domain name inside the container, if omitted the container’s domain name will be set to a system-defined value
hostName		Host name for the container, if omitted the container’s hostname will be set to a system-defined value
env		An array of environment variables that are set into the container
cmd		An array of command with arguments that is executed upon the container’s start
privileged	false	Grant root capabilities to all devices on the host system
extraHosts		An array of additional extra host names to IP address mappings added to the container network configuration, the format is: hostname:ip. If the IP of the host machine is to be added to the container’s hosts file the reserved host_ip[] must be provided. If only host_ip (the network-interface part is skipped) is used, by default it will be resolved to the host’s IP on the default bridge network interface for containerm (the default configuration is kanto-cm0) and add it to the container’s hosts file. If the IP of a container in the same bridge network is to be added to the hosts file the reserved container<container-host_name> must be provided.
extraCapabilities		An array of additional capabilities for a container
networkMode		The container’s networking capabilities type based on the desired communication mode. The possible options are: bridge or host
openStdin	true/false	Open the terminal’s standard input for an interaction with the current container
tty	true/false	Attach standard streams to a TTY
mountPoints		An array of the mount points
source		Path to the file or directory on the host that is referred from within the container
destination		Path to the file or directory that is mounted inside the container
propagationMode		Bind propagation for the mount, supported are: rprivate, private, rshared, shared, rslave or slave
decryption
keys		A string array of private keys (GPG private key ring, JWE or PKCS7) used for decrypting the container’s image, the format is: `filepath_private_key[:password]`
recipients		A string array of recipients (only for PKCS7 and must be an x509) used for decrypting the container’s image, the format is: `pkcs7:filepath_x509_certificate`
devices		An array of accessible devices from the host
pathOnHost		Path to the device on the host
pathInContainer		Path to the device in the container
cgroupPermissions	rwm	Cgroup permissions for the device access, possible options are: r(read), w(write), m(mknod) and all combinations are possible
restartPolicy		The container restart policy
type	unless-stopped	The container’s restart policy, the supported types are: always, no, on-failure and unless-stopped
maxRetryCount		Maximum number of retries that are made to restart the container on exit with fail, if the `type` is on-failure
retryTimeout		Timeout period in seconds for each retry that is made to restart the container on exit with fail, if the `type` is on-failure
portMappings		An array of port mappings from the host to a container
proto	tcp	Protocol used for the port mapping from the container to the host, the possible options are: tcp and udp
containerPort		Port number on the container that is mapped to the host port
hostIP	0.0.0.0	Host IP address
hostPort		Beginning of the host ports range
hostPortEnd	<host_port>	Ending of the host ports range
log
type	json-file	Type in which the logs are produced, the possible options are: json-file or none
maxFiles	2	Maximum log files before getting rotated
maxSize	100M	Maximum log file size before getting rotated as a number with a unit suffix of B, K, M and G
rootDir	<meta_path>/containers/<container_id>	Root directory where the container’s log messages are stored
mode	blocking	Messaging delivery mode from the container to the log driver, the supported modes are: blocking and non-blocking
maxBufferSize	1M	Maximum size of the buffered container’s log messages in a non-blocking mode as a number with a unit suffix of B, K, M and G
resources
memory		Hard memory limitation of the container as a number with a unit suffix of B, K, M and G, the minimum allowed value is 3M
memoryReservation		Soft memory limitation of the container as a number with a unit suffix of B, K, M and G, if `memory` is specified, the `memoryReservation` must be smaller than it
memorySwap		Total amount of memory and swap that the container can use as a number with a unit suffix of B, K, M and G, use -1 to allow the container to use unlimited swap

Example : Create and automatically start a new Hello World container.

Topic: command//edge:device:edge:containers/req//createWithConfig

{
	"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": ""
			},
		}
    }
}

Response

Hono Command : command//<name>:<namespace>:edge:containers/res//createWithConfig

Ditto Message:

Name Value Description
topic <name>/<namespace>:edge:containers/things/live/messages/createWithConfig Information about the affected Thing and the type of operation
path /features/ContainerFactory/outbox/messages/createWithConfig A path to the ContainerFactory Feature, it’s message channel, and command
Headers Additional headers
content-type application/json The content type
correlation-id <UUID>
Value UUID of the created container

Name	Value	Description
topic	`<name>/<namespace>:edge:containers/things/live/messages/createWithConfig`	Information about the affected Thing and the type of operation
path	`/features/ContainerFactory/outbox/messages/createWithConfig`	A path to the `ContainerFactory` Feature, it’s message channel, and command
Headers		Additional headers
content-type	`application/json`	The content type
correlation-id	<UUID>
Value		UUID of the created container

Example : Response of a createWithConfig operation.

Topic: command//edge:device:edge:containers/res//createWithConfig

{
	"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>"
}

2 - Container API

The container service offers a comprehensive range of operations for managing existing containers. Users can effortlessly start, pause, resume or stop, containers with specific configurations. Additionally, they have the flexibility to rename, update, or remove containers as needed.

Start

Start an existing container.

Request

Hono Command: command//<name>:<namespace>:edge:containers/req//start

Ditto Message:

Name Value Description
topic <name>/<namespace>:edge:containers/things/live/messages/start Information about the affected Thing and the type of operation
path /features/Container:<UUID>/inbox/messages/start A path to the Container Feature, it’s message channel, and start command
Headers Additional headers
response-required true/false If response is required
content-type application/json The content type
correlation-id container UUID The container UUID
Value

Name	Value	Description
topic	`<name>/<namespace>:edge:containers/things/live/messages/start`	Information about the affected Thing and the type of operation
path	`/features/Container:<UUID>/inbox/messages/start`	A path to the `Container` Feature, it’s message channel, and `start` command
Headers		Additional headers
response-required	true/false	If response is required
content-type	`application/json`	The content type
correlation-id	container UUID	The container UUID
Value

Example : Start an existing container.

Topic: command//edge:device:edge:containers/req//start

{
	"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":{}
}

Response

Hono Command : command//<name>:<namespace>:edge:containers/res//start

Ditto Message:

Name Value Description
topic <name>/<namespace>:edge:containers/things/live/messages/start Information about the affected Thing and the type of operation
path /features/Container:<UUID>/outbox/messages/start A path to the Container Feature, it’s message channel, and start command
Headers Additional headers
content-type application/json The content type
correlation-id <UUID> The same correlation id as the request message
Status Status of the operation start over the container

Name	Value	Description
topic	`<name>/<namespace>:edge:containers/things/live/messages/start`	Information about the affected Thing and the type of operation
path	`/features/Container:<UUID>/outbox/messages/start`	A path to the `Container` Feature, it’s message channel, and `start` command
Headers		Additional headers
content-type	`application/json`	The content type
correlation-id	<UUID>	The same correlation id as the request message
Status		Status of the operation start over the container

Example : Response of a successful start operation.

Topic: `command//edge:device:edge:containers/res//start``

{
	"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.

Request

Hono Command: command//<name>:<namespace>:edge:containers/req//stop

Ditto Message:

Name Value Description
topic <name>/<namespace>:edge:containers/things/live/messages/stop Information about the affected Thing and the type of operation
path /features/Container:<UUID>/inbox/messages/stop A path to the Container Feature, it’s message channel, and stop command
Headers Additional headers
response-required true/false If response is required
content-type application/json The content type
correlation-id container UUID The container UUID
Value

Name	Value	Description
topic	`<name>/<namespace>:edge:containers/things/live/messages/stop`	Information about the affected Thing and the type of operation
path	`/features/Container:<UUID>/inbox/messages/stop`	A path to the `Container` Feature, it’s message channel, and `stop` command
Headers		Additional headers
response-required	true/false	If response is required
content-type	`application/json`	The content type
correlation-id	container UUID	The container UUID
Value

Example : Stop an existing and running container.

Topic: command//edge:device:edge:containers/req//stop

{
	"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":{}
}

Response

Hono Command : command//<name>:<namespace>:edge:containers/res//stop

Ditto Message:

Name Value Description
topic <name>/<namespace>:edge:containers/things/live/messages/stop Information about the affected Thing and the type of operation
path /features/Container:<UUID>/outbox/messages/stop A path to the Container Feature, it’s message channel, and stop command
Headers Additional headers
content-type application/json The content type
correlation-id <UUID> The same correlation id as the request message
Status Status of the operation stop over the container

Name	Value	Description
topic	`<name>/<namespace>:edge:containers/things/live/messages/stop`	Information about the affected Thing and the type of operation
path	`/features/Container:<UUID>/outbox/messages/stop`	A path to the `Container` Feature, it’s message channel, and `stop` command
Headers		Additional headers
content-type	`application/json`	The content type
correlation-id	<UUID>	The same correlation id as the request message
Status		Status of the operation stop over the container

Example : Response of a successful stop operation.

Topic: `command//edge:device:edge:containers/res//stop``

{
	"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.

Request

Hono Command: command//<name>:<namespace>:edge:containers/req//stopWithOptions

Ditto Message:

Name Value Description
topic <name>/<namespace>:edge:containers/things/live/messages/stopWithOptions Information about the affected Thing and the type of operation
path /features/Container:<UUID>/inbox/messages/stopWithOptions A path to the Container Feature, it’s message channel, and stopWithOptions command
Headers Additional headers
response-required true/false If response is required
content-type application/json The content type
correlation-id container UUID The container UUID
Value
signal SIGTERM Stop a container using a specific signal. Signals could be specified by using their names or numbers, e.g. SIGINT or 2
timeout -1 « 63 // -9223372036854775808 Sets the timeout period in seconds to gracefully stop the container. When timeout expires the container process would be forcibly killed
force true/false Whether to send a SIGKILL signal to the container’s process if it does not finish within the timeout specified

Name	Value	Description
topic	`<name>/<namespace>:edge:containers/things/live/messages/stopWithOptions`	Information about the affected Thing and the type of operation
path	`/features/Container:<UUID>/inbox/messages/stopWithOptions`	A path to the `Container` Feature, it’s message channel, and `stopWithOptions` command
Headers		Additional headers
response-required	true/false	If response is required
content-type	`application/json`	The content type
correlation-id	container UUID	The container UUID
Value
signal	`SIGTERM`	Stop a container using a specific signal. Signals could be specified by using their names or numbers, e.g. `SIGINT` or 2
timeout	-1 « 63 // -9223372036854775808	Sets the timeout period in seconds to gracefully stop the container. When timeout expires the container process would be forcibly killed
force	true/false	Whether to send a SIGKILL signal to the container’s process if it does not finish within the timeout specified

Example : Stop an existing and running container with specified options.

Topic: command//edge:device:edge:containers/req//stopWithOptions

{
	"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
	}
}

Response

Hono Command : command//<name>:<namespace>:edge:containers/res//stopWithOptions

Ditto Message:

Name Value Description
topic <name>/<namespace>:edge:containers/things/live/messages/stopWithOptions Information about the affected Thing and the type of operation
path /features/Container:<UUID>/outbox/messages/stopWithOptions A path to the Container Feature, it’s message channel, and stopWithOptions command
Headers Additional headers
content-type application/json The content type
correlation-id <UUID> The same correlation id as the request message
Status Status of the operation stop with options over the container

Name	Value	Description
topic	`<name>/<namespace>:edge:containers/things/live/messages/stopWithOptions`	Information about the affected Thing and the type of operation
path	`/features/Container:<UUID>/outbox/messages/stopWithOptions`	A path to the `Container` Feature, it’s message channel, and `stopWithOptions` command
Headers		Additional headers
content-type	`application/json`	The content type
correlation-id	<UUID>	The same correlation id as the request message
Status		Status of the operation stop with options over the container

Example : Response of a successful the stopWithOptions operation.

Topic: `command//edge:device:edge:containers/res//stopWithOptions``

{
	"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.

Request

Hono Command: command//<name>:<namespace>:edge:containers/req//rename

Ditto Message:

Name Value Description
topic <name>/<namespace>:edge:containers/things/live/messages/rename Information about the affected Thing and the type of operation
path /features/Container:<UUID>/inbox/messages/rename A path to the Container Feature, it’s message channel, and rename command
Headers Additional headers
response-required true/false If response is required
content-type application/json The content type
correlation-id container UUID The container UUID
Value The new name of the container

Name	Value	Description
topic	`<name>/<namespace>:edge:containers/things/live/messages/rename`	Information about the affected Thing and the type of operation
path	`/features/Container:<UUID>/inbox/messages/rename`	A path to the `Container` Feature, it’s message channel, and `rename` command
Headers		Additional headers
response-required	true/false	If response is required
content-type	`application/json`	The content type
correlation-id	container UUID	The container UUID
Value		The new name of the container

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

Topic: command//edge:device:edge:containers/req//rename

{
	"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"
}

Response

Hono Command : command//<name>:<namespace>:edge:containers/res//rename

Ditto Message:

Name Value Description
topic <name>/<namespace>:edge:containers/things/live/messages/rename Information about the affected Thing and the type of operation
path /features/Container:<UUID>/outbox/messages/rename A path to the Container Feature, it’s message channel, and rename command
Headers Additional headers
content-type application/json The content type
correlation-id <UUID> The same correlation id as the request message
Status Status of the operation rename container

Name	Value	Description
topic	`<name>/<namespace>:edge:containers/things/live/messages/rename`	Information about the affected Thing and the type of operation
path	`/features/Container:<UUID>/outbox/messages/rename`	A path to the `Container` Feature, it’s message channel, and `rename` command
Headers		Additional headers
content-type	`application/json`	The content type
correlation-id	<UUID>	The same correlation id as the request message
Status		Status of the operation rename container

Example : The response of the rename operation.

Topic: `command//edge:device:edge:containers/res//rename``

{
	"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.

Request

Hono Command: command//<name>:<namespace>:edge:containers/req//update

Ditto Message:

Name Value Description
topic <name>/<namespace>:edge:containers/things/live/messages/update Information about the affected Thing and the type of operation
path /features/Container:<UUID>/inbox/messages/update A path to the Container Feature, it’s message channel, and update command
Headers Additional headers
response-required true/false If response is required
content-type application/json The content type
correlation-id container UUID The container UUID
Value
restartPolicy Updates the restart policy for the container. The policy will be applied when the container exits
type no/always/unless-stopped/on-failure The container’s restart policy, the supported types are: always, no, on-failure and unless-stopped
maxRetryCount -1 « 31 // -2147483648 Maximum number of retries that are made to restart the container on exit with fail, if the type is on-failure
timeout -1 « 63 // -9223372036854775808 Timeout period in seconds for each retry that is made to restart the container on exit with fail, if the type is on-failure
resources
memory Hard memory limitation of the container as a number with a unit suffix of B, K, M and G, the minimum allowed value is 3M
memoryReservation Soft memory limitation of the container as a number with a unit suffix of B, K, M and G, if memory is specified, the memoryReservation must be smaller than it
memorySwap Total amount of memory and swap that the container can use as a number with a unit suffix of B, K, M and G, use -1 to allow the container to use unlimited swap

Name	Value	Description
topic	`<name>/<namespace>:edge:containers/things/live/messages/update`	Information about the affected Thing and the type of operation
path	`/features/Container:<UUID>/inbox/messages/update`	A path to the `Container` Feature, it’s message channel, and `update` command
Headers		Additional headers
response-required	true/false	If response is required
content-type	`application/json`	The content type
correlation-id	container UUID	The container UUID
Value
restartPolicy		Updates the restart policy for the container. The policy will be applied when the container exits
type	no/always/unless-stopped/on-failure	The container’s restart policy, the supported types are: always, no, on-failure and unless-stopped
maxRetryCount	-1 « 31 // -2147483648	Maximum number of retries that are made to restart the container on exit with fail, if the `type` is on-failure
timeout	-1 « 63 // -9223372036854775808	Timeout period in seconds for each retry that is made to restart the container on exit with fail, if the `type` is on-failure
resources
memory		Hard memory limitation of the container as a number with a unit suffix of B, K, M and G, the minimum allowed value is 3M
memoryReservation		Soft memory limitation of the container as a number with a unit suffix of B, K, M and G, if `memory` is specified, the `memoryReservation` must be smaller than it
memorySwap		Total amount of memory and swap that the container can use as a number with a unit suffix of B, K, M and G, use -1 to allow the container to use unlimited swap

Example : Update an existing container resources and restart policy.

Topic: command//edge:device:edge:containers/req//update

{
	"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",
		}
	}
}

Response

Hono Command : command//<name>:<namespace>:edge:containers/res//update

Ditto Message:

Name Value Description
topic <name>/<namespace>:edge:containers/things/live/messages/update Information about the affected Thing and the type of operation
path /features/Container:<UUID>/outbox/messages/update A path to the Container Feature, it’s message channel, and update command
Headers Additional headers
content-type application/json The content type
correlation-id <UUID> The same correlation id as the request message
Status Status of the update operation over the container

Name	Value	Description
topic	`<name>/<namespace>:edge:containers/things/live/messages/update`	Information about the affected Thing and the type of operation
path	`/features/Container:<UUID>/outbox/messages/update`	A path to the `Container` Feature, it’s message channel, and `update` command
Headers		Additional headers
content-type	`application/json`	The content type
correlation-id	<UUID>	The same correlation id as the request message
Status		Status of the `update` operation over the container

Example : Successful response of an update operation.

Topic: `command//edge:device:edge:containers/res//update``

{
	"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.

Request

Hono Command: command//<name>:<namespace>:edge:containers/req//remove

Ditto Message:

Name Value Description
topic <name>/<namespace>:edge:containers/things/live/messages/remove Information about the affected Thing and the type of operation
path /features/Container:<UUID>/inbox/messages/remove A path to the Container Feature, it’s message channel, and remove command
Headers Additional headers
response-required true/false If response is required
content-type application/json The content type
correlation-id container UUID The container UUID
Value true/false Force stopping before removing a container

Name	Value	Description
topic	`<name>/<namespace>:edge:containers/things/live/messages/remove`	Information about the affected Thing and the type of operation
path	`/features/Container:<UUID>/inbox/messages/remove`	A path to the `Container` Feature, it’s message channel, and `remove` command
Headers		Additional headers
response-required	true/false	If response is required
content-type	`application/json`	The content type
correlation-id	container UUID	The container UUID
Value	true/false	Force stopping before removing a container

Example : Remove an existing container.

Topic: command//edge:device:edge:containers/req//remove

{
	"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
}

Response

Hono Command : command//<name>:<namespace>:edge:containers/res//remove

Ditto Message:

Name Value Description
topic <name>/<namespace>:edge:containers/things/live/messages/remove Information about the affected Thing and the type of operation
path /features/Container:<UUID>/outbox/messages/remove A path to the Container Feature, it’s message channel, and remove command
Headers Additional headers
content-type application/json The content type
correlation-id <UUID> The same correlation id as the request message
Status Status of the operation remove container

Name	Value	Description
topic	`<name>/<namespace>:edge:containers/things/live/messages/remove`	Information about the affected Thing and the type of operation
path	`/features/Container:<UUID>/outbox/messages/remove`	A path to the `Container` Feature, it’s message channel, and `remove` command
Headers		Additional headers
content-type	`application/json`	The content type
correlation-id	<UUID>	The same correlation id as the request message
Status		Status of the operation remove container

Example : Successful response of an remove operation.

Topic: `command//edge:device:edge:containers/res//remove``

{
	"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
}

3 - Metrics API

With the metrics service, you can request and receive metrics data for specific containers.

Request

Request to receive data from the container.

Request

Hono Command: command//<name>:<namespace>:edge:containers/req//request

Ditto Message:

Name Value Description
topic <name>/<namespace>:edge:containers/things/live/messages/request Information about the affected Thing and the type of operation
path /features/Metrics/inbox/messages/request A path to the Metrics Feature, it’s message channel, and request command
Headers Additional headers
response-required true/false If response is required
content-type application/json The content type
correlation-id container UUID The container UUID
Value
frequency Time interval of how often the metrics data will be published as duration string (e.g. 5s)
filter Filter defines the type of metric data to be reported
id An array of identifiers whose metric data to be reported, supported are: cpu.utilization, memory.utilization, memory.total, memory.used, io.readBytes, io.writeBytes, net.readBytes, net.writeBytes, pids
originator Metrics data originator

Name	Value	Description
topic	`<name>/<namespace>:edge:containers/things/live/messages/request`	Information about the affected Thing and the type of operation
path	`/features/Metrics/inbox/messages/request`	A path to the `Metrics` Feature, it’s message channel, and `request` command
Headers		Additional headers
response-required	true/false	If response is required
content-type	`application/json`	The content type
correlation-id	container UUID	The container UUID
Value
frequency		Time interval of how often the metrics data will be published as duration string (e.g. 5s)
filter		Filter defines the type of metric data to be reported
id		An array of identifiers whose metric data to be reported, supported are: `cpu.utilization`, `memory.utilization`, `memory.total`, `memory.used`, `io.readBytes`, `io.writeBytes`, `net.readBytes`, `net.writeBytes`, `pids`
originator		Metrics data originator

Example : Request metrics data with a specified filter and frequency.

Topic: command//edge:device:edge:containers/req//request

{
	"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"
	}
}

Response

Hono Command : command//<name>:<namespace>:edge:containers/res//request

Ditto Message:

Name Value Description
topic <name>/<namespace>:edge:containers/things/live/messages/request Information about the affected Thing and the type of operation
path /features/Metrics/outbox/messages/request A path to the Metrics Feature, it’s message channel, and request command
Headers Additional headers
content-type application/json The content type
correlation-id <UUID> The same correlation id as the sent request message
Status Status of the request metrics operation

Name	Value	Description
topic	`<name>/<namespace>:edge:containers/things/live/messages/request`	Information about the affected Thing and the type of operation
path	`/features/Metrics/outbox/messages/request`	A path to the `Metrics` Feature, it’s message channel, and `request` command
Headers		Additional headers
content-type	`application/json`	The content type
correlation-id	<UUID>	The same correlation id as the sent request message
Status		Status of the `request` metrics operation

Example : The response of the request metrics data operation.

Topic: `command//edge:device:edge:containers/res//request``

{
	"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.

Response

Hono Command : command//<name>:<namespace>:edge:containers/res//data

Ditto Message:

Name Value Description
topic <name>/<namespace>:edge:containers/things/live/messages/data Information about the affected Thing and the type of operation
path /features/Metrics/outbox/messages/data A path to the Metrics Feature and it’s message channel.
Headers Additional headers
content-type application/json The content type
Value The value of the received data from the container in json format
timestamp The timestamp in ms when this measure data is published
shapshot All the measurements collected per originator
originator The originator for whose metric data to be reported
measurements An array of measurements identifier and value for originator
id The identifier whose metric data to be reported, supported are: cpu.utilization, memory.utilization, memory.total, memory.used, io.readBytes, io.writeBytes, net.readBytes, net.writeBytes, pids
value The measured value per metric ID

Name	Value	Description
topic	`<name>/<namespace>:edge:containers/things/live/messages/data`	Information about the affected Thing and the type of operation
path	`/features/Metrics/outbox/messages/data`	A path to the `Metrics` Feature and it’s message channel.
Headers		Additional headers
content-type	`application/json`	The content type
Value		The value of the received data from the container in json format
timestamp		The timestamp in ms when this measure data is published
shapshot		All the measurements collected per originator
originator		The originator for whose metric data to be reported
measurements		An array of measurements identifier and value for originator
id		The identifier whose metric data to be reported, supported are: `cpu.utilization`, `memory.utilization`, `memory.total`, `memory.used`, `io.readBytes`, `io.writeBytes`, `net.readBytes`, `net.writeBytes`, `pids`
value		The measured value per metric ID

Example : Metrics data from a container.

Topic: `command//edge:device:edge:containers/res//data``

{
	"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 - Software Updatable API

The software updatable service utilizes the Eclipse hawkBit message format to install a specified list of containers (software modules) and remove already installed modules.

Install

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

Request

Hono Command: command//<name>:<namespace>:edge:containers/req//install

Ditto Message:

Name Value Description
topic <name>/<namespace>:edge:containers/things/live/messages/install Information about the affected Thing and the type of operation
path /features/SoftwareUpdatable/inbox/messages/install A path to the SoftwareUpdatable Feature, it’s message channel, and install command
Headers Additional headers
response-required true/false If response is required
content-type application/json The content type
correlation-id container UUID The container UUID
Value
correlationId Unique identifier that is used to associate and track the series of messages
weight The weight is the priority in case of multiple, parallel instructions
metadata The metadata is any other information which should be passed to the device
forced true/false Forced to install the software modules
softwareModules An array of modules that will be installed
metadata The metadata is any other information which should be passed to the device
softwareModule An unique identifier for the software module
name The name of the software module
version The version of the software module
artifacts An array of artifacts contained in the software module
filename The file name of the artifact behind the provided URLs
size The size of the file in bytes
download A map with protocols and links for artifact download
key HTTP/HTTPS/FTP/SFTP Available transport protocols
url URL to download the artifact
md5url MD5URL to download the MD5SUM file
checksums A map with checksums to verify the proper download
MD5 MD5 checksum of the downloaded file
SHA1 SHA1 checksum of the downloaded file
SHA256 SHA256 checksum of the downloaded file

Name	Value	Description
topic	`<name>/<namespace>:edge:containers/things/live/messages/install`	Information about the affected Thing and the type of operation
path	`/features/SoftwareUpdatable/inbox/messages/install`	A path to the `SoftwareUpdatable` Feature, it’s message channel, and `install` command
Headers		Additional headers
response-required	true/false	If response is required
content-type	`application/json`	The content type
correlation-id	container UUID	The container UUID
Value
correlationId		Unique identifier that is used to associate and track the series of messages
weight		The weight is the priority in case of multiple, parallel instructions
metadata		The metadata is any other information which should be passed to the device
forced	true/false	Forced to install the software modules
softwareModules		An array of modules that will be installed
metadata		The metadata is any other information which should be passed to the device
softwareModule		An unique identifier for the software module
name		The name of the software module
version		The version of the software module
artifacts		An array of artifacts contained in the software module
filename		The file name of the artifact behind the provided URLs
size		The size of the file in bytes
download		A map with protocols and links for artifact download
key	HTTP/HTTPS/FTP/SFTP	Available transport protocols
url		URL to download the artifact
md5url		MD5URL to download the MD5SUM file
checksums		A map with checksums to verify the proper download
MD5		MD5 checksum of the downloaded file
SHA1		SHA1 checksum of the downloaded file
SHA256		SHA256 checksum of the downloaded file

Example : In this example, you can install the listed modules.

Topic: command//edge:device:edge:containers/req//install

{
	"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
					}
				]
			}
		]
	}
}

Response

Hono Command : command//<name>:<namespace>:edge:containers/res//install

Ditto Message:

Name Value Description
topic <name>/<namespace>:edge:containers/things/live/messages/install Information about the affected Thing and the type of operation
path /features/SoftwareUpdatable/outbox/messages/install A path to the SoftwareUpdatable Feature, it’s message channel, and install command
Headers Additional headers
content-type application/json The content type
correlation-id <UUID> The same correlation id as the sent request message
Status Status of the install operation`

Name	Value	Description
topic	`<name>/<namespace>:edge:containers/things/live/messages/install`	Information about the affected Thing and the type of operation
path	`/features/SoftwareUpdatable/outbox/messages/install`	A path to the `SoftwareUpdatable` Feature, it’s message channel, and `install` command
Headers		Additional headers
content-type	`application/json`	The content type
correlation-id	<UUID>	The same correlation id as the sent request message
Status		Status of the `install` operation`

Example : Response of a successful install of the software modules.

Topic: `command//edge:device:edge:containers/res//install``

{
	"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.

Request

Hono Command: command//<name>:<namespace>:edge:containers/req//remove

Ditto Message:

Name Value Description
topic <name>/<namespace>:edge:containers/things/live/messages/remove Information about the affected Thing and the type of operation
path /features/SoftwareUpdatable/inbox/messages/remove A path to the SoftwareUpdatable Feature, it’s message channel, and remove command
Headers Additional headers
response-required true/false If response is required
content-type application/json The content type
correlation-id container UUID The container UUID
Value Json presentation of the software module to be removed
correlationId Unique identifier that is used to associate and track the series of messages
weight The weight is the priority in case of multiple, parallel instructions
metadata The metadata is any other information which should be passed to the device
forced true/false Force remove the software modules
software An array of software modules to be removed
group An identifier which groups the dependency into a certain category
name The dependency name
version The dependency version
type The “category” classifier of the dependency

Name	Value	Description
topic	`<name>/<namespace>:edge:containers/things/live/messages/remove`	Information about the affected Thing and the type of operation
path	`/features/SoftwareUpdatable/inbox/messages/remove`	A path to the `SoftwareUpdatable` Feature, it’s message channel, and `remove` command
Headers		Additional headers
response-required	true/false	If response is required
content-type	`application/json`	The content type
correlation-id	container UUID	The container UUID
Value		Json presentation of the software module to be removed
correlationId		Unique identifier that is used to associate and track the series of messages
weight		The weight is the priority in case of multiple, parallel instructions
metadata		The metadata is any other information which should be passed to the device
forced	true/false	Force remove the software modules
software		An array of software modules to be removed
group		An identifier which groups the dependency into a certain category
name		The dependency name
version		The dependency version
type		The “category” classifier of the dependency

Example : In this example, you can remove an existing software modules.

Topic: command//edge:device:edge:containers/req//remove

{
	"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":""
			}
		]
	}
}

Response

Hono Command : command//<name>:<namespace>:edge:containers/res//remove

Ditto Message:

Name Value Description
topic <name>/<namespace>:edge:containers/things/live/messages/remove Information about the affected Thing and the type of operation
path /features/SoftwareUpdatable/outbox/messages/remove A path to the SoftwareUpdatable Feature, it’s message channel, and remove command
Headers Additional headers
correlation-id container UUID The container UUID
Status Status of the operation remove software modules from container

Name	Value	Description
topic	`<name>/<namespace>:edge:containers/things/live/messages/remove`	Information about the affected Thing and the type of operation
path	`/features/SoftwareUpdatable/outbox/messages/remove`	A path to the `SoftwareUpdatable` Feature, it’s message channel, and `remove` command
Headers		Additional headers
correlation-id	container UUID	The container UUID
Status		Status of the operation remove software modules from container

Example : The response of successful removal of software modules.

Topic: `command//edge:device:edge:containers/res//remove``

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