Guest24897
/
DockerCLI
mirror of https://github.com/docker/cli.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

docs: unify "docker create" and "docker run" reference 

The `docker create` command shares most (all) of its options with `docker run`,
which uses `docker create` under the hood. The `docker create` reference docs
already referred users to the `docker run` sections for details, but some
flags were only documented on the `docker create` page.

This patch:

- moves those flags from the `docker create` to the `docker run` page
- does some minor rephrasing and touch-ups.

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
This commit is contained in:
Sebastiaan van Stijn 2022-03-01 12:29:54 +01:00
parent 6c6203fcc5
commit 6c16afe1d4
No known key found for this signature in database
GPG Key ID: 76698F39D527CE8C
2 changed files with 61 additions and 78 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

91
docs/reference/commandline/create.md
View File

@ -134,35 +134,51 @@ Options:
## Description ## Description
The `docker create` command creates a writeable container layer over the The `docker container create` (or shorthand: `docker create`) command creates a
specified image and prepares it for running the specified command. The 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` 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 except the container is never started. You can then use the `docker container start`
`docker start <container_id>` command to start the container at any point. (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 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 so that it is ready to start when you need it. The initial status of the
new container is `created`. 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.
## Examples ## Examples
### Create and start a container ### Create and start a container
```console The following example creates an interactive container with a pseudo-TTY attached,
$ docker create -t -i fedora bash then starts the container and attaches to it:
```console
$ docker container create -i -t --name mycontainer alpine
6d8af538ec541dd581ebc2a24153a28329acb5268abe5ef868c1f1a261221752 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 ### 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` (i.e., `docker run` too). For example, this allows you to `create` the `data`
volume container, and then use it from another container: volume container, and then use it from another container:
@ -199,58 +215,3 @@ drwxr-sr-x 3 1000 staff 60 Dec 1 03:28 .local
drwx--S--- 2 1000 staff 460 Dec 5 00:51 .ssh drwx--S--- 2 1000 staff 460 Dec 5 00:51 .ssh
drwxr-xr-x 32 1000 staff 1140 Dec 5 04:01 docker 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=<value>` 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 <minor>`
the required device when it is added.
NOTE: initially present devices still need to be explicitly added to
the create/run command

42
docs/reference/commandline/run.md
View File

@ -610,9 +610,32 @@ PS C:\> docker run --device=class/86E0D1E0-8089-11D0-9CE4-08003E301F73 mcr.micro
> This option fails if the container isolation is `hyperv` or when running Linux > This option fails if the container isolation is `hyperv` or when running Linux
> Containers on Windows (LCOW). > Containers on Windows (LCOW).
### <a name="device-cgroup-rule"></a> 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 <minor>`
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 ### 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/). 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/) Visit [Specify a container's resources](https://docs.docker.com/config/containers/resource_constraints/)
for more information. for more information.
@ -776,9 +799,9 @@ and 30 seconds for Windows containers.
### Specify isolation technology for container (--isolation) ### Specify isolation technology for container (--isolation)
This option is useful in situations where you are running Docker containers on This option is useful in situations where you are running Docker containers on
Windows. The `--isolation <value>` option sets a container's isolation technology. Windows. The `--isolation=<value>` option sets a container's isolation technology.
On Linux, the only supported is the `default` option which uses On Linux, the only supported is the `default` option which uses Linux namespaces.
Linux namespaces. These two commands are equivalent on Linux: These two commands are equivalent on Linux:
```console ```console
$ docker run -d busybox top $ docker run -d busybox top
@ -787,16 +810,15 @@ $ docker run -d --isolation default busybox top
On Windows, `--isolation` can take one of these values: On Windows, `--isolation` can take one of these values:
| Value | Description | | Value | Description |
|:----------|:------------------------------------------------------------------------------------------------------------------| |:----------|:-------------------------------------------------------------------------------------------|
| `default` | Use the value specified by the Docker daemon's `--exec-opt` or system default (see below). | | `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). | | `process` | Shared-kernel namespace isolation. |
| `hyperv` | Hyper-V hypervisor partition-based isolation. | | `hyperv` | Hyper-V hypervisor partition-based isolation. |
The default isolation on Windows server operating systems is `process`. The default The default isolation on Windows server operating systems is `process`, and `hyperv`
isolation on Windows client operating systems is `hyperv`. An attempt to start a container on a client on Windows client operating systems, such as Windows 10. Process isolation is more
operating system older than Windows 10 1809 with `--isolation process` will fail. performant, but requires the image to
On Windows server, assuming the default configuration, these commands are equivalent On Windows server, assuming the default configuration, these commands are equivalent
and result in `process` isolation: and result in `process` isolation: