Merge pull request #20975 from dvdksn/cli-27.3.1

vendor: v27.3.1 CLI reference

data/engine-cli/docker.yaml

@@ -101,8 +101,7 @@ long: |-
     $ docker run -v /host:/container example/mysql
     ```
 
-    > **Note**
-    >
+    > [!NOTE]
     > Do not use the `-t` and `-a stderr` options together due to
     > limitations in the `pty` implementation. All `stderr` in `pty` mode
     > simply goes to `stdout`.
@@ -162,8 +161,7 @@ long: |-
     [change the `.docker` directory](#change-the-docker-directory) section to use a
     different location.
 
-    > **Warning**
-    >
+    > [!WARNING]
     > The configuration file and other files inside the `~/.docker` configuration
     > directory may contain sensitive information, such as authentication information
     > for proxies or, depending on your credential store, credentials for your image
@@ -239,8 +237,7 @@ long: |-
     [environment variables](#environment-variables) and [HTTP/HTTPS proxy](/engine/daemon/proxy/#httphttps-proxy)
     sections for configuring proxy settings for the CLI and daemon.
 
-    > **Warning**
-    >
+    > [!WARNING]
     > Proxy settings may contain sensitive information (for example, if the proxy
     > requires authentication). Environment variables are stored as plain text in
     > the container's configuration, and as such can be inspected through the remote
@@ -608,8 +605,7 @@ examples: |-
     $ docker -H tcp://174.17.0.1:2376 ps
     ```
 
-    > **Note**
-    >
+    > [!NOTE]
     > By convention, the Docker daemon uses port `2376` for secure TLS connections,
     > and port `2375` for insecure, non-TLS connections.
 

data/engine-cli/docker_config_create.yaml

@@ -5,8 +5,7 @@ long: |-
 
     For detailed information about using configs, refer to [store configuration data using Docker Configs](/engine/swarm/configs/).
 
-    > **Note**
-    >
+    > [!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](/engine/swarm/) in the

data/engine-cli/docker_config_inspect.yaml

@@ -11,8 +11,7 @@ long: |-
 
     For detailed information about using configs, refer to [store configuration data using Docker Configs](/engine/swarm/configs/).
 
-    > **Note**
-    >
+    > [!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](/engine/swarm/) in the

data/engine-cli/docker_config_ls.yaml

@@ -6,8 +6,7 @@ long: |-
 
     For detailed information about using configs, refer to [store configuration data using Docker Configs](/engine/swarm/configs/).
 
-    > **Note**
-    >
+    > [!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](/engine/swarm/) in the

data/engine-cli/docker_config_rm.yaml

@@ -6,8 +6,7 @@ long: |-
 
     For detailed information about using configs, refer to [store configuration data using Docker Configs](/engine/swarm/configs/).
 
-    > **Note**
-    >
+    > [!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](/engine/swarm/) in the
@@ -34,8 +33,7 @@ examples: |-
     sapth4csdo5b6wz2p5uimh5xg
     ```
 
-    > **Warning**
-    >
+    > [!WARNING]
     > This command doesn't ask for confirmation before removing a config.
     { .warning }
 deprecated: false

data/engine-cli/docker_container_attach.yaml

@@ -8,8 +8,7 @@ long: |-
     ID or name. This lets you view its output or control it interactively, as
     though the commands were running directly in your terminal.
 
-    > **Note**
-    >
+    > [!NOTE]
     > The `attach` command displays the output of the container's `ENTRYPOINT` and
     > `CMD` process. This can appear as if the attach command is hung when in fact
     > the process may simply not be writing any output at that time.
@@ -22,8 +21,7 @@ long: |-
     the container. If the container was run with `-i` and `-t`, you can detach from
     a container and leave it running using the `CTRL-p CTRL-q` key sequence.
 
-    > **Note**
-    >
+    > [!NOTE]
     > A process running as PID 1 inside a container is treated specially by
     > Linux: it ignores any signal with the default action. So, the process
     > doesn't terminate on `SIGINT` or `SIGTERM` unless it's coded to do so.

data/engine-cli/docker_container_kill.yaml

@@ -17,8 +17,7 @@ long: |-
     process. For example, the `SIGHUP` signal in most cases will be non-terminal,
     and the container will continue running after receiving the signal.
 
-    > **Note**
-    >
+    > [!NOTE]
     > `ENTRYPOINT` and `CMD` in the *shell* form run as a child process of
     > `/bin/sh -c`, which does not pass signals. This means that the executable is
     > not the container’s PID 1 and does not receive Unix signals.

data/engine-cli/docker_container_run.yaml

@@ -1260,8 +1260,7 @@ examples: |-
     those with `--network=host`, have their own UTS namespace. Setting `--uts` to
     `host` results in the container using the same UTS namespace as the host.
 
-    > **Note**
-    >
+    > [!NOTE]
     > Docker disallows combining the `--hostname` and `--domainname` flags with
     > `--uts=host`. This is to prevent containers running in the host's UTS
     > namespace from attempting to change the hosts' configuration.
@@ -1319,8 +1318,7 @@ examples: |-
     do. This flag exists to allow special use-cases, like running Docker within
     Docker.
 
-    > **Warning**
-    >
+    > [!WARNING]
     > Use the `--privileged` flag with caution.
     > A container with `--privileged` is not a securely sandboxed process.
     > Containers in this mode can get a root shell on the host
@@ -1502,8 +1500,7 @@ examples: |-
     page](/network/) explains in detail how to publish ports
     with Docker.
 
-    > **Note**
-    >
+    > [!NOTE]
     > If you don't specify an IP address (i.e., `-p 80:80` instead of `-p
     > 127.0.0.1:80:80`) when publishing a container's ports, Docker publishes the
     > port on all interfaces (address `0.0.0.0`) by default. These ports are
@@ -1684,8 +1681,7 @@ examples: |-
     connectivity, containers connected to the same multi-host network but launched
     from different Engines can also communicate in this way.
 
-    > **Note**
-    >
+    > [!NOTE]
     > The default bridge network only allows containers to communicate with each other using
     > internal IP addresses. User-created bridge networks provide DNS resolution between
     > containers using container names.
@@ -1753,8 +1749,7 @@ examples: |-
     $ docker run -itd --network=name=my-net,\"driver-opt=com.docker.network.endpoint.sysctls=net.ipv4.conf.IFNAME.log_martians=1,net.ipv4.conf.IFNAME.forwarding=0\",ip=192.0.2.42 busybox
     ```
 
-    > **Note**
-    >
+    > [!NOTE]
     > Network drivers may restrict the sysctl settings that can be modified and, to protect
     > the operation of the network, new restrictions may be added in the future.
 
@@ -1881,8 +1876,7 @@ examples: |-
     fdisk: unable to open /dev/xvdc: Operation not permitted
     ```
 
-    > **Note**
-    >
+    > [!NOTE]
     > The `--device` option cannot be safely used with ephemeral devices. You shouldn't
     > add block devices that may be removed to untrusted containers with `--device`.
 
@@ -1904,15 +1898,13 @@ examples: |-
     PS C:\> docker run --device=class/86E0D1E0-8089-11D0-9CE4-08003E301F73 mcr.microsoft.com/windows/servercore:ltsc2019
     ```
 
-    > **Note**
-    >
+    > [!NOTE]
     > The `--device` option is only supported on process-isolated Windows containers,
     > and produces an error if the container isolation is `hyperv`.
 
     #### CDI devices
 
-    > **Note**
-    >
+    > [!NOTE]
     > The CDI feature is experimental, and potentially subject to change.
     > CDI is currently only supported for Linux containers.
 
@@ -1979,8 +1971,7 @@ examples: |-
     $ cat somefile | docker run -i -a stdin mybuilder dobuild
     ```
 
-    > **Note**
-    >
+    > [!NOTE]
     > A process running as PID 1 inside a container is treated specially by
     > Linux: it ignores any signal with the default action. So, the process
     > doesn't terminate on `SIGINT` or `SIGTERM` unless it's coded to do so.
@@ -2093,16 +2084,16 @@ examples: |-
     Then, a user could ask `udev` to execute a script that would `docker exec my-container mknod newDevX c 42 <minor>`
     the required device when it is added.
 
-    > **Note**: You still need to explicitly add initially present devices to the
+    > [!NOTE]
+    > You still need to explicitly add initially present devices to the
     > `docker run` / `docker create` command.
 
     ### Access an NVIDIA GPU {#gpus}
 
     The `--gpus` flag allows you to access NVIDIA GPU resources. First you need to
     install the [nvidia-container-runtime](https://nvidia.github.io/nvidia-container-runtime/).
 
-    > **Note**
-    >
+    > [!NOTE]
     > You can also specify a GPU as a CDI device with the `--device` flag, see
     > [CDI devices](#cdi-devices).
 
@@ -2212,11 +2203,10 @@ examples: |-
     `--rm` flag:
 
     ```text
-    --rm=false: Automatically remove the container when it exits
+    --rm: Automatically remove the container when it exits
     ```
 
-    > **Note**
-    >
+    > [!NOTE]
     > If you set the `--rm` flag, Docker also removes the anonymous volumes
     > associated with the container when the container is removed. This is similar
     > to running `docker rm -v my-container`. Only volumes that are specified
@@ -2314,14 +2304,12 @@ examples: |-
     1024
     ```
 
-    > **Note**
-    >
+    > [!NOTE]
     > If you don't provide a hard limit value, Docker uses the soft limit value
     > for both values. If you don't provide any values, they are inherited from
     > the default `ulimits` set on the daemon.
 
-    > **Note**
-    >
+    > [!NOTE]
     > The `as` option is deprecated.
     > In other words, the following script is not supported:
     >
