Docker CLI: использование флага --format и шаблонов Go

Быстрые ссылки

• Какие команды поддерживают “–format”?
• Простой пример
• Доступ к значениям вывода
• Простые трансформации
• Работа с массивами
• Табулирование вывода
• Условное форматирование
• Расширенное форматирование с использованием jq
• Лучшие практики и шпаргалка
• Заключение

Какие команды поддерживают “–format”?

Флаг --format поддерживают многие часто используемые команды Docker CLI. Его можно применять к docker inspect и к командам, выводящим списки объектов, таким как:

docker ps

docker images

docker volumes

Когда вы указываете --format, Docker пропускает оригинальный вывод через строку шаблона Go, которую вы передаёте. Шаблоны получают доступ к данным, которые CLI получает от API, и позволяют подставлять значения, форматировать строки и строить компактные представления.

Важно: чтобы понять, какие поля доступны в шаблоне, сначала посмотрите «сырую» структуру вывода (JSON) той команды, с которой вы работаете.

Простой пример

Запуск docker inspect для контейнера обычно даёт длинную JSON-структуру. С помощью --format можно извлечь только интересующие поля. Пример: статус контейнера, PID и время запуска:

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

Такой шаблон гораздо удобнее для быстрого сканирования, чем полный JSON.

Доступ к значениям вывода

В шаблонах динамические части заключаются в двойных фигурных скобках. Синтаксис {{.Field}} указывает на поле в JSON-представлении вывода команды. Для вложенных полей используется точечная нотация .Field.NestedValue.

Чтобы узнать доступные поля:

• Для docker inspect — смотрите JSON напрямую (по умолчанию этот вывод JSON).
• Для команд вроде ps и images можно вывести структуру как JSON через специальный шаблон:

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

Функция json показывает «сырые» данные, которые можно затем анализировать или передавать внешним инструментам.

Простые трансформации

Шаблоны включают функции для преобразования строк. Например upper, lower и title:

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

Чтобы добавить перенос строки между значениями, используйте println:

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

Совет: цепочки функций поддерживаются — можно оборачивать одну функцию в другую, если это читабельно.

Работа с массивами

Шаблоны умеют итерировать массивы. Функция range проходит по элементам и задаёт текущую точку контекста в переменной ..

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

Чтобы объединить элементы массива в одну строку, используйте join:

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

join полезен для команд, где аргументы хранятся массивом.

Табулирование вывода

Многие команды по умолчанию показывают таблицу. Вы можете создавать собственные таблицы с помощью специального компонента table и символа табуляции (\t) для разделения колонок. Docker автоматически добавит заголовки колонок для полей из шаблона:

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

Колонки автоматически подстраиваются по ширине содержимого.

Условное форматирование

Шаблоны поддерживают условные конструкции if/else. Это позволяет менять отображаемое значение в зависимости от состояния:

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

Доступные операторы сравнения: eq, ne, lt, lte, gt, gte. Также есть логические and, or, not.

Расширенное форматирование с использованием jq

Флаг --format удобен для человекочитаемых строк. Если нужно сложное манипулирование JSON, продолжайте с инструментом jq. docker inspect отдаёт JSON по умолчанию и его можно передать в jq:

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

Для других команд сначала конвертируйте вывод в JSON с --format '{{json .}}', затем передавайте в jq:

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

jq предлагает мощный язык запросов по JSON и удобен для скриптов и CI-пайплайнов.

Шпаргалка функций и часто используемые паттерны

Функции шаблонов, которые часто пригодятся:

• upper, lower, title — преобразование регистра.
• println — вывести перенос строки.
• range — итерирование массива.
• join — объединение элементов массива в строку.
• json — вернуть сырые данные JSON.
• eq, ne, lt, lte, gt, gte — сравнения.
• and, or, not — логические операции.
• table + \t — построение таблиц.

Примеры паттернов:

