Tornando-se um usuário avançado da CLI do Docker com “–format” e modelos de saída

Usar a CLI do Docker para listar e inspecionar recursos em seu sistema geralmente produz uma saída detalhada que pode ocultar detalhes importantes. O Docker suporta a sintaxe do modelo Go junto com o --format sinalizador para lhe dar controle sobre o que é exibido.

Aprender a usar modelos pode torná-lo um usuário avançado da CLI do Docker. Eles permitem que você selecione e transforme com eficiência as saídas de comando para criar as visualizações de que você precisa. Isso resulta em uma experiência CLI mais produtiva e menos tempo gasto na varredura de longas linhas de console.

Quais comandos suportam “–format”?

a --format a bandeira suporta os mais usados docker comandos. Você pode usá-lo com docker inspect e comandos que produzem listas de itens, como docker ps, docker imagesS docker volumes.

Ao incluir o --format check, o Docker enviará a saída do comando por meio da string do modelo Go que você fornecer. Você pode usar as funções de modelo fornecidas pelo Go para consumir espaços reservados definidos pelo Docker. Estes dão acesso aos dados obtidos pela CLI.

Um exemplo básico

Corre docker inspect em um contêiner retorna um objeto JSON longo que geralmente transborda sua janela de terminal. Vestindo --format, você pode extrair as partes específicas dos dados que lhe interessam. Aqui está um exemplo mostrando o status do contêiner, PID e hora de início:

~$ docker inspect 94a8d1315315 --format '{{.State.Status}} (PID: {{.State.Pid}}) {{.State.StartedAt}}'
running (PID: 1488278) 2022-03-22T20:45:58.614115689Z

É muito mais fácil detectar valores de destino usando um modelo do que rastrear manualmente o JSON bruto.

Acesso aos valores de saída

As partes dinâmicas do seu modelo estão entre parênteses duplos. Você pode referenciar os valores dentro da saída do comando Docker usando o {{.Field}} sintaxe. Field deve ser o nome de uma propriedade na representação JSON dessa saída. Os campos aninhados são selecionados usando uma sintaxe encadeada semelhante aos acessos de propriedade em JavaScript, .Field.NestedValue.

Você pode determinar quais campos estão disponíveis visualizando a saída bruta do comando. docker inspect mostrar JSON por padrão; isso pode ser atribuído diretamente aos espaços reservados da sintaxe do modelo. Para outros comandos como ps S imagesvocê pode recuperar a estrutura JSON subjacente usando um modelo especial:

docker ps --format '{{json .}}`

a json retorna a versão JSON bruta dos dados que você fornece.

transformações simples

As funções de transformação oferecem uma maneira conveniente de manipular valores. upper S lower converter strings para maiúsculas e minúsculas, respectivamente. Você pode aplicar distinção entre maiúsculas e minúsculas a uma string com title. As funções são inseridas no modelo antes do valor em que operam:

~$ docker inspect 94a8d1315315 --format '{{upper .State.Status}} (PID: {{.State.Pid}})'
RUNNING (PID: 1488278)

Se você quiser adicionar um novo caractere de linha entre os valores, use o println Função:

~$ docker inspect 94a8d1315315 --format '{{.State.Status}} {{.State.Pid}}{{println}}{{.State.StartedAt}}'
running 1488278
2022-03-22T20:45:58.614115689Z

trabalhar com matrizes

A sintaxe do modelo tem suporte interno para iteração pelos elementos de uma matriz. a range A função faz um loop pelos valores de um array e define o . variável para cada:

~$ docker inspect 94a8d1315315 --format '{{range .Mounts}}{{println .Destination}}{{end}}'
/config
/data

Você pode combinar elementos de matriz junto com o join Função:

~$ docker inspect 94a8d1315315 --format '{{join .Config.Cmd " "}}'
caddy run --config /etc/caddy/Caddyfile --adapter caddyfile

Isso cria uma string que incorpora cada valor na matriz. Os elementos são vinculados ao texto especificado como o segundo parâmetro do argumento.

saída de tabulação

Muitos comandos do Docker por padrão exibem dados em um layout de tabela legível por humanos. Você pode criar suas próprias tabelas usando o especial table componente de modelo.

Usar t caracteres para separar os campos de dados em colunas da tabela. O modelo será executado para cada um dos elementos incluídos na saída do comando da CLI do Docker. As colunas da tabela são dimensionadas automaticamente para corresponder ao comprimento de seu conteúdo.

~$ docker images --format 'table {{.ID}}t{{.Tag}}t{{.Size}}'
IMAGE ID       TAG          SIZE
ede20431e41f   caddy        40.4MB
e5179b119094   <none>       40.4MB

O Docker inclui automaticamente os cabeçalhos de coluna apropriados para os campos em seu modelo.

Formato condicional

Os modelos também suportam instruções condicionais “if”. Você pode personalizar dinamicamente a saída do comando exibindo um valor diferente com base em uma condição:

~$ docker ps --format '{{.ID}} {{if eq .State "running"}}Alive{{else}}Not Running{{end}}'
94a8d1315315 Alive

Este modelo mostra ou Alive qualquer Not Running dependendo se cada recipiente State o campo está definido para running. a if O bloco é seguido pelo valor que é exibido quando a condição é correspondida. um opcional else o bloco pode ser encadeado posteriormente. A condição é encerrada por {{end}} palavra chave.

Os modelos Go compreendem vários operadores de comparação. a eq mostrado acima verifica se o primeiro valor é igual ao segundo. As seguintes opções estão disponíveis adicionalmente:

• ne – Uma comparação “não igual a”.
• lt – Uma comparação “menor que” (
• lte – Uma comparação “menor ou igual a” (
• gt – Uma comparação “maior que” (>).
• gte – Uma comparação “maior ou igual a” (> =).

existir and, orS not palavras-chave também para encadear condições em expressões complexas.

Formatação avançada usando Jq

a --format flag é usado principalmente para criar strings de saída legíveis por humanos. Se você se sentir mais confortável inspecionando JSON bruto, poderá usar outras ferramentas como jq para manipular a saída do Docker mais diretamente. Isso pode ser útil quando você deseja criar consultas mais avançadas do que os modelos Go sozinhos podem fornecer.

docker inspect produz JSON por padrão, então sua saída pode ser canalizada diretamente para jq:

~$ docker inspect 94a8d1315315 | jq .[0].Config.Cmd
[
  "caddy",
  "run",
  "--config",
  "/etc/caddy/Caddyfile",
  "--adapter",
  "caddyfile"
]

A saída de outros comandos deve ser convertida em seu JSON bruto com --format antes de ir para jq:

~$ docker images --format '{{json .}}' | jq .Size
"968MB"
"946MB"
"40.1MB"

Jq fornece sua própria sintaxe para selecionar, manipular e formatar dados JSON. O básico é semelhante aos espaços reservados de modelo em Go. Os campos são referenciados usando o .Field sintaxe. Há suporte para selecionar elementos de matriz usando o .[index] notação.

conclusão

A CLI do Docker se torna mais poderosa quando você pode visualizar e manipular seletivamente os dados de saída. Vá modelos com o --format sinalizador fornece uma maneira de criar interfaces personalizadas que tornam o gerenciamento de seus contêineres mais rápido.

Em algumas situações, --format ele ainda pode não oferecer o poder e a flexibilidade de que você precisa. Comandos de pipeline do Docker para ferramentas externas como jq fornece outra maneira de interrogar rapidamente sua instalação e exibir seus dados em outros sistemas.