From 418f68ca86250af144bce7ccd68ef10c18fa98f0 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Thu, 11 Mar 2021 15:41:56 +0100 Subject: [PATCH] engine: sync reference docs Signed-off-by: Sebastiaan van Stijn --- _data/engine-cli/docker_node_ls.yaml | 42 +++++- _data/engine-cli/docker_push.yaml | 2 +- _data/engine-cli/docker_rm.yaml | 30 ++++- _data/engine-cli/docker_service_ls.yaml | 164 +++++++++++++++++------- 4 files changed, 186 insertions(+), 52 deletions(-) diff --git a/_data/engine-cli/docker_node_ls.yaml b/_data/engine-cli/docker_node_ls.yaml index 76376e3cae..1bbd100ac1 100644 --- a/_data/engine-cli/docker_node_ls.yaml +++ b/_data/engine-cli/docker_node_ls.yaml @@ -68,6 +68,7 @@ examples: |- * [id](#id) * [label](#label) + * [node.label](#nodelabel) * [membership](#membership) * [name](#name) * [role](#role) @@ -85,7 +86,10 @@ examples: |- #### label - The `label` filter matches nodes based on engine labels and on the presence of a `label` alone or a `label` and a value. Node labels are currently not used for filtering. + The `label` filter matches nodes based on engine labels and on the presence of a + `label` alone or a `label` and a value. Engine labels are configured in + the [daemon configuration](dockerd.md#daemon-configuration-file). To filter on + Swarm `node` labels, use [`node.label` instead](#nodelabel). The following filter matches nodes with the `foo` label regardless of its value. @@ -96,6 +100,42 @@ examples: |- 1bcef6utixb0l0ca7gxuivsj0 swarm-worker2 Ready Active ``` + #### node.label + + The `node.label` filter matches nodes based on node labels and on the presence + of a `node.label` alone or a `node.label` and a value. + + The following filter updates nodes to have a `region` node label: + + ```console + $ docker node update --label-add region=region-a swarm-test-01 + $ docker node update --label-add region=region-a swarm-test-02 + $ docker node update --label-add region=region-b swarm-test-03 + $ docker node update --label-add region=region-b swarm-test-04 + ``` + + Show all nodes that have a `region` node label set: + + ```console + $ docker node ls --filter node.label=region + + ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS ENGINE VERSION + yg550ettvsjn6g6t840iaiwgb * swarm-test-01 Ready Active Leader 20.10.2 + 2lm9w9kbepgvkzkkeyku40e65 swarm-test-02 Ready Active Reachable 20.10.2 + hc0pu7ntc7s4uvj4pv7z7pz15 swarm-test-03 Ready Active Reachable 20.10.2 + n41b2cijmhifxxvz56vwrs12q swarm-test-04 Ready Active 20.10.2 + ``` + + Show all nodes that have a `region` node label, with value `region-a`: + + ```console + $ docker node ls --filter node.label=region=region-a + + ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS ENGINE VERSION + yg550ettvsjn6g6t840iaiwgb * swarm-test-01 Ready Active Leader 20.10.2 + 2lm9w9kbepgvkzkkeyku40e65 swarm-test-02 Ready Active Reachable 20.10.2 + ``` + #### membership The `membership` filter matches nodes based on the presence of a `membership` and a value diff --git a/_data/engine-cli/docker_push.yaml b/_data/engine-cli/docker_push.yaml index 171fe8bb12..d96a74bb94 100644 --- a/_data/engine-cli/docker_push.yaml +++ b/_data/engine-cli/docker_push.yaml @@ -88,7 +88,7 @@ examples: |- ### Push all tags of an image - Use the `-a` (or `--all-tags`) option to push To push all tags of a local image. + Use the `-a` (or `--all-tags`) option to push all tags of a local image. The following example creates multiple tags for an image, and pushes all those tags to Docker Hub. diff --git a/_data/engine-cli/docker_rm.yaml b/_data/engine-cli/docker_rm.yaml index 10294bb6bf..357e896417 100644 --- a/_data/engine-cli/docker_rm.yaml +++ b/_data/engine-cli/docker_rm.yaml @@ -74,13 +74,33 @@ examples: |- ### Remove all stopped containers - ```bash - $ docker rm $(docker ps -a -q) + Use the [`docker container prune`](container_prune.md) command to remove all + stopped containers, or refer to the [`docker system prune`](system_prune.md) + command to remove unused containers in addition to other Docker resources, such + as (unused) images and networks. + + Alternatively, you can use the `docker ps` with the `-q` / `--quiet` option to + generate a list of container IDs to remove, and use that list as argument for + the `docker rm` command. + + Combining commands can be more flexible, but is less portable as it depends + on features provided by the shell, and the exact syntax may differ depending on + what shell is used. To use this approach on Windows, consider using PowerShell + or Bash. + + The example below uses `docker ps -q` to print the IDs of all containers that + have exited (`--filter status=exited`), and removes those containers with + the `docker rm` command: + + ```console + $ docker rm $(docker ps --filter status=exited -q) ``` - This command deletes all stopped containers. The command - `docker ps -a -q` above returns all existing container IDs and passes them to - the `rm` command which deletes them. Running containers are not deleted. + Or, using the `xargs` Linux utility; + + ```console + $ docker ps --filter status=exited -q | xargs docker rm + ``` ### Remove a container and its volumes diff --git a/_data/engine-cli/docker_service_ls.yaml b/_data/engine-cli/docker_service_ls.yaml index b0886d2168..f1ecdadc16 100644 --- a/_data/engine-cli/docker_service_ls.yaml +++ b/_data/engine-cli/docker_service_ls.yaml @@ -41,51 +41,125 @@ options: experimentalcli: false kubernetes: false swarm: false -examples: "On a manager node:\n\n```bash\n$ docker service ls\n\nID NAME - \ MODE REPLICAS IMAGE\nc8wgl7q4ndfd frontend replicated - \ 5/5 nginx:alpine\ndmu1ept4cxcf redis replicated 3/3 - \ redis:3.0.6\niwe3278osahj mongo global 7/7 mongo:3.3\nhh08h9uu8uwr - \ job replicated-job 1/1 (3/5 completed) nginx:latest \n```\n\nThe - `REPLICAS` column shows both the *actual* and *desired* number of tasks for\nthe - service. If the service is in `replicated-job` or `global-job`, it will\nadditionally - show the completion status of the job as completed tasks over\ntotal tasks the job - will execute.\n\n### Filtering\n\nThe filtering flag (`-f` or `--filter`) format - is of \"key=value\". If there is more\nthan one filter, then pass multiple flags - (e.g., `--filter \"foo=bar\" --filter \"bif=baz\"`)\n\nThe currently supported filters - are:\n\n* [id](service_ls.md#id)\n* [label](service_ls.md#label)\n* [mode](service_ls.md#mode)\n* - [name](service_ls.md#name)\n\n#### id\n\nThe `id` filter matches all or part of - a service's id.\n\n```bash\n$ docker service ls -f \"id=0bcjw\"\nID NAME - \ MODE REPLICAS IMAGE\n0bcjwfh8ychr redis replicated 1/1 redis:3.0.6\n```\n\n#### - label\n\nThe `label` filter matches services based on the presence of a `label` - alone or\na `label` and a value.\n\nThe following filter matches all services with - a `project` label regardless of\nits value:\n\n```bash\n$ docker service ls --filter - label=project\nID NAME MODE REPLICAS IMAGE\n01sl1rp6nj5u - \ frontend2 replicated 1/1 nginx:alpine\n36xvvwwauej0 frontend replicated - \ 5/5 nginx:alpine\n74nzcxxjv6fq backend replicated 3/3 redis:3.0.6\n```\n\nThe - following filter matches only services with the `project` label with the\n`project-a` - value.\n\n```bash\n$ docker service ls --filter label=project=project-a\nID NAME - \ MODE REPLICAS IMAGE\n36xvvwwauej0 frontend replicated 5/5 nginx:alpine\n74nzcxxjv6fq - \ backend replicated 3/3 redis:3.0.6\n```\n\n#### mode\n\nThe `mode` filter - matches on the mode (either `replicated` or `global`) of a service.\n\nThe following - filter matches only `global` services.\n\n```bash\n$ docker service ls --filter - mode=global\nID NAME MODE REPLICAS - \ IMAGE\nw7y0v2yrn620 top global 1/1 - \ busybox\n```\n\n#### name\n\nThe `name` filter matches on all or - part of a service's name.\n\nThe following filter matches services with a name containing - `redis`.\n\n```bash\n$ docker service ls --filter name=redis\nID NAME - \ MODE REPLICAS IMAGE\n0bcjwfh8ychr redis replicated 1/1 redis:3.0.6\n```\n\n### - Formatting\n\nThe formatting options (`--format`) pretty-prints services output\nusing - a Go template.\n\nValid placeholders for the Go template are listed below:\n\nPlaceholder - | Description\n------------|------------------------------------------------------------------------------------------\n`.ID` - \ | Service ID\n`.Name` | Service name\n`.Mode` | Service mode (replicated, - global)\n`.Replicas` | Service replicas\n`.Image` | Service image\n`.Ports` | - Service ports published in ingress mode\n\nWhen using the `--format` option, the - `service ls` command will either\noutput the data exactly as the template declares - or, when using the\n`table` directive, includes column headers as well.\n\nThe following - example uses a template without headers and outputs the\n`ID`, `Mode`, and `Replicas` - entries separated by a colon (`:`) for all services:\n\n```bash\n$ docker service - ls --format \"{{.ID}}: {{.Mode}} {{.Replicas}}\"\n\n0zmvwuiu3vue: replicated 10/10\nfm6uf97exkul: - global 5/5\n```" +examples: |- + On a manager node: + + ```bash + $ docker service ls + + ID NAME MODE REPLICAS IMAGE + c8wgl7q4ndfd frontend replicated 5/5 nginx:alpine + dmu1ept4cxcf redis replicated 3/3 redis:3.0.6 + iwe3278osahj mongo global 7/7 mongo:3.3 + hh08h9uu8uwr job replicated-job 1/1 (3/5 completed) nginx:latest + ``` + + The `REPLICAS` column shows both the *actual* and *desired* number of tasks for + the service. If the service is in `replicated-job` or `global-job`, it will + additionally show the completion status of the job as completed tasks over + total tasks the job will execute. + + ### Filtering + + The filtering flag (`-f` or `--filter`) format is of "key=value". 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](service_ls.md#id) + * [label](service_ls.md#label) + * [mode](service_ls.md#mode) + * [name](service_ls.md#name) + + #### id + + The `id` filter matches all or part of a service's id. + + ```bash + $ docker service ls -f "id=0bcjw" + ID NAME MODE REPLICAS IMAGE + 0bcjwfh8ychr redis replicated 1/1 redis:3.0.6 + ``` + + #### label + + The `label` filter matches services based on the presence of a `label` alone or + a `label` and a value. + + The following filter matches all services with a `project` label regardless of + its value: + + ```bash + $ docker service ls --filter label=project + ID NAME MODE REPLICAS IMAGE + 01sl1rp6nj5u frontend2 replicated 1/1 nginx:alpine + 36xvvwwauej0 frontend replicated 5/5 nginx:alpine + 74nzcxxjv6fq backend replicated 3/3 redis:3.0.6 + ``` + + The following filter matches only services with the `project` label with the + `project-a` value. + + ```bash + $ docker service ls --filter label=project=project-a + ID NAME MODE REPLICAS IMAGE + 36xvvwwauej0 frontend replicated 5/5 nginx:alpine + 74nzcxxjv6fq backend replicated 3/3 redis:3.0.6 + ``` + + #### mode + + The `mode` filter matches on the mode (either `replicated` or `global`) of a service. + + The following filter matches only `global` services. + + ```bash + $ docker service ls --filter mode=global + ID NAME MODE REPLICAS IMAGE + w7y0v2yrn620 top global 1/1 busybox + ``` + + #### name + + The `name` filter matches on all or part of a service's name. + + The following filter matches services with a name containing `redis`. + + ```bash + $ docker service ls --filter name=redis + ID NAME MODE REPLICAS IMAGE + 0bcjwfh8ychr redis replicated 1/1 redis:3.0.6 + ``` + + ### Formatting + + The formatting options (`--format`) pretty-prints services output + using a Go template. + + Valid placeholders for the Go template are listed below: + + Placeholder | Description + ------------|------------------------------------------------------------------------------------------ + `.ID` | Service ID + `.Name` | Service name + `.Mode` | Service mode (replicated, global) + `.Replicas` | Service replicas + `.Image` | Service image + `.Ports` | Service ports published in ingress mode + + When using the `--format` option, the `service ls` command will either + output the data exactly as the template declares or, when using the + `table` directive, includes column headers as well. + + The following example uses a template without headers and outputs the + `ID`, `Mode`, and `Replicas` entries separated by a colon (`:`) for all services: + + ```bash + $ docker service ls --format "{{.ID}}: {{.Mode}} {{.Replicas}}" + + 0zmvwuiu3vue: replicated 10/10 + fm6uf97exkul: global 5/5 + ``` deprecated: false min_api_version: "1.24" experimental: false