Hadolint — линтер для Dockerfile: руководство и внедрение

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

• Getting Started

• Linting a Dockerfile

• What Does Hadolint Look For?

• Customizing Configuration

• Output Formats

• Summary

Dockerfile описывают содержимое Docker-образа набором инструкций в текстовом файле. Синтаксис Dockerfile обычно прост, но есть подводные камни, которые легко пропустить в сложных проектах или при командной разработке. Автоматическая валидация Dockerfile помогает сохранить единообразие и снизить риск ошибок на этапе сборки образов.

Hadolint — это линтер для Dockerfile, который находит типичные проблемы и нарушения практик. Он парсит Dockerfile в абстрактное синтаксическое дерево (AST) и проверяет его по предопределённым правилам. Кроме того, Hadolint включает правила ShellCheck, поэтому он также анализирует shell-скрипты внутри инструкций

RUN

и подсказывает распространённые ошибки в bash-скриптах.

Getting Started

Hadolint распространяется в нескольких форматах. Самый быстрый путь начать — скачать последнюю предкомпилированную бинарную сборку для вашей ОС с релизов проекта на GitHub.

У Hadolint также есть официальный Docker-образ

hadolint/hadolint

если вы предпочитаете не устанавливать бинарный файл локально. В качестве ещё одного варианта можно использовать веб-версию для экспериментальной проверки отдельных Dockerfile.

Linting a Dockerfile

Запустите Hadolint, указав путь к Dockerfile для начала сканирования:

hadolint Dockerfile

Если вы используете Docker-образ Hadolint, удобнее передать содержимое Dockerfile в контейнер через stdin:

docker run --rm -i hadolint/hadolint < Dockerfile

Результат проверки выводится в терминал. В примере Hadolint указывает, что инструкция RUN apt-get install небезопасна, потому что пакеты не фиксируются по версиям. Без явного указания версий содержимое образа может меняться между сборками, что приводит к трудноотлавливаемым проблемам.

Что проверяет Hadolint

Hadolint содержит десятки встроенных правил для проверки распространённых ошибок конфигурации и вопросов безопасности. Цель — приблизить Dockerfile к рекомендациям по созданию образов.

Примеры областей проверки:

• использование ненулевого (не root) пользователя в финальном образе;
• относительные пути в инструкции WORKDIR;
• наличие нескольких инструкций HEALTHCHECK;
• отсутствие явно закреплённых тегов и версий образов;
• ошибки Bash-скриптов благодаря интеграции с ShellCheck.

Правила идентифицируются по номерам с префиксами HL (Hadolint) или SC (ShellCheck). Каждой проверке присваивается уровень серьёзности — от «Ошибка» до «Информация». Ошибки следует исправлять в первую очередь.

Настройка конфигурации

Hadolint настраивается через файл .hadolint.yaml. Он ищет конфиг в нескольких местах: рабочая директория проекта, каталоги конфигурации пользователя и домашняя директория. Используется только первый найденный файл — слияния конфигураций между разными местоположениями не происходит.

Конфигурация позволяет игнорировать правила и менять уровни их серьёзности. Это полезно, когда стандартный набор проверок не подходит под особенности вашего окружения. Если вы добавите .hadolint.yaml рядом с Dockerfile в репозитории, команда сможет согласовать поведение линтера для всех участников.

Многие поля конфигурации также доступны как флаги CLI и переменные окружения.

Правила отключаются через поле ignored. Это должен быть список идентификаторов правил.

ignored:

- DL3010

- DL3020

Если нужно понизить серьёзность правила, не отключая его полностью, используйте ключ override. Он позволяет снизить или повысить уровень внимательности для конкретного правила:

override:

  warning:

  - DL3020

В примере правило DL3020 понижается с уровня «ошибка» до «предупреждение». Это правило требует использовать COPY вместо ADD при работе с файлами и папками из build-контекста.

Глобально можно настроить порог неудачи проверки. Поле failure-threshold заставит Hadolint завершиться с кодом ошибки, если в выводе будет хотя бы один тест заданного уровня серьёзности или выше:

failure-threshold: warning

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

Вы можете отключить завершение с ошибкой, установив no-fail: true в конфиге или передав флаг --no-fail. Тогда Hadolint всегда вернёт код выхода 0, что бывает полезно, если вы хотите сделать проверку не блокирующей в CI.