• Однострочный статус контейнера: --format '{{.ID}} {{.State.Status}}'.
• Таблица с названием и размером образа: --format 'table {{.Repository}}\t{{.Tag}}\t{{.Size}}'.
• Список томов с путями монтирования: --format '{{range .Mounts}}{{.Destination}}{{println}}{{end}}'.

Лучшие практики

• Начинайте с вывода JSON ({{json .}}), чтобы понять структуру.
• Пишите шаблоны инкрементально: сначала поле, затем — функции и условие.
• Избегайте очень длинных шаблонов в командной строке — храните их в скриптах или файлах конфигурации.
• Для сложных агрегаций и фильтрации используйте jq вместо чрезмерного усложнения шаблона.
• Добавляйте заголовки колонок явно, если шаблон используется в автоматизированных отчетах.

Чек-листы по ролям

Для инженера DevOps:

• Составьте набор шаблонов, которые помогают быстро проверять работоспособность сервисов.
• Интегрируйте шаблоны в мониторинг и администрирование контейнеров.

Для разработчика:

• Используйте --format в локальной отладке для быстрого вывода нужных полей.
• Предпочитайте join при просмотре аргументов команд.

Для SRE:

• Соберите шаблоны, полезные при инцидентах (статус, PID, время запуска, журналы).
• Автоматизируйте скрипты, которые собирают данные для постмортема.

Когда –format не подходит

• Если вам нужно сложное агрегированное преобразование (несколько уровней группировок или вычислений), лучше использовать jq или экспортировать данные в систему аналитики.
• Если структура API часто меняется, длинные шаблоны будут хрупкими; держите шаблоны в VCS и тестируйте их.
• Для бинарных данных и больших логов шаблоны не оптимальны.

Мини‑методология для создания шаблона

1. Посмотрите сырой JSON: docker --format '{{json .}}' или docker inspect.
2. Выберите минимальные поля, которые вам нужны.
3. Напишите шаблон с учётом читаемости (переносы, табуляция).
4. Добавьте условные ветви для редких состояний.
5. Перенесите шаблон в скрипт и добавьте тестовые примеры.

Совместимость и миграция

Шаблоны Go — часть клиента Docker. В разных версиях API названия полей могут меняться; при обновлении Docker проверяйте существующие шаблоны. Для команд, которые выводят списки, используйте {{json .}} как единый способ получения стабильного входа для внешних инструментов.

Примеры часто используемых команд (шпаргалка)

• Показать только ID и статус контейнеров:

docker ps --format '{{.ID}}\t{{.Status}}'

• Получить список команд запуска образа в виде строки:

docker inspect  --format '{{join .Config.Cmd " "}}'

• Показать образы в таблице с тегом и размером:

docker images --format 'table {{.Repository}}\t{{.Tag}}\t{{.Size}}'

Когда использовать jq вместо шаблонов

Используйте jq, если вы:

• Нуждаетесь в сложной фильтрации, агрегации или вычислениях по JSON.
• Подготавливаете данные для других систем в формате JSON.
• Пишете повторно используемые скрипты для CI/CD, где требуется предсказуемый JSON.

jq даёт выразительный DSL для JSON и хорошо сочетается с docker --format '{{json .}}'.

Заключение

Флаг --format значительно упрощает работу с Docker CLI: он делает вывод коротким, структурированным и удобным для чтения. Для сложных задач комбинируйте шаблоны с jq и храните шаблоны в скриптах или репозитории конфигураций. Включите краткую шпаргалку функций и несколько проверенных шаблонов в ваш набор инструментов — это повысит скорость диагностики и автоматизации.

Важно: тестируйте шаблоны при обновлениях Docker и API, чтобы избежать внезапных поломок автоматизации.

Краткое резюме

• --format позволяет выбирать и форматировать поля вывода Docker.
• Используйте json, range, join, table, if и функции преобразования для гибкого отображения.
• Для сложных трансформаций предпочитайте jq.

Примечание: храните часто используемые шаблоны в репозитории и добавляйте простые тесты для них, чтобы сохранить стабильность при обновлениях.