WorkloadLibrary
WorkloadLibrary — це сутність каталогу, що містить багаторазово використовувані фрагменти шаблонів Workload. Сутності Recipes і FeatureRecipes, які розгортають однакову форму робочого навантаження — сервер, що надає метрики, пакетне завдання, пару sidecar-контейнерів, — оголошують цю форму один раз у бібліотеці й посилаються на неї під час використання через директиву workload: { $import: ... }. Сутність бібліотеки належить до рівня 3: вона необов’язкова й призначена для каталогів, яким потрібне повторне використання робочих навантажень між сутностями Recipe. Каталоги, у яких кожна сутність Recipes має власну окрему форму робочого навантаження, постачаються без жодної сутності WorkloadLibrary.
Роль сутності WorkloadLibrary
Архітектори платформи створюють сутності WorkloadLibraries, щоб централізувати вміст Workload, який повторюється в сутностях Recipes і FeatureRecipes каталогу. Бібліотека — це не інструкція збирання, яку можна розгорнути; це простір імен визначень. Автори сутностей Recipe і FeatureRecipe посилаються на записи бібліотеки директивою $import:, яку пишуть один раз і використовують усюди, де розв’язується імпорт.
Розподіл між «бібліотекою» і «споживачем» навмисний. Сутності Recipes кодують інструкції збирання (source, valuesMapping, artifacts). Сутності FeatureRecipes кодують поведінкові приєднання. Сутності WorkloadLibraries кодують лише вміст Workload — форму робочого навантаження, яку провайдер синтезує в нативні для провайдера маніфести. Розмежування трьох ролей дає змогу кожному виду сутностей розвиватися у власному темпі; автори, яким не потрібен спільний вміст робочих навантажень, ніколи не стикаються із сутністю бібліотеки.
Оболонка сутності
Сутність WorkloadLibrary має стандартну оболонку каталогу. apiVersion: aggrega.ai/v1beta1 і kind: WorkloadLibrary позначають тип сутності; metadata.name — це ідентифікатор у стилі PascalCase; metadata.version дотримується суворого семантичного версіонування. Обидва поля обов’язкові. metadata.description, metadata.labels і metadata.annotations необов’язкові — мітки й анотації є непрозорими метаданими, які оголошує автор і які передаються для того, щоб за ними могло зіставляти все, що читає бібліотеку, і компілятор не інтерпретує їхніх значень. Вміст бібліотеки розміщено в spec.workloads — обов’язковій мапі, яка має оголошувати принаймні один запис.
Оболонка закрита на всіх трьох рівнях — корінь документа, metadata і spec відхиляють ключі, яких не оголошує схема.
apiVersion: aggrega.ai/v1beta1kind: WorkloadLibrarymetadata: name: BaseWorkloads version: 1.0.0spec: workloads: SimpleServer: | apiVersion: aggrega.ai/v1beta1 kind: Workload replicas: {{ optional .infra `replicas` 2 }} containers: app: image: "{{ .values.image }}" ports: web: {{ optional .values `port` 8080 }} services: http: type: ClusterIP ports: web: {{ optional .values `port` 8080 }}Створення записів Workload
Кожен запис — це фрагмент шаблону Go, записаний як рядок YAML. Результатом рендерингу запису є цілий документ Workload — він містить власні apiVersion: aggrega.ai/v1beta1 і kind: Workload, — оскільки поле workload: сутності Recipe приймає один повний Workload, а не фрагмент, вставлений в інший документ, і імпорт заміняє все поле. Запис MappingLibrary так само є цілим: його імпорт заміняє все valuesMapping: сутності Recipe.
Тіло непрозоре для оболонки сутності. Компілятор зберігає рядок дослівно під час завантаження WorkloadLibrary і не розбирає там шаблон; парсер шаблонів запускається під час споживання, коли сутність Recipe або FeatureRecipe імпортує запис. Дослівне збереження фрагмента зберігає точність авторського тексту для повторного виведення, а також означає, що помилка шаблону виявляється там, де запис споживається і відомий його контекст опор, а не в бібліотеці.
Оскільки документ Workload багаторядковий, записи використовують літеральний скаляр YAML (|), щоб символи нового рядка й відступи зберігалися при повному циклі обробки:
spec: workloads: BatchJob: | apiVersion: aggrega.ai/v1beta1 kind: Workload form: task containers: worker: image: "{{ .values.image }}" command: ["{{ .values.entrypoint }}"]Значення запису має бути рядковим скаляром. Відображення або послідовність на місці тіла відхиляються — тіло запису є текстом шаблону, а не структурованим YAML, який обходить компілятор.
Усередині запису доступний повний словник композиції шаблонів Go: {{ define "name" }}...{{ end }} оголошує повторно використовувані блоки в межах однієї бібліотеки, {{ template "name" . }} викликає їх, а конвеєри та функції відповідають стандартному пакету Go text/template. Контекст опор, який може читати запис, — .values, .infra, .locals, .context, .features — той самий, що читає будь-який шаблон Workload, і він описаний на сторінці Workload у розділі про обчислення шаблонів.
Цільовий provider має підтримувати синтез робочих навантажень. Сутність Recipe, яка імпортує запис бібліотеки, але прив’язана до provider, що не може синтезувати Workload, явно зупиняється під час рендерингу, а не виводить погіршену форму; каталог стандартної бібліотеки оголошує workloadSchema для provider, які це підтримують, як задокументований контракт.
Єдиний режим створення
WorkloadLibrary постачається з одним режимом створення: шаблонами Go. spec не приймає жодної паралельної поверхні створення і жодного запасного виходу для виразності на рівні бібліотеки.
Причина — однорідність поверхні споживання. Recipes і FeatureRecipes повністю побудовані на шаблонах Go, і їхній власний вміст обчислюється тим самим рушієм шаблонів Go, що й розв’язує імпортований фрагмент. Паралельна поверхня створення змусила б авторів перемикатися між моделями обчислення в межах рендерингу однієї сутності Recipe — одна модель для власного вмісту сутності Recipe, інша для будь-якого імпортованого запису бібліотеки. Однорідна поверхня означає, що автори вивчають одну модель обчислення і застосовують її всюди.
Автори, яким потрібна виразність понад словник композиції шаблонів Go, виконують композицію на вищому рівні — через Components або Features, що обгортають записи бібліотеки власними змістовними варіаціями, — а не переходять до другої мови створення всередині бібліотеки.
Домовленості щодо іменування
Імена бібліотек і ключі записів робочих навантажень записуються в PascalCase. JSON Schema оболонки сутності примусово застосовує цю домовленість у двох місцях через обмеження за шаблоном:
metadata.nameвідповідає^[A-Z][A-Za-z0-9]*$.- Ключі мапи
spec.workloadsвідповідають тому самому шаблону черезpropertyNames.
Сутність WorkloadLibrary з ключем не в PascalCase у spec.workloads не проходить валідацію оболонки під час завантаження робочого простору. Ця перевірка має суттєве значення: ключі записів робочих навантажень з’являються у фрагменті посилання #/workloads/<name>, тож ключ не в PascalCase поширився б через кожного споживача, що імпортує запис.
Одноманітність іменування зберігає фрагмент #/workloads/<name> зрозумілим: #/workloads/BatchJob читається з першого погляду.
Посилання на записи бібліотеки
Автори сутностей Recipe та FeatureRecipe посилаються на запис робочого навантаження всередині блоку workload: { $import: ... } за його ідентичністю у вигляді простого імені:
# Inside a Recipe's spec:spec: workload: $import: "BaseWorkloads#/workloads/SimpleServer"Фрагмент #/workloads/<name> вибирає запис і відрізняє посилання на робоче навантаження від #/mappings/<name> сутності MappingLibrary та #/schemas/<name> сутності SchemaLibrary. Посилання не містить хоста реєстру; форма з хостом oci://… відхиляється як схемою конверта, так і в місці використання, тож фізичне розташування реєстру ніколи не потрапляє до авторського коду. Автор може вказати необов’язкову нижню межу версії як <Library>:<version>#/workloads/<name> — роздільником версії є :, як у зіставленнях recipe/feature та в закріпленні lock-файлу, а запис @ натомість відхиляється з діагностикою, що називає виправлене посилання. Розв’язану версію надає lock-файл кожної сутності Release, який закріплює кожну використану бібліотеку за іменем, версією та дайджестом вмісту; фізичне розташування прив’язується під час розв’язання.
Те саме поле workload: приймає ще дві форми — вбудований рядок шаблону Go та $import: локального шляху до файлу відносно каталогу сутності Recipe. Три форми розрізняються за формою вмісту, і всі три дають однакову сутність Workload після розбору. Див. Recipe, щоб дізнатися, як workload: поєднується з іншими видами вхідних даних сутності Recipe, та vocabulary/cross-document-ref щодо ширшої відмінності між $ref: і $import:.
Композиція між бібліотеками
Запис WorkloadLibrary може бути переспрямуванням $import: на рівні кореня поля: перший токен його тіла — $import: <Library>#/workloads/<entry>, що замінює весь запис вмістом запису, на який посилається, — повторне використання за ідентичністю, а не шаблонізація на місці. Переспрямування розв’язується під час споживання, а не під час завантаження WorkloadLibrary, і розв’язується рекурсивно, тож імпортований запис сам може бути переспрямуванням $import: на рівні кореня поля. Ланцюжок, що замикається сам на себе, зупиняється з діагностикою, яка називає цикл. $import: діє лише для цілого запису; це не шаблонна функція всередині фрагмента. Щоб компонувати текст шаблону в межах одного запису, використовуйте Go template define / template.
# In library A — alias an entry to a shared entry in another library:spec: workloads: StandardServer: | $import: PlatformWorkloads#/workloads/MetricsServerНевідома назва бібліотеки та назва запису, відсутня в бібліотеці, яка таки розв’язується, повідомляються як окремі діагностики, тож автор може відрізнити відсутню залежність від запису з помилкою в назві.
Розміщення в рівнях
WorkloadLibrary належить до рівня 3 у моделі документації за рівнями сутностей — це опція для каталогів, яким потрібне повторне використання вмісту workload між сутностями Recipe. Каталоги, чиї Recipes містять власний окремий вміст workload, постачаються без жодної сутності WorkloadLibrary; позначка рівня сигналізує «розширене; пропустіть, якщо не потрібно» для навігації документацією, а не можливості. Компілятор обробляє WorkloadLibrary так само, як інші види сутностей каталогу: та сама валідація обгортки під час завантаження робочого простору, той самий конвеєр публікації в OCI під час випуску, те саме закріплення в lock-файлі за назвою, версією та дайджестом вмісту.
Цей вид бібліотеки — один із набору на рівні каталогу: SchemaLibrary містить визначення схем для повторного використання, MappingLibrary містить фрагменти відображень для повторного використання, ArtifactLibrary містить набори артефактів для повторного використання, WorkloadLibrary містить вміст workload для повторного використання. Кожна з них підключається незалежно; каталоги постачають ті, що їм потрібні, і жодних інших.
Чим WorkloadLibrary не є
Кілька поширених хибних уявлень, яким варто запобігти:
-
Не заміна вбудованого
workload:. Більшість Recipes містять вміст робочого навантаження, достатньо специфічний, щоб розміщуватися вбудовано, де автор читає його разом з рештою сутності Recipe. WorkloadLibrary допомагає, коли ТА САМА форма робочого навантаження з’являється в багатьох Recipes; для одноразового вмісту правильний вибір — вбудоване написання. -
Не місце для часткових фрагментів. Запис рендериться в повний документ Workload. Документ values сутності Recipe належить до MappingLibrary, набір допоміжних файлів — до ArtifactLibrary, а визначення схем — до SchemaLibrary. Види бібліотек розділяються за типом вмісту, а не за шаблоном повторного використання.
-
Не сутність, яку можна розгорнути незалежно. Запис бібліотеки — це вміст Workload, а вміст Workload ніколи не адресується сам по собі: він існує як вхідні дані, які споживає сутність Recipe або FeatureRecipe. Публікація WorkloadLibrary робить її записи доступними для імпорту; вона не робить їх доступними для розгортання.
-
Не параметричне повторне використання поза механізмами Go template. Автори, яким потрібна параметрична варіативність, використовують механізми Go template
{{ define }}+{{ template }}усередині записів бібліотеки або контекст стовпа, який надає сутність Recipe, що її споживає. Сама сутність бібліотеки не містить жодних механізмів параметричних допоміжних засобів.