From be3e8f36329900ee5727ae49f743eea1f1c7f5a8 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Tue, 4 May 2021 15:47:17 +0200 Subject: [PATCH] update engine reference docs regenerated the yaml-docs with the latest changes from the 20.10 branch Signed-off-by: Sebastiaan van Stijn --- _data/engine-cli/docker_config.yaml | 2 +- _data/engine-cli/docker_config_create.yaml | 72 +++++++++++- _data/engine-cli/docker_config_inspect.yaml | 70 ++++++++++- _data/engine-cli/docker_config_ls.yaml | 124 +++++++++++++++++++- _data/engine-cli/docker_config_rm.yaml | 24 +++- _data/engine-cli/docker_stop.yaml | 4 +- 6 files changed, 290 insertions(+), 6 deletions(-) diff --git a/_data/engine-cli/docker_config.yaml b/_data/engine-cli/docker_config.yaml index 3689f3b235..81801f1d9f 100644 --- a/_data/engine-cli/docker_config.yaml +++ b/_data/engine-cli/docker_config.yaml @@ -1,6 +1,6 @@ command: docker config short: Manage Docker configs -long: Manage Docker configs +long: Manage configs. usage: docker config pname: docker plink: docker.yaml diff --git a/_data/engine-cli/docker_config_create.yaml b/_data/engine-cli/docker_config_create.yaml index 18fc458b5a..a064019741 100644 --- a/_data/engine-cli/docker_config_create.yaml +++ b/_data/engine-cli/docker_config_create.yaml @@ -1,6 +1,16 @@ command: docker config create short: Create a config from a file or STDIN -long: Create a config from a file or STDIN +long: |- + Creates a config using standard input or from a file for the config content. + + For detailed information about using configs, refer to [store configuration data using Docker Configs](https://docs.docker.com/engine/swarm/configs/). + + > **Note** + > + > This is a cluster management command, and must be executed on a swarm + > manager node. To learn about managers and workers, refer to the + > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the + > documentation. usage: docker config create [OPTIONS] CONFIG file|- pname: docker config plink: docker_config.yaml @@ -23,6 +33,66 @@ options: experimentalcli: false kubernetes: false swarm: false +examples: |- + ### Create a config + + ```bash + $ printf | docker config create my_config - + + onakdyv307se2tl7nl20anokv + + $ docker config ls + + ID NAME CREATED UPDATED + onakdyv307se2tl7nl20anokv my_config 6 seconds ago 6 seconds ago + ``` + + ### Create a config with a file + + ```bash + $ docker config create my_config ./config.json + + dg426haahpi5ezmkkj5kyl3sn + + $ docker config ls + + ID NAME CREATED UPDATED + dg426haahpi5ezmkkj5kyl3sn my_config 7 seconds ago 7 seconds ago + ``` + + ### Create a config with labels + + ```bash + $ docker config create \ + --label env=dev \ + --label rev=20170324 \ + my_config ./config.json + + eo7jnzguqgtpdah3cm5srfb97 + ``` + + ```bash + $ docker config inspect my_config + + [ + { + "ID": "eo7jnzguqgtpdah3cm5srfb97", + "Version": { + "Index": 17 + }, + "CreatedAt": "2017-03-24T08:15:09.735271783Z", + "UpdatedAt": "2017-03-24T08:15:09.735271783Z", + "Spec": { + "Name": "my_config", + "Labels": { + "env": "dev", + "rev": "20170324" + }, + "Data": "aGVsbG8K" + } + } + ] + ``` deprecated: false min_api_version: "1.30" experimental: false diff --git a/_data/engine-cli/docker_config_inspect.yaml b/_data/engine-cli/docker_config_inspect.yaml index 015af0db13..aae83ba95f 100644 --- a/_data/engine-cli/docker_config_inspect.yaml +++ b/_data/engine-cli/docker_config_inspect.yaml @@ -1,6 +1,22 @@ command: docker config inspect short: Display detailed information on one or more configs -long: Display detailed information on one or more configs +long: |- + Inspects the specified config. + + By default, this renders all results in a JSON array. If a format is specified, + the given template will be executed for each result. + + Go's [text/template](http://golang.org/pkg/text/template/) package + describes all the details of the format. + + For detailed information about using configs, refer to [store configuration data using Docker Configs](https://docs.docker.com/engine/swarm/configs/). + + > **Note** + > + > This is a cluster management command, and must be executed on a swarm + > manager node. To learn about managers and workers, refer to the + > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the + > documentation. usage: docker config inspect [OPTIONS] CONFIG [CONFIG...] pname: docker config plink: docker_config.yaml @@ -23,6 +39,58 @@ options: experimentalcli: false kubernetes: false swarm: false +examples: |- + ### Inspect a config by name or ID + + You can inspect a config, either by its *name*, or *ID* + + For example, given the following config: + + ```bash + $ docker config ls + + ID NAME CREATED UPDATED + eo7jnzguqgtpdah3cm5srfb97 my_config 3 minutes ago 3 minutes ago + ``` + + ```bash + $ docker config inspect config.json + ``` + + The output is in JSON format, for example: + + ```json + [ + { + "ID": "eo7jnzguqgtpdah3cm5srfb97", + "Version": { + "Index": 17 + }, + "CreatedAt": "2017-03-24T08:15:09.735271783Z", + "UpdatedAt": "2017-03-24T08:15:09.735271783Z", + "Spec": { + "Name": "my_config", + "Labels": { + "env": "dev", + "rev": "20170324" + }, + "Data": "aGVsbG8K" + } + } + ] + ``` + + ### Formatting + + You can use the --format option to obtain specific information about a + config. The following example command outputs the creation time of the + config. + + ```bash + $ docker config inspect --format='{{.CreatedAt}}' eo7jnzguqgtpdah3cm5srfb97 + + 2017-03-24 08:15:09.735271783 +0000 UTC + ``` deprecated: false min_api_version: "1.30" experimental: false diff --git a/_data/engine-cli/docker_config_ls.yaml b/_data/engine-cli/docker_config_ls.yaml index 100f632f72..b12b15846b 100644 --- a/_data/engine-cli/docker_config_ls.yaml +++ b/_data/engine-cli/docker_config_ls.yaml @@ -1,7 +1,17 @@ command: docker config ls aliases: list short: List configs -long: List configs +long: |- + Run this command on a manager node to list the configs in the swarm. + + For detailed information about using configs, refer to [store configuration data using Docker Configs](https://docs.docker.com/engine/swarm/configs/). + + > **Note** + > + > This is a cluster management command, and must be executed on a swarm + > manager node. To learn about managers and workers, refer to the + > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the + > documentation. usage: docker config ls [OPTIONS] pname: docker config plink: docker_config.yaml @@ -33,6 +43,118 @@ options: experimentalcli: false kubernetes: false swarm: false +examples: |- + ```bash + $ docker config ls + + ID NAME CREATED UPDATED + 6697bflskwj1998km1gnnjr38 q5s5570vtvnimefos1fyeo2u2 6 weeks ago 6 weeks ago + 9u9hk4br2ej0wgngkga6rp4hq my_config 5 weeks ago 5 weeks ago + mem02h8n73mybpgqjf0kfi1n0 test_config 3 seconds ago 3 seconds ago + ``` + + ### Filtering + + The filtering flag (`-f` or `--filter`) format is a `key=value` pair. If there is more + than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`) + + The currently supported filters are: + + - [id](#id) (config's ID) + - [label](#label) (`label=` or `label==`) + - [name](#name) (config's name) + + #### id + + The `id` filter matches all or prefix of a config's id. + + ```bash + $ docker config ls -f "id=6697bflskwj1998km1gnnjr38" + + ID NAME CREATED UPDATED + 6697bflskwj1998km1gnnjr38 q5s5570vtvnimefos1fyeo2u2 6 weeks ago 6 weeks ago + ``` + + #### label + + The `label` filter matches configs based on the presence of a `label` alone or + a `label` and a value. + + The following filter matches all configs with a `project` label regardless of + its value: + + ```bash + $ docker config ls --filter label=project + + ID NAME CREATED UPDATED + mem02h8n73mybpgqjf0kfi1n0 test_config About an hour ago About an hour ago + ``` + + The following filter matches only services with the `project` label with the + `project-a` value. + + ```bash + $ docker service ls --filter label=project=test + + ID NAME CREATED UPDATED + mem02h8n73mybpgqjf0kfi1n0 test_config About an hour ago About an hour ago + ``` + + #### name + + The `name` filter matches on all or prefix of a config's name. + + The following filter matches config with a name containing a prefix of `test`. + + ```bash + $ docker config ls --filter name=test_config + + ID NAME CREATED UPDATED + mem02h8n73mybpgqjf0kfi1n0 test_config About an hour ago About an hour ago + ``` + + ### Format the output + + The formatting option (`--format`) pretty prints configs output + using a Go template. + + Valid placeholders for the Go template are listed below: + + | Placeholder | Description | + | ------------ | ------------------------------------------------------------------------------------ | + | `.ID` | Config ID | + | `.Name` | Config name | + | `.CreatedAt` | Time when the config was created | + | `.UpdatedAt` | Time when the config was updated | + | `.Labels` | All labels assigned to the config | + | `.Label` | Value of a specific label for this config. For example `{{.Label "my-label"}}` | + + When using the `--format` option, the `config ls` command will either + output the data exactly as the template declares or, when using the + `table` directive, will include column headers as well. + + The following example uses a template without headers and outputs the + `ID` and `Name` entries separated by a colon (`:`) for all images: + + ```bash + $ docker config ls --format "{{.ID}}: {{.Name}}" + + 77af4d6b9913: config-1 + b6fa739cedf5: config-2 + 78a85c484f71: config-3 + ``` + + To list all configs with their name and created date in a table format you + can use: + + ```bash + $ docker config ls --format "table {{.ID}}\t{{.Name}}\t{{.CreatedAt}}" + + ID NAME CREATED + 77af4d6b9913 config-1 5 minutes ago + b6fa739cedf5 config-2 3 hours ago + 78a85c484f71 config-3 10 days ago + ``` deprecated: false min_api_version: "1.30" experimental: false diff --git a/_data/engine-cli/docker_config_rm.yaml b/_data/engine-cli/docker_config_rm.yaml index 991ecfc9ec..317784005d 100644 --- a/_data/engine-cli/docker_config_rm.yaml +++ b/_data/engine-cli/docker_config_rm.yaml @@ -1,10 +1,32 @@ command: docker config rm aliases: remove short: Remove one or more configs -long: Remove one or more configs +long: |- + Removes the specified configs from the swarm. + + For detailed information about using configs, refer to [store configuration data using Docker Configs](https://docs.docker.com/engine/swarm/configs/). + + > **Note** + > + > This is a cluster management command, and must be executed on a swarm + > manager node. To learn about managers and workers, refer to the + > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the + > documentation. usage: docker config rm CONFIG [CONFIG...] pname: docker config plink: docker_config.yaml +examples: |- + This example removes a config: + + ```bash + $ docker config rm my_config + sapth4csdo5b6wz2p5uimh5xg + ``` + + > **Warning** + > + > Unlike `docker rm`, this command does not ask for confirmation before removing + > a config. deprecated: false min_api_version: "1.30" experimental: false diff --git a/_data/engine-cli/docker_stop.yaml b/_data/engine-cli/docker_stop.yaml index 3d775e86e3..0e67c53248 100644 --- a/_data/engine-cli/docker_stop.yaml +++ b/_data/engine-cli/docker_stop.yaml @@ -2,7 +2,9 @@ command: docker stop short: Stop one or more running containers long: |- The main process inside the container will receive `SIGTERM`, and after a grace - period, `SIGKILL`. + period, `SIGKILL`. The first signal can be changed with the `STOPSIGNAL` + instruction in the container's Dockerfile, or the `--stop-signal` option to + `docker run`. usage: docker stop [OPTIONS] CONTAINER [CONTAINER...] pname: docker plink: docker.yaml