From 098129a0c12e3a79398b307b38a67198bd3b66fc Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Fri, 1 Apr 2022 21:37:25 +0200 Subject: [PATCH] engine: update reference docs with latest changes from 20.10 branch Signed-off-by: Sebastiaan van Stijn --- _data/engine-cli/docker_build.yaml | 34 +++---- _data/engine-cli/docker_checkpoint.yaml | 2 +- _data/engine-cli/docker_config_ls.yaml | 2 +- _data/engine-cli/docker_context.yaml | 2 +- _data/engine-cli/docker_cp.yaml | 58 +++++++---- _data/engine-cli/docker_create.yaml | 92 +++++------------ _data/engine-cli/docker_history.yaml | 14 +-- _data/engine-cli/docker_images.yaml | 16 +-- _data/engine-cli/docker_import.yaml | 7 +- _data/engine-cli/docker_network_connect.yaml | 10 +- _data/engine-cli/docker_network_create.yaml | 2 +- _data/engine-cli/docker_network_ls.yaml | 22 ++-- _data/engine-cli/docker_node_ls.yaml | 20 ++-- _data/engine-cli/docker_node_ps.yaml | 20 ++-- _data/engine-cli/docker_plugin_ls.yaml | 14 +-- _data/engine-cli/docker_pull.yaml | 6 +- _data/engine-cli/docker_run.yaml | 100 +++++++++++++++---- _data/engine-cli/docker_search.yaml | 2 +- _data/engine-cli/docker_secret_ls.yaml | 2 +- _data/engine-cli/docker_service_create.yaml | 19 ++-- _data/engine-cli/docker_service_ls.yaml | 16 +-- _data/engine-cli/docker_service_ps.yaml | 20 ++-- _data/engine-cli/docker_stack_ls.yaml | 2 +- _data/engine-cli/docker_stack_ps.yaml | 20 ++-- _data/engine-cli/docker_stack_services.yaml | 14 +-- _data/engine-cli/docker_stats.yaml | 30 +++--- _data/engine-cli/docker_volume_ls.yaml | 16 +-- 27 files changed, 307 insertions(+), 255 deletions(-) diff --git a/_data/engine-cli/docker_build.yaml b/_data/engine-cli/docker_build.yaml index 76373b92e4..6c5836b755 100644 --- a/_data/engine-cli/docker_build.yaml +++ b/_data/engine-cli/docker_build.yaml @@ -41,16 +41,16 @@ long: |- The following table represents all the valid suffixes with their build contexts: - Build Syntax Suffix | Commit Used | Build Context Used - --------------------------------|-----------------------|------------------- - `myrepo.git` | `refs/heads/master` | `/` - `myrepo.git#mytag` | `refs/tags/mytag` | `/` - `myrepo.git#mybranch` | `refs/heads/mybranch` | `/` - `myrepo.git#pull/42/head` | `refs/pull/42/head` | `/` - `myrepo.git#:myfolder` | `refs/heads/master` | `/myfolder` - `myrepo.git#master:myfolder` | `refs/heads/master` | `/myfolder` - `myrepo.git#mytag:myfolder` | `refs/tags/mytag` | `/myfolder` - `myrepo.git#mybranch:myfolder` | `refs/heads/mybranch` | `/myfolder` + | Build Syntax Suffix | Commit Used | Build Context Used | + |--------------------------------|-----------------------|--------------------| + | `myrepo.git` | `refs/heads/master` | `/` | + | `myrepo.git#mytag` | `refs/tags/mytag` | `/` | + | `myrepo.git#mybranch` | `refs/heads/mybranch` | `/` | + | `myrepo.git#pull/42/head` | `refs/pull/42/head` | `/` | + | `myrepo.git#:myfolder` | `refs/heads/master` | `/myfolder` | + | `myrepo.git#master:myfolder` | `refs/heads/master` | `/myfolder` | + | `myrepo.git#mytag:myfolder` | `refs/tags/mytag` | `/myfolder` | + | `myrepo.git#mybranch:myfolder` | `refs/heads/mybranch` | `/myfolder` | > **Note** > @@ -699,11 +699,11 @@ examples: |- Linux namespaces. On Microsoft Windows, you can specify these values: - | Value | Description | - |-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------| - | `default` | Use the value specified by the Docker daemon's `--exec-opt` . If the `daemon` does not specify an isolation technology, Microsoft Windows uses `process` as its default value. | - | `process` | Namespace isolation only. | - | `hyperv` | Hyper-V hypervisor partition-based isolation. | + | Value | Description | + |-----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| + | `default` | Use the value specified by the Docker daemon's `--exec-opt` . If the `daemon` does not specify an isolation technology, Microsoft Windows uses `process` as its default value. | + | `process` | Namespace isolation only. | + | `hyperv` | Hyper-V hypervisor partition-based isolation. | Specifying the `--isolation` flag without a value is the same as setting `--isolation="default"`. @@ -723,10 +723,10 @@ examples: |- ```dockerfile FROM debian AS build-env - ... + # ... FROM alpine AS production-env - ... + # ... ``` ```console diff --git a/_data/engine-cli/docker_checkpoint.yaml b/_data/engine-cli/docker_checkpoint.yaml index 5b614f3a22..c2b9713145 100644 --- a/_data/engine-cli/docker_checkpoint.yaml +++ b/_data/engine-cli/docker_checkpoint.yaml @@ -5,7 +5,7 @@ long: |- container by checkpointing it, which turns its state into a collection of files on disk. Later, the container can be restored from the point it was frozen. - This is accomplished using a tool called [CRIU](http://criu.org), which is an + This is accomplished using a tool called [CRIU](https://criu.org), which is an external dependency of this feature. A good overview of the history of checkpoint and restore in Docker is available in this [Kubernetes blog post](https://kubernetes.io/blog/2015/07/how-did-quake-demo-from-dockercon-work/). diff --git a/_data/engine-cli/docker_config_ls.yaml b/_data/engine-cli/docker_config_ls.yaml index cbec42e317..351c86a264 100644 --- a/_data/engine-cli/docker_config_ls.yaml +++ b/_data/engine-cli/docker_config_ls.yaml @@ -121,7 +121,7 @@ examples: |- Valid placeholders for the Go template are listed below: | Placeholder | Description | - | ------------ | ------------------------------------------------------------------------------------ | + |--------------|--------------------------------------------------------------------------------------| | `.ID` | Config ID | | `.Name` | Config name | | `.CreatedAt` | Time when the config was created | diff --git a/_data/engine-cli/docker_context.yaml b/_data/engine-cli/docker_context.yaml index b85be83336..720419555c 100644 --- a/_data/engine-cli/docker_context.yaml +++ b/_data/engine-cli/docker_context.yaml @@ -1,6 +1,6 @@ command: docker context short: Manage contexts -long: Manage contexts +long: Manage contexts. usage: docker context pname: docker plink: docker.yaml diff --git a/_data/engine-cli/docker_cp.yaml b/_data/engine-cli/docker_cp.yaml index 87090f16b4..e39d37d19a 100644 --- a/_data/engine-cli/docker_cp.yaml +++ b/_data/engine-cli/docker_cp.yaml @@ -64,25 +64,6 @@ long: |- you must be explicit with a relative or absolute path, for example: `/path/to/file:name.txt` or `./file:name.txt` - - It is not possible to copy certain system files such as resources under - `/proc`, `/sys`, `/dev`, [tmpfs](run.md#mount-tmpfs---tmpfs), and mounts created by - the user in the container. However, you can still copy such files by manually - running `tar` in `docker exec`. Both of the following examples do the same thing - in different ways (consider `SRC_PATH` and `DEST_PATH` are directories): - - ```console - $ docker exec CONTAINER tar Ccf $(dirname SRC_PATH) - $(basename SRC_PATH) | tar Cxf DEST_PATH - - ``` - - ```console - $ tar Ccf $(dirname SRC_PATH) - $(basename SRC_PATH) | docker exec -i CONTAINER tar Cxf DEST_PATH - - ``` - - Using `-` as the `SRC_PATH` streams the contents of `STDIN` as a tar archive. - The command extracts the content of the tar to the `DEST_PATH` in container's - filesystem. In this case, `DEST_PATH` must specify a directory. Using `-` as - the `DEST_PATH` streams the contents of the resource as a tar archive to `STDOUT`. usage: "docker cp [OPTIONS] CONTAINER:SRC_PATH DEST_PATH|-\n\tdocker cp [OPTIONS] SRC_PATH|- CONTAINER:DEST_PATH" pname: docker @@ -108,6 +89,45 @@ options: experimentalcli: false kubernetes: false swarm: false +examples: |- + Copy a local file into container + + ```console + $ docker cp ./some_file CONTAINER:/work + ``` + + Copy files from container to local path + + ```console + $ docker cp CONTAINER:/var/logs/ /tmp/app_logs + ``` + + Copy a file from container to stdout. Please note `cp` command produces a tar stream + + ```console + $ docker cp CONTAINER:/var/logs/app.log - | tar x -O | grep "ERROR" + ``` + + ### Corner cases + + It is not possible to copy certain system files such as resources under + `/proc`, `/sys`, `/dev`, [tmpfs](run.md#mount-tmpfs---tmpfs), and mounts created by + the user in the container. However, you can still copy such files by manually + running `tar` in `docker exec`. Both of the following examples do the same thing + in different ways (consider `SRC_PATH` and `DEST_PATH` are directories): + + ```console + $ docker exec CONTAINER tar Ccf $(dirname SRC_PATH) - $(basename SRC_PATH) | tar Cxf DEST_PATH - + ``` + + ```console + $ tar Ccf $(dirname SRC_PATH) - $(basename SRC_PATH) | docker exec -i CONTAINER tar Cxf DEST_PATH - + ``` + + Using `-` as the `SRC_PATH` streams the contents of `STDIN` as a tar archive. + The command extracts the content of the tar to the `DEST_PATH` in container's + filesystem. In this case, `DEST_PATH` must specify a directory. Using `-` as + the `DEST_PATH` streams the contents of the resource as a tar archive to `STDOUT`. deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_create.yaml b/_data/engine-cli/docker_create.yaml index 44d8a19795..cc63bbef9e 100644 --- a/_data/engine-cli/docker_create.yaml +++ b/_data/engine-cli/docker_create.yaml @@ -1,17 +1,23 @@ command: docker create short: Create a new container long: |- - The `docker create` command creates a writeable container layer over the - specified image and prepares it for running the specified command. The + The `docker container create` (or shorthand: `docker create`) command creates a + new container from the specified image, without starting it. + + When creating a container, the docker daemon creates a writeable container layer + over the specified image and prepares it for running the specified command. The container ID is then printed to `STDOUT`. This is similar to `docker run -d` - except the container is never started. You can then use the - `docker start ` command to start the container at any point. + except the container is never started. You can then use the `docker container start` + (or shorthand: `docker start`) command to start the container at any point. This is useful when you want to set up a container configuration ahead of time so that it is ready to start when you need it. The initial status of the new container is `created`. - Please see the [run command](run.md) section and the [Docker run reference](../run.md) for more details. + The `docker create` command shares most of its options with the `docker run` + command (which performs a `docker create` before starting it). Refer to the + [`docker run` command](run.md) section and the [Docker run reference](../run.md) + for details on the available flags and options. usage: docker create [OPTIONS] IMAGE [COMMAND] [ARG...] pname: docker plink: docker.yaml @@ -900,19 +906,29 @@ options: examples: |- ### Create and start a container - ```console - $ docker create -t -i fedora bash + The following example creates an interactive container with a pseudo-TTY attached, + then starts the container and attaches to it: + ```console + $ docker container create -i -t --name mycontainer alpine 6d8af538ec541dd581ebc2a24153a28329acb5268abe5ef868c1f1a261221752 - $ docker start -a -i 6d8af538ec5 + $ docker container start --attach -i mycontainer + / # echo hello world + hello world + ``` - bash-4.2# + The above is the equivalent of a `docker run`: + + ```console + $ docker run -it --name mycontainer2 alpine + / # echo hello world + hello world ``` ### Initialize volumes - As of v1.4.0 container volumes are initialized during the `docker create` phase + Container volumes are initialized during the `docker create` phase (i.e., `docker run` too). For example, this allows you to `create` the `data` volume container, and then use it from another container: @@ -949,62 +965,6 @@ examples: |- drwx--S--- 2 1000 staff 460 Dec 5 00:51 .ssh drwxr-xr-x 32 1000 staff 1140 Dec 5 04:01 docker ``` - - - Set storage driver options per container. - - ```console - $ docker create -it --storage-opt size=120G fedora /bin/bash - ``` - - This (size) will allow to set the container rootfs size to 120G at creation time. - This option is only available for the `devicemapper`, `btrfs`, `overlay2`, - `windowsfilter` and `zfs` graph drivers. - For the `devicemapper`, `btrfs`, `windowsfilter` and `zfs` graph drivers, - user cannot pass a size less than the Default BaseFS Size. - For the `overlay2` storage driver, the size option is only available if the - backing fs is `xfs` and mounted with the `pquota` mount option. - Under these conditions, user can pass any size less than the backing fs size. - - ### Specify isolation technology for container (--isolation) - - This option is useful in situations where you are running Docker containers on - Windows. The `--isolation=` option sets a container's isolation - technology. On Linux, the only supported is the `default` option which uses - Linux namespaces. On Microsoft Windows, you can specify these values: - - - | Value | Description | - |-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------| - | `default` | Use the value specified by the Docker daemon's `--exec-opt` . If the `daemon` does not specify an isolation technology, Microsoft Windows uses `process` as its default value if the - daemon is running on Windows server, or `hyperv` if running on Windows client. | - | `process` | Namespace isolation only. | - | `hyperv` | Hyper-V hypervisor partition-based isolation. | - - Specifying the `--isolation` flag without a value is the same as setting `--isolation="default"`. - - ### Dealing with dynamically created devices (--device-cgroup-rule) - - Devices available to a container are assigned at creation time. The - assigned devices will both be added to the cgroup.allow file and - created into the container once it is run. This poses a problem when - a new device needs to be added to running container. - - One of the solutions is to add a more permissive rule to a container - allowing it access to a wider range of devices. For example, supposing - our container needs access to a character device with major `42` and - any number of minor number (added as new devices appear), the - following rule would be added: - - ```console - $ docker create --device-cgroup-rule='c 42:* rmw' -name my-container my-image - ``` - - Then, a user could ask `udev` to execute a script that would `docker exec my-container mknod newDevX c 42 ` - the required device when it is added. - - NOTE: initially present devices still need to be explicitly added to - the create/run command deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_history.yaml b/_data/engine-cli/docker_history.yaml index 27512c2bd2..64db5a5894 100644 --- a/_data/engine-cli/docker_history.yaml +++ b/_data/engine-cli/docker_history.yaml @@ -75,14 +75,14 @@ examples: |- Valid placeholders for the Go template are listed below: - | Placeholder | Description | - | --------------- | ----------- | - | `.ID` | Image ID | + | Placeholder | Description | + |-----------------|-----------------------------------------------------------------------------------------------------------| + | `.ID` | Image ID | | `.CreatedSince` | Elapsed time since the image was created if `--human=true`, otherwise timestamp of when image was created | - | `.CreatedAt` | Timestamp of when image was created | - | `.CreatedBy` | Command that was used to create the image | - | `.Size` | Image disk size | - | `.Comment` | Comment for image | + | `.CreatedAt` | Timestamp of when image was created | + | `.CreatedBy` | Command that was used to create the image | + | `.Size` | Image disk size | + | `.Comment` | Comment for image | When using the `--format` option, the `history` command will either output the data exactly as the template declares or, when using the diff --git a/_data/engine-cli/docker_images.yaml b/_data/engine-cli/docker_images.yaml index cce2142719..2532e2fcce 100644 --- a/_data/engine-cli/docker_images.yaml +++ b/_data/engine-cli/docker_images.yaml @@ -323,15 +323,15 @@ examples: |- Valid placeholders for the Go template are listed below: - | Placeholder | Description| - | ---- | ---- | - | `.ID` | Image ID | - | `.Repository` | Image repository | - | `.Tag` | Image tag | - | `.Digest` | Image digest | + | Placeholder | Description | + |-----------------|------------------------------------------| + | `.ID` | Image ID | + | `.Repository` | Image repository | + | `.Tag` | Image tag | + | `.Digest` | Image digest | | `.CreatedSince` | Elapsed time since the image was created | - | `.CreatedAt` | Time when the image was created | - | `.Size` | Image disk size | + | `.CreatedAt` | Time when the image was created | + | `.Size` | Image disk size | When using the `--format` option, the `image` command will either output the data exactly as the template declares or, when using the diff --git a/_data/engine-cli/docker_import.yaml b/_data/engine-cli/docker_import.yaml index 478a5ec10e..69be47d194 100644 --- a/_data/engine-cli/docker_import.yaml +++ b/_data/engine-cli/docker_import.yaml @@ -9,9 +9,8 @@ long: |- the host. To import from a remote location, specify a `URI` that begins with the `http://` or `https://` protocol. - The `--change` option will apply `Dockerfile` instructions to the image - that is created. - Supported `Dockerfile` instructions: + The `--change` option applies `Dockerfile` instructions to the image that is + created. Supported `Dockerfile` instructions: `CMD`|`ENTRYPOINT`|`ENV`|`EXPOSE`|`ONBUILD`|`USER`|`VOLUME`|`WORKDIR` usage: docker import [OPTIONS] file|URL|- [REPOSITORY[:TAG]] pname: docker @@ -47,7 +46,7 @@ options: examples: |- ### Import from a remote location - This will create a new untagged image. + This creates a new untagged image. ```console $ docker import https://example.com/exampleimage.tgz diff --git a/_data/engine-cli/docker_network_connect.yaml b/_data/engine-cli/docker_network_connect.yaml index d8741cf240..c8700505dd 100644 --- a/_data/engine-cli/docker_network_connect.yaml +++ b/_data/engine-cli/docker_network_connect.yaml @@ -68,7 +68,8 @@ examples: |- ### Connect a container to a network when it starts - You can also use the `docker run --network=` option to start a container and immediately connect it to a network. + You can also use the `docker run --network=` option to start a + container and immediately connect it to a network. ```console $ docker run -itd --network=multi-host-network busybox @@ -119,14 +120,17 @@ examples: |- $ docker network connect --ip 172.20.128.2 multi-host-network container2 ``` - To verify the container is connected, use the `docker network inspect` command. Use `docker network disconnect` to remove a container from the network. + To verify the container is connected, use the `docker network inspect` command. + Use `docker network disconnect` to remove a container from the network. Once connected in network, containers can communicate using only another container's IP address or name. For `overlay` networks or custom plugins that support multi-host connectivity, containers connected to the same multi-host network but launched from different Engines can also communicate in this way. - You can connect a container to one or more networks. The networks need not be the same type. For example, you can connect a single container bridge and overlay networks. + You can connect a container to one or more networks. The networks need not be + the same type. For example, you can connect a single container bridge and overlay + networks. deprecated: false min_api_version: "1.21" experimental: false diff --git a/_data/engine-cli/docker_network_create.yaml b/_data/engine-cli/docker_network_create.yaml index 891ee58ef0..f4e920eb98 100644 --- a/_data/engine-cli/docker_network_create.yaml +++ b/_data/engine-cli/docker_network_create.yaml @@ -300,7 +300,7 @@ examples: |- |--------------|----------------|--------------------------------------------| | `--gateway` | - | IPv4 or IPv6 Gateway for the master subnet | | `--ip-range` | `--fixed-cidr` | Allocate IPs from a range | - | `--internal` | - | Restrict external access to the network | + | `--internal` | - | Restrict external access to the network | | `--ipv6` | `--ipv6` | Enable IPv6 networking | | `--subnet` | `--bip` | Subnet for network | diff --git a/_data/engine-cli/docker_network_ls.yaml b/_data/engine-cli/docker_network_ls.yaml index d1afb71c53..dcc05a3bfa 100644 --- a/_data/engine-cli/docker_network_ls.yaml +++ b/_data/engine-cli/docker_network_ls.yaml @@ -220,17 +220,17 @@ examples: |- Valid placeholders for the Go template are listed below: - Placeholder | Description - -------------|------------------------------------------------------------------------------------------ - `.ID` | Network ID - `.Name` | Network name - `.Driver` | Network driver - `.Scope` | Network scope (local, global) - `.IPv6` | Whether IPv6 is enabled on the network or not. - `.Internal` | Whether the network is internal or not. - `.Labels` | All labels assigned to the network. - `.Label` | Value of a specific label for this network. For example `{{.Label "project.version"}}` - `.CreatedAt` | Time when the network was created + | Placeholder | Description | + |--------------|----------------------------------------------------------------------------------------| + | `.ID` | Network ID | + | `.Name` | Network name | + | `.Driver` | Network driver | + | `.Scope` | Network scope (local, global) | + | `.IPv6` | Whether IPv6 is enabled on the network or not. | + | `.Internal` | Whether the network is internal or not. | + | `.Labels` | All labels assigned to the network. | + | `.Label` | Value of a specific label for this network. For example `{{.Label "project.version"}}` | + | `.CreatedAt` | Time when the network was created | When using the `--format` option, the `network ls` command will either output the data exactly as the template declares or, when using the diff --git a/_data/engine-cli/docker_node_ls.yaml b/_data/engine-cli/docker_node_ls.yaml index 879c3f2225..a6041eac64 100644 --- a/_data/engine-cli/docker_node_ls.yaml +++ b/_data/engine-cli/docker_node_ls.yaml @@ -185,16 +185,16 @@ examples: |- Valid placeholders for the Go template are listed below: - Placeholder | Description - -----------------|------------------------------------------------------------------------------------------ - `.ID` | Node ID - `.Self` | Node of the daemon (`true/false`, `true`indicates that the node is the same as current docker daemon) - `.Hostname` | Node hostname - `.Status` | Node status - `.Availability` | Node availability ("active", "pause", or "drain") - `.ManagerStatus` | Manager status of the node - `.TLSStatus` | TLS status of the node ("Ready", or "Needs Rotation" has TLS certificate signed by an old CA) - `.EngineVersion` | Engine version + | Placeholder | Description | + |------------------|-------------------------------------------------------------------------------------------------------| + | `.ID` | Node ID | + | `.Self` | Node of the daemon (`true/false`, `true`indicates that the node is the same as current docker daemon) | + | `.Hostname` | Node hostname | + | `.Status` | Node status | + | `.Availability` | Node availability ("active", "pause", or "drain") | + | `.ManagerStatus` | Manager status of the node | + | `.TLSStatus` | TLS status of the node ("Ready", or "Needs Rotation" has TLS certificate signed by an old CA) | + | `.EngineVersion` | Engine version | When using the `--format` option, the `node ls` command will either output the data exactly as the template declares or, when using the diff --git a/_data/engine-cli/docker_node_ps.yaml b/_data/engine-cli/docker_node_ps.yaml index 6f5f0a147a..3f3079bb88 100644 --- a/_data/engine-cli/docker_node_ps.yaml +++ b/_data/engine-cli/docker_node_ps.yaml @@ -140,16 +140,16 @@ examples: |- Valid placeholders for the Go template are listed below: - Placeholder | Description - ----------------|------------------------------------------------------------------------------------------ - `.ID` | Task ID - `.Name` | Task name - `.Image` | Task image - `.Node` | Node ID - `.DesiredState` | Desired state of the task (`running`, `shutdown`, or `accepted`) - `.CurrentState` | Current state of the task - `.Error` | Error - `.Ports` | Task published ports + | Placeholder | Description | + |-----------------|------------------------------------------------------------------| + | `.ID` | Task ID | + | `.Name` | Task name | + | `.Image` | Task image | + | `.Node` | Node ID | + | `.DesiredState` | Desired state of the task (`running`, `shutdown`, or `accepted`) | + | `.CurrentState` | Current state of the task | + | `.Error` | Error | + | `.Ports` | Task published ports | When using the `--format` option, the `node ps` command will either output the data exactly as the template declares or, when using the diff --git a/_data/engine-cli/docker_plugin_ls.yaml b/_data/engine-cli/docker_plugin_ls.yaml index a0b60df550..c2659bfdcd 100644 --- a/_data/engine-cli/docker_plugin_ls.yaml +++ b/_data/engine-cli/docker_plugin_ls.yaml @@ -91,13 +91,13 @@ examples: |- Valid placeholders for the Go template are listed below: - Placeholder | Description - -------------------|------------------------------------------------------------ - `.ID` | Plugin ID - `.Name` | Plugin name and tag - `.Description` | Plugin description - `.Enabled` | Whether plugin is enabled or not - `.PluginReference` | The reference used to push/pull from a registry + | Placeholder | Description | + |--------------------|-------------------------------------------------| + | `.ID` | Plugin ID | + | `.Name` | Plugin name and tag | + | `.Description` | Plugin description | + | `.Enabled` | Whether plugin is enabled or not | + | `.PluginReference` | The reference used to push/pull from a registry | When using the `--format` option, the `plugin ls` command will either output the data exactly as the template declares or, when using the diff --git a/_data/engine-cli/docker_pull.yaml b/_data/engine-cli/docker_pull.yaml index 9a049dc677..b33ba647c8 100644 --- a/_data/engine-cli/docker_pull.yaml +++ b/_data/engine-cli/docker_pull.yaml @@ -130,8 +130,8 @@ examples: |- So far, you've pulled images by their name (and "tag"). Using names and tags is a convenient way to work with images. When using tags, you can `docker pull` an image again to make sure you have the most up-to-date version of that image. - For example, `docker pull ubuntu:14.04` pulls the latest version of the Ubuntu - 14.04 image. + For example, `docker pull ubuntu:20.04` pulls the latest version of the Ubuntu + 20.04 image. In some cases you don't want images to be updated to newer versions, but prefer to use a fixed version of an image. Docker enables you to pull an image by its @@ -140,7 +140,7 @@ examples: |- and guarantee that the image you're using is always the same. To know the digest of an image, pull the image first. Let's pull the latest - `ubuntu:14.04` image from Docker Hub: + `ubuntu:20.04` image from Docker Hub: ```console $ docker pull ubuntu:20.04 diff --git a/_data/engine-cli/docker_run.yaml b/_data/engine-cli/docker_run.yaml index 4f5e9d31c3..b0c6fcfac5 100644 --- a/_data/engine-cli/docker_run.yaml +++ b/_data/engine-cli/docker_run.yaml @@ -1114,7 +1114,7 @@ examples: |- Note that ports which are not bound to the host (i.e., `-p 80:80` instead of `-p 127.0.0.1:80:80`) will be accessible from the outside. This also applies if - you configured UFW to block this specific port, as Docker manages his + you configured UFW to block this specific port, as Docker manages its own iptables rules. [Read more](https://docs.docker.com/network/iptables/) ```console @@ -1124,6 +1124,48 @@ examples: |- This exposes port `80` of the container without publishing the port to the host system's interfaces. + ### Set the pull policy (--pull) + + Use the `--pull` flag to set the image pull policy when creating (and running) + the container. + + The `--pull` flag can take one of these values: + + | Value | Description | + |:--------------------|:------------------------------------------------------------------------------------------------------------------| + | `missing` (default) | Pull the image if it was not found in the image cache, or use the cached image otherwise. | + | `never` | Do not pull the image, even if it's missing, and produce an error if the image does not exist in the image cache. | + | `always` | Always perform a pull before creating the container. | + + When creating (and running) a container from an image, the daemon checks if the + image exists in the local image cache. If the image is missing, an error is + returned to the cli, allowing it to initiate a pull. + + The default (`missing`) is to only pull the image if it is not present in the + daemon's image cache. This default allows you to run images that only exist + locally (for example, images you built from a Dockerfile, but that have not + been pushed to a registry), and reduces networking. + + The `always` option always initiates a pull before creating the container. This + option makes sure the image is up-to-date, and prevents you from using outdated + images, but may not be suitable in situations where you want to test a locally + built image before pushing (as pulling the image overwrites the existing image + in the image cache). + + The `never` option disables (implicit) pulling images when creating containers, + and only uses images that are available in the image cache. If the specified + image is not found, an error is produced, and the container is not created. + This option is useful in situations where networking is not available, or to + prevent images from being pulled implicitly when creating containers. + + The following example shows `docker run` with the `--pull=never` option set, + which produces en error as the image is missing in the image-cache: + + ```console + $ docker run --pull=never hello-world + docker: Error response from daemon: No such image: hello-world:latest. + ``` + ### Set environment variables (-e, --env, --env-file) ```console @@ -1169,10 +1211,10 @@ examples: |- VAR2=value2 USER - $ docker run --env-file env.list ubuntu env | grep VAR + $ docker run --env-file env.list ubuntu env | grep -E 'VAR|USER' VAR1=value1 VAR2=value2 - USER=denis + USER=jonzeolla ``` ### Set metadata on container (-l, --label, --label-file) @@ -1376,9 +1418,32 @@ examples: |- > This option fails if the container isolation is `hyperv` or when running Linux > Containers on Windows (LCOW). + ### Using dynamically created devices (--device-cgroup-rule) + + Devices available to a container are assigned at creation time. The + assigned devices will both be added to the cgroup.allow file and + created into the container once it is run. This poses a problem when + a new device needs to be added to running container. + + One of the solutions is to add a more permissive rule to a container + allowing it access to a wider range of devices. For example, supposing + our container needs access to a character device with major `42` and + any number of minor number (added as new devices appear), the + following rule would be added: + + ```console + $ docker run -d --device-cgroup-rule='c 42:* rmw' -name my-container my-image + ``` + + Then, a user could ask `udev` to execute a script that would `docker exec my-container mknod newDevX c 42 ` + the required device when it is added. + + > **Note**: initially present devices still need to be explicitly added to the + > `docker run` / `docker create` command. + ### Access an NVIDIA GPU - The `--gpus­` flag allows you to access NVIDIA GPU resources. First you need to + The `--gpus` flag allows you to access NVIDIA GPU resources. First you need to install [nvidia-container-runtime](https://nvidia.github.io/nvidia-container-runtime/). Visit [Specify a container's resources](https://docs.docker.com/config/containers/resource_constraints/) for more information. @@ -1400,7 +1465,7 @@ examples: |- The example below exposes the first and third GPUs. ```console - $ docker run -it --rm --gpus device=0,2 nvidia-smi + $ docker run -it --rm --gpus '"device=0,2"' nvidia-smi ``` ### Restart policies (--restart) @@ -1485,7 +1550,7 @@ examples: |- > In other words, the following script is not supported: > > ```console - > $ docker run -it --ulimit as=1024 fedora /bin/bash` + > $ docker run -it --ulimit as=1024 fedora /bin/bash > ``` The values are sent to the appropriate `syscall` as they are set. @@ -1541,9 +1606,9 @@ examples: |- ### Specify isolation technology for container (--isolation) This option is useful in situations where you are running Docker containers on - Windows. The `--isolation ` option sets a container's isolation technology. - On Linux, the only supported is the `default` option which uses - Linux namespaces. These two commands are equivalent on Linux: + Windows. The `--isolation=` option sets a container's isolation technology. + On Linux, the only supported is the `default` option which uses Linux namespaces. + These two commands are equivalent on Linux: ```console $ docker run -d busybox top @@ -1552,16 +1617,15 @@ examples: |- On Windows, `--isolation` can take one of these values: + | Value | Description | + |:----------|:-------------------------------------------------------------------------------------------| + | `default` | Use the value specified by the Docker daemon's `--exec-opt` or system default (see below). | + | `process` | Shared-kernel namespace isolation. | + | `hyperv` | Hyper-V hypervisor partition-based isolation. | - | Value | Description | - |:----------|:------------------------------------------------------------------------------------------------------------------| - | `default` | Use the value specified by the Docker daemon's `--exec-opt` or system default (see below). | - | `process` | Shared-kernel namespace isolation (not supported on Windows client operating systems older than Windows 10 1809). | - | `hyperv` | Hyper-V hypervisor partition-based isolation. | - - The default isolation on Windows server operating systems is `process`. The default - isolation on Windows client operating systems is `hyperv`. An attempt to start a container on a client - operating system older than Windows 10 1809 with `--isolation process` will fail. + The default isolation on Windows server operating systems is `process`, and `hyperv` + on Windows client operating systems, such as Windows 10. Process isolation is more + performant, but requires the image to On Windows server, assuming the default configuration, these commands are equivalent and result in `process` isolation: diff --git a/_data/engine-cli/docker_search.yaml b/_data/engine-cli/docker_search.yaml index 198bd84e83..e7b82b5a47 100644 --- a/_data/engine-cli/docker_search.yaml +++ b/_data/engine-cli/docker_search.yaml @@ -153,7 +153,7 @@ examples: |- Valid placeholders for the Go template are: | Placeholder | Description | - | -------------- | --------------------------------- | + |----------------|-----------------------------------| | `.Name` | Image Name | | `.Description` | Image description | | `.StarCount` | Number of stars for the image | diff --git a/_data/engine-cli/docker_secret_ls.yaml b/_data/engine-cli/docker_secret_ls.yaml index d4ea333152..5fd6473acf 100644 --- a/_data/engine-cli/docker_secret_ls.yaml +++ b/_data/engine-cli/docker_secret_ls.yaml @@ -121,7 +121,7 @@ examples: |- Valid placeholders for the Go template are listed below: | Placeholder | Description | - | ------------ | ------------------------------------------------------------------------------------ | + |--------------|--------------------------------------------------------------------------------------| | `.ID` | Secret ID | | `.Name` | Secret name | | `.CreatedAt` | Time when the secret was created | diff --git a/_data/engine-cli/docker_service_create.yaml b/_data/engine-cli/docker_service_create.yaml index d3d5359a3c..a994bc1bb6 100644 --- a/_data/engine-cli/docker_service_create.yaml +++ b/_data/engine-cli/docker_service_create.yaml @@ -1240,16 +1240,15 @@ examples: |- expression (AND match). Constraints can match node or Docker Engine labels as follows: - node attribute | matches | example - ---------------------|--------------------------------|----------------------------------------------- - `node.id` | Node ID | `node.id==2ivku8v2gvtg4` - `node.hostname` | Node hostname | `node.hostname!=node-2` - `node.role` | Node role (`manager`/`worker`) | `node.role==manager` - `node.platform.os` | Node operating system | `node.platform.os==windows` - `node.platform.arch` | Node architecture | `node.platform.arch==x86_64` - `node.labels` | User-defined node labels | `node.labels.security==high` - `engine.labels` | Docker Engine's labels | `engine.labels.operatingsystem==ubuntu-14.04` - + | node attribute | matches | example | + |----------------------|--------------------------------|-----------------------------------------------| + | `node.id` | Node ID | `node.id==2ivku8v2gvtg4` | + | `node.hostname` | Node hostname | `node.hostname!=node-2` | + | `node.role` | Node role (`manager`/`worker`) | `node.role==manager` | + | `node.platform.os` | Node operating system | `node.platform.os==windows` | + | `node.platform.arch` | Node architecture | `node.platform.arch==x86_64` | + | `node.labels` | User-defined node labels | `node.labels.security==high` | + | `engine.labels` | Docker Engine's labels | `engine.labels.operatingsystem==ubuntu-14.04` | `engine.labels` apply to Docker Engine labels like operating system, drivers, etc. Swarm administrators add `node.labels` for operational purposes by using diff --git a/_data/engine-cli/docker_service_ls.yaml b/_data/engine-cli/docker_service_ls.yaml index 8b580c212f..960293d0ab 100644 --- a/_data/engine-cli/docker_service_ls.yaml +++ b/_data/engine-cli/docker_service_ls.yaml @@ -138,14 +138,14 @@ examples: |- 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 + | 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 diff --git a/_data/engine-cli/docker_service_ps.yaml b/_data/engine-cli/docker_service_ps.yaml index 063996545e..05bce66933 100644 --- a/_data/engine-cli/docker_service_ps.yaml +++ b/_data/engine-cli/docker_service_ps.yaml @@ -182,16 +182,16 @@ examples: |- Valid placeholders for the Go template are listed below: - Placeholder | Description - ----------------|------------------------------------------------------------------------------------------ - `.ID` | Task ID - `.Name` | Task name - `.Image` | Task image - `.Node` | Node ID - `.DesiredState` | Desired state of the task (`running`, `shutdown`, or `accepted`) - `.CurrentState` | Current state of the task - `.Error` | Error - `.Ports` | Task published ports + | Placeholder | Description | + |-----------------|------------------------------------------------------------------| + | `.ID` | Task ID | + | `.Name` | Task name | + | `.Image` | Task image | + | `.Node` | Node ID | + | `.DesiredState` | Desired state of the task (`running`, `shutdown`, or `accepted`) | + | `.CurrentState` | Current state of the task | + | `.Error` | Error | + | `.Ports` | Task published ports | When using the `--format` option, the `service ps` command will either output the data exactly as the template declares or, when using the diff --git a/_data/engine-cli/docker_stack_ls.yaml b/_data/engine-cli/docker_stack_ls.yaml index bdde631b88..c2ebc8ff53 100644 --- a/_data/engine-cli/docker_stack_ls.yaml +++ b/_data/engine-cli/docker_stack_ls.yaml @@ -75,7 +75,7 @@ examples: |- Valid placeholders for the Go template are listed below: | Placeholder | Description | - | --------------- | ------------------ | + |-----------------|--------------------| | `.Name` | Stack name | | `.Services` | Number of services | | `.Orchestrator` | Orchestrator name | diff --git a/_data/engine-cli/docker_stack_ps.yaml b/_data/engine-cli/docker_stack_ps.yaml index a860fff6db..bf870e8d37 100644 --- a/_data/engine-cli/docker_stack_ps.yaml +++ b/_data/engine-cli/docker_stack_ps.yaml @@ -177,16 +177,16 @@ examples: |- Valid placeholders for the Go template are listed below: - Placeholder | Description - ----------------|------------------------------------------------------------------------------------------ - `.ID` | Task ID - `.Name` | Task name - `.Image` | Task image - `.Node` | Node ID - `.DesiredState` | Desired state of the task (`running`, `shutdown`, or `accepted`) - `.CurrentState` | Current state of the task - `.Error` | Error - `.Ports` | Task published ports + | Placeholder | Description | + |-----------------|------------------------------------------------------------------| + | `.ID` | Task ID | + | `.Name` | Task name | + | `.Image` | Task image | + | `.Node` | Node ID | + | `.DesiredState` | Desired state of the task (`running`, `shutdown`, or `accepted`) | + | `.CurrentState` | Current state of the task | + | `.Error` | Error | + | `.Ports` | Task published ports | When using the `--format` option, the `stack ps` command will either output the data exactly as the template declares or, when using the diff --git a/_data/engine-cli/docker_stack_services.yaml b/_data/engine-cli/docker_stack_services.yaml index 6249a768b4..3035330b31 100644 --- a/_data/engine-cli/docker_stack_services.yaml +++ b/_data/engine-cli/docker_stack_services.yaml @@ -120,13 +120,13 @@ examples: |- 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 + | Placeholder | Description | + |-------------|-----------------------------------| + | `.ID` | Service ID | + | `.Name` | Service name | + | `.Mode` | Service mode (replicated, global) | + | `.Replicas` | Service replicas | + | `.Image` | Service image | When using the `--format` option, the `stack services` command will either output the data exactly as the template declares or, when using the diff --git a/_data/engine-cli/docker_stats.yaml b/_data/engine-cli/docker_stats.yaml index 2c82eeb910..99c0aaa376 100644 --- a/_data/engine-cli/docker_stats.yaml +++ b/_data/engine-cli/docker_stats.yaml @@ -103,6 +103,13 @@ examples: |- 67b2525d8ad1 foobar 0.00% 1.727MiB / 1.952GiB 0.09% 2.48kB / 0B 4.11MB / 0B 2 ``` + Running `docker stats` on container with name nginx and getting output in `json` format. + + ```console + $ docker stats nginx --no-stream --format "{{ json . }}" + {"BlockIO":"0B / 13.3kB","CPUPerc":"0.03%","Container":"nginx","ID":"ed37317fbf42","MemPerc":"0.24%","MemUsage":"2.352MiB / 982.5MiB","Name":"nginx","NetIO":"539kB / 606kB","PIDs":"2"} + ``` + Running `docker stats` with customized format on all (Running and Stopped) containers. ```console @@ -149,18 +156,17 @@ examples: |- Valid placeholders for the Go template are listed below: - Placeholder | Description - ------------ | -------------------------------------------- - `.Container` | Container name or ID (user input) - `.Name` | Container name - `.ID` | Container ID - `.CPUPerc` | CPU percentage - `.MemUsage` | Memory usage - `.NetIO` | Network IO - `.BlockIO` | Block IO - `.MemPerc` | Memory percentage (Not available on Windows) - `.PIDs` | Number of PIDs (Not available on Windows) - + | Placeholder | Description | + |--------------|----------------------------------------------| + | `.Container` | Container name or ID (user input) | + | `.Name` | Container name | + | `.ID` | Container ID | + | `.CPUPerc` | CPU percentage | + | `.MemUsage` | Memory usage | + | `.NetIO` | Network IO | + | `.BlockIO` | Block IO | + | `.MemPerc` | Memory percentage (Not available on Windows) | + | `.PIDs` | Number of PIDs (Not available on Windows) | When using the `--format` option, the `stats` command either outputs the data exactly as the template declares or, when using the diff --git a/_data/engine-cli/docker_volume_ls.yaml b/_data/engine-cli/docker_volume_ls.yaml index 1ccd2016a1..4a691f0655 100644 --- a/_data/engine-cli/docker_volume_ls.yaml +++ b/_data/engine-cli/docker_volume_ls.yaml @@ -162,14 +162,14 @@ examples: |- Valid placeholders for the Go template are listed below: - Placeholder | Description - --------------|------------------------------------------------------------------------------------------ - `.Name` | Volume name - `.Driver` | Volume driver - `.Scope` | Volume scope (local, global) - `.Mountpoint` | The mount point of the volume on the host - `.Labels` | All labels assigned to the volume - `.Label` | Value of a specific label for this volume. For example `{{.Label "project.version"}}` + | Placeholder | Description | + |---------------|---------------------------------------------------------------------------------------| + | `.Name` | Volume name | + | `.Driver` | Volume driver | + | `.Scope` | Volume scope (local, global) | + | `.Mountpoint` | The mount point of the volume on the host | + | `.Labels` | All labels assigned to the volume | + | `.Label` | Value of a specific label for this volume. For example `{{.Label "project.version"}}` | When using the `--format` option, the `volume ls` command will either output the data exactly as the template declares or, when using the