зеркало из https://github.com/microsoft/docker.git
Rewrite ENTRYPOINT documentation covering all the combinations with examples.
Docker-DCO-1.1-Signed-off-by: Sven Dowideit <SvenDowideit@docker.com> (github: SvenDowideit)
This commit is contained in:
Sven Dowideit
Родитель
ba14ddf85b
Коммит
0390d04d8a
|
|
@ -460,43 +460,140 @@ The copy obeys the following rules:
|
|||
ENTRYPOINT has two forms:
|
||||
|
||||
- `ENTRYPOINT ["executable", "param1", "param2"]`
|
||||
(*exec* form, the preferred form)
|
||||
(the preferred *exec* form)
|
||||
- `ENTRYPOINT command param1 param2`
|
||||
(*shell* form)
|
||||
|
||||
There can only be one `ENTRYPOINT` in a `Dockerfile`. If you have more
|
||||
than one `ENTRYPOINT`, then only the last one in the `Dockerfile` will
|
||||
have an effect.
|
||||
An `ENTRYPOINT` allows you to configure a container that will run as an executable.
|
||||
|
||||
An `ENTRYPOINT` helps you to configure a container that you can run as
|
||||
an executable. That is, when you specify an `ENTRYPOINT`, then the whole
|
||||
container runs as if it was just that executable.
|
||||
For example, the following will start nginx with its default content, listening
|
||||
on port 80:
|
||||
|
||||
Unlike the behavior of the `CMD` instruction, The `ENTRYPOINT`
|
||||
instruction adds an entry command that will **not** be overwritten when
|
||||
arguments are passed to `docker run`. This allows arguments to be passed
|
||||
to the entry point, i.e. `docker run <image> -d` will pass the `-d`
|
||||
argument to the entry point.
|
||||
docker run -i -t --rm -p 80:80 nginx
|
||||
|
||||
You can specify parameters either in the `ENTRYPOINT` JSON array (as in
|
||||
"like an exec" above), or by using a `CMD` instruction. Parameters in
|
||||
the `ENTRYPOINT` instruction will not be overridden by the `docker run`
|
||||
arguments, but parameters specified via a `CMD` instruction will be
|
||||
overridden by `docker run` arguments.
|
||||
Command line arguments to `docker run <image>` will be appended after all
|
||||
elements in an *exec* form `ENTRYPOINT`, and will override all elements specified
|
||||
using `CMD`.
|
||||
This allows arguments to be passed to the entry point, i.e., `docker run <image> -d`
|
||||
will pass the `-d` argument to the entry point.
|
||||
You can override the `ENTRYPOINT` instruction using the `docker run --entrypoint`
|
||||
flag.
|
||||
|
||||
Like a `CMD`, you can specify a plain string for the `ENTRYPOINT` and it
|
||||
will execute in `/bin/sh -c`:
|
||||
The *shell* form prevents any `CMD` or `run` command line arguments from being
|
||||
used, but has the disadvantage that your `ENTRYPOINT` will be started as a
|
||||
subcommand of `/bin/sh -c`, which does not pass signals.
|
||||
This means that the executable will not be the container's `PID 1` - and
|
||||
will _not_ receive Unix signals - so your executable will not receive a
|
||||
`SIGTERM` from `docker stop <container>`.
|
||||
|
||||
Only the last `ENTRYPOINT` instruction in the `Dockerfile` will have an effect.
|
||||
|
||||
### Exec form ENTRYPOINT example
|
||||
|
||||
You can use the *exec* form of `ENTRYPOINT` to set fairly stable default commands
|
||||
and arguments and then use either form of `CMD` to set additional defaults that
|
||||
are more likely to be changed.
|
||||
|
||||
FROM ubuntu
|
||||
ENTRYPOINT ls -l
|
||||
ENTRYPOINT ["top", "-b"]
|
||||
CMD ["-c"]
|
||||
|
||||
For example, that `Dockerfile`'s image will *always* take a directory as
|
||||
an input and return a directory listing. If you wanted to make this
|
||||
optional but default, you could use a `CMD` instruction:
|
||||
When you run the container, you can see that `top` is the only process:
|
||||
|
||||
FROM ubuntu
|
||||
CMD ["-l"]
|
||||
ENTRYPOINT ["ls"]
|
||||
$ docker run -it --rm --name test top -H
|
||||
top - 08:25:00 up 7:27, 0 users, load average: 0.00, 0.01, 0.05
|
||||
Threads: 1 total, 1 running, 0 sleeping, 0 stopped, 0 zombie
|
||||
%Cpu(s): 0.1 us, 0.1 sy, 0.0 ni, 99.7 id, 0.0 wa, 0.0 hi, 0.0 si, 0.0 st
|
||||
KiB Mem: 2056668 total, 1616832 used, 439836 free, 99352 buffers
|
||||
KiB Swap: 1441840 total, 0 used, 1441840 free. 1324440 cached Mem
|
||||
|
||||
PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND
|
||||
1 root 20 0 19744 2336 2080 R 0.0 0.1 0:00.04 top
|
||||
|
||||
To examine the result further, you can use `docker exec`:
|
||||
|
||||
$ docker exec -it test ps aux
|
||||
USER PID %CPU %MEM VSZ RSS TTY STAT START TIME COMMAND
|
||||
root 1 2.6 0.1 19752 2352 ? Ss+ 08:24 0:00 top -b -H
|
||||
root 7 0.0 0.1 15572 2164 ? R+ 08:25 0:00 ps aux
|
||||
|
||||
And you can gracefully request `top` to shut down using `docker stop test`.
|
||||
|
||||
If you need to write a starter script for a single executable, you can ensure that
|
||||
the final executable receives the Unix signals by using `exec` and `gosu`
|
||||
(see [the Dockerfile best practices](/articles/dockerfile_best-practices/#entrypoint)
|
||||
for more details):
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
set -e
|
||||
|
||||
if [ "$1" = 'postgres' ]; then
|
||||
chown -R postgres "$PGDATA"
|
||||
|
||||
if [ -z "$(ls -A "$PGDATA")" ]; then
|
||||
gosu postgres initdb
|
||||
fi
|
||||
|
||||
exec gosu postgres "$@"
|
||||
fi
|
||||
|
||||
exec "$@"
|
||||
```
|
||||
|
||||
Lastly, if you need to do some extra cleanup (or communicate with other containers)
|
||||
on shutdown, or are co-ordinating more than one executable, you may need to ensure
|
||||
that the `ENTRYPOINT` script receives the Unix signals, passes them on, and then
|
||||
does some more work:
|
||||
|
||||
```
|
||||
#!/bin/sh
|
||||
# Note: I've written this using sh so it works in the busybox container too
|
||||
|
||||
# USE the trap if you need to also do manual cleanup after the service is stopped,
|
||||
# or need to start multiple services in the one container
|
||||
trap "echo TRAPed signal" HUP INT QUIT KILL TERM
|
||||
|
||||
# start service in background here
|
||||
/usr/sbin/apachectl start
|
||||
|
||||
echo "[hit enter key to exit] or run 'docker stop <container>'"
|
||||
read
|
||||
|
||||
# stop service and clean up here
|
||||
echo "stopping apache"
|
||||
/usr/sbin/apachectl stop
|
||||
|
||||
echo "exited $0"
|
||||
```
|
||||
|
||||
If you run this image with `docker run -it --rm -p 80:80 --name test apache`,
|
||||
you can then examine the container's processes with `docker exec`, or `docker top`,
|
||||
and then ask the script to stop Apache:
|
||||
|
||||
```bash
|
||||
$ docker exec -it test ps aux
|
||||
USER PID %CPU %MEM VSZ RSS TTY STAT START TIME COMMAND
|
||||
root 1 0.1 0.0 4448 692 ? Ss+ 00:42 0:00 /bin/sh /run.sh 123 cmd cmd2
|
||||
root 19 0.0 0.2 71304 4440 ? Ss 00:42 0:00 /usr/sbin/apache2 -k start
|
||||
www-data 20 0.2 0.2 360468 6004 ? Sl 00:42 0:00 /usr/sbin/apache2 -k start
|
||||
www-data 21 0.2 0.2 360468 6000 ? Sl 00:42 0:00 /usr/sbin/apache2 -k start
|
||||
root 81 0.0 0.1 15572 2140 ? R+ 00:44 0:00 ps aux
|
||||
$ docker top test
|
||||
PID USER COMMAND
|
||||
10035 root {run.sh} /bin/sh /run.sh 123 cmd cmd2
|
||||
10054 root /usr/sbin/apache2 -k start
|
||||
10055 33 /usr/sbin/apache2 -k start
|
||||
10056 33 /usr/sbin/apache2 -k start
|
||||
$ /usr/bin/time docker stop test
|
||||
test
|
||||
real 0m 0.27s
|
||||
user 0m 0.03s
|
||||
sys 0m 0.03s
|
||||
```
|
||||
|
||||
> **Note:** you can over ride the `ENTRYPOINT` setting using `--entrypoint`,
|
||||
> but this can only set the binary to *exec* (no `sh -c` will be used).
|
||||
|
||||
> **Note**:
|
||||
> The *exec* form is parsed as a JSON array, which means that
|
||||
|
|
@ -505,13 +602,71 @@ optional but default, you could use a `CMD` instruction:
|
|||
> **Note**:
|
||||
> Unlike the *shell* form, the *exec* form does not invoke a command shell.
|
||||
> This means that normal shell processing does not happen. For example,
|
||||
> `CMD [ "echo", "$HOME" ]` will not do variable substitution on `$HOME`.
|
||||
> `ENTRYPOINT [ "echo", "$HOME" ]` will not do variable substitution on `$HOME`.
|
||||
> If you want shell processing then either use the *shell* form or execute
|
||||
> a shell directly, for example: `CMD [ "sh", "-c", "echo", "$HOME" ]`.
|
||||
> a shell directly, for example: `ENTRYPOINT [ "sh", "-c", "echo", "$HOME" ]`.
|
||||
> Variables that are defined in the `Dockerfile`using `ENV`, will be substituted by
|
||||
> the `Dockerfile` parser.
|
||||
|
||||
> **Note**:
|
||||
> It is preferable to use the JSON array format for specifying
|
||||
> `ENTRYPOINT` instructions.
|
||||
### Shell form ENTRYPOINT example
|
||||
|
||||
You can specify a plain string for the `ENTRYPOINT` and it will execute in `/bin/sh -c`.
|
||||
This form will use shell processing to substitute shell environment variables,
|
||||
and will ignore any `CMD` or `docker run` command line arguments.
|
||||
To ensure that `docker stop` will signal any long running `ENTRYPOINT` executable
|
||||
correctly, you need to remember to start it with `exec`:
|
||||
|
||||
FROM ubuntu
|
||||
ENTRYPOINT exec top -b
|
||||
|
||||
When you run this image, you'll see the single `PID 1` process:
|
||||
|
||||
$ docker run -it --rm --name test top
|
||||
Mem: 1704520K used, 352148K free, 0K shrd, 0K buff, 140368121167873K cached
|
||||
CPU: 5% usr 0% sys 0% nic 94% idle 0% io 0% irq 0% sirq
|
||||
Load average: 0.08 0.03 0.05 2/98 6
|
||||
PID PPID USER STAT VSZ %VSZ %CPU COMMAND
|
||||
1 0 root R 3164 0% 0% top -b
|
||||
|
||||
Which will exit cleanly on `docker stop`:
|
||||
|
||||
$ /usr/bin/time docker stop test
|
||||
test
|
||||
real 0m 0.20s
|
||||
user 0m 0.02s
|
||||
sys 0m 0.04s
|
||||
|
||||
If you forget to add `exec` to the beginning of your `ENTRYPOINT`:
|
||||
|
||||
FROM ubuntu
|
||||
ENTRYPOINT top -b
|
||||
CMD --ignored-param1
|
||||
|
||||
You can then run it (giving it a name for the next step):
|
||||
|
||||
$ docker run -it --name test top --ignored-param2
|
||||
Mem: 1704184K used, 352484K free, 0K shrd, 0K buff, 140621524238337K cached
|
||||
CPU: 9% usr 2% sys 0% nic 88% idle 0% io 0% irq 0% sirq
|
||||
Load average: 0.01 0.02 0.05 2/101 7
|
||||
PID PPID USER STAT VSZ %VSZ %CPU COMMAND
|
||||
1 0 root S 3168 0% 0% /bin/sh -c top -b cmd cmd2
|
||||
7 1 root R 3164 0% 0% top -b
|
||||
|
||||
You can see from the output of `top` that the specified `ENTRYPOINT` is not `PID 1`.
|
||||
|
||||
If you then run `docker stop test`, the container will not exit cleanly - the
|
||||
`stop` command will be forced to send a `SIGKILL` after the timeout:
|
||||
|
||||
$ docker exec -it test ps aux
|
||||
PID USER COMMAND
|
||||
1 root /bin/sh -c top -b cmd cmd2
|
||||
7 root top -b
|
||||
8 root ps aux
|
||||
$ /usr/bin/time docker stop test
|
||||
test
|
||||
real 0m 10.19s
|
||||
user 0m 0.04s
|
||||
sys 0m 0.03s
|
||||
|
||||
## VOLUME
|
||||
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче