From 03dc8832ed04c339a6483ea8abe1a486eab23fd3 Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Wed, 8 Nov 2023 17:13:44 +0100
Subject: [PATCH] docs: improve docs on container identification
Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
---
docs/reference/commandline/run.md | 59 +++++++++++++++-----
docs/reference/run.md | 93 ++++++++++++++++++-------------
2 files changed, 99 insertions(+), 53 deletions(-)
diff --git a/docs/reference/commandline/run.md b/docs/reference/commandline/run.md
index 0585294f4d..5a374afa8d 100644
--- a/docs/reference/commandline/run.md
+++ b/docs/reference/commandline/run.md
@@ -128,27 +128,58 @@ Use `docker ps -a` to view a list of all containers, including those that are st
## Examples
-### Assign name and allocate pseudo-TTY (--name, -it)
+### Assign name (--name)
+
+The `--name` flag lets you specify a custom identifier for a container. The
+following example runs a container named `test` using the `nginx:alpine` image
+in [detached mode](#detach).
```console
-$ docker run --name test -it debian
-
-root@d6c0fe130dba:/# exit 13
-$ echo $?
-13
-$ docker ps -a | grep test
-d6c0fe130dba debian:7 "/bin/bash" 26 seconds ago Exited (13) 17 seconds ago test
+$ docker run --name test -d nginx:alpine
+4bed76d3ad428b889c56c1ecc2bf2ed95cb08256db22dc5ef5863e1d03252a19
+$ docker ps
+CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
+4bed76d3ad42 nginx:alpine "/docker-entrypoint.…" 1 second ago Up Less than a second 80/tcp test
```
-This example runs a container named `test` using the `debian:latest`
-image. The `-it` instructs Docker to allocate a pseudo-TTY connected to
-the container's stdin; creating an interactive `bash` shell in the container.
-The example quits the `bash` shell by entering
-`exit 13`, passing the exit code on to the caller of
-`docker run`, and recording it in the `test` container's metadata.
+You can reference the container by name with other commands. For example, the
+following commands stop and remove a container named `test`:
+
+```console
+$ docker stop test
+test
+$ docker rm test
+test
+```
+
+If you don't specify a custom name using the `--name` flag, the daemon assigns
+a randomly generated name, such as `vibrant_cannon`, to the container. Using a
+custom-defined name provides the benefit of having an easy-to-remember ID for a
+container.
+
+Moreover, if you connect the container to a user-defined bridge network, other
+containers on the same network can refer to the container by name via DNS.
+
+```console
+$ docker network create mynet
+cb79f45948d87e389e12013fa4d969689ed2c3316985dd832a43aaec9a0fe394
+$ docker run --name test --net mynet -d nginx:alpine
+58df6ecfbc2ad7c42d088ed028d367f9e22a5f834d7c74c66c0ab0485626c32a
+$ docker run --net mynet busybox:latest ping test
+PING test (172.18.0.2): 56 data bytes
+64 bytes from 172.18.0.2: seq=0 ttl=64 time=0.073 ms
+64 bytes from 172.18.0.2: seq=1 ttl=64 time=0.411 ms
+64 bytes from 172.18.0.2: seq=2 ttl=64 time=0.319 ms
+64 bytes from 172.18.0.2: seq=3 ttl=64 time=0.383 ms
+...
+```
### Capture container ID (--cidfile)
+To help with automation, you can have Docker write the container ID out to a
+file of your choosing. This is similar to how some programs might write out
+their process ID to a file (you might've seen them as PID files):
+
```console
$ docker run --cidfile /tmp/docker_test.cid ubuntu echo "test"
```
diff --git a/docs/reference/run.md b/docs/reference/run.md
index db298c86c3..4f43d7eba7 100644
--- a/docs/reference/run.md
+++ b/docs/reference/run.md
@@ -22,14 +22,43 @@ A `docker run` command takes the following form:
$ docker run [OPTIONS] IMAGE[:TAG|@DIGEST] [COMMAND] [ARG...]
```
-The `docker run` command must specify an [image](https://docs.docker.com/glossary/#image)
+The `docker run` command must specify an [image reference](#image-references)
to create the container from.
+### Image references
+
+The image reference is the name and version of the image. You can use the image
+reference to create or run a container based on an image.
+
+- `docker run IMAGE[:TAG][@DIGEST]`
+- `docker create IMAGE[:TAG][@DIGEST]`
+
+An image tag is the image version, which defaults to `latest` when omitted. Use
+the tag to run a container from specific version of an image. For example, to
+run version `23.10` of the `ubuntu` image: `docker run ubuntu:23.10`.
+
+#### Image digests
+
+Images using the v2 or later image format have a content-addressable identifier
+called a digest. As long as the input used to generate the image is unchanged,
+the digest value is predictable.
+
+The following example runs a container from the `alpine` image with the
+`sha256:9cacb71397b640eca97488cf08582ae4e4068513101088e9f96c9814bfda95e0` digest:
+
+```console
+$ docker run alpine@sha256:9cacb71397b640eca97488cf08582ae4e4068513101088e9f96c9814bfda95e0 date
+```
+
+### Options
+
`[OPTIONS]` let you configure options for the container. For example, you can
give the container a name (`--name`), or run it as a background process (`-d`).
You can also set options to control things like resource constraints and
networking.
+### Commands and arguments
+
You can use the `[COMMAND]` and `[ARG...]` positional arguments to specify
commands and arguments for the container to run when it starts up. For example,
you can specify `sh` as the `[COMMAND]`, combined with the `-i` and `-t` flags,
@@ -95,55 +124,41 @@ For more information about re-attaching to a background container, see
## Container identification
-### Name (--name)
-
-The operator can identify a container in three ways:
+You can identify a container in three ways:
| Identifier type | Example value |
|:----------------------|:-------------------------------------------------------------------|
-| UUID long identifier | "f78375b1c487e03c9438c729345e54db9d20cfa2ac1fc3494b6eb60872e74778" |
-| UUID short identifier | "f78375b1c487" |
-| Name | "evil_ptolemy" |
+| UUID long identifier | `f78375b1c487e03c9438c729345e54db9d20cfa2ac1fc3494b6eb60872e74778` |
+| UUID short identifier | `f78375b1c487` |
+| Name | `evil_ptolemy` |
-The UUID identifiers come from the Docker daemon. If you do not assign a
-container name with the `--name` option, then the daemon generates a random
-string name for you. Defining a `name` can be a handy way to add meaning to a
-container. If you specify a `name`, you can use it when referencing the
-container within a Docker network. This works for both background and foreground
-Docker containers.
+The UUID identifier is a random ID assigned to the container by the daemon.
-> **Note**
->
-> Containers on the default bridge network must be linked to communicate by name.
+The daemon generates a random string name for containers automatically. You can
+also defined a custom name using [the `--name` flag](./commandline/run.md#name).
+Defining a `name` can be a handy way to add meaning to a container. If you
+specify a `name`, you can use it when referring to the container in a
+user-defined network. This works for both background and foreground Docker
+containers.
-### PID equivalent
+A container identifier is not the same thing as an image reference. The image
+reference specifies which image to use when you run a container. You can't run
+`docker exec nginx:alpine sh` to open a shell in a container based on the
+`nginx:alpine` image, because `docker exec` expects a container identifier
+(name or ID), not an image.
-Finally, to help with automation, you can have Docker write the
-container ID out to a file of your choosing. This is similar to how some
-programs might write out their process ID to a file (you've seen them as
-PID files):
-
- --cidfile="": Write the container ID to the file
-
-### Image[:tag]
-
-While not strictly a means of identifying a container, you can specify a version of an
-image you'd like to run the container with by adding `image[:tag]` to the command. For
-example, `docker run ubuntu:22.04`.
-
-### Image[@digest]
-
-Images using the v2 or later image format have a content-addressable identifier
-called a digest. As long as the input used to generate the image is unchanged,
-the digest value is predictable and referenceable.
-
-The following example runs a container from the `alpine` image with the
-`sha256:9cacb71397b640eca97488cf08582ae4e4068513101088e9f96c9814bfda95e0` digest:
+While the image used by a container is not an identifier for the container, you
+find out the IDs of containers using an image by using the `--filter` flag. For
+example, the following `docker ps` command gets the IDs of all running
+containers based on the `nginx:alpine` image:
```console
-$ docker run alpine@sha256:9cacb71397b640eca97488cf08582ae4e4068513101088e9f96c9814bfda95e0 date
+$ docker ps -q --filter ancestor=nginx:alpine
```
+For more information about using filters, see
+[Filtering](https://docs.docker.com/config/filter/).
+
## PID settings (--pid)
--pid="" : Set the PID (Process) Namespace mode for the container,