MappingLibrary
MappingLibrary — це сутність каталогу, що містить фрагменти шаблонів Go для повторного використання. Recipes і FeatureRecipes, які мають спільний цілий документ valuesMapping: — значення, які кожен із кількох Recipes, що беруть як джерело той самий чарт, передає йому, — оголошують його один раз у бібліотеці й посилаються на нього під час використання за допомогою директиви 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 для значень чарта, не є коренем, який визначає цей контекст: запис, що його читає, зупиняє збірку й називає посилання.
Створення записів зіставлення
Кожен запис зіставлення — це фрагмент шаблону 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>, без хоста реєстру. Версію надає lockfile окремої сутності Release (ім’я + версія + дайджест вмісту); автор може задати необов’язкову нижню межу мінімальної версії у вигляді <Library>:<version>#/mappings/<name> (роздільником версії є :, як і у відображеннях recipe/feature та в закріпленні в lockfile), а фізичне розташування прив’язується під час розв’язання.
Композиція між бібліотеками
Запис MappingLibrary може бути переспрямуванням $import: на рівні кореня поля: перший токен його тіла — $import: <Library>#/mappings/<entry>, який замінює весь запис вмістом запису, на який посилається, — повторне використання за ідентичністю, а не шаблонізація на місці. Переспрямування розв’язується під час споживання (рендеринг Recipe), а не під час завантаження MappingLibrary, і рекурсивно — імпортований запис сам може бути переспрямуванням $import: на рівні кореня поля. $import: діє лише на весь запис; це не шаблонна функція всередині фрагмента. Щоб скомпонувати текст шаблону всередині одного фрагмента, використовуйте Go template 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 покриває той самий сценарій використання.