Чеклист приёмки приложения и oss.yaml

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

M9 уроки 1–6 — весь путь от структуры registry до полного CI-пайплайна. Этот заключительный урок модуля M9 закрывает вопрос лицензионной чистоты пакета через oss.yaml и формирует итоговый чеклист приёмки перед публикацией.

Теория

oss.yaml — обязательные поля

oss.yaml — это плоский список компонентов (не обёрнутый в ключ вроде items:), каждый элемент которого линтер oss (часть pkglint, M9 урок 2) проверяет отдельно:

1
2
3
4
5
6

- id: umami
  name: umami
  description: "Web-аналитика с открытым исходным кодом"
  license: MIT
  link: https://github.com/umami-software/umami
  version: "2.15.0"

Обязательные непустые поля для каждого элемента: id (стабильный идентификатор компонента для диагностики), name (имя используемого open-source компонента), description, license (одна строка — идентификатор лицензии, а не список; для компонентов с двойным лицензированием используется составное значение по SPDX-соглашению, например MIT OR Apache-2.0), link (ссылка на источник — исходный репозиторий или лицензию). Версия задаётся одним из двух взаимоисключающих способов: либо одиночным полем version (точная версия, использованная в конкретной сборке — критично для отслеживания уязвимостей через связь с CVE-базами), либо списком versions (элементы с name/version/condition — для случая, когда пакет в разных конфигурациях использует разные версии зависимости); указывать оба поля одновременно линтер считает ошибкой, как и не указывать ни одного.

Лицензионная проверка зависимостей: зачем это нужно бизнесу, а не только формальность

oss.yaml — не бюрократическая формальность, а инструмент реального юридического и security-риск-менеджмента: организации, устанавливающие Application-пакеты через каталог Deckhouse, должны иметь возможность провести аудит используемых лицензий (например, чтобы избежать случайного использования компонента с лицензией AGPL в контексте, где это создаёт юридические обязательства раскрытия исходного кода всей интегрированной системы) и отслеживать версии зависимостей для целей управления уязвимостями (например, при выходе критического CVE для конкретной версии библиотеки — по oss.yaml можно быстро определить, какие пакеты каталога её используют).

Полный чеклист приёмки Application-пакета

Синтез всех критериев, разобранных по отдельности на протяжении курса, в единый итоговый список для самопроверки перед публикацией:

1. Структура пакета (M5 урок 1) — все обязательные файлы и директории присутствуют, опциональные — по необходимости.
2. package.yaml (M5 урок 2) — корректные name (≤24 символов), descriptions на обоих языках, requirements точно отражают реальные зависимости от Module/Kubernetes/Deckhouse.
3. Контракт настроек (M5 урок 3) — config-values.yaml и values.yaml синхронизированы, internal.* поля не экспонированы пользователю.
4. Ограничения Application соблюдены (M5 урок 5) — нет попыток создать CRD, cluster-wide ресурсы, хуки за пределами namespace инстанса.
5. pkglint проходит без ошибок и предупреждений (M9 урок 2).
6. Nelm-аннотации корректны (M6, M7) — защита данных (resource-policy: keep+reclaimPolicy: Retain), корректный порядок ресурсов, отсутствие известных pitfalls (null-значения, lookup, недетерминированные функции).
7. Оптимизация сборки применена, где уместно (M8) — cache-repo настроен в CI, минимизация размера образов рассмотрена.
8. oss.yaml полон и точен — все зависимости с открытым исходным кодом перечислены с корректными лицензиями и версиями.
9. CI/CD настроен полностью (M9 урок 6) — раздельные dev/prod потоки, ручной gate на production, защищённые переменные для секретов.
10. Production Operations готовность (M10) — мониторинг, HPA/VPA, PDB, backup-стратегия предусмотрены (детально разбирается в следующем модуле).

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

• Заполнять oss.yaml формально, копируя из шаблона без фактической проверки реальных зависимостей. Устаревший или неточный oss.yaml не защищает от реальных юридических/security-рисков — только создаёт иллюзию проверенности.
• Не обновлять version в oss.yaml при обновлении зависимости в коде. Рассинхронизация между реально используемой версией и задекларированной в oss.yaml версией срывает саму цель документа — отслеживаемость для целей security.
• Считать чеклист приёмки формальностью, выполняемой «для галочки» перед первой публикацией, но не пересматриваемой при последующих обновлениях. Каждое существенное изменение пакета (новая зависимость, новый паттерн Nelm-аннотаций) — повод пересмотреть релевантные пункты чеклиста заново.

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

Практики в кластере в этом уроке нет — материал относится к финальной проверке пакета перед публикацией.

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

Составьте полный oss.yaml для пакета Umami, перечислив все значимые open-source зависимости (сам Umami, используемая база данных как отдельный компонент, если она upstream-зависимость, а не собственный код), и пройдите весь чеклист приёмки из теории построчно, отмечая выполнение каждого пункта — это финальная веха перед M10 (Production Operations) и M11 (капстоун).

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

1

d8 package verify    # включает линтер oss, проверяющий формат oss.yaml

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

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

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

• Deckhouse — Разработка Application-пакета
• GitHub — internal/packagecmd/internal/verify/lint/linters/oss/
• Внутренняя wiki Flant: «Заполнение oss.yaml», «Чеклист приемки модуля» (адаптировано для Application).

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

• Готовим 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.06 — Полный .gitlab-ci.yml.
• Следующий модуль: M10 — Production Operations, урок 1.

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