From 9dc59dc980ed39a638a4294eef077d933893a306 Mon Sep 17 00:00:00 2001 From: Antonia Avramova Date: Fri, 28 Jun 2024 09:38:03 +0300 Subject: [PATCH] [#278] Expand documentation with API definitions, message formats and other technical details. (#325) Signed-off-by: Antonia Avramova Signed-off-by: Kristiyan Gostev Co-authored-by: Kristiyan Gostev --- .../local-digital-twins-config.md | 2 +- .../containers/api-reference/_index.md | 7 + .../api-reference/container-factory.md | 263 ++++++++++ .../containers/api-reference/container.md | 473 ++++++++++++++++++ .../containers/api-reference/metrics.md | 207 ++++++++ .../api-reference/software-updatable.md | 217 ++++++++ .../docs/references/file-backup/_index.md | 7 + .../references/file-backup/file-backup-api.md | 177 +++++++ .../{ => file-backup}/file-backup-config.md | 2 +- .../docs/references/file-upload/_index.md | 7 + .../references/file-upload/file-upload-api.md | 401 +++++++++++++++ .../{ => file-upload}/file-upload-config.md | 2 +- .../references/software-updatable/_index.md | 7 + .../software-updatable-api.md | 243 +++++++++ .../software-update-config.md | 2 +- .../docs/references/system-metrics/_index.md | 7 + .../system-metrics/system-metrics-api.md | 175 +++++++ .../system-metrics-config.md | 2 +- .../docs/references/update-manager/_index.md | 7 + .../update-manager/update-manager-api.md | 212 ++++++++ .../update-manager-config.md | 0 21 files changed, 2415 insertions(+), 5 deletions(-) rename web/site/content/docs/references/{ => connectivity}/local-digital-twins-config.md (99%) create mode 100644 web/site/content/docs/references/containers/api-reference/_index.md create mode 100644 web/site/content/docs/references/containers/api-reference/container-factory.md create mode 100644 web/site/content/docs/references/containers/api-reference/container.md create mode 100644 web/site/content/docs/references/containers/api-reference/metrics.md create mode 100644 web/site/content/docs/references/containers/api-reference/software-updatable.md create mode 100644 web/site/content/docs/references/file-backup/_index.md create mode 100644 web/site/content/docs/references/file-backup/file-backup-api.md rename web/site/content/docs/references/{ => file-backup}/file-backup-config.md (99%) create mode 100644 web/site/content/docs/references/file-upload/_index.md create mode 100644 web/site/content/docs/references/file-upload/file-upload-api.md rename web/site/content/docs/references/{ => file-upload}/file-upload-config.md (99%) create mode 100644 web/site/content/docs/references/software-updatable/_index.md create mode 100644 web/site/content/docs/references/software-updatable/software-updatable-api.md rename web/site/content/docs/references/{ => software-updatable}/software-update-config.md (99%) create mode 100644 web/site/content/docs/references/system-metrics/_index.md create mode 100644 web/site/content/docs/references/system-metrics/system-metrics-api.md rename web/site/content/docs/references/{ => system-metrics}/system-metrics-config.md (99%) create mode 100644 web/site/content/docs/references/update-manager/_index.md create mode 100644 web/site/content/docs/references/update-manager/update-manager-api.md rename web/site/content/docs/references/{ => update-manager}/update-manager-config.md (100%) diff --git a/web/site/content/docs/references/local-digital-twins-config.md b/web/site/content/docs/references/connectivity/local-digital-twins-config.md similarity index 99% rename from web/site/content/docs/references/local-digital-twins-config.md rename to web/site/content/docs/references/connectivity/local-digital-twins-config.md index e6cf1706..2cfce3a2 100644 --- a/web/site/content/docs/references/local-digital-twins-config.md +++ b/web/site/content/docs/references/connectivity/local-digital-twins-config.md @@ -3,7 +3,7 @@ title: "Local digital twins configuration" type: docs description: > Customize the local digital twins persistency, access and synchronization. -weight: 2 +weight: 4 --- ### Properties diff --git a/web/site/content/docs/references/containers/api-reference/_index.md b/web/site/content/docs/references/containers/api-reference/_index.md new file mode 100644 index 00000000..90165de4 --- /dev/null +++ b/web/site/content/docs/references/containers/api-reference/_index.md @@ -0,0 +1,7 @@ +--- +title: "API Reference" +type: docs +description: > + API Reference for the Container Management Things service. +weight: 3 +--- diff --git a/web/site/content/docs/references/containers/api-reference/container-factory.md b/web/site/content/docs/references/containers/api-reference/container-factory.md new file mode 100644 index 00000000..3663bfda --- /dev/null +++ b/web/site/content/docs/references/containers/api-reference/container-factory.md @@ -0,0 +1,263 @@ +--- +title: "Container Factory API" +type: docs +description: > + The container factory service provides the ability to create new containers form a container image, or from a [container configuration](../container-config.md). +weight: 2 +--- + +## **Create** +Create a container from a single container image reference with an option to start it. + +
+ Request + +**Hono Command:** `command//::edge:containers/req//create` + +**Ditto Message:** + +> | Name | Value | Description | +> | - | - | - | +> | topic | `/: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 {{% refn "https://github.com/opencontainers/image-spec" %}}OCI Image Specification{{% /refn %}}, 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` +```json +{ + "topic":"edge/device:edge:containers/things/live/messages/create", + "headers":{ + "response-required":true, + "content-type":"application/json", + "correlation-id":"" + }, + "path":"/features/ContainerFactory/inbox/messages/create", + "value":{ + "imageRef":"docker.io/library/hello-world:latest", + "start":true + } +} +``` +
+ +
+ Response + +**Hono Command** : `command//::edge:containers/res//create` + +**Ditto Message:** + +> | Name | Value | Description | +> | - | - | - | +> | topic | `/: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 | \ | 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`` +```json +{ + "topic":"edge/device:edge:containers/things/live/messages/create", + "headers":{ + "content-type":"application/json", + "correlation-id":"" + }, + "path":"/features/ContainerFactory/outbox/messages/create", + "value":"" +} +``` +
+ +## **Create with config** +Create a container with a specified container configuration. + +
+ Request + +**Hono Command:** `command//::edge:containers/req//createWithConfig` + +**Ditto Message:** + +> | Name | Value | Description | +> | - | - | - | +> | topic | `/: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 {{% refn "https://github.com/opencontainers/image-spec" %}}OCI Image Specification{{% /refn %}}, 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_ 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 | | 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 | /containers/ | 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` +```json +{ + "topic":"edge/device:edge:containers/things/live/messages/createWithConfig", + "headers":{ + "response-required":true, + "content-type":"application/json", + "correlation-id":"" + }, + "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//::edge:containers/res//createWithConfig` + +**Ditto Message:** + +> | Name | Value | Description | +> | - | - | - | +> | topic | `/: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 | \ | | +> | **Value** | | UUID of the created container | + +
+ +**Example** : Response of a `createWithConfig` operation. + +**Topic:** `command//edge:device:edge:containers/res//createWithConfig` +```json +{ + "topic":"edge/device:edge:containers/things/live/messages/createWithConfig", + "headers":{ + "content-type":"application/json", + "correlation-id":"" + }, + "path":"/features/ContainerFactory/outbox/messages/createWithConfig", + "value":"" +} +``` +
\ No newline at end of file diff --git a/web/site/content/docs/references/containers/api-reference/container.md b/web/site/content/docs/references/containers/api-reference/container.md new file mode 100644 index 00000000..41696695 --- /dev/null +++ b/web/site/content/docs/references/containers/api-reference/container.md @@ -0,0 +1,473 @@ +--- +title: "Container API" +type: docs +description: > + 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. +weight: 3 +--- + +## **Start** +Start an existing container. + +
+ Request + +**Hono Command:** `command//::edge:containers/req//start` + +**Ditto Message:** + +> | Name | Value | Description | +> | - | - | - | +> | topic | `/:edge:containers/things/live/messages/start` | Information about the affected Thing and the type of operation | +> | path | `/features/Container:/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` +```json +{ + "topic":"edge/device:edge:containers/things/live/messages/start", + "headers":{ + "response-required":true, + "content-type":"application/json", + "correlation-id":"" + }, + "path":"/features/Container:/inbox/messages/start", + "value":{} +} +``` +
+ +
+ Response + +**Hono Command** : `command//::edge:containers/res//start` + +**Ditto Message:** + +> | Name | Value | Description | +> | - | - | - | +> | topic | `/:edge:containers/things/live/messages/start` | Information about the affected Thing and the type of operation | +> | path | `/features/Container:/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 | \ | 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`` +```json +{ + "topic":"edge/device:edge:containers/things/live/messages/start", + "headers":{ + "content-type":"application/json", + "correlation-id":"" + }, + "path":"/features/Container:/outbox/messages/start", + "status": 204 +} +``` +
+ +## **Stop** +Stop an existing and running container. + +
+ Request + +**Hono Command:** `command//::edge:containers/req//stop` + +**Ditto Message:** + +> | Name | Value | Description | +> | - | - | - | +> | topic | `/:edge:containers/things/live/messages/stop` | Information about the affected Thing and the type of operation | +> | path | `/features/Container:/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` +```json +{ + "topic":"edge/device:edge:containers/things/live/messages/stop", + "headers":{ + "response-required":true, + "content-type":"application/json", + "correlation-id":"" + }, + "path":"/features/Container:/inbox/messages/stop", + "value":{} +} +``` +
+ +
+ Response + +**Hono Command** : `command//::edge:containers/res//stop` + +**Ditto Message:** + +> | Name | Value | Description | +> | - | - | - | +> | topic | `/:edge:containers/things/live/messages/stop` | Information about the affected Thing and the type of operation | +> | path | `/features/Container:/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 | \ | 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`` +```json +{ + "topic":"edge/device:edge:containers/things/live/messages/stop", + "headers":{ + "content-type":"application/json", + "correlation-id":"" + }, + "path":"/features/Container:/outbox/messages/stop", + "status":204 +} +``` +
+ +## **Stop with options** +Stop an existing and running container with given options. + +
+ Request + +**Hono Command:** `command//::edge:containers/req//stopWithOptions` + +**Ditto Message:** + +> | Name | Value | Description | +> | - | - | - | +> | topic | `/:edge:containers/things/live/messages/stopWithOptions` | Information about the affected Thing and the type of operation | +> | path | `/features/Container:/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` +```json +{ + "topic":"edge/device:edge:containers/things/live/messages/stopWithOptions", + "headers":{ + "response-required":true, + "content-type":"application/json", + "correlation-id":"" + }, + "path":"/features/Container:/inbox/messages/stopWithOptions", + "value":{ + "signal":"SIGINT", + "timeout": 30, + "force": true + } +} +``` +
+ +
+ Response + +**Hono Command** : `command//::edge:containers/res//stopWithOptions` + +**Ditto Message:** + +> | Name | Value | Description | +> | - | - | - | +> | topic | `/:edge:containers/things/live/messages/stopWithOptions` | Information about the affected Thing and the type of operation | +> | path | `/features/Container:/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 | \ | 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`` +```json +{ + "topic":"edge/device:edge:containers/things/live/messages/stopWithOptions", + "headers":{ + "content-type":"application/json", + "correlation-id":"" + }, + "path":"/features/Container:/outbox/messages/stopWithOptions", + "status":204 +} +``` +
+ +## **Rename** +Change the name of an existing container to the specified new name. + +
+ Request + +**Hono Command:** `command//::edge:containers/req//rename` + +**Ditto Message:** + +> | Name | Value | Description | +> | - | - | - | +> | topic | `/:edge:containers/things/live/messages/rename` | Information about the affected Thing and the type of operation | +> | path | `/features/Container:/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` +```json +{ + "topic":"edge/device:edge:containers/things/live/messages/rename", + "headers":{ + "response-required":true, + "content-type":"application/json", + "correlation-id":"" + }, + "path":"/features/Container:/inbox/messages/rename", + "value":"new_container_name" +} +``` +
+ +
+ Response + +**Hono Command** : `command//::edge:containers/res//rename` + +**Ditto Message:** + +> | Name | Value | Description | +> | - | - | - | +> | topic | `/:edge:containers/things/live/messages/rename` | Information about the affected Thing and the type of operation | +> | path | `/features/Container:/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 | \ | 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`` +```json +{ + "topic":"edge/device:edge:containers/things/live/messages/rename", + "headers":{ + "content-type":"application/json", + "correlation-id":"" + }, + "path":"/features/Container:/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//::edge:containers/req//update` + +**Ditto Message:** + +> | Name | Value | Description | +> | - | - | - | +> | topic | `/:edge:containers/things/live/messages/update` | Information about the affected Thing and the type of operation | +> | path | `/features/Container:/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` +```json +{ + "topic":"edge/device:edge:containers/things/live/messages/update", + "headers":{ + "response-required":true, + "content-type":"application/json", + "correlation-id":"" + }, + "path":"/features/Container:/inbox/messages/update", + "value":{ + "restartPolicy":{ + "type":"on-failure", + "maxRetryCount":3, + "timeout":10 + }, + "resources":{ + "memory":"500M", + "memoryReservation":"300M", + "memorySwap":"1G", + } + } +} +``` +
+ +
+ Response + +**Hono Command** : `command//::edge:containers/res//update` + +**Ditto Message:** + +> | Name | Value | Description | +> | - | - | - | +> | topic | `/:edge:containers/things/live/messages/update` | Information about the affected Thing and the type of operation | +> | path | `/features/Container:/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 | \ | 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`` +```json +{ + "topic":"edge/device:edge:containers/things/live/messages/update", + "headers":{ + "content-type":"application/json", + "correlation-id":"" + }, + "path":"/features/Container:/outbox/messages/update", + "status":204 +} +``` +
+ +## **Remove** +Remove an existing container. + +
+ Request + +**Hono Command:** `command//::edge:containers/req//remove` + +**Ditto Message:** + +> | Name | Value | Description | +> | - | - | - | +> | topic | `/:edge:containers/things/live/messages/remove` | Information about the affected Thing and the type of operation | +> | path | `/features/Container:/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` +```json +{ + "topic":"edge/device:edge:containers/things/live/messages/remove", + "headers":{ + "response-required":true, + "content-type":"application/json", + "correlation-id":"" + }, + "path":"/features/Container:/inbox/messages/remove", + "value":true +} +``` +
+ +
+ Response + +**Hono Command** : `command//::edge:containers/res//remove` + +**Ditto Message:** + +> | Name | Value | Description | +> | - | - | - | +> | topic | `/:edge:containers/things/live/messages/remove` | Information about the affected Thing and the type of operation | +> | path | `/features/Container:/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 | \ | 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`` +```json +{ + "topic":"edge/device:edge:containers/things/live/messages/remove", + "headers":{ + "content-type":"application/json", + "correlation-id":"" + }, + "path":"/features/Container:/outbox/messages/remove", + "status":204 +} +``` +
\ No newline at end of file diff --git a/web/site/content/docs/references/containers/api-reference/metrics.md b/web/site/content/docs/references/containers/api-reference/metrics.md new file mode 100644 index 00000000..778093ec --- /dev/null +++ b/web/site/content/docs/references/containers/api-reference/metrics.md @@ -0,0 +1,207 @@ +--- +title: "Metrics API" +type: docs +description: > + With the metrics service, you can request and receive metrics data for specific containers. +weight: 4 +--- + +## **Request** +Request to receive data from the container. + +
+ Request + +**Hono Command:** `command//::edge:containers/req//request` + +**Ditto Message:** + +> | Name | Value | Description | +> | - | - | - | +> | topic | `/: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` +```json +{ + "topic":"edge/device:edge:containers/things/live/messages/request", + "headers":{ + "response-required":true, + "content-type":"application/json", + "correlation-id":"" + }, + "path":"/features/Metrics/inbox/messages/request", + "value":{ + "filter":[ + { + "id":null, + "originator":"SYSTEM" + } + ], + "frequency":"2s" + } +} +``` +
+ +
+ Response + +**Hono Command** : `command//::edge:containers/res//request` + +**Ditto Message:** + +> | Name | Value | Description | +> | - | - | - | +> | topic | `/: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 | \ | 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`` +```json +{ + "topic":"edge/device:edge:containers/things/live/messages/request", + "headers":{ + "content-type":"application/json", + "correlation-id":"" + }, + "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//::edge:containers/res//data` + +**Ditto Message:** + +> | Name | Value | Description | +> | - | - | - | +> | topic | `/: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`` +```json +{ + "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 + } +} +``` +
diff --git a/web/site/content/docs/references/containers/api-reference/software-updatable.md b/web/site/content/docs/references/containers/api-reference/software-updatable.md new file mode 100644 index 00000000..bdd27769 --- /dev/null +++ b/web/site/content/docs/references/containers/api-reference/software-updatable.md @@ -0,0 +1,217 @@ +--- +title: "Software Updatable API" +type: docs +description: > + The software updatable service utilizes the Eclipse hawkBit message format to install a specified list of containers (software modules) and remove already installed modules. +weight: 4 +--- + +## **Install** +You can install a specified list of containers (software modules). + +
+ Request + +**Hono Command:** `command//::edge:containers/req//install` + +**Ditto Message:** + +> | Name | Value | Description | +> | - | - | - | +> | topic | `/: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` +```json +{ + "topic":"edge/device:edge:containers/things/live/messages/install", + "headers":{ + "response-required":true, + "content-type":"application/json", + "correlation-id":"" + }, + "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//::edge:containers/res//install` + +**Ditto Message:** + +> | Name | Value | Description | +> | - | - | - | +> | topic | `/: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 | \ | 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`` +```json +{ + "topic":"edge/device:edge:containers/things/live/messages/install", + "headers":{ + "content-type":"application/json", + "correlation-id":"" + }, + "path":"/features/SoftwareUpdatable/outbox/messages/install", + "status": 204 +} +``` +
+ +## **Remove** +Remove of an installed software module. + +
+ Request + +**Hono Command:** `command//::edge:containers/req//remove` + +**Ditto Message:** + +> | Name | Value | Description | +> | - | - | - | +> | topic | `/: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` +```json +{ + "topic":"edge/device:edge:containers/things/live/messages/remove", + "headers":{ + "response-required":true, + "content-type":"application/json", + "correlation-id":"" + }, + "path":"/features/SoftwareUpdatable/inbox/messages/remove", + "value": { + "correlationId":"other_correlation_id", + "forced":true, + "software":[ + { + "name":"influxdb", + "version":"" + } + ] + } +} +``` +
+ +
+ Response + +**Hono Command** : `command//::edge:containers/res//remove` + +**Ditto Message:** + +> | Name | Value | Description | +> | - | - | - | +> | topic | `/: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`` +```json +{ + "topic":"edge/device:edge:containers/things/live/messages/remove", + "headers":{ + "correlation-id":"" + }, + "path":"/features/SoftwareUpdatable/outbox/messages/remove", + "status":204 +} +``` +
\ No newline at end of file diff --git a/web/site/content/docs/references/file-backup/_index.md b/web/site/content/docs/references/file-backup/_index.md new file mode 100644 index 00000000..7bf5afb2 --- /dev/null +++ b/web/site/content/docs/references/file-backup/_index.md @@ -0,0 +1,7 @@ +--- +title: "File Backup" +type: docs +description: > + Customize the files backup and restore to and from a backend storage. +weight: 6 +--- diff --git a/web/site/content/docs/references/file-backup/file-backup-api.md b/web/site/content/docs/references/file-backup/file-backup-api.md new file mode 100644 index 00000000..cf2da55c --- /dev/null +++ b/web/site/content/docs/references/file-backup/file-backup-api.md @@ -0,0 +1,177 @@ +--- +title: "File Backup API" +type: docs +description: > + The file backup service allows you to backup and restore data to and from a backend storage. +weight: 4 +--- + +## **Backup** +Create a file backup. + +
+ Request + +**Hono Command:** `command//:/req//backup` + +**Ditto Message:** + +> | Name | Value | Description | +> | - | - | - | +> | topic | `//things/live/messages/backup` | Information about the affected Thing and the type of operation | +> | path | `/features/BackupAndRestore/inbox/messages/backup` | A path to the `BackupAndRestore` Feature, it's message channel, and `backup` command | +> | **Headers** | | Additional headers | +> | response-required | true/false | If response is required | +> | content-type | `application/json` | The content type | +> | correlation-id | UUID | Used for correlating protocol messages, the same correlation-id as the sent back response message | +> | **Value** | | | +> | correlationID | UUID | Identifier of the backup file | +> | providers | | The providers of the restore command | +> | **options** | | | +> | backup.dir | | A local directory, to be backed up | +> | https.url | | The URL for restoring the backed up directory | + +
+ +**Example** : Back up a directory. + +**Topic:** `command//edge:device/req//backup` +```json +{ + "topic":"edge/device/things/live/messages/backup", + "headers":{ + "response-required":true, + "content-type":"application/json", + "correlation-id":"" + }, + "path":"/features/BackupAndRestore/inbox/messages/backup", + "value":{ + "correlationID":"upload-id-1704439450#n", + "providers":{}, + "options":{ + "backup.dir":"/var/tmp/backup", + "https.url":"" + } + } +} +``` +
+ +
+ Response + +**Hono Command** : `command//:/res//backup` + +**Ditto Message:** + +> | Name | Value | Description | +> | - | - | - | +> | topic | `//things/live/messages/backup` | Information about the affected Thing and the type of operation | +> | path | `/features/BackupAndRestore/outbox/messages/backup` | A path to the `BackupAndRestore` Feature, it's message channel, and `backup` command | +> | **Headers** | | Additional headers | +> | content-type | `application/json` | The content type | +> | correlation-id | \ | The same correlation id as the request message | +> | **Status** | | Status of the `backup` operation | + +
+ +**Example** : Successful response of a `backup` operation. + +**Topic:** `command//edge:device/res//backup`` +```json +{ + "topic":"edge/device/things/live/messages/backup", + "headers":{ + "content-type":"application/json", + "correlation-id":"" + }, + "path":"/features/BackupAndRestore/outbox/messages/backup", + "status":204 +} +``` +
+ +## **Restore** +Restore the backed up files or directory from a backend service. + +
+ Request + +**Hono Command:** `command//:/req//restore` + +**Ditto Message:** + +> | Name | Value | Description | +> | - | - | - | +> | topic | `//things/live/messages/restore` | Information about the affected Thing and the type of operation | +> | path | `/features/BackupAndRestore/inbox/messages/restore` | A path to the `BackupAndRestore` Feature, it's message channel, and `restore` command | +> | **Headers** | | Additional headers | +> | response-required | true/false | If response is required | +> | content-type | `application/json` | The content type | +> | correlation-id | UUID | Used for correlating protocol messages, the same correlation-id as the sent back response message | +> | **Value** | | | +> | correlationID | other UUID | Identifier of the restored file | +> | providers | | Storage provider, one of `aws`, `azure`, `generic` | +> | **options** | | Options are specific for each provider | +> | backup.dir | | A local directory, which to be backed up and then uploaded, using a storage provider of choice and temporary credentials | +> | https.url | | The URL for restoring the backed up directory | + +
+ +**Example** : Restore a backup from a storage provider. + +**Topic:** `command//edge:device/req//restore` +```json +{ + "topic":"edge/device/things/live/messages/restore", + "headers":{ + "response-required":true, + "content-type":"application/json", + "correlation-id":"" + }, + "path":"/features/BackupAndRestore/inbox/messages/restore", + "value":{ + "correlationID":"upload-id-1704439450#n", + "providers":{}, + "options":{ + "backup.dir":"/var/tmp/backup", + "https.url":"https://raw.githubusercontent.com/eclipse-kanto/container-management/main/containerm/pkg/testutil/config/" + } + } +} +``` +
+ +
+ Response + +**Hono Command** : `command//:/res//restore` + +**Ditto Message:** + +> | Name | Value | Description | +> | - | - | - | +> | topic | `//things/live/messages/restore` | Information about the affected Thing and the type of operation | +> | path | `/features/BackupAndRestore/outbox/messages/restore` | A path to the `BackupAndRestore` Feature, it's message channel, and `restore` command | +> | **Headers** | | Additional headers | +> | content-type | `application/json` | The content type | +> | correlation-id | \ | The same correlation id as the request message | +> | **Status** | | Status of the operation restore | + +
+ +**Example** : Response of a successful `restore` operation. + +**Topic:** `command//edge:device/res//restore`` +```json +{ + "topic":"edge/device/things/live/messages/restore", + "headers":{ + "content-type":"application/json", + "correlation-id":"" + }, + "path":"/features/BackupAndRestore/outbox/messages/restore", + "status": 204 +} +``` +
\ No newline at end of file diff --git a/web/site/content/docs/references/file-backup-config.md b/web/site/content/docs/references/file-backup/file-backup-config.md similarity index 99% rename from web/site/content/docs/references/file-backup-config.md rename to web/site/content/docs/references/file-backup/file-backup-config.md index 896e0298..3ee3363b 100644 --- a/web/site/content/docs/references/file-backup-config.md +++ b/web/site/content/docs/references/file-backup/file-backup-config.md @@ -3,7 +3,7 @@ title: "File backup configuration" type: docs description: > Customize the files backup and restore to and from a backend storage. -weight: 6 +weight: 3 --- ### Properties diff --git a/web/site/content/docs/references/file-upload/_index.md b/web/site/content/docs/references/file-upload/_index.md new file mode 100644 index 00000000..89b70031 --- /dev/null +++ b/web/site/content/docs/references/file-upload/_index.md @@ -0,0 +1,7 @@ +--- +title: "File Upload" +type: docs +description: > + Customize the files transfer to a backend storage. +weight: 5 +--- diff --git a/web/site/content/docs/references/file-upload/file-upload-api.md b/web/site/content/docs/references/file-upload/file-upload-api.md new file mode 100644 index 00000000..cda70cff --- /dev/null +++ b/web/site/content/docs/references/file-upload/file-upload-api.md @@ -0,0 +1,401 @@ +--- +title: "File Upload API" +type: docs +description: > + The file upload service provides the ability to start, trigger, cancel, activate or deactivate upload of the file. +weight: 4 +--- + +## **Start** +Start a file upload operation. + +
+ Request + +**Hono Command:** `command//:/req//start` + +**Ditto Message:** + +> | Name | Value | Description | +> | - | - | - | +> | topic | `//things/live/messages/start` | Information about the affected Thing and the type of operation | +> | path | `/features/AutoUploadable/inbox/messages/start` | A path to the `AutoUploadable` 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 | UUID | Used for correlating protocol messages, the same correlation-id as the sent back response message | +> | **Value** | | | +> | correlationID | other UUID | Identifier of the uploaded file | +> | **options** | | Options are specific for each provider | +> | storage.provider | aws/azure/generic | Storage provider that will be used for uploading the files | + +
+ +**Example** : Start uploading a file. + +**Topic:** `command//edge:device/req//start` +```json +{ + "topic":"edge/device/things/live/messages/start", + "headers":{ + "response-required":true, + "content-type":"application/json", + "correlation-id":"" + }, + "path":"/features/AutoUploadable/inbox/messages/start", + "value":{ + "correlationID":"upload-id-1704439450#n", + "options":{ + "aws.access.key.id":"AWSACCESSKEYID", + "aws.region":"eu-central-1", + "aws.s3.bucket":"blob-upload-test", + "aws.secret.access.key":"AWSSECRETACCESSKEY", + "storage.provider":"aws" + } + } +} +``` +
+ +
+ Response + +**Hono Command** : `command//:/res//start` + +**Ditto Message:** + +> | Name | Value | Description | +> | - | - | - | +> | topic | `//things/live/messages/start` | Information about the affected Thing and the type of operation | +> | path | `/features/AutoUploadable/outbox/messages/start` | A path to the `AutoUploadable` Feature, it's message channel, and `start` command | +> | **Headers** | | Additional headers | +> | content-type | `application/json` | The content type | +> | correlation-id | \ | The same correlation id as the sent request message | +> | **Status** | | Status of the operation start upload the file | + +
+ +**Example** : Successful response of a `start` file upload operation. + +**Topic:** `command//edge:device/res//start`` +```json +{ + "topic":"edge/device/things/live/messages/start", + "headers":{ + "content-type":"application/json", + "correlation-id":"" + }, + "path":"/features/AutoUploadable/outbox/messages/start", + "status": 204 +} +``` +
+ +## **Trigger** +Trigger a file upload operation. + +
+ Request + +**Hono Command:** `command//:/req//trigger` + +**Ditto Message:** + +> | Name | Value | Description | +> | - | - | - | +> | topic | `//things/live/messages/trigger` | Information about the affected Thing and the type of operation | +> | path | `/features/AutoUploadable/inbox/messages/trigger` | A path to the `AutoUploadable` Feature, it's message channel, and `trigger` command | +> | **Headers** | | Additional headers | +> | response-required | true/false | If response is required | +> | content-type | `application/json` | The content type | +> | correlation-id | UUID | Used for correlating protocol messages, the same correlation-id as the sent back response message | +> | **Value** | | | +> | correlationID | other UUID | Identifier of the triggered file | +> | **options** | | Options are specific for each provider | + +
+ +**Example** : Trigger a file upload operation. + +**Topic:** `command//edge:device/req//trigger` +```json +{ + "topic":"edge/device/things/live/messages/trigger", + "headers":{ + "response-required":true, + "content-type":"application/json", + "correlation-id":"" + }, + "path":"/features/AutoUploadable/inbox/messages/trigger", + "value":{ + "correlationID":"other ", + "options":{} + } +} +``` +
+ +
+ Response + +**Hono Command** : `command//:/res//trigger` + +**Ditto Message:** + +> | Name | Value | Description | +> | - | - | - | +> | topic | `//things/live/messages/trigger` | Information about the affected Thing and the type of operation | +> | path | `/features/AutoUploadable/outbox/messages/trigger` | A path to the `AutoUploadable` Feature, it's message channel, and `trigger` command | +> | **Headers** | | Additional headers | +> | content-type | `application/json` | The content type | +> | correlation-id | \ | The same correlation id as the sent request message | +> | **Status** | | Status of the `trigger` operation | + +
+ +**Example** : Successful response of a `trigger` operation. + +**Topic:** `command//edge:device/res//trigger`` +```json +{ + "topic":"edge/device/things/live/messages/trigger", + "headers":{ + "content-type":"application/json", + "correlation-id":"" + }, + "path":"/features/AutoUploadable/outbox/messages/trigger", + "status":204 +} +``` +
+ +## **Cancel** +Cancel a file upload operation. + +
+ Request + +**Hono Command:** `command//:/req//cancel` + +**Ditto Message:** + +> | Name | Value | Description | +> | - | - | - | +> | topic | `//things/live/messages/cancel` | Information about the affected Thing and the type of operation | +> | path | `/features/AutoUploadable/inbox/messages/cancel` | A path to the `AutoUploadable` Feature, it's message channel, and `cancel` command | +> | **Headers** | | Additional headers | +> | response-required | true/false | If response is required | +> | content-type | `application/json` | The content type | +> | correlation-id | UUID | Used for correlating protocol messages, the same correlation-id as the sent back response message | +> | **Value** | | | +> | correlationID | other UUID | Identifier of the uploaded file | +> | statusCode | | This status code is set to update status code | +> | message | | This message is set to update status message | + +
+ +**Example** : Cancel a file upload operation. + +**Topic:** `command//edge:device/req//cancel` +```json +{ + "topic":"edge/device/things/live/messages/cancel", + "headers":{ + "response-required":true, + "content-type":"application/json", + "correlation-id":"" + }, + "path":"/features/AutoUploadable/inbox/messages/cancel", + "value":{ + "correlationID":"upload-id-1704439450#n", + "statusCode": 400, + "message":"description why the upload is canceled " + } +} +``` +
+ +
+ Response + +**Hono Command** : `command//:/res//cancel` + +**Ditto Message:** + +> | Name | Value | Description | +> | - | - | - | +> | topic | `//things/live/messages/cancel` | Information about the affected Thing and the type of operation | +> | path | `/features/AutoUploadable/outbox/messages/cancel` | A path to the `AutoUploadable` Feature, it's message channel, and `cancel` command | +> | **Headers** | | Additional headers | +> | content-type | `application/json` | The content type | +> | correlation-id | \ | The same correlation id as the sent request message | +> | **Status** | | Status of the operation `cancel` file upload | + +
+ +**Example** : The response of the cancel file upload operation. + +**Topic:** `command//edge:device/res//cancel`` +```json +{ + "topic":"edge/device/things/live/messages/cancel", + "headers":{ + "content-type":"application/json", + "correlation-id":"" + }, + "path":"/features/AutoUploadable/outbox/messages/cancel", + "status":204 +} +``` +
+ +## **Activate** +Activate an upload of a file. + +
+ Request + +**Hono Command:** `command//:/req//activate` + +**Ditto Message:** + +> | Name | Value | Description | +> | - | - | - | +> | topic | `//things/live/messages/activate` | Information about the affected Thing and the type of operation | +> | path | `/features/AutoUploadable/inbox/messages/activate` | A path that references a part of a Thing which is affected by this message | +> | **Headers** | | Additional headers | +> | response-required | true/false | If response is required | +> | content-type | `application/json` | The content type | +> | correlation-id | UUID | Used for correlating protocol messages, the same correlation-id as the sent back response message | +> | **Value** | | | +> | from | | A Time after which the upload must be activated | +> | to | | A Time grater than `from` marks the end of activated | + +
+ +**Example** : Activate file upload. + +**Topic:** `command//edge:device/req//activate` +```json +{ + "topic":"edge/device/things/live/messages/activate", + "headers":{ + "response-required":true, + "content-type":"application/json", + "correlation-id":"" + }, + "path":"/features/AutoUploadable/inbox/messages/activate", + "value":{ + "from":957139200, + "to":959817599 + } +} +``` +
+ +
+ Response + +**Hono Command** : `command//:/res//activate` + +**Ditto Message:** + +> | Name | Value | Description | +> | - | - | - | +> | topic | `//things/live/messages/activate` | Information about the affected Thing and the type of operation | +> | path | `/features/AutoUploadable/outbox/messages/activate` | A path to the `AutoUploadable` Feature, it's message channel, and `activate` command | +> | **Headers** | | Additional headers | +> | content-type | `application/json` | The content type | +> | correlation-id | \ | The same correlation id as the sent request message | +> | **Status** | | Status of the operation `activate` file upload | + +
+ +**Example** : Successful response of an activate file upload operation. + +**Topic:** `command//edge:device/res//activate`` +```json +{ + "topic":"edge/device/things/live/messages/activate", + "headers":{ + "content-type":"application/json", + "correlation-id":"" + }, + "path":"/features/AutoUploadable/outbox/messages/activate", + "status":204 +} +``` +
+ +## **Deactivate** +Deactivate a file upload. + +
+ Request + +**Hono Command:** `command//:/req//deactivate` + +**Ditto Message:** + +> | Name | Value | Description | +> | - | - | - | +> | topic | `//things/live/messages/deactivate` | Information about the affected Thing and the type of operation | +> | path | `/features/AutoUploadable/inbox/messages/deactivate` | A path to the `AutoUploadable` Feature, it's message channel, and `deactivate` command | +> | **Headers** | | Additional headers | +> | response-required | true/false | If response is required | +> | content-type | `application/json` | The content type | +> | correlation-id | UUID | Used for correlating protocol messages, the same correlation-id as the response message | +> | **Value** | | | + +
+ +**Example** : Deactivate a file upload. + +**Topic:** `command//edge:device/req//deactivate` +```json +{ + "topic":"edge/device/things/live/messages/deactivate", + "headers":{ + "response-required":true, + "content-type":"application/json", + "correlation-id":"" + }, + "path":"/features/AutoUploadable/inbox/messages/deactivate", + "value":{} +} +``` +
+ +
+ Response + +**Hono Command** : `command//:0/res//deactivate` + +**Ditto Message:** + +> | Name | Value | Description | +> | - | - | - | +> | topic | `//things/live/messages/deactivate` | Information about the affected Thing and the type of operation | +> | path | `/features/AutoUploadable/outbox/messages/deactivate` | A path to the `AutoUploadable` Feature, it's message channel, and `deactivate` command | +> | **Headers** | | Additional headers | +> | content-type | `application/json` | The content type | +> | correlation-id | \ | The same correlation id as the sent request message | +> | **Status** | | Status of the operation `deactivate` file upload | + +
+ +**Example** : Successful response of the `deactivate` file upload operation. + +**Topic:** `command//edge:device/res//deactivate`` +```json +{ + "topic":"edge/device/things/live/messages/deactivate", + "headers":{ + "content-type":"application/json", + "correlation-id":"" + }, + "path":"/features/AutoUploadable/outbox/messages/deactivate", + "status":204 +} +``` +
\ No newline at end of file diff --git a/web/site/content/docs/references/file-upload-config.md b/web/site/content/docs/references/file-upload/file-upload-config.md similarity index 99% rename from web/site/content/docs/references/file-upload-config.md rename to web/site/content/docs/references/file-upload/file-upload-config.md index d94c3fc9..3b150d0a 100644 --- a/web/site/content/docs/references/file-upload-config.md +++ b/web/site/content/docs/references/file-upload/file-upload-config.md @@ -3,7 +3,7 @@ title: "File upload configuration" type: docs description: > Customize the files transfer to a backend storage. -weight: 5 +weight: 3 --- ### Properties diff --git a/web/site/content/docs/references/software-updatable/_index.md b/web/site/content/docs/references/software-updatable/_index.md new file mode 100644 index 00000000..26846e84 --- /dev/null +++ b/web/site/content/docs/references/software-updatable/_index.md @@ -0,0 +1,7 @@ +--- +title: "Software Updatable" +type: docs +description: > + Customize the deployment and management of software artifacts. +weight: 4 +--- diff --git a/web/site/content/docs/references/software-updatable/software-updatable-api.md b/web/site/content/docs/references/software-updatable/software-updatable-api.md new file mode 100644 index 00000000..288248c1 --- /dev/null +++ b/web/site/content/docs/references/software-updatable/software-updatable-api.md @@ -0,0 +1,243 @@ +--- +title: "Software Updatable API" +type: docs +description: > + The software updatable service provides the ability to install given list of software modules and to download modules. +weight: 4 +--- + +## **Install** +Install given list of software modules. + +
+ Request + +**Hono Command:** `command//:/req//install` + +**Ditto Message:** + +> | Name | Value | Description | +> | - | - | - | +> | topic | `//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 | UUID | Used for correlating protocol messages, the same correlation-id as the response message | +> | **Value** | | JSON presentation of software module that will be installed | +> | 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 remove the software modules | +> | **softwareModules** | | An array of software modules to 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 | +> | size | | Artifact file size in bytes | +> | **download** | | A map with protocols and links for downloading the artifacts | +> | 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 | +> | SHA1 | | MD5 checksum | +> | SHA256 | | MD5 checksum | + +
+ +**Example** : Install a `hello-world` software module. + +**Topic:** `command//edge:device/req//install` +```json +{ + "topic":"edge/device/things/live/messages/install", + "headers":{ + "response-required":true, + "content-type":"application/json", + "correlation-id":"" + }, + "path":"/features/SoftwareUpdatable/inbox/messages/install", + "value":{ + "correlationId":"other_correlation_id", + "softwareModules":[ + { + "softwareModule":{ + "name":"install-hello", + "version":"1.0.0" + }, + "artifacts":[ + { + "checksums":{ + "SHA256":"db954c633393c1402f145a60fd58d312f5af96ce49422fcfd6ce42a3c4cceeca", + "MD5":"8c5a0fa2c01e218262d672bf643652fd", + "SHA1":"7539b451d818d94bcd97d401a5467b3e1c0b8981" + }, + "download":{ + "HTTPS":{ + "url":"https://github.com/eclipse-kanto/kanto/raw/main/quickstart/install_hello.sh" + } + }, + "filename":"install.sh", + "size":544 + } + ] + } + ] + } +} +``` +
+ +
+ Response + +**Hono Command** : `command//:/res//install` + +**Ditto Message:** + +> | Name | Value | Description | +> | - | - | - | +> | topic | `//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 | \ | The same correlation id as the sent request message | +> | **Status** | | Status of the operation install software modules | + +
+ +**Example** : The response of the install software modules operation. + +**Topic:** `command//edge:device/res//install`` +```json +{ + "topic":"edge/device/things/live/messages/install", + "headers":{ + "content-type":"application/json", + "correlation-id":"" + }, + "path":"/features/SoftwareUpdatable/outbox/messages/install", + "status": 204 +} +``` +
+ +## **Download** +Download software modules. + +
+ Request + +**Hono Command:** `command//:/req//download` + +**Ditto Message:** + +> | Name | Value | Description | +> | - | - | - | +> | topic | `//things/live/messages/download` | Information about the affected Thing and the type of operation | +> | path | `/features/SoftwareUpdatable/inbox/messages/download` | A path to the `SoftwareUpdatable` Feature, it's message channel, and `download` command | +> | **Headers** | | Additional headers | +> | response-required | true/false | If response is required | +> | content-type | `application/json` | The content type | +> | correlation-id | UUID | Used for correlating protocol messages, the same correlation-id as the sent back response message | +> | **Value** | | JSON representation of the software modules that will be downloaded | +> | 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 | Remove the software modules forcefully | +> | **softwareModules** | | An array of software modules that will be downloaded| +> | metadata | | The metadata is any other information which should be passed to the device | +> | **softwareModule** | | A 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 | +> | size | | Artifact file size in bytes | +> | **download** | | A map with protocols and links for downloading the artifacts | +> | 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 | +> | SHA1 | | MD5 checksum | +> | SHA256 | | MD5 checksum | + +
+ +**Example** : Download a hello-world software module. + +**Topic:** `command//edge:device/req//download` +```json +{ + "topic":"edge/device/things/live/messages/download", + "headers":{ + "response-required":true, + "content-type":"application/json", + "correlation-id":"" + }, + "path":"/features/SoftwareUpdatable/inbox/messages/download", + "value": { + "correlationId":"other_correlation_id", + "softwareModules":[ + { + "softwareModule":{ + "name":"install-hello", + "version":"1.0.0" + }, + "artifacts":[ + { + "checksums":{ + "SHA256":"db954c633393c1402f145a60fd58d312f5af96ce49422fcfd6ce42a3c4cceeca", + "MD5":"8c5a0fa2c01e218262d672bf643652fd", + "SHA1":"7539b451d818d94bcd97d401a5467b3e1c0b8981" + }, + "download":{ + "HTTPS":{ + "url":"https://github.com/eclipse-kanto/kanto/raw/main/quickstart/install_hello.sh" + } + }, + "filename":"install.sh", + "size":544 + } + ] + } + ], + } +} +``` +
+ +
+ Response + +**Hono Command** : `command//:/res//download` + +**Ditto Message:** + +> | Name | Value | Description | +> | - | - | - | +> | topic | `//things/live/messages/download` | Information about the affected Thing and the type of operation | +> | path | `/features/SoftwareUpdatable/outbox/messages/download` | A path to the `SoftwareUpdatable` Feature, it's message channel, and `download` command | +> | **Headers** | | Additional headers | +> | correlation-id | container UUID | The same correlation id as the request message | +> | **Status** | | Status of the `download` operation | + +
+ +**Example** : Successful download response. + +**Topic:** `command//edge:device/res//download`` +```json +{ + "topic":"edge/device/things/live/messages/download", + "headers":{ + "correlation-id":"" + }, + "path":"/features/SoftwareUpdatable/outbox/messages/download", + "status":204 +} +``` +
\ No newline at end of file diff --git a/web/site/content/docs/references/software-update-config.md b/web/site/content/docs/references/software-updatable/software-update-config.md similarity index 99% rename from web/site/content/docs/references/software-update-config.md rename to web/site/content/docs/references/software-updatable/software-update-config.md index d0abf059..6bce0ef4 100644 --- a/web/site/content/docs/references/software-update-config.md +++ b/web/site/content/docs/references/software-updatable/software-update-config.md @@ -3,7 +3,7 @@ title: "Software update configuration" type: docs description: > Customize the deployment and management of software artifacts. -weight: 4 +weight: 3 --- ### Properties diff --git a/web/site/content/docs/references/system-metrics/_index.md b/web/site/content/docs/references/system-metrics/_index.md new file mode 100644 index 00000000..7099b20c --- /dev/null +++ b/web/site/content/docs/references/system-metrics/_index.md @@ -0,0 +1,7 @@ +--- +title: "System Metrics" +type: docs +description: > + Customize the reporting of system metrics. +weight: 7 +--- diff --git a/web/site/content/docs/references/system-metrics/system-metrics-api.md b/web/site/content/docs/references/system-metrics/system-metrics-api.md new file mode 100644 index 00000000..06990ed9 --- /dev/null +++ b/web/site/content/docs/references/system-metrics/system-metrics-api.md @@ -0,0 +1,175 @@ +--- +title: "System Metrics API" +type: docs +description: > + The system metrics service provides the ability to request and receive metrics data. +weight: 4 +--- + +## **Request** +Request to receive metrics data. + +
+ Request + +**Hono Command:** `command//:/req//request` + +**Ditto Message:** + +> | Name | Value | Description | +> | - | - | - | +> | topic | `//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 | Used for correlating protocol messages, the same correlation-id as the sent back response message | +> | **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 specified filter and frequency. + +**Topic:** `command//edge:device/req//request` +```json +{ + "topic":"edge/device/things/live/messages/request", + "headers":{ + "response-required":true, + "content-type":"application/json", + "correlation-id":"" + }, + "path":"/features/Metrics/inbox/messages/request", + "value":{ + "filter":[ + { + "id":["io.*","cpu.*","memory.*"], + "originator":"SYSTEM" + } + ], + "frequency":"5s" + } +} +``` +
+ +
+ Response + +**Hono Command** : `command//:/res//request` + +**Ditto Message:** + +> | Name | Value | Description | +> | - | - | - | +> | topic | `//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 | \ | The same correlation id as the request message | +> | **Status** | | Status of the operation request the metrics data | + +
+ +**Example** : Successful response of a `request` metrics message. + +**Topic:** `command//edge:device/res//request`` +```json +{ + "topic":"edge/device/things/live/messages/request", + "headers":{ + "content-type":"application/json", + "correlation-id":"" + }, + "path":"/features/Metrics/outbox/messages/request", + "status": 204 +} +``` +
+ +## **Data** +Metrics data reported by the device. + +
+ Response + +**Hono Command** : `command//:/res//data` + +**Ditto Message:** + +> | Name | Value | Description | +> | - | - | - | +> | topic | `//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, it's message channel, and metrics data | +> | **Headers** | | Additional headers | +> | content-type | `application/json` | The content type | +> | **Value** | | The value of the received data from the device in json format | +> | timestamp | | The timestamp in ms when this measure data is published | +> | **snapshot** | | All the measurements collected at a concrete time 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, cpu.load1, cpu.load5, cpu.load15, memory.utilization, memory.total, memory.available, memory.used, io.readBytes, io.writeBytes | +> | value | | The measured value per metric ID | + +
+ +**Example** : Metrics data from the device. + +**Topic:** `command//edge:device/res//data`` +```json +{ + "topic":"edge/device/things/live/messages/data", + "headers":{ + "content-type":"application/json", + }, + "path":"/features/Metrics/outbox/messages/data", + "value":{ + "snapshot":[ + { + "originator":"SYSTEM", + "measurements":[ + { + "id":"cpu.utilization", + "value":1.1555555555484411 + }, + { + "id":"cpu.load1", + "value":0.17 + }, + { + "id":"cpu.load5", + "value":0.27 + }, + { + "id":"cpu.load15", + "value":0.24 + }, + { + "id":"memory.total", + "value":10371616768 + }, + { + "id":"memory.available", + "value":5281644544 + }, + { + "id":"memory.used", + "value":4563206144 + }, + { + "id":"memory.utilization", + "value":43.99705702662538 + } + ] + } + ], + "timestamp":1234567890 + } +} +``` +
diff --git a/web/site/content/docs/references/system-metrics-config.md b/web/site/content/docs/references/system-metrics/system-metrics-config.md similarity index 99% rename from web/site/content/docs/references/system-metrics-config.md rename to web/site/content/docs/references/system-metrics/system-metrics-config.md index 004d1b1f..9e325dd3 100644 --- a/web/site/content/docs/references/system-metrics-config.md +++ b/web/site/content/docs/references/system-metrics/system-metrics-config.md @@ -3,7 +3,7 @@ title: "System metrics configuration" type: docs description: > Customize the reporting of system metrics. -weight: 7 +weight: 3 --- ### Properties diff --git a/web/site/content/docs/references/update-manager/_index.md b/web/site/content/docs/references/update-manager/_index.md new file mode 100644 index 00000000..75500f1e --- /dev/null +++ b/web/site/content/docs/references/update-manager/_index.md @@ -0,0 +1,7 @@ +--- +title: "Update Manager" +type: docs +description: > + The kanto update manager service provides orchestration of OTA Updates towards a target device in a smart way. +weight: 8 +--- diff --git a/web/site/content/docs/references/update-manager/update-manager-api.md b/web/site/content/docs/references/update-manager/update-manager-api.md new file mode 100644 index 00000000..823bd3f0 --- /dev/null +++ b/web/site/content/docs/references/update-manager/update-manager-api.md @@ -0,0 +1,212 @@ +--- +title: "Update Manager API" +type: docs +description: > + The kanto update manager service provides orchestration of OTA Updates towards a target device in a smart way. +weight: 5 +--- + +## **Apply** +Applies a [desired state](https://github.com/eclipse-kanto/update-manager/blob/main/docs/desired-state-specification.md) to the device. + +
+ Request + +**Hono Command:** `command//:/req//apply` + +**Ditto Message:** + +> | Name | Value | Description | +> | - | - | - | +> | topic | `//things/live/messages/apply` | Information about the affected Thing and the type of operation | +> | path | `/features/UpdateManager/inbox/messages/apply` | A path to the `UpdateManager` Feature, it's message channel, and `apply` command | +> | **Headers** | | Additional headers | +> | response-required | true/false | If response is required | +> | content-type | `application/json` | The content type | +> | correlation-id | container UUID | Used for correlating protocol messages, the same correlation-id as the sent back response message | +> | **Value** | | | +> | activityId | | The activity id of the new desired state | +> | **desiredState** | | The [desired state](https://github.com/eclipse-kanto/update-manager/blob/main/docs/desired-state-specification.md) to be applied on a device | +> | **baselines** | | An array of domain or cross-domain dependencies between components | +> | title | | The title of the dependency | +> | description | | The description of the dependency | +> | preconditions | | The preconditions of the dependency | +> | components | | An array of the components of the dependency | +> | **domains** | | An array of desired state for a single domain | +> | id | | The id of this domain| +> | **config** | | An array of key/value string pair| +> | key | | The key string | +> | value | | The value of the key string | +> | **components** | | An array of desired state component with additional key-value configuration pairs | +> | id | | The id of the component | +> | version | | The version of the component | +> | key | | The key string | +> | value | | The value of the key string | + +
+ +**Example** : Apply a desired state to the device. + +**Topic:** `command//edge:device/req//apply` +```json +{ + "topic":"edge/device/things/live/messages/apply", + "headers":{ + "response-required":true, + "content-type":"application/json", + "correlation-id":"" + }, + "path":"/features/UpdateManager/inbox/messages/apply", + "value":{ + "activityId": "d91ad6fe-9b0c-4549-bf31-17d0a71b61de", + "desiredState": { + "baselines": [ + { + "title": "simple-baseline", + "description": "", + "precondition": "", + "components": [ + "domain:component1", + "domain:component2" + ] + } + ], + "domains": [ + { + "id": "containers", + "config": [ + { + "key": "source", + "value": "value" + } + ], + "components": [ + { + "id": "containers:influxdb", + "version": "2.7.1", + "config": [ + { + "key": "image", + "value": "docker.io/library/influxdb:$influxdb_version" + } + ] + } + ] + } + ] + } + } +} +``` +
+ +
+ Response + +**Hono Command** : `command//:/res//apply` + +**Ditto Message:** + +> | Name | Value | Description | +> | - | - | - | +> | topic | `//things/live/messages/apply` | Information about the affected Thing and the type of operation | +> | path | `/features/UpdateManager/outbox/messages/apply` | A path to the `UpdateManager` Feature, it's message channel, and `apply` command | +> | **Headers** | | Additional headers | +> | content-type | `application/json` | The content type | +> | correlation-id | \ | The same correlation id as the request message | +> | **Status** | | Status of the operation apply | + +
+ + +**Example** : Successful response of an `apply` desired state operation. + +**Topic:** `command//edge:device/res//apply` +```json +{ + "topic": "edge/device/things/live/messages/apply", + "headers": { + "content-type": "application/json", + "correlation-id": "" + }, + "path": "/features/UpdateManager/outbox/messages/apply", + "status": 204 +} +``` +
+ +## **Refresh** +Reads the [current state](https://github.com/eclipse-kanto/update-manager/blob/main/docs/current-state-specification.md) from the device and updates the status of the `UpdateManager` feature. + +
+ Request + +**Hono Command:** `command//:/req//refresh` + +**Ditto Message:** + +> | Name | Value | Description | +> | - | - | - | +> | topic | `//things/live/messages/refresh` | Information about the affected Thing and the type of operation | +> | path | `/features/UpdateManager/inbox/messages/refresh` | A path to the `UpdateManager` Feature, it's message channel, and `refresh` 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** | | | +> | activityId | | The activity id of the `refresh` operation | + +
+ +**Example** : Update the status of the `UpdateManager` feature. + +**Topic:** `command//edge:device/req//refresh` +```json +{ + "topic": "edge/device/things/live/messages/refresh", + "headers": { + "response-required": true, + "content-type":" application/json", + "correlation-id": "" + }, + "path": "/features/UpdateManager/inbox/messages/refresh", + "value": { + "activityId": "e08b071c-c19e-41de-8da0-e2843113161f" + } +} +``` +
+ +
+ Response + +**Hono Command** : `command//:/res//refresh` + +**Ditto Message:** + +> | Name | Value | Description | +> | - | - | - | +> | topic | `//things/live/messages/refresh` | Information about the affected Thing and the type of operation | +> | path | `/features/UpdateManager/outbox/messages/refresh` | A path to the `UpdateManager` Feature, it's message channel, and `refresh` command | +> | **Headers** | | Additional headers | +> | content-type | `application/json` | The content type | +> | correlation-id | \ | The same correlation id as the request message | +> | **Status** | | Status of the `refresh` operation | + +
+ +**Example** : Successful response of a `refresh` operation. + +**Topic:** `command//edge:device/res//refresh` +```json +{ + "topic": "edge/device/things/live/messages/refresh", + "headers": { + "content-type": "application/json", + "correlation-id": "" + }, + "path": "/features/UpdateManager/outbox/messages/refresh", + "status": 204 +} +``` +
\ No newline at end of file diff --git a/web/site/content/docs/references/update-manager-config.md b/web/site/content/docs/references/update-manager/update-manager-config.md similarity index 100% rename from web/site/content/docs/references/update-manager-config.md rename to web/site/content/docs/references/update-manager/update-manager-config.md