Como usar o comando docker compose ps para listar contêineres

Introdução

Neste laboratório, você aprenderá como usar efetivamente o comando docker compose ps para listar os contêineres gerenciados pelo Docker Compose. Você começará instalando o Docker Compose e configurando um projeto simples com um arquivo docker-compose.yml.

Após a configuração, você explorará como listar apenas os contêineres em execução, incluir contêineres parados na saída, filtrar contêineres com base em seu status e formatar a saída como JSON para facilitar a análise e a integração. Essa experiência prática o equipará com as habilidades necessárias para monitorar e gerenciar seus serviços Docker Compose de forma eficiente.

Listar contêineres em execução com docker compose ps

Nesta etapa, você aprenderá como listar contêineres em execução usando docker compose ps. Antes de podermos usar docker compose, precisamos instalá-lo.

Primeiro, vamos instalar o Docker Compose. Vamos baixar a versão estável mais recente.

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 baixa o binário do Docker Compose para a arquitetura do seu sistema e o salva em /usr/local/bin/docker-compose.

Em seguida, precisamos aplicar permissões de execução ao binário.

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

Agora, vamos verificar a instalação verificando a versão.

docker-compose --version

Você deve ver a versão instalada do Docker Compose na saída.

Para demonstrar docker compose ps, precisamos de um arquivo docker-compose.yml e alguns serviços para executar. Vamos criar um arquivo docker-compose.yml simples no seu diretório ~/project.

nano ~/project/docker-compose.yml

Adicione o seguinte conteúdo ao arquivo:

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

Este arquivo docker-compose.yml define dois serviços: web usando a imagem nginx e app usando a imagem alpine. O serviço web mapeia a porta 80 no host para a porta 80 no contêiner. O serviço app executa o comando sleep infinity para manter o contêiner em execução.

Salve o arquivo e saia do editor (Ctrl+X, Y, Enter).

Agora, vamos baixar as imagens necessárias.

docker pull nginx:latest
docker pull alpine:latest

Esses comandos baixam as imagens nginx:latest e alpine:latest do Docker Hub.

Em seguida, inicie os serviços definidos no arquivo docker-compose.yml. Certifique-se de estar no diretório ~/project.

cd ~/project
docker-compose up -d

O comando docker-compose up -d constrói, cria, inicia e anexa aos contêineres para um serviço. A flag -d executa os contêineres em modo detached, o que significa que eles são executados em segundo plano.

Agora que os contêineres estão em execução, podemos usar docker compose ps para listá-los.

docker-compose ps

Este comando lista os contêineres em execução definidos no seu arquivo docker-compose.yml. Você deve ver uma saída semelhante a esta, mostrando os nomes dos contêineres, comandos, status e portas.

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

A saída mostra que os contêineres project-app-1 e project-web-1 estão em execução. O NAME é tipicamente o nome do projeto (o nome do diretório) seguido pelo nome do serviço e um número.

Listar todos os contêineres, incluindo os parados

Na etapa anterior, usamos docker compose ps para listar apenas os contêineres em execução. Às vezes, você pode precisar ver todos os contêineres, incluindo aqueles que foram parados ou finalizados.

Para listar todos os contêineres, incluindo os parados, você pode usar a flag -a com o comando docker compose ps.

Primeiro, vamos parar um dos contêineres em execução para ver o efeito da flag -a. Vamos parar o serviço app. Certifique-se de estar no diretório ~/project.

cd ~/project
docker-compose stop app

Este comando para o contêiner para o serviço app. O contêiner não estará mais em execução, mas ainda existirá.

Agora, vamos listar os contêineres novamente usando docker compose ps.

docker-compose ps

Você deve ver que apenas o contêiner web está listado como em execução. O contêiner app não é exibido porque está parado.

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

Agora, vamos usar a flag -a para listar todos os contêineres, incluindo o parado.

docker-compose ps -a

Este comando mostrará todos os contêineres definidos no seu arquivo docker-compose.yml, independentemente do seu status.

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

