Cómo usar el comando docker compose ps para listar contenedores

Introducción

En este laboratorio, aprenderás a utilizar eficazmente el comando docker compose ps para listar los contenedores gestionados por Docker Compose. Comenzarás instalando Docker Compose y configurando un proyecto simple con un archivo docker-compose.yml.

Después de la configuración, explorarás cómo listar solo los contenedores en ejecución, incluir contenedores detenidos en la salida, filtrar contenedores según su estado y formatear la salida como JSON para facilitar su análisis e integración. Esta experiencia práctica te proporcionará las habilidades necesarias para monitorear y gestionar tus servicios de Docker Compose de manera eficiente.

Listar contenedores en ejecución con docker compose ps

En este paso, aprenderás a listar contenedores en ejecución usando docker compose ps. Antes de poder usar docker compose, necesitamos instalarlo.

Primero, instalemos Docker Compose. Descargaremos la última versión estable.

sudo curl -L "https://github.com/docker/compose/releases/download/v2.20.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose

Este comando descarga el binario de Docker Compose para la arquitectura de tu sistema y lo guarda en /usr/local/bin/docker-compose.

A continuación, debemos aplicar permisos de ejecución al binario.

sudo chmod +x /usr/local/bin/docker-compose

Ahora, verifiquemos la instalación comprobando la versión.

docker-compose --version

Deberías ver la versión instalada de Docker Compose en la salida.

Para demostrar docker compose ps, necesitamos un archivo docker-compose.yml y algunos servicios en ejecución. Creemos un archivo docker-compose.yml simple en tu directorio ~/project.

nano ~/project/docker-compose.yml

Añade el siguiente contenido al archivo:

version: "3.8"
services:
  web:
    image: nginx:latest
    ports:
      - "80:80"
  app:
    image: alpine:latest
    command: sleep infinity

Este archivo docker-compose.yml define dos servicios: web usando la imagen nginx y app usando la imagen alpine. El servicio web mapea el puerto 80 del host al puerto 80 del contenedor. El servicio app ejecuta el comando sleep infinity para mantener el contenedor en ejecución.

Guarda el archivo y sal del editor (Ctrl+X, Y, Enter).

Ahora, descarguemos las imágenes necesarias.

docker pull nginx:latest
docker pull alpine:latest

Estos comandos descargan las imágenes nginx:latest y alpine:latest desde Docker Hub.

A continuación, inicia los servicios definidos en el archivo docker-compose.yml. Asegúrate de estar en el directorio ~/project.

cd ~/project
docker-compose up -d

El comando docker-compose up -d construye, crea, inicia y conecta los contenedores para un servicio. La bandera -d ejecuta los contenedores en modo detached, lo que significa que se ejecutan en segundo plano.

Ahora que los contenedores están en ejecución, podemos usar docker compose ps para listarlos.

docker-compose ps

Este comando lista los contenedores en ejecución definidos en tu archivo docker-compose.yml. Deberías ver una salida similar a esta, mostrando los nombres de los contenedores, comandos, estado y puertos.

NAME                COMMAND             SERVICE             STATUS              PORTS
project-app-1       "sleep infinity"    app                 running
project-web-1       "/docker-entrypoint.sh nginx -g 'daemon off;'"   web                 running             0.0.0.0:80->80/tcp

La salida muestra que los contenedores project-app-1 y project-web-1 están en ejecución. El NAME típicamente es el nombre del proyecto (el nombre del directorio) seguido del nombre del servicio y un número.

Listar todos los contenedores incluyendo los detenidos

En el paso anterior, usamos docker compose ps para listar solo los contenedores en ejecución. A veces, es necesario ver todos los contenedores, incluyendo aquellos que se han detenido o finalizado.

Para listar todos los contenedores, incluyendo los detenidos, puedes usar la bandera -a con el comando docker compose ps.

Primero, detengamos uno de los contenedores en ejecución para observar el efecto de la bandera -a. Detendremos el servicio app. Asegúrate de estar en el directorio ~/project.

cd ~/project
docker-compose stop app

Este comando detiene el contenedor del servicio app. El contenedor dejará de ejecutarse, pero seguirá existiendo.

Ahora, listemos los contenedores nuevamente usando docker compose ps.

docker-compose ps

Deberías ver que solo el contenedor web aparece como en ejecución. El contenedor app no se muestra porque está detenido.

NAME                COMMAND             SERVICE             STATUS              PORTS
project-web-1       "/docker-entrypoint.sh nginx -g 'daemon off;'"   web                 running             0.0.0.0:80->80/tcp

Ahora, usemos la bandera -a para listar todos los contenedores, incluyendo el detenido.

docker-compose ps -a

Este comando mostrará todos los contenedores definidos en tu archivo docker-compose.yml, independientemente de su estado.

NAME                COMMAND             SERVICE             STATUS              PORTS
project-app-1       "sleep infinity"    app                 exited (0)
project-web-1       "/docker-entrypoint.sh nginx -g 'daemon off;'"   web                 running             0.0.0.0:80->80/tcp

Puedes observar que ambos contenedores, project-app-1 y project-web-1, aparecen listados. La columna STATUS para project-app-1 muestra exited, indicando que está detenido.

Usar docker compose ps -a es útil para ver el estado de todos tus servicios, incluso si no están activos actualmente.

