Cómo usar el comando docker container restart para gestionar contenedores

Introducción

En este laboratorio, aprenderás a gestionar eficazmente contenedores Docker utilizando el comando docker restart. Comenzarás comprendiendo el proceso básico de reiniciar un contenedor en ejecución, una operación fundamental para aplicar cambios o resolver problemas.

Sobre esta base, explorarás opciones de reinicio más avanzadas. Esto incluye especificar un tiempo de espera personalizado (timeout) para el proceso de reinicio, lo que te permitirá controlar cuánto tiempo espera Docker para que un contenedor se detenga correctamente antes de forzar su terminación. Finalmente, aprenderás a reiniciar un contenedor utilizando una señal específica (signal), proporcionando un control granular sobre el comportamiento de apagado del contenedor durante un reinicio.

Skills Graph

Reiniciar un contenedor en ejecución

En este paso, aprenderás cómo reiniciar un contenedor Docker en ejecución. Reiniciar un contenedor es una operación común cuando necesitas aplicar cambios de configuración, solucionar problemas o simplemente refrescar el estado del contenedor.

Primero, descarguemos una imagen simple de Nginx para usar en nuestros ejemplos. Utilizaremos la imagen nginx:latest.

docker pull nginx:latest

Deberías ver una salida que indica que la imagen está siendo descargada y extraída.

A continuación, ejecutaremos un contenedor basado en esta imagen. Lo ejecutaremos en modo desacoplado (-d) para que se ejecute en segundo plano y le asignaremos un nombre (--name my-nginx).

docker run -d --name my-nginx nginx:latest

Este comando iniciará el contenedor Nginx y mostrará su ID de contenedor.

Para verificar que el contenedor está en ejecución, puedes usar el comando docker ps.

docker ps

Deberías ver el contenedor my-nginx listado con un estado de Up.

Ahora, reiniciemos el contenedor en ejecución usando el comando docker restart seguido del nombre del contenedor.

docker restart my-nginx

Este comando detendrá el contenedor y luego lo volverá a iniciar.

Para confirmar que el contenedor ha sido reiniciado y está nuevamente en ejecución, usa docker ps una vez más.

docker ps

Deberías ver el contenedor my-nginx listado nuevamente, y la columna STATUS debería mostrar Up con un tiempo que indica que fue iniciado recientemente.

Reiniciar un contenedor con un tiempo de espera específico

En este paso, aprenderás cómo reiniciar un contenedor Docker con un tiempo de espera (timeout) específico. Cuando reinicias un contenedor, Docker envía una señal de parada (por defecto, SIGTERM) al proceso principal del contenedor. Si el proceso no termina dentro de un período determinado, Docker envía una señal de terminación (SIGKILL) para forzar su detención. El tiempo de espera predeterminado es de 10 segundos. Puedes ajustar este tiempo usando la bandera -t o --time con el comando docker restart.

Utilicemos el contenedor my-nginx que creamos en el paso anterior. Primero, verifica que esté en ejecución.

docker ps

Si el contenedor no está en ejecución, inícialo nuevamente:

docker start my-nginx

Ahora, reiniciaremos el contenedor con un tiempo de espera de 5 segundos. Esto significa que Docker esperará 5 segundos después de enviar la señal de parada antes de enviar la señal de terminación.

docker restart -t 5 my-nginx

Deberías ver el nombre del contenedor impreso, indicando que el comando de reinicio se ejecutó.

Para observar el efecto del tiempo de espera, normalmente necesitarías un contenedor que tarde más de los 10 segundos predeterminados en apagarse correctamente. Sin embargo, para este ejercicio, nos enfocamos en la sintaxis del comando.

Probemos reiniciar con un tiempo de espera más largo, digamos 20 segundos.

docker restart --time 20 my-nginx

Nuevamente, verás el nombre del contenedor impreso.

La opción -t o --time es útil cuando tienes aplicaciones en contenedores que requieren más tiempo para realizar operaciones de limpieza antes de apagarse.

Para confirmar que el contenedor sigue en ejecución después del reinicio, usa docker ps.

docker ps

Deberías ver my-nginx listado con un estado de Up.

Reiniciar un contenedor con una señal específica

En este paso, aprenderás cómo reiniciar un contenedor Docker enviando una señal específica al proceso principal del contenedor. Mientras que docker restart envía una señal de parada predeterminada (SIGTERM) seguida de una señal de terminación (SIGKILL) después de un tiempo de espera, es posible que necesites enviar una señal diferente dependiendo de la aplicación que se ejecute dentro del contenedor. Esto se puede lograr deteniendo primero el contenedor con una señal específica usando docker stop y luego iniciándolo nuevamente con docker start.

Utilicemos nuevamente el contenedor my-nginx. Asegúrate de que esté en ejecución.

docker ps

Si no está en ejecución, inícialo:

docker start my-nginx

Ahora, detendremos el contenedor enviando la señal SIGKILL. Esta señal termina el proceso inmediatamente sin permitir que realice ninguna operación de limpieza.

docker stop -s SIGKILL my-nginx

Deberías ver el nombre del contenedor impreso, y si ejecutas docker ps, el contenedor ya no debería aparecer en la lista.

docker ps

El contenedor ahora está detenido. Para reiniciarlo, simplemente lo iniciamos nuevamente.

docker start my-nginx

El contenedor debería estar ahora en ejecución nuevamente. Verifica con docker ps.

docker ps

Deberías ver my-nginx listado con un estado de Up.

Mientras que SIGKILL es una detención forzosa, también puedes enviar otras señales como SIGHUP o SIGINT, si tu aplicación está configurada para manejarlas para cierres o recargas elegantes. Sin embargo, la configuración predeterminada del contenedor nginx maneja SIGTERM de manera adecuada.

Detengamos el contenedor nuevamente, esta vez usando la señal predeterminada SIGTERM (que es la predeterminada para docker stop si no se especifica ninguna señal).

docker stop my-nginx

Verifica que esté detenido:

docker ps

Ahora, inícialo una última vez.

docker start my-nginx

Verifica que esté en ejecución:

docker ps

Al combinar docker stop -s <signal> y docker start, tienes un control más granular sobre cómo se detiene un contenedor antes de ser reiniciado.

Resumen

En este laboratorio, aprendiste el proceso fundamental para reiniciar un contenedor Docker en ejecución utilizando el comando docker restart. Practicaste cómo descargar una imagen Docker, ejecutar un contenedor en modo desatendido (detached), verificar su estado y luego reiniciarlo exitosamente.

Además, exploraste cómo controlar el proceso de reinicio especificando un período de tiempo de espera mediante el uso de las banderas -t o --time, lo que te permite ajustar el tiempo que Docker espera para que un contenedor se detenga correctamente antes de terminarlo forzosamente.