The Docker CLI offers multiple ways to stop container processes. In this short article, we will cover three of those commands, docker kill
, docker stop
and docker pause
. These commands stop container processes without removing the container. In this article we would use other commands docker to investigate the container state when those commands are used. Docker commands used to investigate the container state:
-
docker top
: used to display the running processes of a container. -
docker events
: get a list of events from the server. -
docker stats
: shows a live stream of container(s) resource usage statistics. -
docker inspect
: provides detailed information about the container.
The docker image used for this test is the nginx image. Steps to start the test container
-
Pull the nginx image
docker pull nginx
-
Run the container
docker run --name nginx-test -d nginx
docker kill
and docker stop
commands
After running the kill or stop command you would notice that the contained killed does not show while running the docker ps
command, however the container is still visible when running the same command with the -a argument (docker ps -a
).
docker top
command would show an error informing that no container is running.
If docker stats
command is run before and after the kill or stop command, you might notice a difference in the outputs. Now the last docker stats
command output should show that CPU and Memory are not used. Resources are not used when this commands axecuted.
docker kill
vs docker stop
Even though these two commands seem to have the same result, there are some differences. The docker kill
command stops the main process of a container abruptly while docker stop
attempts to stop the container gracefully allowing the main process to cleanup before shutting down. And inspection of the container using docker inspect
would shows that the Exit Code under container Status is 0 when the container was stopped using docker stop
, while the same command run after docker kill
shows an Exit Code of 137 (non 0 exit) in the container status.
docker kill
or docker stop
followed by docker events
command
When running docker events
command after a kill command, the event are kill (signal 9) and die. While running docker events
command after a stop command, the events are kill(signal 15) followed by die(exit code 137 ) and stop.
docker pause
command
Unlike the docker kill
and docker stop
commands, the docker pause
does not stop the container processes. Instead it suspends the container processes. In this state the container is not consuming CPU but would still keep its portion of the memory.
After running the pause command you would notice that the container shows while running docker ps
command. The docker top
command would show the processes on the container.
If docker stats
command is run before and after the kill or stop commands, you might notice a difference in the outputs. Now the docker stats
output should show that CPU is not in use, but Memory is still consumed.
Summary
The table below summarises the result of docker commands after running each of commands kill, stop and pause.
Docker command | docker stop | docker kill | docker pause |
---|---|---|---|
docker ps |
- No container. - docker ps -a : Exit code = 0
|
- No container. - docker ps -a : Exit code = 137
|
It shows with status Paused |
docker top | failed | failed | Displays processes |
docker stats |
- CPU is FREE. - Memory is FREE. - No running processes |
- CPU is FREE . - Memory is FREE . - No running processes |
- CPU is FREE . - Memory is used . - Processes still present. |
docker events |
- kill (signal 15) - die - stop |
- kill (signal 9) - Die (exit Code 137) |
- pause |
docker inspect |
- Status: exited - ExitCode: 137 |
- Status: exited - ExitCode: 0 |
- Status: paused - ExitCode: 0 |
Undo command |
docker start , docker restart
|
docker start
|
docker unpause to resume
|
Conclusion
The docker kill
,docker stop
and docker pause
are commands used to stop container processes. However, there are few differences. docker pause
still consumes memory when used, since this memory is used to continue the process in progress. docker kill
and docker stop
completely stop any process running and does not consume host resources. The docker kill
command is similar to the docker stop
command, however it does allow graceful stopping of processes, leading to non 0 (137) exit code.