Доверенные регистры

Конфиг также можно использовать для задания доверенных реестров образов. При заполненном поле trustedRegistries Hadolint будет предупреждать о ссылках на образы из иных регистров:

trustedRegistries:

- docker.io

- docker-registry.example.com

Схемы меток

Hadolint поддерживает базовую валидацию меток (LABEL). Это позволяет требовать, чтобы добавляемые метки соответствовали заданной схеме типов. Пример конфигурации:

label-schema:

  notes: text

  app-version: semver

  built-at: rfc3339

В этом фрагменте notes — произвольный текст, app-version — версия в формате semver, built-at — временная метка в формате RFC 3339. Полный перечень типов можно найти в документации Hadolint.

По умолчанию допускаются метки, не перечисленные в схеме. Если вы хотите запретить неизвестные метки, включите strict-labels: true или используйте флаг --strict-labels.

Форматы вывода

Поддерживаются несколько форматов вывода через опцию format или флаг --format. По умолчанию используется tty — цветной вывод в терминал. Цвета можно отключить флагом --no-color.

Альтернативные форматы:

• json — подробная JSON-структура, удобная для скриптов и автоматической обработки.
• checkstyle — совместимый с Checkstyle отчёт.
• codeclimate — формат для Code Climate.
• gitlab_codeclimate — вариант для интеграции с GitLab CI и отображения результатов в MR.

Эти форматы удобны для автоматической интеграции в CI/CD и аналитические пайплайны.

Когда Hadolint не подходит

Hadolint отлично подходит для автоматической проверки синтаксиса и распространённых рекомендаций, но есть случаи, когда он не заменит человеческий код-ревью:

• проект использует нестандартный build-процесс, завязанный на специфичных хаков, которые Hadolint посчитает нарушением правил;
• нужны проверки безопасности уровня SAST/DAST, анализа зависимостей и сканирования уязвимостей — для этого нужны специализированные инструменты;
• требуется анализ runtime-поведений образа (поведение в контейнере, сетевые зависимости, эксплуатационные сценарии) — это выходит за рамки статической проверки Dockerfile.

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

Альтернативные подходы и инструменты

Если Hadolint по каким‑то причинам не подходит, можно рассмотреть:

• собственные CI-скрипты на основе регулярных выражений и shell-валидаторов;
• более широкие платформы проверки инфраструктуры (например, инструменты для IaC и безопасность контейнеров);
• комбинирование Hadolint с Snyk, Trivy, Clair и другими сканерами образов для проверки уязвимостей.

Комбинация статической проверки Dockerfile + сканирование образов по слоям даёт наиболее полный уровень контроля качества.

Ментальные модели и эвристики

Простые правила, которые помогают оценивать Dockerfile:

• «Меньше слоёв — лучше» — комбинируйте связанные RUN-команды в один слой, избегайте лишних инструкций.
• «Иммутабельность» — фиксируйте версии пакетов и базовых образов, чтобы сборки были детерминированными.
• «Минимизация привилегий» — переход на непользовательского пользователя в финальном образе.
• «Явная очистка» — удаляйте кэш менеджера пакетов и временные файлы в том же слое, где устанавливаете пакеты.

Эти эвристики часто отражены в правилах Hadolint и упрощают принятие решений.

Краткая методология внедрения Hadolint

1. Запустите Hadolint локально на существующих Dockerfile, оцените список проблем.
2. Создайте базовый .hadolint.yaml в репозитории, отключив только те правила, которые точно не применимы.
3. Интегрируйте Hadolint в CI с порогом failure-threshold для предупреждений или ошибок по мере зрелости процесса.
4. Обучите команду: короткий чеклист при PR, объясняющий типичные исправления.
5. Регулярно пересматривайте конфиг по мере роста проекта.

Роли и чеклисты

Developer (разработчик):

• запускать Hadolint локально перед созданием коммита;
• исправлять ошибки уровня «Ошибка» и оценивать предупреждения;
• добавлять тестовый пример Dockerfile при значительных изменениях.

Reviewer (код-ревьюер):