@@ -2386,8 +2374,7 @@ examples: |-
     $ docker run --security-opt label=level:s0:c100,c200 -it fedora bash
     ```
 
-    > **Note**
-    >
+    > [!NOTE]
     > Automatic translation of MLS labels isn't supported.
 
     To disable the security labeling for a container entirely, you can use
@@ -2405,8 +2392,7 @@ examples: |-
     $ docker run --security-opt label=type:svirt_apache_t -it ubuntu bash
     ```
 
-    > **Note**
-    >
+    > [!NOTE]
     > You would have to write policy defining a `svirt_apache_t` type.
 
     To prevent your container processes from gaining additional privileges, you can
@@ -2527,8 +2513,7 @@ examples: |-
     $ docker run --sysctl net.ipv4.ip_forward=1 someimage
     ```
 
-    > **Note**
-    >
+    > [!NOTE]
     > Not all sysctls are namespaced. Docker does not support changing sysctls
     > inside of a container that also modify the host system. As the kernel
     > evolves we expect to see more sysctls become namespaced.

data/engine-cli/docker_container_stats.yaml

@@ -10,8 +10,7 @@ long: |-
     If you need more detailed information about a container's resource usage, use
     the `/containers/(id)/stats` API endpoint.
 
-    > **Note**
-    >
+    > [!NOTE]
     > On Linux, the Docker CLI reports memory usage by subtracting cache usage from
     > the total memory usage. The API does not perform such a calculation but rather
     > provides the total memory usage and the amount from the cache so that clients
@@ -22,8 +21,7 @@ long: |-
     > field. On cgroup v2 hosts, the cache usage is defined as the value of
     > `inactive_file` field.
 
-    > **Note**
-    >
+    > [!NOTE]
     > The `PIDS` column contains the number of processes and kernel threads created
     > by that container. Threads is the term used by Linux kernel. Other equivalent
     > terms are "lightweight process" or "kernel task", etc. A large number in the

data/engine-cli/docker_container_update.yaml

@@ -13,8 +13,7 @@ long: |-
     4.6, you can only update `--kernel-memory` on a stopped container or on
     a running container with kernel memory initialized.
 
-    > **Warning**
-    >
+    > [!WARNING]
     > The `docker update` and `docker container update` commands are not supported
     > for Windows containers.
     { .warning }
@@ -219,8 +218,7 @@ examples: |-
     If the container was started without `--kernel-memory` you need to stop
     the container before updating kernel memory.
 
-    > **Note**
-    >
+    > [!NOTE]
     > The `--kernel-memory` option has been deprecated since Docker 20.10.
 
     For example, if you started a container with this command:

data/engine-cli/docker_image_build.yaml

@@ -2,8 +2,7 @@ command: docker image build
 aliases: docker image build, docker build, docker builder build
 short: Build an image from a Dockerfile
 long: |-
-    > **Note**
-    >
+    > [!NOTE]
     > This page refers to the **legacy implementation** of `docker build`,
     > using the legacy (pre-BuildKit) build backend.
     > This configuration is only relevant if you're building Windows containers.
@@ -420,7 +419,7 @@ examples: |-
 
     #### Overview
 
-    > **Note**
+    > [!NOTE]
     > The `--squash` option is an experimental feature, and should not be considered
     > stable.
 

data/engine-cli/docker_image_ls.yaml

@@ -92,6 +92,17 @@ options:
       experimentalcli: false
       kubernetes: false
       swarm: false
+    - option: tree
+      value_type: bool
+      default_value: "false"
+      description: List multi-platform images as a tree (EXPERIMENTAL)
+      deprecated: false
+      hidden: false
+      min_api_version: "1.47"
+      experimental: false
+      experimentalcli: true
+      kubernetes: false
+      swarm: false
 inherited_options:
     - option: help
       value_type: bool

data/engine-cli/docker_image_prune.yaml

@@ -112,6 +112,7 @@ examples: |-
     format is the `label!=...` (`label!=<key>` or `label!=<key>=<value>`), which removes
     images without the specified labels.
 
+    > [!NOTE]
     > **Predicting what will be removed**
     >
     > If you are using positive filtering (testing for the existence of a label or
@@ -216,8 +217,7 @@ examples: |-
     $ docker image prune --filter="label!=maintainer=john"
     ```
 
-    > **Note**
-    >
+    > [!NOTE]
     > You are prompted for confirmation before the `prune` removes
     > anything, but you are not shown a list of what will potentially be removed.
     > In addition, `docker image ls` doesn't support negative filtering, so it

data/engine-cli/docker_image_pull.yaml

@@ -195,8 +195,7 @@ examples: |-
     LABEL org.opencontainers.image.authors="some maintainer <[email protected]>"
     ```
 
-    > **Note**
-    >
+    > [!NOTE]
     > Using this feature "pins" an image to a specific version in time.
     > Docker does therefore not pull updated versions of an image, which may include
     > security updates. If you want to pull an updated image, you need to change the