Перейти к содержимому
AggregaAggrega
Выберите язык: Русский
Эта страница переведена машинным способом. Читать оригинал на английском.

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/v1beta1
kind: MappingLibrary
metadata:
name: BaseMappings
version: 1.0.0
spec:
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 покрывает тот же сценарий.