0%

Жизненный цикл через d8 package

Уровень: advanced ~55 мин Практика: Umami (MIT)

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

  • M5.08 — Go-хуки Application — у вас должен быть полностью собранный пакет Umami со всеми гранями из предыдущих уроков M5

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

M5 уроки 1–8 — вы собрали полный пакет Umami: структуру, package.yaml, контракт настроек, шаблоны, ограничения, CRD, хуки. Теперь — как этот пакет реально проходит путь от директории на диске до опубликованного, устанавливаемого артефакта.

Теория

d8 package — встроенная команда d8, а не отдельный плагин

Команда d8 package (как и d8 k, разобранный в M2 уроке 2) в актуальных версиях deckhouse-cli зарегистрирована как встроенная top-level команда наряду с bootstrap/build/verify — устанавливать её отдельно не нужно, достаточно установить сам d8. В более ранних версиях deckhouse-cli package поставлялась как lazy-loaded плагин через механизм d8 plugins — если у вас установлена такая версия, тот же результат даёт:

1

d8 plugins install package

bootstrap application — генерация скелета

1
2
3
4

d8 package bootstrap application myapp --hooks
cd myapp
git remote add origin <gitlab-repo.git>
git push --set-upstream origin main
ФлагЧто генерирует
(без флагов)минимальная структура: package.yaml, templates/, openapi/
--hooksдополнительно каркас hooks/batch/ с примером Go-хука (M5 урок 8)
--extendedрасширенный набор файлов (дополнительная документация, примеры конфигурации)
--werfдобавляет werf.yaml/werf-giterminism.yaml для собственной сборки образов (M3)
-o <path>директория назначения (по умолчанию — текущая, с именем пакета)

После генерации команда сама инициализирует Git-репозиторий — что подчёркивает: giterminism-принципы (M3 урок 6) действуют не только для образов, но и для всего пакета в целом — версия пакета детерминирована относительно конкретного коммита.

build --version — сборка и публикация

1

d8 package build --version v0.1.0 --repo dev-registry.deckhouse.io/deckhouse/packages

Полный набор флагов:

ФлагНазначение
--version/-v <semver>версия пакета для публикации — инжектится в package.yaml (M5 урок 2) на этом шаге, а не редактируется вручную
--repo/-r <address>адрес registry назначения
--user/-u, --token/-tучётные данные для аутентификации в registry
--force/-fперезапись уже существующей версии (используется осторожно — обычно версии считаются иммутабельными)
--debugподробный вывод для диагностики проблем сборки
--sign --sign-cert --sign-keyкриптографическая подпись пакета (для цепочки доверия поставки, детально — практика подписи в M10)

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

1
2
3
4

export PACKAGE_BUILD_REPOSITORY="dev-registry.deckhouse.io/deckhouse/packages"
export PACKAGE_BUILD_REPOSITORY_USER="ci-bot"
export PACKAGE_BUILD_REPOSITORY_TOKEN="${CI_REGISTRY_TOKEN}"
d8 package build --version "${CI_COMMIT_TAG}"

Что происходит на каждом шаге build:

  1. Валидация package.yaml (базовая структурная проверка, отдельная от полного pkglint).
  2. Сборка образов через Werf в изолированном Docker-контексте (images/*, если есть собственные, M3).
  3. Упаковка чарта и метаданных пакета в единый артефакт.
  4. Пуш в указанный --repo с тегом, соответствующим --version.

verify — это и есть запуск pkglint

1

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

d8 package verify — прямой интерфейс к pkglint (6 линтеров: docs/icon/images/layout/oss/templates, детально разбираем весь набор правил в M9). Ключевая деталь: --remote <ref> позволяет проверить уже собранный и опубликованный пакет в реестре, а не только локальную рабочую директорию — полезно для проверки, что именно попало в registry, независимо от текущего состояния локальной директории разработчика (которое могло измениться после публикации).

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

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

  • Использовать устаревшую версию deckhouse-cli, где d8 package ещё был плагином, и не знать об отличии. В DKP 1.76+ команда встроена; если d8 package --help не работает — обновите d8 через trdl (в legacy-версиях помогал d8 plugins install package).
  • Использовать --force при публикации версии по умолчанию, «на всякий случай». Версии пакетов должны быть иммутабельными по конвенции (аналог семверных Git-тегов, M3 урок 7) — перезапись уже опубликованной версии ломает воспроизводимость для пользователей, уже установивших эту версию.
  • Хранить PACKAGE_BUILD_REPOSITORY_TOKEN как явный флаг команды в логах CI. Используйте переменные окружения — они не попадают в историю выполненных команд так же явно, как аргументы CLI, видимые в логах процесса.

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

Практики в кластере в этом уроке нет — весь цикл bootstrap/build/verify выполняется локально/в CI до попадания пакета в кластер; первая реальная установка через Application CR — с завершением модуля (M5 урок 10) и далее в M6.

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

🧩 Практика урока: Umami · лицензия MIT
  1. Проверьте пакет Umami перед сборкой:
1

d8 package verify
  1. Исправьте все ошибки (не предупреждения) из вывода, затем соберите и опубликуйте тестовую версию:
1
2

git tag v0.1.0
d8 package build --version v0.1.0 --repo <ваш-тестовый-registry>/packages
  1. Проверьте уже опубликованную версию удалённо (не трогая локальную директорию):
1

d8 package verify --remote <ваш-тестовый-registry>/packages/umami:v0.1.0
  1. Смоделируйте CI-сценарий с переменными окружения вместо флагов:
1
2
3
4

export PACKAGE_BUILD_REPOSITORY="<ваш-тестовый-registry>/packages"
export PACKAGE_BUILD_REPOSITORY_USER="ci-bot"
export PACKAGE_BUILD_REPOSITORY_TOKEN="demo-token"
d8 package build --version v0.1.1

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

1
2
3
4

d8 package --help
d8 package bootstrap application <name> [--hooks] [--extended] [--werf] [-o <path>]
d8 package build --version/-v <semver> [--repo/-r <addr>] [--user/-u <user>] [--token/-t <token>] [--force/-f] [--debug] [--sign --sign-cert --sign-key]
d8 package verify [--hide-warnings] [--show-ignored] [--remote <ref>] [--lint-config <path>]

Полная шпаргалка d8: 📋 d8 .

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

Как поставляется команда d8 package в актуальных версиях deckhouse-cli?

В более ранних версиях deckhouse-cli package была lazy-loaded плагином, но теперь зарегистрирована как встроенная команда наравне с bootstrap/build/verify.

Источник: GitHub — deckhouse/deckhouse-cli

Откуда берётся реальное значение version в package.yaml при публикации?

Версия пакета детерминирована конкретной сборкой, а не редактируется вручную в файле.

Источник: Deckhouse — Разработка Application-пакета

Что делает d8 package verify?

verify — прямой интерфейс к pkglint, детально разбираемому в M9.

Источник: Deckhouse — Разработка Application-пакета

Зачем нужен флаг --remote у d8 package verify?

--remote позволяет проверить фактически опубликованный артефакт, независимо от текущего состояния локальной рабочей директории.

Источник: Deckhouse — Разработка Application-пакета

Почему не рекомендуется использовать --force при публикации версии пакета 'на всякий случай'?

Тот же принцип, что и с семверными Git-тегами образов — иммутабельность версий критична для надёжности установки/отката.

Источник: Рекомендуемая литература

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

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

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

Книги

  • Marko Lukša. Kubernetes in Action. 2nd ed., 2022. ISBN 978-1617297618.

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