package.yaml — разбор каждого поля

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

M5 урок 1 — общая структура пакета, package.yaml как его манифест. Здесь — построчный разбор каждого поля.

Теория

Полный манифест package.yaml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

apiVersion: v1
type: "Application"
name: umami
descriptions:
  ru: "Umami — простая и приватная веб-аналитика с открытым исходным кодом"
  en: "Umami — simple, privacy-focused, open-source web analytics"
version: "v1.0.1" # инжектится автоматически при сборке — см. ниже
stage: "Preview"
category: "Analytics"
requirements:
  deckhouse:
    constraint: ">= 1.70"
  kubernetes:
    constraint: ">= 1.31"
  modules:
    mandatory:
      - name: cert-manager
        constraint: ">= 1.0.0"

apiVersion/type/name

apiVersion — версия схемы самого package.yaml (не версия пакета и не версия платформы). type: "Application" — явно фиксирует, что это именно Application-пакет (в отличие от module.yaml у Module, где такого поля просто нет в этом виде, т.к. сам файл называется иначе). name — машинное имя пакета (то же значение указывается как spec.packageName при установке, M5 урок 6) — официальная документация не фиксирует для него отдельный лимит символов. Лимит 24 символа, который важно держать в уме при проектировании пакета, относится не к name в package.yaml, а к имени устанавливаемого инстанса (metadata.name ресурса Application) и к имени ресурса внутри пакета: именно {{ .Application.Instance.Name }}-<component> (M5 урок 4), а не имя пакета, попадает в итоговое имя Pod’а — оба компонента ограничены 24 символами и вместе со служебным суффиксом Deployment (15 символов) укладываются в лимит имени Pod’а в Kubernetes (63 символа, M1 урок 1).

descriptions — обязательная локализация

1
2
3

descriptions:
  ru: "..."
  en: "..."

Оба языка (ru/en) — часть контракта marketplace-каталога Deckhouse (курс целиком на русском, но сам пакет для реального marketplace должен поддерживать оба языка интерфейса платформы).

version — инжектится CI из тега, не редактируется руками

Поле version в package.yaml в репозитории обычно оставляют пустым или с плейсхолдер-значением — реальное значение подставляется автоматически во время d8 package build --version <semver> (M5 урок 9), беря значение из Git-тега (или явного флага команды). Это тот же принцип детерминированности версии, что и content-based тегирование образов werf (M8 урок 3) — версия пакета должна однозначно соответствовать конкретному состоянию репозитория на момент сборки, а не редактироваться вручную (что легко приводит к рассинхрону между тем, что в файле, и тем, что реально собрано и опубликовано).

stage — матрица зрелости пакета

Поле stage сигнализирует пользователям каталога о степени зрелости/готовности пакета к продакшену (аналог release channels платформы из M2 урока 2, но на уровне отдельного пакета, а не всей платформы) — типичные значения включают Preview/General Availability и промежуточные градации, конкретный набор значений и правила перехода между ними определяются конвенцией marketplace (детально разбираем процесс публикации в M9).

category — классификация в каталоге

Свободная категория для фильтрации в UI marketplace (Analytics, Databases, Monitoring и подобные) — влияет только на UX обнаружения пакета пользователями, не на техническую работу самого пакета.

requirements — три типа зависимостей

1
2
3
4
5
6
7
8
9

requirements:
  deckhouse:
    constraint: ">= 1.70"
  kubernetes:
    constraint: ">= 1.31"
  modules:
    mandatory:
      - name: cert-manager
        constraint: ">= 1.0.0"

Три независимые категории требований:

1. deckhouse.constraint — минимальная (или диапазон) версия самой платформы Deckhouse, необходимая для корректной работы пакета (например, если пакет использует возможности CRD платформы, появившиеся в определённой версии).
2. kubernetes.constraint — версия самого Kubernetes. Здесь действует важная конвенция экосистемы Deckhouse: обязательство поддерживать как минимум две предыдущие минорные версии Kubernetes (аналог политики поддержки версий у самого upstream Kubernetes, N-2) — то есть при выходе новой минорной версии K8s пакет не должен немедленно требовать её, оставляя пользователям на предыдущих двух минорных версиях возможность установки.
3. modules.mandatory — список Module, обязательных для работы пакета, с собственными версионными ограничениями для каждого — это именно тот механизм, детально разбираемый в M6 уроке 1, который связывает Application с платформенными зависимостями.

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

• Редактировать version в package.yaml руками перед коммитом. Это поле управляется CI/сборочным процессом через Git-теги — ручное редактирование создаёт рассинхрон между заявленной и реально собранной версией.
• Путать лимит 24 символа для имени пакета (name в package.yaml) с лимитом на имя устанавливаемого инстанса. Реальное ограничение в 24 символа документировано для metadata.name ресурса Application (имя инстанса) и для имени ресурса внутри пакета — не для name самого пакета в манифесте; превышение этих лимитов может привести к невалидным именам ресурсов Kubernetes на этапе рендера шаблонов, если сумма (инстанс + ресурс + суффикс) превысит 63 символа лимита имени Pod’а.
• Указывать точную версию (= 1.70) вместо диапазона (>= 1.70) в requirements. Точное совпадение делает пакет хрупким к любому патч-обновлению платформы/модуля — конвенция экосистемы предполагает диапазоны с нижней границей, если не доказана конкретная несовместимость с более новыми версиями.

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

Практики в кластере в этом уроке нет — фокус на статическом манифесте.

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

1. Напишите полный package.yaml для Umami, добавив зависимость от managed-postgres (сходный сценарий с pgadmin разбирается детально в M6 уроке 2):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

apiVersion: v1
type: "Application"
name: umami
descriptions:
  ru: "Umami — простая и приватная веб-аналитика с открытым исходным кодом"
  en: "Umami — simple, privacy-focused, open-source web analytics"
version: "v0.0.0-placeholder"
stage: "Preview"
category: "Analytics"
requirements:
  deckhouse:
    constraint: ">= 1.70"
  kubernetes:
    constraint: ">= 1.31"
  modules:
    mandatory:
      - name: managed-postgres
        constraint: ">= 1.0.0"

2. Проверьте базовую валидность через линтер (полный список правил — M9, здесь только быстрая проверка синтаксиса):

1

d8 package verify

3. Посчитайте длину планируемого имени инстанса (например, umami-analytics, как в примере M5 урока 6) и убедитесь, что оно укладывается в реальный лимит 24 символа для metadata.name ресурса Application (лимит относится к имени инстанса, а не к name в package.yaml):

1

echo -n "umami-analytics" | wc -c

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

1

d8 package verify

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

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

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

• Deckhouse — Разработка Application-пакета
• Deckhouse — Зависимости Module

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

• Разворачиваем приложение в кластере 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.

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

• Предыдущий урок: M5.01 — Анатомия пакета Application целиком.
• Следующий урок: M5.03 — Контракт настроек: обе схемы.
• Зависимости от Module детально: M6 урок 1.

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