• проверять, что Dockerfile соответствует политике проекта и проходит Hadolint;
• при отклонении правила записывать причину в ревью;
• следить за тем, чтобы изменения в .hadolint.yaml сопровождались обоснованием.

DevOps/CI-администратор:

• обеспечить наличие Hadolint в CI-образах;
• настроить приемлемый failure-threshold и политику для --no-fail при необходимости;
• вести мониторинг ложных срабатываний и корректировать конфиг.

Критерии приёмки

• Dockerfile проходит Hadolint на уровне «ошибка» — 0 ошибок.
• Важные предупреждения задокументированы и обсуждены.
• Конфиг .hadolint.yaml хранится в репозитории и обновлённо документирован.

Примеры конфигураций

Минимальный пример, выключающий два правила:

ignored:
  - DL3010
  - DL3020

Понижение уровня серьёзности для одного правила:

override:
  warning:
    - DL3020

Включение строгой проверки меток и доверенных регистров:

strict-labels: true
trustedRegistries:
  - docker.io
label-schema:
  app-version: semver
  built-at: rfc3339

SOP: быстрое руководство по исправлению ошибок

1. Выполните hadolint Dockerfile или docker run --rm -i hadolint/hadolint < Dockerfile.
2. Первичные исправления: фиксация версий базового образа и пакетов, объединение RUN-команд, удаление лишних ADD.
3. Запустите hadolint повторно и убедитесь, что критические ошибки исправлены.
4. Зафиксируйте изменения в Git и оформите PR с ссылкой на исправления.

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

Hadolint — кроссплатформенный инструмент: бинарные сборки доступны для большинства операционных систем, а Docker-образ позволяет запускать его без установки. При миграции CI-скриптов проверьте, что используемый формат вывода (json, codeclimate и т. п.) поддерживается текущими инструментами отчётности.

Примеры типичных исправлений (cheat sheet)

• Проблема: RUN apt-get install package без фиксации версии. Решение: указывать точную версию или обновлять образ ввиду политики проекта.

• Проблема: использование ADD для простых копий файлов. Решение: заменить на COPY.

• Проблема: временные файлы остаются в образе. Решение: удалить кеши и временные файлы в том же RUN, где они создавались.

Когда и как интегрировать в CI

• На начальном этапе рекомендовано запускать Hadolint в отдельной не блокирующей задаче (--no-fail), чтобы собрать список проблем.
• После устранения критических ошибок перевести задачу в блокирующую, установив failure-threshold: warning или failure-threshold: error.
• Используйте format: gitlab_codeclimate или codeclimate для визуализации проблем в интерфейсе MR, если CI поддерживает такие интеграции.

Заключение

Hadolint — надёжный инструмент для автоматической проверки Dockerfile, который экономит время и повышает качество образов. Он удобно настраивается, совместим с CI и дополняет инструменты безопасности и тестирования. Используйте Hadolint как первый слой контроля качества в цепочке сборки образов.

Important: Hadolint не заменяет анализ уязвимостей и runtime-тесты — комбинируйте разные инструменты для полного покрытия.

Социальный превью

OG title: Hadolint — линтер для Dockerfile

OG description: Быстрое руководство по установке, настройке и интеграции Hadolint для проверки Dockerfile и улучшения качества Docker-образов.

Короткое объявление (100–200 слов)

Hadolint — простой и мощный линтер для Dockerfile, который помогает командам находить ошибки конфигурации и улучшать практики сборки образов. Он анализирует Dockerfile через AST, включает правила ShellCheck для проверки скриптов внутри RUN и поддерживает гибкую настройку через .hadolint.yaml. Hadolint можно запускать как бинарь, через официальный Docker-образ или использовать онлайн-версию для быстрых экспериментов. Интегрируйте Hadolint в CI, чтобы получать быстрые отчёты при изменениях Dockerfile и ускорять код-ревью. Настройте вывод в json или codeclimate для автоматической обработки, а также используйте доверенные регистры и строгую схему меток для соответствия политике проекта.

Summary

Hadolint автоматизирует обнаружение проблем в Dockerfile, помогает следовать лучшим практикам сборки и легко интегрируется в CI. Настраивайте .hadolint.yaml для снижения ложных срабатываний и комбинируйте инструмент с анализаторами уязвимостей для полного покрытия.