Como usar o comando docker stop para gerenciar o Docker Desktop

Introdução

Neste laboratório, você aprenderá como gerenciar efetivamente seus contêineres Docker usando o comando docker stop. Abordaremos o uso básico para parar um contêiner em execução, exploraremos diferentes opções para controlar o processo de parada, incluindo como forçar a parada de um contêiner e como definir um tempo limite (timeout) para a operação de parada. Ao final deste laboratório, você estará proficiente no uso do docker stop para terminar seus contêineres Docker de forma graciosa e forçada.

Entenda o uso básico do docker stop no Docker Desktop

Nesta etapa, aprenderemos o uso básico do comando docker stop. O comando docker stop é usado para parar um ou mais contêineres em execução. Por padrão, o comando envia um sinal SIGTERM para o contêiner e, após um período de carência (grace period), envia um sinal SIGKILL se o contêiner não tiver parado.

Primeiro, vamos executar um contêiner simples que permanecerá em execução. Usaremos a imagem ubuntu e executaremos um comando que mantém o contêiner ativo.

docker run -d ubuntu sleep infinity

A flag -d executa o contêiner em modo detached, o que significa que ele é executado em segundo plano. sleep infinity é um comando que fará com que o contêiner permaneça em execução indefinidamente.

Agora, vamos listar os contêineres em execução para obter o ID do contêiner.

docker ps

Você deve ver uma saída semelhante a esta, mostrando seu contêiner ubuntu em execução:

CONTAINER ID   IMAGE          COMMAND           CREATED         STATUS         PORTS     NAMES
<container_id>   ubuntu         "sleep infinity"   X seconds ago   Up X seconds             <container_name>

Substitua <container_id> pelo ID real do seu contêiner em execução, obtido na saída de docker ps. Agora, pare o contêiner usando o comando docker stop seguido pelo ID do contêiner.

docker stop <container_id>

Após executar este comando, o contêiner deve parar. Você pode verificar isso listando os contêineres em execução novamente.

docker ps

Desta vez, o comando docker ps não deve mostrar o contêiner que você acabou de parar.

Para ver todos os contêineres, incluindo aqueles que foram parados, você pode usar a flag -a com docker ps.

docker ps -a

Isso mostrará o contêiner parado com o status Exited.

Parar o Docker Desktop usando a opção detach

Nesta etapa, exploraremos a parada de um contêiner usando a opção detach. Embora o docker stop em si não tenha uma opção detach da mesma forma que o docker run tem, o conceito de detaching é inerente à forma como o docker stop funciona quando você o executa em seu terminal. O comando é executado e retorna o controle ao seu terminal assim que o sinal de parada é enviado, permitindo que você continue com outras tarefas.

Vamos começar executando outro contêiner que iremos parar. Usaremos a imagem nginx desta vez. Primeiro, puxe a imagem nginx se você não a tiver localmente.

docker pull nginx

Agora, execute o contêiner nginx em modo detached.

docker run -d nginx

Obtenha o ID do contêiner nginx em execução.

docker ps

Você verá uma saída semelhante a esta, mostrando tanto o contêiner ubuntu anterior (se você não o removeu) quanto o novo contêiner nginx:

CONTAINER ID   IMAGE          COMMAND                  CREATED         STATUS         PORTS     NAMES
<nginx_container_id>   nginx          "nginx -g 'daemon off"   X seconds ago   Up X seconds   80/tcp    <nginx_container_name>
<ubuntu_container_id>   ubuntu         "sleep infinity"         Y minutes ago   Exited Y minutes ago             <ubuntu_container_name>

Agora, pare o contêiner nginx usando seu ID.

docker stop <nginx_container_id>

Quando você executa docker stop, o comando envia o sinal de parada e retorna imediatamente o controle ao seu terminal. Este é o comportamento "detached" da perspectiva da sua sessão de terminal – você não precisa esperar que o contêiner pare totalmente antes de poder digitar outro comando.

Verifique se o contêiner nginx foi parado.

docker ps

O contêiner nginx não deve mais aparecer na lista de contêineres em execução.

Forçar a parada do Docker Desktop

Nesta etapa, aprenderemos como forçar a parada de um contêiner usando o comando docker stop. Embora o docker stop por padrão envie um sinal de parada gracioso (SIGTERM), às vezes um contêiner pode não responder a este sinal e precisa ser parado à força. Isso é alcançado pelo comportamento padrão do docker stop, que envia um SIGKILL após um tempo limite.

Vamos executar um contêiner que pode ser difícil de parar graciosamente. Usaremos um contêiner ubuntu simples novamente, mas desta vez simularemos um processo que ignora o sinal SIGTERM.