Você pode ver que os contêineres project-app-1 e project-web-1 estão listados. A coluna STATUS para project-app-1 mostra exited, indicando que ele está parado.

Usar docker compose ps -a é útil para ver o estado de todos os seus serviços, mesmo que eles não estejam atualmente ativos.

Filtrar contêineres por status

Nas etapas anteriores, aprendemos como listar contêineres em execução e todos os contêineres. Às vezes, você pode querer filtrar a lista de contêineres com base em seu status.

O comando docker compose ps permite que você filtre a saída usando a flag --filter. Você pode filtrar por vários critérios, incluindo o status do contêiner.

Os status comuns do contêiner são:

• created: O contêiner foi criado, mas não iniciado.
• restarting: O contêiner está em processo de reinicialização.
• running: O contêiner está atualmente em execução.
• removing: O contêiner está sendo removido.
• paused: O contêiner está pausado.
• exited: O contêiner foi parado.
• dead: O contêiner está morto.

Vamos filtrar os contêineres para mostrar apenas os que estão em execução. Já sabemos que docker compose ps por padrão mostra os contêineres em execução, mas podemos conseguir o mesmo usando o filtro. Certifique-se de estar no diretório ~/project.

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

Este comando listará apenas os contêineres com o status running. Você deve ver apenas o contêiner 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

Agora, vamos filtrar os contêineres para mostrar apenas os que foram finalizados (exited). Lembre-se que paramos o contêiner app na etapa anterior, então seu status deve ser exited.

docker-compose ps --filter status=exited

Este comando listará apenas os contêineres com o status exited. Você deve ver apenas o contêiner app listado.

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

Você também pode filtrar por vários status fornecendo a flag --filter várias vezes. Por exemplo, para listar contêineres que estão em execução ou finalizados:

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

Este comando listará os contêineres web e 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 status é uma maneira poderosa de encontrar rapidamente contêineres em um estado específico, o que é muito útil para depurar e gerenciar seus serviços.

Formatar a saída como JSON

Nas etapas anteriores, listamos e filtramos contêineres usando docker compose ps. Por padrão, a saída é formatada em uma tabela legível por humanos. No entanto, para scripting ou integração com outras ferramentas, você pode precisar da saída em um formato estruturado como JSON.

O comando docker compose ps permite que você formate a saída usando a flag --format. Você pode especificar vários formatos, incluindo json.

Vamos listar todos os contêineres (em execução e parados) e formatar a saída como JSON. Certifique-se de estar no diretório ~/project.

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

Este comando irá gerar as informações sobre todos os contêineres em formato JSON. A saída será um array JSON, onde cada elemento representa um contêiner e seus detalhes.

[
  {
    "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"
      }
    ]
  }
]

A saída JSON fornece uma representação estruturada das informações do contêiner, tornando-a fácil de analisar e processar programaticamente. Cada contêiner é representado como um objeto JSON com campos como ID, Name, Image, State, Status, etc.

Usar a flag --format json é particularmente útil quando você precisa extrair informações específicas sobre seus contêineres para fins de automação ou relatórios.

Finalmente, vamos limpar os contêineres que criamos durante este laboratório.

docker-compose down

Este comando para e remove os contêineres, redes e volumes criados por docker-compose up.

Resumo

Neste laboratório, você aprendeu como usar o comando docker compose ps para listar contêineres gerenciados pelo Docker Compose. Você começou instalando o Docker Compose e verificando sua instalação. Em seguida, você criou um arquivo docker-compose.yml simples, definindo dois serviços e puxando as imagens necessárias. Você usou docker-compose up -d para iniciar os serviços em modo detached (desanexado).

Você então explorou o comando docker compose ps para listar os contêineres em execução. Você aprendeu como incluir contêineres parados na saída usando a flag -a, filtrar contêineres por status usando a opção --filter status=<status>, e formatar a saída como JSON usando a opção --format json. Finalmente, você limpou os recursos criados parando e removendo os serviços usando docker-compose down.