MappingLibrary
MappingLibrary — это сущность каталога, содержащая переиспользуемые фрагменты шаблонов Go. Сущности Recipes и FeatureRecipes, у которых общий целый документ valuesMapping: — значения, которые каждый из нескольких Recipes с одним и тем же chart в качестве источника передаёт этому chart, — объявляют его один раз в библиотеке и ссылаются на него в момент использования с помощью директивы valuesMapping: { $import: ... }. Сущность библиотеки относится к уровню 3: она подключается по желанию в каталогах, которым нужно переиспользование сопоставлений между сущностями Recipe. Каталоги без повторяющегося содержимого шаблонов поставляются вообще без MappingLibrary.
Роль MappingLibrary
Архитекторы платформы создают MappingLibraries, чтобы централизовать фрагменты шаблонов Go, повторяющиеся в Recipes и FeatureRecipes каталога. Библиотека — это не развёртываемая инструкция сборки, а пространство имён определений. Авторы сущностей Recipe и FeatureRecipe ссылаются на записи библиотеки директивой $import:, которая пишется один раз и используется везде, где разрешается импорт.
Разделение на «библиотеку» и «потребителя» сделано намеренно. Recipes кодируют инструкции сборки (source, valuesMapping, artifacts). FeatureRecipes кодируют поведенческие присоединения. MappingLibraries кодируют только фрагменты шаблонов — содержимое шаблонов Go, которое другие сущности используют во время рендеринга. Чёткое разделение трёх ролей позволяет каждому виду сущностей развиваться в собственном темпе; авторы, которым не нужно общее содержимое шаблонов, никогда не сталкиваются с сущностью библиотеки.
Оболочка сущности
Сущность MappingLibrary несёт стандартную оболочку каталога. apiVersion: aggrega.ai/v1beta1 и kind: MappingLibrary обозначают вид сущности; metadata.name — идентификатор в стиле PascalCase; metadata.version следует строгому семантическому версионированию. Содержимое библиотеки находится в spec.mappings — обязательном словаре, в котором должна быть объявлена хотя бы одна запись.
apiVersion: aggrega.ai/v1beta1kind: MappingLibrarymetadata: name: BaseMappings version: 1.0.0spec: mappings: SimpleValues: 'image: {{ .values.image }}' Replicas: 'replicas: {{ optional .infra "replicas" 1 }}'Запись вычисляется собственным движком шаблонов использующей её сущности Recipe, в контексте рендеринга этой сущности Recipe, поэтому она читает те же столпы в нижнем регистре, что и собственное valuesMapping: сущности Recipe, — .values, .infra, .context и остальные — и использует те же функции, например учитывающий наличие помощник optional для отсутствующего ключа. .Values, написание Helm для значений chart, не является корнем, который определяет этот контекст: запись, читающая его, останавливает сборку с указанием ссылки.
Написание записей сопоставления
Каждая запись сопоставления — это фрагмент шаблона Go, записанный как строка YAML. Фрагмент непрозрачен для оболочки сущности: компилятор сохраняет строку дословно при загрузке сущности MappingLibrary и разбирает её в момент использования, когда сущность Recipe или FeatureRecipe импортирует запись через valuesMapping: { $import: ... }. Импорт заменяет всё valuesMapping: сущности Recipe — отображение $import: не содержит других ключей, — поэтому запись является полным документом значений, а не фрагментом, вставляемым в него.
Короткие фрагменты умещаются в одну строку:
spec: mappings: AppName: 'fullnameOverride: "{{ .context.rendered_name }}"'Многострочные фрагменты используют литеральный скаляр YAML (|), чтобы переводы строк и отступы сохранялись при обработке туда и обратно:
spec: mappings: ProbeBlock: | readinessProbe: httpGet: path: /healthz port: {{ .values.port }} livenessProbe: httpGet: path: /healthz port: {{ .values.port }}Внутри фрагментов доступен весь словарь композиции шаблонов Go: {{ define "name" }}...{{ end }} объявляет переиспользуемые блоки в пределах одной библиотеки; {{ template "name" . }} вызывает их; конвейеры и функции поддерживаются в соответствии со стандартным пакетом Go text/template.
Единый режим написания
MappingLibrary поставляется с одним режимом написания: шаблоны Go. spec не принимает параллельной поверхности для написания, и на уровне библиотеки нет запасного выхода для выразительности.
Причина — единообразие поверхности потребления. Recipes и FeatureRecipes целиком построены на шаблонах Go, и их собственное содержимое вычисляется тем же движком шаблонов Go, который разрешает импортированную запись, поэтому запись читается в точности так же, как собственный текст сущности Recipe, и авторы изучают одну модель вычисления. Словарь композиции шаблонов Go — {{ define }} и {{ template }} внутри библиотеки и директива $import: в момент использования — даёт переиспользуемые блоки и параметризованный вызов, которые нужны библиотеке.
Авторы, которым нужна выразительность сверх того, что предлагает словарь композиции шаблонов Go, выполняют композицию на более высоком уровне — с помощью сущностей Components или Features, которые оборачивают библиотечные записи собственными содержательными вариациями, — а не переходят к параллельному языку написания внутри самой MappingLibrary.
Соглашения об именовании
Имена библиотек и ключи записей сопоставления записываются в PascalCase. JSON Schema оболочки сущности обеспечивает соблюдение этого соглашения в двух местах с помощью ограничений по шаблону:
metadata.nameсоответствует^[A-Z][A-Za-z0-9]*$.- Ключи словаря
spec.mappingsсоответствуют тому же шаблону черезpropertyNames.
Сущность MappingLibrary с ключом не в PascalCase в spec.mappings не проходит проверку оболочки при загрузке рабочего пространства. Эта проверка несёт реальную нагрузку: ключи записей сопоставления входят во фрагмент ссылки #/mappings/<name>; ключи не в PascalCase распространились бы на каждого потребителя, импортирующего запись.
Единообразие именования сохраняет фрагмент #/mappings/<name> удобочитаемым: #/mappings/ProbeBlock понятен с первого взгляда.
Ссылки на записи библиотеки
Авторы сущностей Recipe и FeatureRecipe ссылаются на запись сопоставления внутри блока valuesMapping: { $import: ... } по её идентичности в виде голого имени:
# Inside a Recipe's valuesMapping block:spec: valuesMapping: $import: "BaseMappings#/mappings/ProbeBlock"Фрагмент #/mappings/<name> выбирает запись и отличает ссылку на сопоставление от ссылки #/schemas/<name> сущности SchemaLibrary. Ссылка использует ту же модель идентичности по голому имени, что и $ref: в SchemaLibrary, — <Library>#/mappings/<name>, без хоста реестра. Версию предоставляет lock-файл конкретной сущности Release (имя + версия + дайджест содержимого); автор может указать необязательную нижнюю границу версии в виде <Library>:<version>#/mappings/<name> (разделитель версии — :, как в сопоставлениях рецептов и функций и в закреплении в lock-файле), а физическое расположение привязывается во время разрешения.
Композиция между библиотеками
Запись MappingLibrary может быть перенаправлением $import: на уровне корня поля: первый токен её тела — $import: <Library>#/mappings/<entry>, что заменяет всю запись содержимым указанной записи: это повторное использование по идентичности, а не шаблонизация на месте. Перенаправление разрешается в момент потребления (при рендеринге сущности Recipe), а не при загрузке MappingLibrary, причём рекурсивно: импортируемая запись сама может быть перенаправлением $import: на уровне корня поля. $import: действует только на запись целиком; это не шаблонная функция внутри фрагмента. Чтобы скомпоновать текст шаблона внутри одного фрагмента, используйте Go-шаблоны define / template.
# In library A — alias an entry to a shared entry in another library:spec: mappings: StandardProbe: | $import: MonitoringLibrary#/mappings/PrometheusAnnotationsБиблиотеки могут свободно ссылаться друг на друга. Цепочка, замыкающаяся на себя, останавливается при рендеринге использующей её сущности Recipe с диагностикой, называющей каждый шаг цикла.
Размещение по уровням
MappingLibrary относится к уровню 3 в модели документации по уровням сущностей — это опция для каталогов, которым нужно повторное использование сопоставлений между сущностями Recipe. Каталоги без повторяющегося шаблонного содержимого обходятся без сущности MappingLibrary; отметка уровня означает «продвинутая тема; пропустите, если не нужна» для навигации по документации, а не уровень возможностей. Компилятор обрабатывает MappingLibrary единообразно с другими видами сущностей каталога: та же проверка оболочки при загрузке рабочего пространства, тот же конвейер публикации в OCI во время выпуска.
На уровне каталога этот вид библиотеки естественно сочетается с SchemaLibrary: SchemaLibrary содержит переиспользуемые определения схем, а MappingLibrary — переиспользуемые фрагменты шаблонов. Каталоги, которым нужны обе, поставляют обе; каталоги, которым не нужна ни одна, не поставляют ни одной.
Чем MappingLibrary не является
Несколько распространённых заблуждений, которые стоит сразу развеять:
-
Не замена встроенному
valuesMapping:. Большинство Recipes содержат простое содержимоеvaluesMapping:, которое выгодно писать встроенно: Recipe остаётся самодостаточным, а автор читает содержимое сопоставления рядом с остальной частью Recipe. MappingLibrary полезна, когда ОДИН И ТОТ ЖЕ фрагмент встречается во многих Recipes; для разовых сопоставлений правильный выбор — встроенное написание. -
Не место для содержимого схем. Определения схем (JSON Schema 2020-12) относятся к SchemaLibrary; фрагменты шаблонов — сюда. Виды библиотек разделяются по типу содержимого, а не по шаблону повторного использования.
-
Не параметрическое повторное использование сверх механизмов шаблонов Go. Авторы, которым нужна параметрическая вариативность, используют механику шаблонов Go
{{ define }}+{{ template arg }}внутри записей библиотеки или компонуют сущности Components / Features, которые оборачивают записи библиотеки собственной вариативностью. Сама сущность библиотеки не содержит механизма параметрических вспомогательных функций (нет блокаtemplates, аналогичного параметрическим вспомогательным функциямspec.templatesсущности SchemaLibrary); словарь композиции шаблонов Go покрывает тот же сценарий.