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
}

Last modified June 28, 2024