Анатомия пакета Application целиком

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

M4 целиком — общий Helm/Nelm-контекст (чарт, шаблоны, секреты). M2 урок 1 — граница Application/Module. Теперь собираем всё вместе: что именно составляет реальный Application-пакет как артефакт для публикации.

Теория

Полное дерево файлов Application-пакета

umami/
├── package.yaml            # манифест пакета — метаданные, версия, требования (M5 урок 2)
├── changelog.yaml           # история изменений версий пакета
├── .gitlab-ci.yml            # пайплайн CI/CD (детально — M10 модуль CI/CD, если применимо к вашей ветке курса)
├── .pkglint.yaml             # конфигурация линтера pkglint (детально — M9)
├── .gitignore
├── docs/
│   ├── README.md              # (ru/en) описание для marketplace
│   └── icon.svg                 # иконка пакета
├── hooks/
│   └── batch/
│       └── my-hooks/            # Go-хуки Application (M5 урок 8)
│           ├── go.mod
│           ├── go.sum
│           └── main.go
├── images/
│   └── backend/
│       └── Dockerfile            # правила сборки образов (тот же werf.yaml/Dockerfile из M3)
├── openapi/
│   ├── config-values.yaml         # контракт Application.spec.settings (M5 урок 3)
│   └── values.yaml                  # полный helm-values контракт (M5 урок 3)
├── templates/                       # Helm-шаблоны (контекст .Application.* — M5 урок 4)
│   ├── deployment.yaml
│   └── service.yaml
└── oss.yaml                        # метаданные open-source лицензии для marketplace

Эта структура — расширение обычного Helm-чарта (M4 урок 1), а не полностью новая модель: templates/, openapi/values.yaml — прямые аналоги templates//values.yaml ванильного чарта, но дополненные package.yaml (метаданные уровня пакета, а не уровня чарта), hooks/ (Go-логика, недоступная в чистом Helm), openapi/config-values.yaml (контракт настроек пользователя, который затем транслируется в helm-values).

Что обязательно, что опционально

Сверка с реальными примерами

При разборе действующих Application-пакетов (девять реальных примеров Applications/* из репозиториев Deckhouse-marketplace) видно, что структура варьируется в деталях: не у всех пакетов есть hooks/ (только там, где нужна валидация настроек сверх возможностей JSON Schema), не все используют собственные images/ (многие Application-пакеты — просто обёртка над уже существующим публичным образом, как Redis/PostgreSQL-совместимые сервисы), но package.yaml + templates/ + openapi/values.yaml присутствуют всегда — это неизменное минимальное ядро любого Application-пакета.

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

• Путать структуру Application-пакета со структурой Module. У Module есть crds/, charts/helm_lib/, полноценный module.yaml с другим набором полей и другими требованиями (RBAC-манифесты, конверсии CRD) — у Application этого попросту нет и не может быть (M2 урок 1).
• Забыть openapi/values.yaml, оставив только config-values.yaml. Это разные контракты с разным назначением (M5 урок 3) — отсутствие values.yaml не позволит корректно валидировать полный набор helm-значений, включая внутренние (internal.*), не предназначенные для прямого управления пользователем.
• Помещать Dockerfile образов не в images/<name>/, а в произвольное место репозитория. Конвенция структуры пакета жёстко фиксирует расположение — линтер pkglint (линтер images) и сборочный пайплайн (d8 package build) ожидают именно эту структуру.

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

Практики в кластере в этом уроке нет — материал про структуру пакета как файловый артефакт, первая установка Application в кластер — в конце модуля M5, после завершения контракта настроек и шаблонов.

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

Umami — self-hosted веб-аналитика (альтернатива Google Analytics), Node.js-бэкенд + PostgreSQL для хранения данных — сквозной пример всего модуля M5: мы будем добавлять грань за гранью к одному и тому же пакету на каждом уроке.

1. Инициализируйте скелет пакета через d8 package bootstrap (детально команда разбирается в M5 уроке 9, здесь — только структура):

1
2
3

d8 package bootstrap application umami --hooks
cd umami
ls -la

2. Изучите сгенерированную структуру и сопоставьте с деревом файлов из теории урока:

1

find . -type f | sort

3. Создайте директорию для образа backend (Umami предоставляет готовый официальный образ, но для практики курса создадим свой минимальный build):

1
2

mkdir -p images/backend
echo 'FROM ghcr.io/umami-software/umami:postgresql-latest' > images/backend/Dockerfile

4. Инициализируйте Git-репозиторий пакета (обязателен для giterminism-принципов werf, унаследованных и здесь):

1
2
3

git init
git add .
git commit -m "chore: скелет Application-пакета umami"

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

1

d8 package bootstrap application <name> [--hooks] [--extended] [--werf] [-o <path>]

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

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

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

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

• Deckhouse — Разработка Application-пакета

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

• Разворачиваем приложение в кластере Kubernetes под управлением Deckhouse c помощью werf — Flant на Habr.
• Готовим Gitea со вкусом werf CI/CD в кластере Deckhouse. Часть 3 — Flant на Habr.
• Вышла werf 2.0: новый движок развёртывания Nelm — Flant на Habr.

Книги

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

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

• Предыдущий модуль: M4.06 — Секреты в шаблонах.
• Следующий урок: M5.02 — package.yaml: разбор каждого поля.

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