Анатомия registry-артефактов экосистемы Deckhouse

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

M5 урок 9 — d8 package build --version. M2 урок 2 — release channels Deckhouse. Этот урок открывает M9 — модуль о публикации, объясняя, куда именно физически попадают артефакты Application-пакета.

Теория

Издания Deckhouse и их отдельные registry-адреса

Коммерческие издания Deckhouse (Enterprise, Standard, Standard+, Basic) размещаются на разных путях одного и того же registry:

registry.deckhouse.io/deckhouse/ee        # Enterprise Edition
registry.deckhouse.io/deckhouse/se        # Standard Edition
registry.deckhouse.io/deckhouse/se-plus   # Standard+ Edition
registry.deckhouse.io/deckhouse/be        # Basic Edition

Это база, от которой строится вся дальнейшая структура — Module и Package (Application) размещаются в подпутях, специфичных для конкретного издания и его артефактов.

Параллельная структура для Module и Package

Артефакты Application-пакетов (Package) и Module в registry устроены параллельно, отличаясь только именем сегмента с релизными метаданными:

Терминологическое отличие только в имени сегмента: у Module он называется release, у Package — version. По устройству оба сегмента идентичны и принимают теги обоих видов — точный семвер (v1.2.3) и имя канала/рекомендованной версии (alpha, beta, stable) — платформа использует их, чтобы быстро определить нужную версию для обновления, не выкачивая основной образ целиком.

Основной образ vs метаданные-артефакт версии

«Основной образ» (…/packages/<name>:<semver>) — это не служебная обёртка, а сам «Bundle»: полное содержимое конкретной версии пакета — templates/ (Helm/Nelm-шаблоны), openapi/ (схемы config-values.yaml/values.yaml) и hooks/. Именно этот образ реально выкачивается платформой при установке или обновлении Application.

Отдельный, значительно более лёгкий артефакт под …/packages/<name>/version:<semver> — не чарт, а метаданные версии: package.yaml, version.json, changelog.yaml. Он нужен PackageRepository (M5 урок 6), чтобы при сканировании registry быстро наполнить объект ApplicationPackageVersion (описания, категория, stage, ограничения по версиям DKP/Kubernetes, зависимости от Module) для отображения в каталоге — не выкачивая полный основной образ только ради каталогизации версии.

extra-образы — что это

Сегмент extra/<extra-name> используется для дополнительных, вспомогательных образов, не являющихся ни главным образом пакета, ни версионным релизом — например, служебные образы для CI, документации, инструментов миграции, которые логически относятся к пакету, но не являются частью самого устанавливаемого чарта.

d8 mirror и офлайн-копирование реестра пакетов

Инструмент d8 mirror (упомянутый в M2 уроке 2 в общей таблице d8-групп) поддерживает зеркалирование и Module, и Package по одинаковой логике, с параллельными флагами:

1

d8 mirror pull --include-package myapp@>=1.0.0 --packages-path-suffix /packages ...

Каждый зеркалируемый пакет упаковывается в архив package-<name>.tar, содержащий главный образ, версионные образы и extra-образы — структурно идентично module-<name>.tar для Module. Отдельно, при каждом запуске d8 mirror pull (независимо от того, какие компоненты выбраны флагами), формируется общий архив package-versions.tar, агрегирующий версионные образы всех пакетов сразу — это гарантирует, что каталог доступных версий пакетов всегда клонируется целиком в офлайн-бандл, даже если конкретные пакеты не были явно запрошены.

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

• Путать сегменты release (для Module) и version (для Package) с местом хранения полноценного чарта. Оба сегмента — это лёгкие метаданные (package.yaml/version.json/changelog.yaml для Package), а не сам устанавливаемый Helm/Nelm-чарт; отличие между ними — только в имени сегмента, не в содержимом.
• Считать, что «основной образ» пакета (.../packages/<name>:<semver>) — только служебная обёртка каталога. На самом деле именно он содержит реальный устанавливаемый артефакт — templates/, openapi/, hooks/; сегмент .../version рядом с ним — только метаданные для каталогизации.
• Не понимать связь между структурой registry и ApplicationPackageVersion. Каждый объект ApplicationPackageVersion в кластере наполняется PackageRepository из метаданных-артефакта под .../packages/<name>/version/<semver> в registry; без понимания этой структуры сложно диагностировать проблемы установки версии, отсутствующей в registry.

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

1

d8 k get applicationpackageversion -A -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.image}{"\n"}{end}'

Сопоставьте путь .spec.image из полученного объекта ApplicationPackageVersion со структурой .../packages/<name>/version/<semver>, разобранной в теории.

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

Изучите итоговый путь публикации, который сгенерирует d8 package build --version для вашего пакета Umami, сравнив его со схемой параллельной структуры Module/Package из теории — это готовит к следующему уроку о pkglint.

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

1

d8 mirror pull --include-package <name>@<constraint> --packages-path-suffix /packages

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

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

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

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

• Deckhouse — структура container registry
• Deckhouse — Разработка Application-пакета
• Deckhouse — Разработка Module
• GitHub — механика d8 mirror pull для Package

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

• Готовим 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.

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

• Предыдущий модуль: M8.07 — werf converge как единая точка входа.
• Следующий урок: M9.02 — pkglint глубоко.

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