-
Notifications
You must be signed in to change notification settings - Fork 8
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add Documentation for the Update Manager (#337)
[#336] Add Documentation for the Update Manager * [#243] Prepare documentation page for the Containers Component configuration (#270) * [#279] Add description for generic flag in suite connector (#280) * [#326] Update UM reference page in regard to owner approval (#327) * [#326] Update UM reference page in regard to owner approval (#330) * Remove signature.tar Signed-off-by: Stoyan Zoubev <[email protected]> Signed-off-by: Kristiyan Gostev <[email protected]> Signed-off-by: Hristo Bozhilov <[email protected]> Signed-off-by: Dimitar Dimitrov <[email protected]> Co-authored-by: Stoyan Zoubev <[email protected]> Co-authored-by: Hristo Bozhilov <[email protected]> Co-authored-by: Dimitar Dimitrov <[email protected]>
- Loading branch information
4 people
authored
Jun 4, 2024
1 parent
9ed6be5
commit 22c8da9
Showing
4 changed files
with
291 additions
and
2 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
179 changes: 179 additions & 0 deletions
179
web/site/content/docs/references/containers/container-component-config.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,179 @@ | ||
| --- | ||
| title: "Container configuration as Desired State component" | ||
| type: docs | ||
| description: > | ||
| Customize the deployment of a container instance as a Desired State component. | ||
| weight: 3 | ||
| --- | ||
|
|
||
| ### Domain Identifier | ||
| The default domain identifier for the Containers Update Agent is `containers`. | ||
| This can be modified within the update agent section in the [container management JSON config file](./container-manager-config). | ||
|
|
||
| ### Containers Update Agent Properties | ||
| To control the container update agent behavior through desired state specification. As defined in the Desired State Specification, all properties are of type string. | ||
|
|
||
| | Key | Required | Default | Description | | ||
| | - | - | - | - | | ||
| | systemContainers | No | | Comma-separated list of container names that shall not be processed by the update agent during the application of the given desired state. This configuration option can be used to temporarily override the general `systemContainers` setting from the update agent section in the container management JSON config file. The setting is valid only for the given desired state where it is present. | | ||
|
|
||
| ### Container Properties | ||
| To control all aspects of the container instance behavior. As defined in the Desired State Specification, all properties are of type string. | ||
|
|
||
| | Key | Required | Default | Description | | ||
| | - | - | - | - | | ||
| | **General config** | | | | | ||
| | image | Yes | | 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`. | | ||
| | env | No | | Sets the provided environment variable in the root container's process environment.Example: `VAR1=2`. If `VAR1`= is used, the environment variable would be set to empty. If `VAR1` is used, the environment variable would be removed from the container environment inherited from the image. The property can be included multiple times, each one specifying another environment variable. | | ||
| | cmd | No | | Command with arguments that is executed upon the container’s start. The property can be included multiple times (order is important), each one specifying another command argument. | | ||
| | **Host config** | | | | | ||
| | device | No | | Device to be made available in the container and optional cgroups permissions configuration. Both path on host and in container must be set. Possible cgroup permissions options are "r" (read), "w" (write), "m" (mknod) and all combinations of the three are possible. If not set, "rwm" is default device configuration. Example: `/dev/ttyACM0:/dev/ttyUSB0[:rwm]`. The property can be included multiple times, each one specifying a separate device. | | ||
| | port | No | | Port to be mapped from the host to the container instance. Format: `[<host-ip>:]<host-port>:<container-port>[-<range>][/<proto>]`. Most common use-case: `80:80`. Mapping the container's 80 port to a host port in the 5000-6000 range: `5000-6000:80/udp`. Specifying port protocol (default is tcp): `80:80/udp`. By default the port mapping will set on all network interfaces, but this is also manageable: `0.0.0.0:80-100:80/udp`. The property can be included multiple times, each one specifying another port mapping. | | ||
| | network | No | bridge | Sets the networking mode for the container. Possible options are: `bridge` - the container is connected to the default bridge network interface of the engine and is assigned an IP. `host` - the container shares the network stack of the host (use with caution as this breaks the network's isolation!) | | ||
| | host | No | | Extra host to be added in the current container's `/etc/hosts` file. Example: hostname1:<IP1>. If the IP of the host machine is to be added to the container's hosts file the reserved `host_ip[_<network-interface>]` must be provided. Example: `local.host.machine.ip.custom.if:host_ip_myNetIf0` - this will automatically resolve the host's IP on the `myNetIf0` network interface and add it to the container's hosts file. `local.host.machine.ip.default.bridge:host_ip` - this will automatically resolve the host's IP on the default bridge network interface for container management and add it to the container's hosts file if the container is configured to use it. The property can be included multiple times, each one specifying another extra host | | ||
| | mount | No | | Sets mount points so a source directory on the host can be accessed via a destination directory in the container. Format: `source:destination[:propagation_mode]`. If the propagation mode parameter is omitted, `rprivate` will be set by default. Available propagation modes are: `rprivate`, `private`, `rshared`, `shared`, `rslave`, `slave`. The property can be included multiple times, each one specifying another mount point. | | ||
| | **IO config** | | | | | ||
| | terminal | No | false | Boolean flag. Enables terminal for the current container, e.g. attach standard streams to a TTY. | | ||
| | interactive | No | false | Boolean flag. Enables interaction with the container, e.g. open the terminal's standard input for an interaction with the container. | | ||
| | privileged | No | false | Boolean flag. Creates the container as privileged, grants root capabilities to all devices on the host system | | ||
| | **Restart policy config** | | | | | ||
| | restartPolicy | string | unless-stopped | The container's restart policy, the supported values are: `always` - an attempt to restart the container will be made made each time the container exits regardless of the exit code, `no` - no attempts to restart the container for any reason will be made, `on-failure` - restart attempts will be made if the container exits with an exit code != 0, `unless-stopped` - restart attempts will be made only if the container has not been stopped by the user. | | ||
| | restartMaxRetries | No | 1 | Integer value. Maximum number of retries that are made to restart the container on exit with fail, valid only if the `restartPolicy` is `on-failure`. | | ||
| | restartTimeout | No | 30 | Integer value. Timeout period in seconds for each retry that is made to restart the container on exit with fail, valid only if the `restartPolicy` is `on-failure`. | | ||
| | **Logging config** | | | | | ||
| | logDriver | No | json-file | Sets the type of the log driver to be used for the container - `json-file`, `none`. | | ||
| | logMaxFiles | No | 2 | Integer value. Sets the max number of log files to be rotated - applicable for `json-file` log driver only. | | ||
| | logMaxSize | No | 100M | Sets the max size of the logs files for rotation in the form of 1, 1.2m, 1g, etc. - applicable for `json-file` log driver only. | | ||
| | logPath | No | | Sets the path to the directory where the log files will be stored - applicable for `json-file` log driver only. | | ||
| | logMode | No | blocking | Sets the mode of the logger - `blocking`, `non-blocking`. | | ||
| | logMaxBufferSize | No | 1M | Sets the max size of the logger buffer in the form of 1, 1.2m - applicable for `non-blocking` mode only. | | ||
| | **Resources config** | | | | | ||
| | memory | No | | Sets the max amount of memory the container can use in the form of 200m, 1.2g. The minimum allowed value is 3m. By default, a container has no memory constraints. | | ||
| | memorySwap | No | | Sets the total amount of memory + swap that the container can use in the form of 200m, 1.2g. If set must not be smaller than `memory`. If equal to `memory`, then the container will not have access to swap. If not set and `memory` is set, than the container can use as much swap as the `memory` setting. If set to -1, the container can use unlimited swap, up to the amount available on the host. | | ||
| | memoryReservation | No | | Sets a soft memory limitation in the form of 200m, 1.2g. Must be smaller than `memory`. When the system detects memory contention or low memory, control groups are pushed back to their soft limits. There is no guarantee that the container memory usage will not exceed the soft limit. | | ||
|
|
||
| #### Desired State Containers Domain Example | ||
|
|
||
| ```json | ||
| { | ||
| "domains": [ | ||
| { | ||
| "id": "containers", | ||
| "config": [ | ||
| { | ||
| "key": "systemContainers", | ||
| "value": "self-update-agent" | ||
| } | ||
| ], | ||
| "components": [ | ||
| { | ||
| "id": "hello-world", | ||
| "version": "latest", | ||
| "config": [ | ||
| { | ||
| "key": "image", | ||
| "value": "docker.io/library/hello-world:latest" | ||
| }, | ||
| { | ||
| "key": "env", | ||
| "value": "x=y" | ||
| }, | ||
| { | ||
| "key": "env", | ||
| "value": "a=b" | ||
| }, | ||
| { | ||
| "key": "cmd", | ||
| "value": "arg1" | ||
| }, | ||
| { | ||
| "key": "cmd", | ||
| "value": "arg2" | ||
| }, | ||
| { | ||
| "key": "device", | ||
| "value": "/dev/tty:/dev/tty:rw" | ||
| }, | ||
| { | ||
| "key": "port", | ||
| "value": "80:80/tcp" | ||
| }, | ||
| { | ||
| "key": "network", | ||
| "value": "host" | ||
| }, | ||
| { | ||
| "key": "host", | ||
| "value": "host_name" | ||
| }, | ||
| { | ||
| "key": "mount", | ||
| "value": "/data:/data:private" | ||
| }, | ||
| { | ||
| "key": "terminal", | ||
| "value": "true" | ||
| }, | ||
| { | ||
| "key": "interactive", | ||
| "value": "true" | ||
| }, | ||
| { | ||
| "key": "privileged", | ||
| "value": "true" | ||
| }, | ||
| { | ||
| "key": "restartPolicy", | ||
| "value": "always" | ||
| }, | ||
| { | ||
| "key": "restartMaxRetries", | ||
| "value": "3" | ||
| }, | ||
| { | ||
| "key": "restartTimeout", | ||
| "value": "1000" | ||
| }, | ||
| { | ||
| "key": "logDriver", | ||
| "value": "json-file" | ||
| }, | ||
| { | ||
| "key": "logMaxFiles", | ||
| "value": "3" | ||
| }, | ||
| { | ||
| "key": "logMaxSize", | ||
| "value": "5M" | ||
| }, | ||
| { | ||
| "key": "logPath", | ||
| "value": "/var/log" | ||
| }, | ||
| { | ||
| "key": "logMode", | ||
| "value": "blocking" | ||
| }, | ||
| { | ||
| "key": "logMaxBufferSize", | ||
| "value": "1M" | ||
| }, | ||
| { | ||
| "key": "memory", | ||
| "value": "200M" | ||
| }, | ||
| { | ||
| "key": "memorySwap", | ||
| "value": "300M" | ||
| }, | ||
| { | ||
| "key": "memoryReservation", | ||
| "value": "100M" | ||
| } | ||
| ] | ||
| } | ||
| ] | ||
| } | ||
| ] | ||
| } | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
109 changes: 109 additions & 0 deletions
109
web/site/content/docs/references/update-manager-config.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,109 @@ | ||
| --- | ||
| title: "Update manager configuration" | ||
| type: docs | ||
| description: > | ||
| Customize the update manager. | ||
| weight: 6 | ||
| --- | ||
|
|
||
| ### Properties | ||
|
|
||
| To control all aspects of the update manager. | ||
|
|
||
| | Property | Type | Default | Description | | ||
| | - | - | - | - | | ||
| | **General** | | | | | ||
| | domain | string | device | The domain of the update manager, used as MQTT topic prefix | | ||
| | domains | string | containers| A comma-separated list of domains handled by the update manager. This configuration option is available only as a flag, but not inside the JSON config file. In JSON config file, the keys inside the Domain agents structure serve as domain names. | | ||
| | phaseTimeout | string | 10m | Timeout as duration string for completing an Update Orchestration phase | | ||
| | rebootAfter | string | 30s | Time period as duration string to wait before a reboot process is initiated after successful update operation | | ||
| | rebootEnabled | bool | true | Enable the reboot process after successful update operation | | ||
| | reportFeedbackInterval | string | 1m | Time interval as duration string for reporting intermediate desired state feedback messages during an active update operation | | ||
| | currentStateDelay | string | 30s | Time interval as duration string for reporting current state messages | | ||
| | thingsEnabled | bool | true | Enable the Update Manager to behave as a thing's feature | | ||
| | ownerConsentCommands | []string | | List of commands for which an owner consent should be granted. Possible values are: 'DOWNLOAD', 'UPDATE', 'ACTIVATE' | | ||
| | ownerConsentTimeout | string | 30m | Timeout as duration string to wait for owner consent" | | ||
| | **Domain agents** | | | Holds a map structure (_agents_) with update agent configurations where each map key is treated as domain name | | ||
| | readTimeout | string | 1m | Timeout as duration string for reading the current state for the domain | | ||
| | rebootRequired | bool | false | Require a reboot for the domain after successful update | | ||
| | **Local connectivity** | | | | | ||
| | broker | string | tcp://localhost:1883 | Address of the MQTT server/broker that the container manager will connect for the local communication, the format is: `scheme://host:port` | | ||
| | keepAlive | string | 20s | Keep alive duration for the MQTT requests as duration string | | ||
| | disconnectTimeout | string | 250ms | Disconnect timeout for the MQTT server/broker as duration string | | ||
| | username | string | | Username that is a part of the credentials | | ||
| | password | string | | Password that is a part of the credentials | | ||
| | acknowledgeTimeout | string | 15s | Acknowledge timeout for the MQTT requests as duration string | | ||
| | connectTimeout | string | 30s | Connect timeout for the MQTT server/broker as duration string | | ||
| | subscribeTimeout | string | 15s | Subscribe timeout for the MQTT requests as duration string | | ||
| | unsubscribeTimeout | string | 5s | Unsubscribe timeout for the MQTT requests as duration string | | ||
| | **Logging** | | | | | ||
| | logFile | string | | Path to the file where the update manager’s log messages are written | | ||
| | logLevel | string | INFO | All log messages at this or a higher level will be logged, the log levels in descending order are: ERROR, WARN, INFO, DEBUG and TRACE | | ||
| | logFileCount | int | 5 | Log file maximum rotations count | | ||
| | logFileMaxAge | int | 28 | Log file rotations maximum age in days, use 0 to not remove old log files | | ||
| | logFileSize | int | 2 | Log file size in MB before it gets rotated | | ||
|
|
||
| ### Example | ||
|
|
||
| An example for configuring the update manager with two domains - `containers` and `custom-domain`, report feedback interval at 30 seconds, and log, written to custom log file `update-manager.log` with | ||
| log level `DEBUG`. | ||
|
|
||
| ```json | ||
| { | ||
| "log": { | ||
| "logFile": "update-manager.log", | ||
| "logLevel": "DEBUG" | ||
| }, | ||
| "agents": { | ||
| "containers": { | ||
| "readTimeout": "30s" | ||
| }, | ||
| "custom-domain": { | ||
| "rebootRequired": true | ||
| } | ||
| }, | ||
| "reportFeedbackInterval": "30s" | ||
| } | ||
| ``` | ||
|
|
||
| ### Template | ||
|
|
||
| The configuration can be further adjusted according to the use case. | ||
| The following template illustrates all possible properties with their default values. | ||
|
|
||
| ```json | ||
| { | ||
| "domain": "device", | ||
| "agents": { | ||
| "containers": { | ||
| "rebootRequired": false, | ||
| "readTimeout": "1m" | ||
| } | ||
| }, | ||
| "log": { | ||
| "logFile": "", | ||
| "logLevel": "INFO", | ||
| "logFileCount": 5, | ||
| "logFileMaxAge": 28, | ||
| "logFileSize": 2 | ||
| }, | ||
| "connection": { | ||
| "broker": "tcp://localhost:1883", | ||
| "keepAlive": "20s", | ||
| "acknowledgeTimeout": "15s", | ||
| "username": "", | ||
| "password": "", | ||
| "connectTimeout": "30a", | ||
| "disconnectTimeout": "250ms", | ||
| "subscribeTimeout": "15s", | ||
| "unsubscribeTimeout": "5s" | ||
| }, | ||
| "phaseTimeout": "10m", | ||
| "rebootAfter": "30s", | ||
| "rebootEnabled": true, | ||
| "reportFeedbackInterval": "1m", | ||
| "currentStateDelay": "30s", | ||
| "thingsEnabled": true, | ||
| "ownerConsentCommands": ["DOWNLOAD"] | ||
| } | ||
| ``` |