docker run -d ubuntu sh -c 'trap "" SIGTERM; sleep infinity'

Neste comando:

• trap "" SIGTERM diz ao shell para ignorar o sinal SIGTERM.
• sleep infinity mantém o contêiner em execução.

Obtenha o ID do contêiner deste novo contêiner ubuntu.

docker ps

Você deve ver o novo contêiner ubuntu em execução.

CONTAINER ID   IMAGE          COMMAND                        CREATED         STATUS         PORTS     NAMES
<force_stop_container_id>   ubuntu         "sh -c 'trap \"\" SIGT…"   X seconds ago   Up X seconds             <container_name>
<nginx_container_id>   nginx          "nginx -g 'daemon off"   Y minutes ago   Exited Y minutes ago   80/tcp    <nginx_container_name>
<ubuntu_container_id>   ubuntu         "sleep infinity"         Z minutes ago   Exited Z minutes ago             <ubuntu_container_name>

Agora, tente parar este contêiner usando o comando docker stop padrão com seu ID.

docker stop <force_stop_container_id>

Como o contêiner está ignorando o sinal SIGTERM, o docker stop esperará pelo período de carência padrão (geralmente 10 segundos) e, em seguida, enviará um sinal SIGKILL, que não pode ser ignorado. Isso irá parar o contêiner à força. Você pode notar um ligeiro atraso antes que o comando termine.

Verifique se o contêiner foi parado.

docker ps

O contêiner não deve mais ser listado como em execução.

Você também pode especificar explicitamente um tempo limite de 0 segundos com a flag -t para enviar imediatamente um sinal SIGKILL, efetivamente forçando a parada sem esperar pelo período de carência. Exploraremos a flag -t na próxima etapa.

Parar o Docker Desktop com um tempo limite (timeout)

Nesta etapa, aprenderemos como parar um contêiner com um tempo limite específico usando a flag -t ou --time com o comando docker stop. Isso permite que você especifique por quanto tempo o Docker deve esperar para que o contêiner saia graciosamente após enviar o sinal SIGTERM antes de forçá-lo a parar com SIGKILL.

Vamos executar um contêiner que iremos parar com um tempo limite. Usaremos a imagem ubuntu e um script que espera por um sinal antes de sair.

docker run -d ubuntu sh -c 'trap "exit 0" SIGTERM; sleep infinity'

Este comando executa um contêiner ubuntu em modo detached. A parte trap "exit 0" SIGTERM configura uma armadilha que fará com que o script saia graciosamente quando receber um sinal SIGTERM. sleep infinity mantém o contêiner em execução até que ele receba o sinal.

Obtenha o ID do contêiner deste novo contêiner ubuntu.

docker ps

Você deve ver o novo contêiner ubuntu em execução.

CONTAINER ID   IMAGE          COMMAND                        CREATED         STATUS         PORTS     NAMES
<timeout_container_id>   ubuntu         "sh -c 'trap \"exit 0\"…"   X seconds ago   Up X seconds             <container_name>
<force_stop_container_id>   ubuntu         "sh -c 'trap \"\" SIGT…"   Y minutes ago   Exited Y minutes ago             <container_name>
<nginx_container_id>   nginx          "nginx -g 'daemon off"   Z minutes ago   Exited Z minutes ago   80/tcp    <nginx_container_name>
<ubuntu_container_id>   ubuntu         "sleep infinity"         A minutes ago   Exited A minutes ago             <ubuntu_container_name>

Agora, pare este contêiner com um tempo limite de 5 segundos usando a flag -t.

docker stop -t 5 <timeout_container_id>

O Docker enviará o sinal SIGTERM e esperará por 5 segundos. Como nosso contêiner está configurado para sair graciosamente no SIGTERM, ele deve parar dentro deste período de tempo limite. Se não parar em 5 segundos, o Docker enviará um SIGKILL.

Verifique se o contêiner foi parado.

docker ps

O contêiner não deve mais ser listado como em execução.

Usar a flag -t é útil quando você deseja dar ao seu contêiner uma quantidade específica de tempo para realizar operações de limpeza antes de ser forçado a parar.

Resumo

Neste laboratório, aprendemos o uso fundamental do comando docker stop para gerenciar contêineres em execução. Começamos entendendo que docker stop envia um sinal SIGTERM seguido por um SIGKILL após um período de carência. Praticamos a parada de um contêiner ubuntu simples em execução no modo detached, identificando seu ID de contêiner usando docker ps e, em seguida, executando docker stop <container_id>. Verificamos o status de parada do contêiner listando os contêineres em execução novamente e também aprendemos como visualizar todos os contêineres, incluindo os parados, usando docker ps -a.