dmtlint — практика анализа существующего Module

Что нужно знать перед уроком

M9 урок 3 — все девять линтеров dmtlint и формат .dmtlint.yaml. Этот урок — практика анализа, а не разработки: студент запускает dmt lint на публичном учебном Module (например, module-template — официальный шаблон-репозиторий Deckhouse для новых Module, используемый только как read-only объект изучения, без копирования его содержимого в репозиторий курса) и учится читать и интерпретировать вывод линтера.

Теория

Почему объект анализа — публичный module-template, а не собственный код

Курс целиком сфокусирован на разработке Application, а не Module (см. M2 урок 1 — Application vs Module). Чтобы студент получил практический навык чтения вывода dmtlint (нужный для диагностики Module, от которых зависит его Application — см. M6), но не отклонился в сторону авторства Module, практика строится вокруг готового публичного репозитория, доступного всем как открытый пример структуры Module (официальный шаблон-репозиторий deckhouse/modules-template на GitHub, содержащий базовый скелет Module с примером GitHub Actions workflow для сборки и публикации). Работа с ним ограничивается командой dmt lint и разбором её вывода — без внесения изменений в код Module.

Пошаговый разбор вывода dmt lint

1
2

git clone --depth 1 https://github.com/deckhouse/modules-template.git /tmp/module-example
dmt lint /tmp/module-example

Типичный вывод линтера структурирован по трём измерениям: линтер (один из девяти), уровень серьёзности (error/warn), конкретное правило и его локация (файл, строка, иногда kind/name конкретного Kubernetes-объекта в шаблоне). Пример типичной структуры находки:

[WARN] rbac: wildcard permission detected
  file: templates/rbac.yaml
  rule: wildcards
  kind: Role, name: module-controller

Разбор такой находки: линтер rbac обнаружил использование verbs: ["*"] вместо явного перечисления конкретных глаголов (get, list, watch и так далее) в Role с именем module-controller — это ровно тот класс проблем, который недоступен pkglint в принципе, поскольку у Application нет собственного RBAC уровня кластера (M9 урок 3).

Сопоставление каждого предупреждения с exclude-rules

Для каждой находки в выводе dmt lint можно определить, каким именно exclude-rules-блоком в .dmtlint.yaml её можно точечно отключить (если решение — сознательно принять риск, а не исправлять). exclude-rules вкладывается внутрь настроек конкретного линтера и группируется по имени конкретного правила (в примере — wildcards, правило линтера rbac), а не задаётся отдельным top-level блоком:

1
2
3
4
5
6

linters-settings:
  rbac:
    exclude-rules:
      wildcards:
        - kind: Role
          name: module-controller

Важно подчеркнуть учебную цель этого упражнения: не «научиться отключать линтер», а научиться читать структуру находки настолько внимательно, чтобы уметь сформулировать точное, минимально широкое исключение — типичная ошибка новичка — отключать линтер целиком (linters-settings.rbac.impact: warn для всего модуля) вместо точечного исключения одной конкретной находки.

Сравнение с pkglint-проверкой Application-пакета из того же домена

Если студент запускал pkglint на собственном пакете Umami (продолжение M9 урока 2), полезно провести прямое сопоставление объёма и характера находок: pkglint на Application-пакете, как правило, даёт находки только по docs/layout/templates/oss (структурные и оформительские), тогда как dmtlint на реальном Module типично выявляет RBAC- и OpenAPI-специфичные проблемы — классы ошибок, которые физически не могут возникнуть в Application-пакете. Это наглядное, эмпирическое (не только теоретическое) подтверждение вывода из M9 урока 3: «у Module в полтора раза больше линтеров и на порядок больше правил, потому что у Module принципиально больше типов сущностей».

Частые ошибки и подводные камни

• Начинать исправлять найденные проблемы в клонированном публичном репозитории. Цель упражнения — анализ, а не разработка или контрибьюция; изменения в клон не сохраняются и не являются частью курса.
• Отключать линтер целиком вместо точечного exclude-rules для конкретной находки. Это ключевая ошибка новичка — грубое отключение линтера скрывает все будущие находки этого класса, а не только текущую, сознательно принятую.
• Путать вывод dmtlint с выводом pkglint при чтении CI-логов сторонних репозиториев. Форматы похожи, но линтеры и правила — из разных наборов; важно ориентироваться по названию конкретного линтера в выводе.

Практика в кластере

Практики в кластере в этом уроке нет — анализ выполняется над исходным кодом Module, а не над состоянием кластера.

Практика разработки

Склонируйте публичный deckhouse/modules-template, запустите dmt lint на нём, задокументируйте (в виде текстовой заметки, не изменяя сам клон) минимум пять найденных находок с указанием линтера, серьёзности и предлагаемого exclude-rules-блока для каждой (даже если реального намерения его применять нет — цель в тренировке чтения структуры находки). Сравните итоговый список с находками pkglint на вашем собственном пакете Umami из M9 урока 2.

Шпаргалка команд урока

1
2
3

git clone --depth 1 https://github.com/deckhouse/modules-template.git /tmp/module-example
dmt lint /tmp/module-example --linter rbac
dmt lint /tmp/module-example --show-ignored

Вопросы для самопроверки

Рекомендуемая литература

Официальная документация

• GitHub — официальный шаблон-репозиторий Module для практики анализа.
• GitHub — README и pkg/linters/

Статьи и блоги

• Готовим Gitea со вкусом werf CI/CD в кластере Deckhouse. Часть 3 — Flant на Habr.
• GitLab + K8s + Werf — Habr.
• Разворачиваем приложение в кластере Kubernetes под управлением Deckhouse c помощью werf — Flant на Habr.

Книги

• Gene Kim, Jez Humble, Patrick Debois, John Willis. The DevOps Handbook. 2nd ed., 2021. ISBN 978-1942788003.

Связанные материалы

• Предыдущий урок: M9.03 — dmtlint: назначение и архитектура.
• Следующий урок: M9.05 — semver-теги и релизный процесс.

✓ Урок пройден — все вопросы самопроверки отвечены верно