mirror of https://github.com/docker/cli.git
docs: improve docs on container identification
Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
This commit is contained in:
David Karlsson
parent
fad227d3fd
commit
03dc8832ed
|
|
@ -128,27 +128,58 @@ Use `docker ps -a` to view a list of all containers, including those that are st
|
|||
|
||||
## Examples
|
||||
|
||||
### <a name="name"></a> Assign name and allocate pseudo-TTY (--name, -it)
|
||||
### <a name="name"></a> 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
|
||||
...
|
||||
```
|
||||
|
||||
### <a name="cidfile"></a> 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"
|
||||
```
|
||||
|
|
|
|||
|
|
@ -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,
|
||||
|
|
|
|||
Loading…
Reference in New Issue