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 в разделе о вычислении шаблонов.
Целевой провайдер должен поддерживать синтез рабочих нагрузок. Recipe, который импортирует запись библиотеки, но привязан к провайдеру, не способному синтезировать Workload, явно останавливается во время рендеринга, а не выводит урезанную форму; каталог стандартной библиотеки объявляет workloadSchema у провайдеров, которые это поддерживают, в качестве документированного контракта.
Единый режим написания
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, у которой в spec.workloads есть ключ не в PascalCase, не проходит проверку оболочки при загрузке рабочего пространства. Эта проверка несёт реальную нагрузку: ключи записей рабочих нагрузок входят во фрагмент ссылки #/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 после разбора. О том, как workload: сочетается с другими видами входных данных сущности Recipe, см. Recipe, а о более общем различии $ref: / $import: — vocabulary/cross-document-ref.
Композиция между библиотеками
Запись WorkloadLibrary может быть перенаправлением $import: на уровне корня поля: первый токен её тела — $import: <Library>#/workloads/<entry>, что заменяет всю запись содержимым указанной записи — повторное использование по идентичности, а не шаблонизация на месте. Перенаправление разрешается во время потребления, а не при загрузке WorkloadLibrary, и разрешается рекурсивно, поэтому импортированная запись сама может быть перенаправлением $import: на уровне корня поля. Цепочка, замыкающаяся сама на себя, останавливается с диагностикой, указывающей цикл. $import: применяется только ко всей записи; это не шаблонная функция внутри фрагмента. Чтобы компоновать текст шаблона внутри одной записи, используйте define / template шаблонов Go.
# In library A — alias an entry to a shared entry in another library:spec: workloads: StandardServer: | $import: PlatformWorkloads#/workloads/MetricsServerНеизвестное имя библиотеки и имя записи, отсутствующее в библиотеке, которая успешно разрешается, сообщаются как разные диагностики, чтобы автор мог отличить отсутствующую зависимость от записи с опечаткой в имени.
Размещение по уровням
WorkloadLibrary относится к уровню 3 в модели документирования уровней сущностей — подключается по желанию в каталогах, которым нужно повторное использование содержимого рабочих нагрузок между сущностями Recipe. Каталоги, в которых Recipes несут собственное отличающееся содержимое рабочих нагрузок, поставляются без какой-либо сущности WorkloadLibrary; отметка уровня означает «продвинутое; пропустите, если не нужно» для навигации по документации, а не возможности. Компилятор обрабатывает WorkloadLibrary так же, как и другие виды сущностей каталога: та же проверка оболочки при загрузке рабочего пространства, тот же конвейер публикации в OCI во время выпуска, та же фиксация в lock-файле по имени, версии и дайджесту содержимого.
Этот вид библиотеки — один из набора на уровне каталога: SchemaLibrary содержит повторно используемые определения схем, MappingLibrary содержит повторно используемые фрагменты отображений, ArtifactLibrary содержит повторно используемые наборы артефактов, WorkloadLibrary содержит повторно используемое содержимое рабочих нагрузок. Каждая из них подключается независимо по желанию; каталоги поставляют те, которые им нужны, и никакие другие.
Чем WorkloadLibrary не является
Несколько распространённых заблуждений, которые стоит сразу развеять:
-
Не замена встроенному
workload:. Большинство сущностей Recipes содержат содержимое рабочей нагрузки, достаточно специфичное, чтобы размещать его встроенно, где автор читает его вместе с остальной частью сущности Recipe. Сущность WorkloadLibrary полезна, когда ОДНА И ТА ЖЕ форма рабочей нагрузки встречается во многих сущностях Recipes; для разового содержимого правильный выбор — встроенное описание. -
Не место для частичных фрагментов. Запись преобразуется в полный документ Workload. Документ values сущности Recipe относится к MappingLibrary, набор вспомогательных файлов — к ArtifactLibrary, а определения схем — к SchemaLibrary. Виды библиотек разделяются по типу содержимого, а не по шаблону повторного использования.
-
Не самостоятельно развёртываемая сущность. Запись библиотеки — это содержимое Workload, а содержимое Workload никогда не адресуется само по себе: оно существует как входные данные, которые потребляет сущность Recipe или FeatureRecipe. Публикация сущности WorkloadLibrary делает её записи импортируемыми, но не делает их развёртываемыми.
-
Не параметрическое повторное использование сверх механизмов Go template. Авторы, которым нужна параметрическая вариативность, используют механику Go template
{{ define }}+{{ template }}внутри записей библиотеки или контекст столпов, который предоставляет потребляющая сущность Recipe. Сама сущность библиотеки не содержит никаких механизмов параметрических помощников.