Filtrar contenedores por estado

En los pasos anteriores, aprendimos cómo listar contenedores en ejecución y todos los contenedores. A veces, es posible que desees filtrar la lista de contenedores según su estado.

El comando docker compose ps permite filtrar la salida usando la bandera --filter. Puedes filtrar por varios criterios, incluyendo el estado del contenedor.

Los estados comunes de los contenedores son:

• created: El contenedor ha sido creado pero no iniciado.
• restarting: El contenedor está en proceso de reinicio.
• running: El contenedor está actualmente en ejecución.
• removing: El contenedor está siendo eliminado.
• paused: El contenedor está pausado.
• exited: El contenedor se ha detenido.
• dead: El contenedor está muerto.

Filtremos los contenedores para mostrar solo los que están en ejecución. Ya sabemos que docker compose ps por defecto muestra los contenedores en ejecución, pero podemos lograr lo mismo usando el filtro. Asegúrate de estar en el directorio ~/project.

cd ~/project
docker-compose ps --filter status=running

Este comando listará solo los contenedores con estado running. Deberías ver solo el contenedor web listado.

NAME                COMMAND             SERVICE             STATUS              PORTS
project-web-1       "/docker-entrypoint.sh nginx -g 'daemon off;'"   web                 running             0.0.0.0:80->80/tcp

Ahora, filtremos los contenedores para mostrar solo los que están detenidos. Recuerda que detuvimos el contenedor app en el paso anterior, por lo que su estado debería ser exited.

docker-compose ps --filter status=exited

Este comando listará solo los contenedores con estado exited. Deberías ver solo el contenedor app listado.

NAME                COMMAND             SERVICE             STATUS              PORTS
project-app-1       "sleep infinity"    app                 exited (0)

También puedes filtrar por múltiples estados proporcionando la bandera --filter varias veces. Por ejemplo, para listar contenedores que estén en ejecución o detenidos:

docker-compose ps --filter status=running --filter status=exited

Este comando listará tanto el contenedor web como el app.

NAME                COMMAND             SERVICE             STATUS              PORTS
project-app-1       "sleep infinity"    app                 exited (0)
project-web-1       "/docker-entrypoint.sh nginx -g 'daemon off;'"   web                 running             0.0.0.0:80->80/tcp

Filtrar por estado es una forma poderosa de encontrar rápidamente contenedores en un estado específico, lo cual es muy útil para depurar y gestionar tus servicios.

Formatear la salida como JSON

En los pasos anteriores, listamos y filtramos contenedores usando docker compose ps. Por defecto, la salida se muestra en una tabla legible para humanos. Sin embargo, para scripting o integración con otras herramientas, podrías necesitar la salida en un formato estructurado como JSON.

El comando docker compose ps permite formatear la salida usando la bandera --format. Puedes especificar varios formatos, incluyendo json.

Listemos todos los contenedores (en ejecución y detenidos) y formateemos la salida como JSON. Asegúrate de estar en el directorio ~/project.

cd ~/project
docker-compose ps -a --format json

Este comando mostrará la información de todos los contenedores en formato JSON. La salida será un array JSON, donde cada elemento representa un contenedor y sus detalles.

[
  {
    "ID": "...",
    "Name": "project-app-1",
    "Image": "alpine:latest",
    "Command": "sleep infinity",
    "Project": "project",
    "Service": "app",
    "Created": "...",
    "State": "exited",
    "Status": "Exited (0) ...",
    "Health": "",
    "ExitCode": 0,
    "Publishers": []
  },
  {
    "ID": "...",
    "Name": "project-web-1",
    "Image": "nginx:latest",
    "Command": "/docker-entrypoint.sh nginx -g 'daemon off;'",
    "Project": "project",
    "Service": "web",
    "Created": "...",
    "State": "running",
    "Status": "Up ...",
    "Health": "",
    "ExitCode": null,
    "Publishers": [
      {
        "URL": "0.0.0.0",
        "TargetPort": 80,
        "PublishedPort": 80,
        "Protocol": "tcp"
      }
    ]
  }
]

La salida JSON proporciona una representación estructurada de la información de los contenedores, facilitando su análisis y procesamiento programático. Cada contenedor se representa como un objeto JSON con campos como ID, Name, Image, State, Status, etc.

Usar la bandera --format json es particularmente útil cuando necesitas extraer información específica sobre tus contenedores para propósitos de automatización o generación de reportes.

Finalmente, limpiemos los contenedores que creamos durante este laboratorio.

docker-compose down

Este comando detiene y elimina los contenedores, redes y volúmenes creados por docker-compose up.

Resumen

En este laboratorio, aprendiste a utilizar el comando docker compose ps para listar contenedores gestionados por Docker Compose. Comenzaste instalando Docker Compose y verificando su instalación. Luego, creaste un archivo simple docker-compose.yml definiendo dos servicios y descargaste las imágenes necesarias. Utilizaste docker-compose up -d para iniciar los servicios en modo desatendido.

Posteriormente, exploraste el comando docker compose ps para listar contenedores en ejecución. Aprendiste cómo incluir contenedores detenidos en la salida usando la bandera -a, filtrar contenedores por estado mediante la opción --filter status=<status>, y formatear la salida como JSON con la opción --format json. Finalmente, limpiaste los recursos creados deteniendo y eliminando los servicios con docker-compose down.