pkglint глубоко — практика на своём пакете

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

M5 урок 9 — первое знакомство с d8 package verify. Этот урок разбирает pkglint (реализацию verify) построчно — все шесть линтеров, конфигурацию и практику исправления реальных предупреждений на пакете Umami.

Теория

d8 package verify — команда, флаги, конфигурация

1

d8 package verify [--hide-warnings] [--show-ignored] [--remote <registry-ref>] [--lint-config <path>]

• --hide-warnings — показывать только ошибки, скрывая предупреждения (полезно для строгого CI-гейта, где важны только блокирующие проблемы).
• --show-ignored — показывать также находки, исключённые через конфигурацию (полезно при отладке самой конфигурации .pkglint.yaml, чтобы убедиться, что исключение действительно применяется к нужным правилам).
• --remote <registry-ref> — проверить не локальную директорию, а уже собранный и опубликованный образ пакета в registry (полезно для проверки того, что реально попало в registry, а не только исходников в git).
• --lint-config <path> — путь к файлу конфигурации, если он не лежит в стандартном месте (.pkglint.yaml в корне пакета).

Полный список шести линтеров pkglint

Почему именно шесть линтеров, а не больше — предвестник сравнения с dmtlint

Обратите внимание на ограниченный набор проверяемых аспектов — все шесть линтеров затрагивают только то, что может существовать в Application-пакете согласно ограничениям из M5 урока 5 (только namespaced-ресурсы, отсутствие CRD, отсутствие RBAC-специфики уровня кластера). У pkglint физически нет линтера для RBAC/CRD/OpenAPI-конверсий — потому что у Application таких сущностей просто не может быть по архитектуре. Это прямая иллюстрация того, почему dmtlint для Module (M9 уроки 3–4) содержит девять линтеров — почти в полтора раза больше, чем у pkglint.

Практический разбор типичных предупреждений

layout: отсутствие обязательного файла changelog.yaml или несоответствие имени директории openapi/ ожидаемому — типичная ошибка при ручном создании структуры пакета без d8 package bootstrap application.

templates: отсутствие обязательных меток (app.kubernetes.io/name, app.kubernetes.io/instance) на ресурсах — легко упустить при написании шаблонов «с нуля» без сверки со стандартными Helm-конвенциями из M4 урока 1.

oss: отсутствие поля с точной версией используемой зависимости с открытым исходным кодом или несоответствие формата лицензии SPDX-идентификатору — частая проблема при неполном заполнении oss.yaml (полностью разбирается в M9 уроке 7).

images: использование мутабельного тега (:latest) как базового образа в Dockerfile/werf.yaml вместо явной версии — нарушает воспроизводимость сборки.

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

• Игнорировать предупреждения pkglint, ориентируясь только на ошибки (--hide-warnings по умолчанию в голове разработчика). Предупреждения часто указывают на реальные проблемы, которые станут ошибками в будущих версиях линтера — стоит стремиться к нулю предупреждений, а не только нулю ошибок.
• Не проверять --remote после публикации. Локальная проверка директории пакета может пройти успешно, но что-то может пойти не так на этапе сборки/публикации (например, werf.yaml некорректно упаковал файлы) — --remote проверяет то, что реально оказалось в registry.
• Не использовать --show-ignored при отладке .pkglint.yaml. Без этого флага легко случайно исключить не то правило или не заметить, что исключение вообще не сработало (например, из-за опечатки в имени правила).

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

Практики в кластере в этом уроке нет — pkglint работает с исходниками пакета и registry, а не с состоянием кластера.

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

1
2

d8 package verify
d8 package verify --show-ignored

Запустите d8 package verify на накопленном за M5–M8 пакете Umami, разберите каждое найденное предупреждение построчно, соотнесите с одним из шести линтеров из теории и исправьте все найденные проблемы, добиваясь чистого прохождения проверки.

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

1
2
3

d8 package verify --hide-warnings
d8 package verify --remote registry.example.org/packages/umami/version/0.1.0
d8 package verify --lint-config ./.pkglint.yaml

Полная таблица команд d8 package — 📋 d8 .

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

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

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

• Deckhouse — Разработка Application-пакета
• GitHub — internal/packagecmd/internal/verify/lint/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.01 — Анатомия registry-артефактов.
• Следующий урок: M9.03 — dmtlint: назначение и архитектура.

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