Docker - what does `docker run --restart always` actually do?

Question

Although it seems like the --restart flag is simple and straightforward, I came up with a number of questions when experimenting with it:

1. With respect to ENTRYPOINT definitions - what are the actual defined semantics during restart?
2. If I exec into the container (I am on a DDC) and kill -9 the process, it restarts, but if I do docker kill it does not. Why?
3. How does restart interact with Shared Data Containers / Named Volumes?

Answer 1

To configure the restart policy for a container, use the --restart flag when using the docker run command. The value of the --restart flag can be any of the following:

no Do not automatically restart the container. (the default)

on-failure Restart the container if it exits due to an error, which manifests as a non-zero exit code.

always Always restart the container if it stops. If it is manually stopped, it is restarted only when Docker daemon restarts or the container itself is manually restarted.

unless-stopped Similar to always, except that when the container is stopped (manually or otherwise), it is not restarted even after Docker daemon restarts.

The following example starts a Redis container and configures it to always restart unless it is explicitly stopped or Docker is restarted.

$ docker run -d --restart unless-stopped redis

This command changes the restart policy for an already running container named redis.

$ docker update --restart unless-stopped redis

And this command will ensure all currently running containers will be restarted unless stopped.

$ docker update --restart unless-stopped $(docker ps -q)

Restart policy details

Keep the following in mind when using restart policies:

• A restart policy only takes effect after a container starts successfully. In this case, starting successfully means that the container is up for at least 10 seconds and Docker has started monitoring it. This prevents a container which does not start at all from going into a restart loop.
• If you manually stop a container, its restart policy is ignored until the Docker daemon restarts or the container is manually restarted. This is another attempt to prevent a restart loop.
• Restart policies only apply to containers. Restart policies for swarm services are configured differently.

Documentation

Answer 2

Restart policies

Using the --restart flag on Docker run you can specify a restart policy for how a container should or should not be restarted on exit.

When a restart policy is active on a container, it will be shown as either Up or Restarting in docker ps. It can also be useful to use docker events to see the restart policy in effect.

docker run --always 

Always restart the container regardless of the exit status. When you specify always, the Docker daemon will try to restart the container indefinitely. The container will also always start on daemon startup, regardless of the current state of the container.

I recommend you this documentation about restart-policies

Documentation - Restart policies

Update Docker v19.03

Restart policies (--restart)

Use Docker’s --restart to specify a container’s restart policy. A restart policy > controls whether the Docker daemon restarts a container after exit. Docker supports the following restart policies:

always Always restart the container regardless of the exit status. When you specify always, the Docker daemon will try to restart the container indefinitely. The container will also always start on daemon startup, regardless of the current state of the container.

$ docker run --restart=always redis

Documentation - Restart policies

Answer 3

I had some time to debug this more today -> because I was using an 'official' docker image I had little to no visibility into what was occurring. To resolve this, I extended the official image and invoked my own entrypoint. The Dockerfile:

FROM officialImage:version

ENV envOne=value1  \
    envTwo=value2
COPY wrapper-entrypoint.sh /
ENTRYPOINT ["/wrapper-entrypoint.sh"]

Then I did a 'set -x' in the wrapper-entrypoint.sh script and invoked the original:

#!/bin/bash
set -x

echo "Be pedantic: all args passed: $@"
bash -x ./original-entrypoint.sh "$@"

From this I found:

• Restart does call the original ENTRYPOINT with the original arguments. The official image I used detected it had already initialized and thus acted differently. This is why I was confused over the semantics. Using -x allowed me to see what was really happening.
• I still don't know why docker kill stops the restart, but that is what I see - at least on Docker Data Center.
• I don't believe Shared Data Volumes affect this in any way, SAVE for the actions a given ENTRYPOINT script might take based upon it's condition at the time of the restart.