Workload
Архитектурная роль вида Workload — зачем он существует, как он сочетается с двумя другими видами входных данных Recipe (sourced и artifacts), а также полная поверхность схемы — описана в ../../architecture/16-recipe-input-composition.md. На этой странице рассматривается поверхность написания Workload: как автор Recipe пишет содержимое Workload, что и когда вычисляет компилятор, как поля Workload взаимодействуют с featuresSchema сущности Component и какие опоры могут читать шаблоны внутри Workload.
Место написания
Содержимое Workload пишется встроенно или в отдельном файле внутри Recipe или FeatureRecipe (см. FeatureRecipe). Recipe объявляет не более одного workload:; FeatureRecipe аналогично объявляет не более одного собственного:
# Inline (block scalar)spec: workload: | apiVersion: aggrega.ai/v1beta1 kind: Workload # ...или
# File-loaded via $import: (path relative to the Recipe directory)spec: workload: $import: ./workload/workload.yamlОбе формы дают один и тот же объект Workload после разбора; выбор определяется лишь удобством написания. Третья форма импортирует Workload, общий для нескольких Recipes, из записи WorkloadLibrary по её идентификатору в виде голого имени: $import: <Library>#/workloads/<entry>. Согласно единому словарю импорта файлов, $import: принимает один источник — более общее различие между $ref: и $import: описано в ../vocabulary/cross-document-ref.md.
YAML сущности Workload не пишется как самостоятельная сущность каталога. Каталога catalog/workload/ не существует; грамматика Workload существует только как содержимое, которое использует Recipe или FeatureRecipe, — написанное встроенно, в файле рядом с ним или в записи WorkloadLibrary. Объявления apiVersion и kind внутри YAML (apiVersion: aggrega.ai/v1beta1, kind: Workload) идентифицируют встроенное содержимое для проверки по схеме; они не делают Workload независимо адресуемым.
Вычисление шаблонов
Содержимое Workload перед разбором обрабатывается как Go-шаблон с полным контекстом столпов. Когда автор Recipe пишет шаблон наподобие следующего…
replicas: {{ optional .infra `replicas` 1 }}…компилятор вычисляет этот шаблон на подпроходе Workload при рендеринге, разрешает .infra.replicas по полезной нагрузке infra узла и разбирает полученный YAML как документ Workload. Значения locals сущности Recipe разрешаются до вычисления Workload, поэтому шаблон Workload читает их, уже разрешёнными, в .locals.
Доступ к столпам внутри шаблонов Workload:
.values— когнитивная полезная нагрузка, написанная разработчиком и объявленная в Aggregate..infra— физические размеры, заданные Ops и объявленные в Release..parameters— уже подставлены при разрешении; видны через.values/.infraвезде, где разработчик или Ops сослались на.parameters.<name>в своих описаниях..locals— приватное состояние Recipe, разрешённое в преамбуле locals и опубликованное при разрешении источников; доступно в каждом месте вычисления шаблонов Workload..context.instance_id— уплощённый идентификатор экземпляра узла; префикс имён ресурсов, которые выдаёт провайдер, называющий синтезированные ресурсы по идентичности..context.rendered_name— имя, которое синтезированным ресурсам даёт провайдер, сам выводящий для них имя, например имя релиза helm; присутствует, только если провайдер его сообщает. См. ../templates/rendered-resource-names.md..context.inject— канал внедрения после перехвата, уже переписанный любымinjectMappingсущности FeatureRecipe на этапе сопоставления внедрения..context.uses— обогащённые рёбра топологии, исходящие из этого узла; каждое несёт разрешённыеprovides,labelsи каскадные аннотации цели, а в.context.uses.<alias>.features.<slot>— вложения, которые несёт это соединение..features— собственные вложения узла, каждое со своимиtype,values,infraи разрешённымиprovides. Вложение, названное по слоту, который Component объявляет вfeaturesSchema, заполняет этот слот (см. ниже). Вложение, которое несёт соединение, сюда не входит; оно читается через своё соединение, и Workload доставляет его, называя соединение (см. Доставка учётных данных, которые несёт соединение).
Полный контракт доступа к столпам см. в ../vocabulary/data-pillars.md, а место вычисления Workload в последовательности вычисления шаблонов — в ../templates/expansion-matrix.md.
Основы семантики полей
Полная схема Workload приведена в ../../architecture/16-recipe-input-composition.md в разделе «The Workload Kind». Описанные ниже соглашения об авторинге охватывают решения на уровне полей, которые принимает автор Recipe.
form
form объявляет абстрактную форму контроллера рабочей нагрузки — тип её жизненного цикла во время выполнения, независимо от целевой платформы. Это одна строка, одно из значений stateless, stateful, daemon, scheduled, task, reference; если поле опущено, используется stateless:
stateless— взаимозаменяемые горизонтально масштабируемые реплики без индивидуальной идентичности (обычный долгоживущий сервис).stateful— реплики со стабильной идентичностью и собственным хранилищем у каждой. ТомpersistentTemplateявляется спутником этой формы.daemon— по одному экземпляру на каждый подходящий хост.scheduled— повторяющиеся запуски по времени.task— однократный запуск до завершения.reference— без собственных контейнеров: компонент представляет внешнюю конечную точку, заданную какendpoint(хост или URL, передаётся в том виде, в каком написан) и необязательныйport. Провайдер helm выводит его как Service типаExternalName; провайдер compose для него ничего не выводит.
Сама форма не содержит платформенных типов ресурсов. Каждый целевой провайдер, синтезирующий Workload, отображает форму на собственную нативную структуру:
form | Kubernetes (helm) | Compose |
|---|---|---|
stateless | Deployment | service (без постоянного тома) |
stateful | StatefulSet | service + именованный том |
daemon | DaemonSet | останавливает сборку |
scheduled | CronJob | останавливает сборку |
task | Job | останавливает сборку |
Провайдеры terraform и cloudformation рендерят Recipes с источником и Recipes только с артефактами и не синтезируют Workload: Recipe, объявляющий workload: и привязанный к любому из них, останавливает сборку с указанием видов входных данных, которые поддерживает провайдер.
Если у целевого провайдера нет чистого отображения для формы, сборка явно останавливается, а не деградирует рабочую нагрузку до структуры, искажающей намерение: выбор формы, которую целевая граница не может выразить, — это ошибка времени сборки, а не тихое понижение. Провайдер compose останавливается на daemon, scheduled и task. Провайдер helm генерирует CronJob для scheduled (см. schedule ниже) и останавливается, только если расписание отсутствует или некорректно.
apiVersion: aggrega.ai/v1beta1kind: Workloadform: statefulcontainers: db: { image: "postgres:16", ports: { db: 5432 } }volumes: data: persistentTemplate: size: "20Gi"services: headless: type: Headless ports: db: 5432schedule
schedule — это cron-расписание для рабочей нагрузки form: scheduled, сопутствующее поле, задающее повторяющейся форме её периодичность. Это одна строка в одном каноническом формате:
- стандартное 5-польное выражение crontab — минута, час, день месяца, месяц, день недели (например,
0 0 * * *— ежедневно в полночь,*/15 * * * *— каждые пятнадцать минут), или - один из макросов
@hourly,@daily,@weekly,@monthly,@yearly.
schedule обязательно при form: scheduled и имеет смысл только в этом случае. Рабочая нагрузка form: scheduled без расписания, расписание, которое не является ни 5-польным выражением, ни распознанным макросом (6-польное выражение с секундами в начале, нераспознанный @-токен или поле с недопустимыми символами), а также поле schedule, заданное для любой другой формы, приводят к остановке сборки с указанием способа исправления. Провайдер helm передаёт значение дословно в spec.schedule генерируемого CronJob.
apiVersion: aggrega.ai/v1beta1kind: Workloadform: scheduledschedule: "0 2 * * *" # daily at 02:00containers: report: image: "reporter:1.0" command: ["/report"]suspend
suspend приостанавливает периодическое расписание рабочей нагрузки form: scheduled. Это логическое значение, по умолчанию false. При suspend: true ресурс расписания по-прежнему рендерится вместе со своим schedule, но ни один запуск по этому расписанию не начинается, пока оно не будет возобновлено, а запуск из ресурса по-прежнему можно начать вручную. Такая форма подходит задаче, которая должна выполняться только по чьему-либо запросу.
Провайдер helm выводит это поле как spec.suspend: true объекта CronJob. В Kubernetes команда kubectl create job <name> --from=cronjob/<cronjob> запускает выполнение из приостановленного CronJob, а расписание возобновляется, как только spec.suspend снова становится false. suspend: false рендерится точно так же, как опущенный suspend, поэтому поле не меняет вывод, пока не задано. У провайдера compose нет формы для расписания, и он останавливает сборку на любой рабочей нагрузке form: scheduled, приостановленной или нет.
suspend: true в любой другой форме останавливает сборку с указанием способа исправления: ни у одной другой формы нет расписания, которое можно было бы приостановить.
apiVersion: aggrega.ai/v1beta1kind: Workloadform: scheduledschedule: "0 2 * * *" # documents when it would run; nothing starts it while suspendedsuspend: truecontainers: report: image: "reporter:1.0" command: ["/report"]replicas
Одно целое число — количество реплик рабочей нагрузки. Если поле опущено, используется 1. Чтобы задавать реплики из размеров, объявленных Ops, используйте шаблонное выражение:
replicas: {{ optional .infra `replicas` 1 }}containers и initContainers
containers — упорядоченное отображение с ключами по имени контейнера. Контейнер 0 (первый ключ отображения) важен для порядка в pod-spec в выводе Kubernetes и для семантики контейнера по умолчанию. initContainers — упорядоченный список init-контейнеров, каждый из которых содержит name, image и ту же структуру авторинга переменных, секретов и монтирований томов, что и основные контейнеры.
name в записи initContainers необязательно. Запись без него получает имя init-<index>, где индекс — позиция записи в списке, начиная с 0. Поскольку имя идентифицирует контейнер в отрендеренном выводе и в любой диагностике, которая на него ссылается, запись, на которую стоит ссылаться, стоит назвать явно.
Сохранение авторского порядка — несущий контракт модели Workload: компилятор при каждой сборке выводит containers, volumes, services, контейнерные ports, контейнерные variables и контейнерные attachments каждый в том порядке, в котором их объявил автор Recipe. Авторы Recipe могут полагаться на упорядоченную форму: когда то, что происходит во время выполнения, зависит от порядка (запуск sidecar-контейнеров, цепочки $(VAR) в переменных окружения, volumeMounts, ссылающиеся на ранее объявленные тома), авторский порядок И ЕСТЬ порядок выполнения внутри каждой из этих коллекций. Окружение контейнера объединяет две из них, и между ними синтезирующие провайдеры записывают сначала записи, читаемые из вложений (attachments, доставляемые as: env), а после них — обычные variables, каждый вид в авторском порядке; поэтому на целевой платформе Kubernetes переменная может ссылаться, как $(NAME), на любую переменную своего контейнера, прочитанную из вложения, и на любую переменную, объявленную до неё (см. порядок окружения в провайдере helm). Контейнер, который задаёт одно имя и как запись variables, и как запись attachments, доставляемую as: env, останавливает сборку, потому что лишь этот порядок решал бы, какое из двух значений увидит процесс (см. A container gives one environment variable two values (Контейнер задаёт одной переменной окружения два значения)).
Авторинг полей контейнера следует этим соглашениям:
imageобычно является шаблонным выражением, ссылающимся на.values.image(образ, выбранный разработчиком), с необязательными переопределениями.infra.*для префикса реестра, зависящего от окружения.variables— простая map вида строка → строка для переменных окружения. Эта map объединяет два различных источника данных через выражения шаблонов Go: литералы пиллара разработчика (записи, выражения шаблонов которых читают.values/.infra/.locals, — данные, происходящие из пилларов Component) и данные межкомпонентного канала (записи, выражения шаблонов которых читают.context.inject.env.<KEY>, — данные, происходящие изprovides:другого компонента и передаваемые через канал топологии). Оба источника попадают в одну и ту же mapvariables; автор выбирает источник для каждой записи в зависимости от того, является ли значение локальным для компонента или получено из другого компонента. Типичные шаблоны:LOG_LEVEL: "{{ .values.log_level }}"— пиллар разработчика (локально для компонента);DB_HOST: "{{ .context.inject.env.DB_HOST }}"— межкомпонентный канал (значение происходит изprovides.hostцелевого компонента и передаётся через объявлениеuses[].inject.env.DB_HOSTвызывающего). Обе формы компилируются в единый список Kubernetesenv:в отрендеренном Deployment; двойная семантика источников существует только на этапе написания.attachmentsссылается на слоты, объявленные вfeaturesSchemaсущности Component, или, через имя соединения, на слот, объявленный сокетом этого соединения (см. раздел об интеграции ниже).ports— отображение именованных портов (web: 8080,admin: 9901); имена портов соответствуют именам портов в области контейнера, и на них ссылаются черезservices.<service>.ports.<portname>. Порт с транспортом, отличным от транспорта цели по умолчанию, задаётся в развёрнутой форме — см. Транспортные протоколы портов ниже.volumeMountsссылается по имени на тома, объявленные в разделеvolumes:сущности Workload.resourcesобъявляетrequestsиlimitsконтейнера — количестваcpuиmemoryи, при необходимости, ключи расширенных ресурсов для GPU и других устройств (см. Рабочие нагрузки с GPU и устройствами ниже).healthиспользует форму намерения (http: /path,tcp: <port>,exec: [cmd, ...]) — см. раздел о проверках работоспособности ниже.
volumes
Каждый том имеет ровно один тип: ephemeral, configmap, secret, persistent или persistentTemplate. Внутри одного объявления тома типы взаимоисключающие; у каждого типа свои обязательные поля:
volumes: app-config: configmap: source: "{{ .locals.app_cm }}" data: persistent: size: "10Gi" class: "gp3" cache: ephemeral: sizeLimit: "1Gi"persistentTemplate создаёт отдельный PVC для каждой реплики при трансляции в форму StatefulSet; при трансляции в compose он деградирует до одного общего именованного тома, и вместе со сборкой выдаётся предупреждение. Сам сгенерированный файл не содержит никакой отметки о деградации — он побайтово совпадает с тем, каким был бы без предупреждения.
Трансляция по провайдерам. Каждый провайдер транслирует пять вариантов томов в свою нативную форму:
| Вариант | Helm / helm-chart (K8s) | Compose | Что теряется |
|---|---|---|---|
ephemeral | emptyDir: { sizeLimit } | запись tmpfs: уровня сервиса с путём монтирования (в памяти) | tmpfs в Compose хранится в RAM; emptyDir в helm по умолчанию хранится на диске узла — семантическое расхождение в носителе данных. sizeLimit никак не попадает в вывод compose: выдаваемая запись — только путь монтирования. Указанный автором sizeLimit вызывает предупреждение unsupported-field с его именем, которое выдаётся вместе со сборкой, а не записывается в сгенерированный файл. |
configmap | Ссылка на том ConfigMap (использует ресурс ConfigMap, выдаваемый секцией artifacts: сущности Recipe или сущностью Feature) | Ссылка configs: уровня сервиса с именем configmap, смонтированная по пути монтирования тома; соответствующая запись configs: верхнего уровня берётся из секции artifacts: сущности Recipe | Обе цели ссылаются на configmap по имени и ни одна не читает его содержимое, поэтому форма описания симметрична. Compose теряет семантику ConfigMap в K8s с обновлением при выкатке: конфигурация compose зафиксирована на содержимом, выданном сборкой. Ссылка, которую не разрешает ни одна запись верхнего уровня, останавливает сборку, а не порождает монтирование, которое во время выполнения оказалось бы висячим. |
secret | Ссылка на том Secret (использует Secret, названный во вложении с учётными данными, — выдаваемый его сущностью FeatureRecipe или уже существующий) | env_file: для секретов в форме переменных окружения или файл секрета, смонтированный через bind, для секретов в форме пути | В Compose нет полноценной семантики Secret из Kubernetes. Секрет в форме пути намеренно не идёт путём configs: варианта configmap: встроенная запись конфигурации записала бы значение секрета в выдаваемый файл compose открытым текстом, а компилятор никогда не разрешает секрет в открытый текст. Источник bind — путь, который оператор делает доступным на хосте compose, вне какого-либо жизненного цикла CRD для получения из хранилища. |
persistent | Ресурс PVC + volume.persistentVolumeClaim | Именованный том | Именованные тома Compose — плоская абстракция на стороне хоста; PVC в helm поддерживает объявление класса хранилища, режима доступа и ёмкости, которые compose игнорирует. |
persistentTemplate | StatefulSet.volumeClaimTemplates (PVC для каждой реплики; спутник form: stateful) | Именованный том (деградация — один общий том для всех реплик, с предупреждением) | Compose не может выразить шаблоны для каждой реплики. Когда persistentTemplate транслируется в compose, выдаётся один именованный том, а сниженная точность сообщается предупреждением вместе со сборкой, а не записывается в сгенерированный файл. Сущностям Workloads, зависящим от изоляции томов по репликам, не следует нацеливаться на границы, состоящие только из compose. |
Форма контроллера выбирается полем form рабочей нагрузки, а не её томами. StatefulSet выдаётся при form: stateful; том persistentTemplate — спутник этой формы: он объявляет хранилище для каждой реплики у рабочей нагрузки, у которой уже есть идентичность каждой реплики, предоставляемая StatefulSet. Объявление тома persistentTemplate в любой другой форме (или в форме по умолчанию stateless) — ошибка времени сборки, называющая исправление: declare form: stateful. Обратное допустимо — рабочей нагрузке с form: stateful не обязательно объявлять том persistentTemplate. Авторам, которым нужна семантика StatefulSet, следует задавать form: stateful напрямую.
Рабочей нагрузке с form: stateful в провайдере helm нужен headless-сервис, управляющий ею: объявите ровно один сервис с type: Headless в той же сущности Workload. Провайдер связывает serviceName у StatefulSet с этим headless-сервисом (он предоставляет стабильные сетевые идентичности каждого пода, нужные StatefulSet). Сборка останавливается, если headless-сервис не объявлен — тогда StatefulSet нечего назвать управляющим сервисом, — или если их объявлено больше одного, и управляющий сервис становится неоднозначным. Рабочая нагрузка StatefulSet может дополнительно объявлять сервисы, не являющиеся headless (например, сервис ClusterIP для доступа клиентов), рядом с единственным управляющим headless-сервисом.
Количества ресурсов
Следующие значения сущности Workload являются количествами — величинами, записанными в нотации, которую Kubernetes использует для ресурсов: значения resources.requests и resources.limits контейнера (или init-контейнера) для cpu, для memory и для каждого ключа расширенного ресурса, а также ephemeral.sizeLimit, persistent.size и persistentTemplate.size тома. Схема Workload типизирует каждое из них как строку и не ограничивает её форму. Провайдер, синтезирующий Workload для цели, проверяет каждое выдаваемое им количество, причём проверяет Workload в том виде, в каком его вычислили шаблоны сущности Recipe, так что значение, пришедшее через infra, параметр сущности Release или любой другой вход шаблона, оценивается по строке, в которую оно отрисовалось.
Количество — это, без чего-либо до или после:
- необязательный знак,
+или-; - число хотя бы с одной цифрой —
2,0.5,.5или1.; - не более одного из двух: экспонента —
eилиE, необязательный знак, затем цифры, как в1e3или5E-2, — или суффикс единицы: десятичный суффиксn,u,m,k,M,G,T,PилиE(от 10⁻⁹ до 10¹⁸ с шагом в тысячу) либо двоичный суффиксKi,Mi,Gi,Ti,PiилиEi(от 1024 до 1024⁶).
500m, 0.5, 2, 128Mi, 1.5Gi, 1e3, 5n и 4u — количества; lots, 1.5 cores, 1 gigabyte, 10 GB и 1e1.5 — нет: экспонента должна быть целым числом. Одиночная E после числа — десятичный суффикс для 10¹⁸ (12E); за которой следуют цифры, она открывает экспоненту (1E3).
Это форма, которую принимает собственный парсер количеств Kubernetes, с одним намеренным отличием: строка, в числе которой нет ни одной цифры, — m, Ki, +, ., e5 — отвергается, тогда как Kubernetes читает её как ноль. Именно такая строка остаётся от шаблона, когда интерполируемое им значение пусто: "{{ .infra.cpu }}m" при пустом cpu отрисовывается в m. Отказ превращает пустой вход в остановку с указанием поля, а не в запрос нулевого размера, о котором ничто не сообщает.
Что каждая цель делает с количеством:
- helm выводит каждое количество дословно, предварительно проверив его на соответствие описанной выше форме. Значение, не соответствующее ей, останавливает сборку с ошибкой, в которой названы узел, путь поля в Workload —
containers.main.resources.requests.cpu,initContainers[0].resources.limits.memory,volumes.data.persistent.size— и само значение. См. Helm Provider → режим Workload (synthesized). - compose переводит
cpuиmemoryв собственные единицы из разобранного значения:cpusстановится десятичным числом ядер (500m→0.5), аmemory— точным числом байтов (1.5Gi→1610612736). Значение, не являющееся количеством, останавливает сборку, как и количество, которое compose не может представить точно, — отрицательная величина, объём памяти, не равный целому числу байтов (1500m), или величина cpu точнее девяти знаков после запятой для ядра; ошибка сообщает, с каким из двух случаев она столкнулась. Числоnvidia.com/gpuчитается так же и становится числом устройств, поэтому значение, не равное целому числу устройств, тоже останавливает сборку. compose не выводит других расширенных ресурсов и размеров томов, поэтому не проверяет ни то, ни другое: любой другой ключ расширенного ресурса иephemeral.sizeLimitотбрасываются с предупреждением, а размер persistent ни на что в его выводе не влияет. См. Compose Provider → ресурсы контейнера.
Проверка оценивает только форму. Может ли кластер запланировать такую величину и подходит ли она устройству — вне её рамок.
services
Упорядоченная карта публикаций сервисов. Каждый сервис объявляет свой тип (ClusterIP, Headless, NodePort, LoadBalancer, Loopback) — насколько далеко доступны его порты — и карту именованных портов. Имена портов должны совпадать с именами портов контейнеров, объявленными в другом месте Workload:
services: http: type: ClusterIP ports: web: 8080 # must exist in containers.<name>.portsНесколько сервисов в одной сущности Workload — обычное дело, когда внутренний и внешний трафик открываются раздельно (внутренний ClusterIP для потребителей внутри кластера, LoadBalancer для внешнего трафика, ClusterIP для сбора метрик Prometheus).
Насколько далеко доступны порты сервиса. Это задаёт type, и каждая цель отображает его в своих терминах:
type | Доступность | helm | compose |
|---|---|---|---|
ClusterIP | соседи рабочей нагрузки в собственной сети цели | Service типа ClusterIP | ничего не публикует; соседи обращаются к порту в сети compose |
Headless | то же самое, но без адреса кластера | Service типа ClusterIP с clusterIP: None | ничего не публикует |
NodePort | за пределами собственной сети цели | Service типа NodePort | каждый порт публикуется на всех интерфейсах хоста в виде <service port>:<container port> |
LoadBalancer | за пределами собственной сети цели | Service типа LoadBalancer | то же, что и для NodePort |
Loopback | только собственный loopback-адрес хоста | останавливает сборку, называя сервис | каждый порт публикуется на loopback-адресе IPv4 в виде 127.0.0.1:<service port>:<container port> |
Номер порта сервиса и порт контейнера, который он называет, — это два числа, как port и targetPort у Kubernetes Service: helm записывает номер записи как port объекта Service и направляет на порт контейнера по его имени, а compose публикует номер записи на хосте на номер порта контейнера. Если оба числа равны, compose записывает это число с обеих сторон.
Loopback предназначен для порта, к которому обращается что-то на той же машине — браузер или агент, работающий на хосте, — и к которому больше ничто обращаться не должно. В compose привязка выполняется только к loopback-адресу IPv4: loopback-адрес IPv6 ::1 не привязывается, поэтому обращайтесь к порту по адресу 127.0.0.1, записанному как 127.0.0.1, а не по имени, которое может разрешиться в ::1. Объявленный транспорт указывается в записи так же, как для любого публикуемого порта, например 127.0.0.1:5514:5514/udp.
Если две записи называют один и тот же порт, побеждает более широкая доступность: порт, который публикует запись NodePort или LoadBalancer, публикуется на всех интерфейсах, даже если его называет и запись Loopback, независимо от того, какая из двух объявлена первой.
В helm запись Loopback останавливает сборку, а не отрисовывается как нечто иное. У сервиса Kubernetes нет типа, привязывающегося к loopback-адресу хоста: то, на каких адресах узлов слушает сервис NodePort, — настройка всего кластера, а не отдельного сервиса. Поэтому сервис ClusterIP потерял бы запрошенную записью досягаемость, а сервис NodePort опубликовал бы порт на каждом адресе узла, который допускает кластер. Остановка называет узел и сервис; см. A service type the helm provider cannot render (Тип сервиса, который провайдер helm не может отрисовать).
Соглашение о синтезированных именах. Когда провайдер helm синтезирует сервисы Workload, metadata.name каждого Service детерминированно выводится из имени, которое несёт собственный контроллер рабочей нагрузки, и ключа сервиса. Для Workload компонента это имя — имя релиза узла: <release name>-<service-key>. Имя релиза — это идентификатор компонента, записанный в алфавите, допустимом для имён Kubernetes, — то же имя, с которым рендерится чарт, доступное в шаблонах Recipe как {{ .context.rendered_name }}, — поэтому оно равно instance_id везде, где идентификатор не содержит подчёркивания и заглавных букв. Workload, объявляющий services.http на узле api-server, создаёт Service с именем api-server-http; тот же Workload на узле billing создаёт billing-http, а на узле my_api — my-zuapi-http. Имя выходного файла следует тому же соглашению: <release name>-<service-key>-service.yaml. Recipe, публикующий адрес такого Service, строит его из {{ .context.rendered_name }}, а не из {{ .context.instance_id }}, который не называет никакой Service везде, где они различаются, — см. ../templates/rendered-resource-names.md.
Workload, который синтезирует FeatureRecipe вложения Feature, получает имя не по имени релиза, а по собственному составному идентификатору вложения: значению, которое его ресурсы несут в метке aggrega.ai/component-id, составленному из компонента-хоста и ключа, записанного в features:, после начального cfr--. Имя релиза, выведенное там, было бы именем хоста и называло бы ресурсы вложения по собственным ресурсам хоста. Поэтому FeatureRecipe, чей Workload объявляет services.scrape, для вложения stats на узле front-door создаёт Deployment cfr--front-door--stats и Service cfr--front-door--stats-scrape. Этот первый сегмент никогда не равен instance_id, и ни один ключ в контексте шаблонов FeatureRecipe его не содержит: в шаблонах вложения {{ .context.rendered_name }} и {{ .context.instance_id }} оба называют хост (front-door), а {{ .attachment_name }} — это только ключ (stats), поэтому {{ .context.rendered_name }}-scrape называет собственный Service scrape хоста, если хост его объявляет, и никогда — Service вложения; см. ../templates/rendered-resource-names.md. Выходной файл стоит за префиксом, который несёт каждый файл, выводимый вложением, — имя хоста и имя вложения, каждое с последующим --, — поэтому этот Service записывается в front-door--stats--cfr--front-door--stats-scrape-service.yaml.
У этого соглашения два практических следствия. Во-первых, коллизии между узлами невозможны по построению: префикс имени различает сервисы всех узлов границы, потому что два разных идентификатора всегда дают два разных имени релиза, идентификатор вложения содержит и его хост, и его ключ, а ни одно имя компонента не может начинаться с cfr-- (на таком имени сборка останавливается — см. Component identity cannot be stamped on what it emits (Идентификатор Component нельзя проставить на то, что он выводит)), так что два Workload, каждый из которых объявляет services.http, создают разные ресурсы K8s Service с непересекающимися именами. Единственный остаток — идентификатор вложения, слишком длинный для цели: он сокращается вокруг дайджеста целого, и два сокращённых идентификатора в принципе могут совпасть — см. Метки происхождения в отрендеренном выводе. Во-вторых, Workload не может объявить один ключ сервиса дважды: карта services:, называющая ключ дважды, отклоняется при разборе YAML сущности Workload, и сборка останавливается с указанием ключа и его строки.
Риск коллизии, который всё же остаётся, связан с границей длины имён K8s: имена Service в Kubernetes ограничены 63 символами, и синтезированная форма <release name>-<service-key> может превысить этот предел, если обе части длинные. Компилятор Aggrega не проверяет этот предел; сборка выводит Service, а Kubernetes отклоняет его при применении. Авторам с глубоко вложенными идентификаторами экземпляров (например, data-layer.regional.eu-west.primary) и длинными ключами сервисов следует удерживать общую длину в пределах 63 символов. То же относится к Workload вложения: составной идентификатор, слишком длинный для цели, сокращается, но добавленный к нему ключ сервиса — нет, поэтому Service вложения с длинным ключом всё равно может превысить 63 символа и собраться без остановки.
Provider-специфичное примечание (compose). Провайдер compose автоматически выводит depends_on из рёбер uses в IR. Эти записи выводятся без условий — они имеют семантику service_started независимо от того, объявляет ли цель healthcheck, — поэтому сервис, все зависимости которого получены из рёбер uses, выводит краткую форму списка (depends_on: [<target>]). Условие на работоспособность цели для записей, выведенных из рёбер, не реализовано. Полная форма выводится там, где запись действительно несёт условие, — так выражается ожидание init-контейнера; см. providers/compose.md.
Транспортные протоколы портов
Порт контейнера можно задать в одной из двух равнозначных форм. Просто число — это краткая форма, она не объявляет транспорт, поэтому цель применяет собственное значение по умолчанию — TCP на каждой цели, где оно есть:
containers: main: image: "{{ .values.image }}" ports: web: 8080Развёрнутая форма содержит номер и транспорт вместе; она нужна порту, когда он передаёт что-либо, кроме значения по умолчанию:
containers: main: image: "{{ .values.image }}" ports: web: 8080 # short form — no transport declared dns: port: 53 protocol: UDP # TCP | UDP | SCTP sigtran: port: 2905 protocol: SCTPОбе формы можно свободно смешивать в одной карте ports, а порт, которому не нужно объявлять транспорт, остаётся в краткой форме.
Транспорт объявляется один раз — на порту контейнера. Запись services.<service>.ports называет порт контейнера и наследует его транспорт, поэтому публикация сервиса не может расходиться с портом, который открыл контейнер. У порта сервиса нет ключа protocol, и попытка его указать отклоняется.
Зачем нужно это поле. Цели развёртывания считают неуказанный транспорт потоковым. Компонент, которому нужен датаграммный порт — медиа в реальном времени, телефония, разрешение имён, частные сети, игровой сервер, — иначе мог бы объявить только номер, и стек развернулся бы, пройдя все проверки, но ни один клиент не смог бы подключиться, потому что трафик датаграммный, а открытый порт — нет. Именно объявление транспорта делает это выразимым.
Компилятор не интерпретирует значение. Он не выводит транспорт из имени порта и не сверяет объявленный транспорт с тем, что на самом деле использует процесс за портом: значение — это данные, которые объявляете вы и которые выводит движок цели. Порт с именем dns без ключа protocol — это TCP-порт, а порт с именем web, объявляющий protocol: UDP, — это UDP-порт.
Поведение на каждой цели.
| Цель | Порт без объявленного транспорта | Объявленный транспорт |
|---|---|---|
| helm | containerPort и порт Service не содержат ключа protocol | выводится дословно как protocol: на порту контейнера и на каждом порту Service, который его называет |
| compose | публикуется как <host>:<container>, без изменений | публикуется как <host>:<container>/tcp или /udp; у SCTP нет записи в compose, и он останавливает сборку, а не публикует порт, который передавал бы другой транспорт |
Порт контейнера, который не публикует ни один сервис, вообще не попадает в файл compose — таково обычное поведение compose для портов контейнера, — поэтому транспорту, объявленному на таком порту, не к чему быть записанным, и сборка не останавливается.
Проверки работоспособности — форма намерения
Каждый контейнер объявляет свои проверки под собственным ключом health: (containers.<name>.health) в абстрактной форме намерения; у сущности Workload нет health верхнего уровня. Каждый провайдер при синтезе переводит намерение в собственную нативную форму проверки.
health: ready: http: /healthz # intent: HTTP GET probe timeoutSeconds: 5 live: tcp: 8080 # intent: TCP socket check timeoutSeconds: 5 startup: exec: ["check-ready.sh"] # intent: command exec timeoutSeconds: 30 periodSeconds: 10Три формы намерения (http:, tcp:, exec:) взаимоисключающие в пределах одного объявления проверки. Для http: без явно указанного порта берётся первое по алфавиту имя порта, которое контейнер объявляет в containers.<name>.ports, — одно и то же правило для обеих целей, поэтому проверка обращается к одному и тому же порту, какая бы цель её ни отрисовывала. Контейнер, не объявляющий ни одного именованного порта, не может иметь HTTP-проверку: сборка останавливается с ошибкой трансляции, в которой названа проблемная проверка.
Трансляция по провайдерам. Каждый провайдер при синтезе переводит абстрактное намерение проверки в свою нативную форму:
| Намерение | Helm (K8s) | Compose | Что теряется |
|---|---|---|---|
http: /path | httpGet.path: /path, httpGet.port: <alphabetically-first port name> | CMD-SHELL "curl -f http://localhost:<port>/path" | В Compose нет нативной формы HTTP-проверки; обёртка CMD-SHELL требует наличия curl в образе контейнера. |
tcp: <port> | tcpSocket.port: <port> | CMD-SHELL "nc -z localhost <port>" | В Compose нет нативной формы TCP-проверки; обёртка CMD-SHELL требует наличия nc в образе контейнера. |
exec: [cmd, ...] | exec.command: [cmd, ...] | CMD [cmd, ...] | Отображение один к одному; оба провайдера передают список команд дословно. |
Обёртки CMD-SHELL в Compose приближённо воспроизводят HTTP- и TCP-проверки через предикаты, вычисляемые оболочкой. Compose недостаёт нативной формы проверки, а не полей времени: заданные periodSeconds, timeoutSeconds, failureThreshold и initialDelaySeconds переносятся в healthcheck как interval, timeout, retries и start_period — пополевое отображение приведено в разделе «Probes» страницы providers/compose.md. Нативная форма exec: вообще не требует обёртки и транслируется один к одному на обеих целях.
Обёрнутая проверка транслируется молча: в сгенерированном docker-compose.yaml она ничем не помечена, и никакая диагностика не сообщает об обёртке. На этом пути сборка сообщает о другом — о слоте проверки, который вообще не попадает в вывод: у сервиса compose один healthcheck, поэтому если сущность Workload объявляет больше одного из ready:, live: и startup:, транслируется только предпочтительный слот (live важнее ready, а тот важнее startup), а предупреждение unsupported-field называет транслированный слот и отброшенные слоты.
Provider-специфичное примечание (compose). Блок health: в Workload, нацеленной на compose, не ставит порядок depends_on в зависимость от работоспособности: записи depends_on провайдера compose, выводимые из рёбер uses:, всегда используют семантику service_started, независимо от того, объявляет ли целевая Workload проверки работоспособности. Привязка этих записей к работоспособности цели не реализована: длинная форма, которая могла бы нести такое условие, сама по себе генерируется — для ожиданий init-контейнеров, поэтому отсутствует именно возможность выбрать привязку ребра к работоспособности, а не форма для её выражения. Полные правила вывода см. в providers/compose.md.
Сквозные поля в форме K8s — scheduling, serviceAccount, podSecurityContext
Схема Workload принимает три необязательных поля верхнего уровня, которые существуют прежде всего для того, чтобы передавать нативные примитивы Kubernetes через провайдер helm, сохраняя структурную форму Aggrega. Провайдер compose транслирует ту часть, у которой есть аналог в Compose, а остальное игнорирует с выдачей предупреждения. Aggrega проверяет внешнюю форму, но не контролирует внутреннее содержимое (см. раздел Поверхность валидации ниже) — нативные для K8s внутренние значения передаются дословно в спецификацию пода, отрисованную helm.
scheduling
scheduling объединяет четыре нативных примитива планирования K8s — nodeSelector, affinity, tolerations, topologySpreadConstraints — в один блок, сгруппированный по назначению. Каждое подполе имеет в точности ту же форму, что и соответствующее поле спецификации пода Kubernetes:
apiVersion: aggrega.ai/v1beta1kind: Workloadscheduling: nodeSelector: disktype: ssd region: us-east-1 tolerations: - key: dedicated operator: Equal value: gpu-workloads effect: NoSchedule affinity: podAntiAffinity: preferredDuringSchedulingIgnoredDuringExecution: - weight: 100 podAffinityTerm: labelSelector: matchLabels: { app: "{{ .context.instance_id }}" } topologyKey: kubernetes.io/hostname topologySpreadConstraints: - maxSkew: 1 topologyKey: topology.kubernetes.io/zone whenUnsatisfiable: ScheduleAnywaycontainers: app: { image: "..." }Трансляция Provider. Провайдер helm передаёт каждое подполе без изменений в отрисованную спецификацию pod. Провайдер compose не транслирует ни одно из четырёх: он опускает весь блок scheduling и выдаёт предупреждение, называющее его.
serviceAccount
serviceAccount — это простая строка с именем ServiceAccount, под которым запускается рабочая нагрузка:
apiVersion: aggrega.ai/v1beta1kind: WorkloadserviceAccount: "{{ .context.rendered_name }}-runner"containers: app: { image: "..." }Имя строится из {{ .context.rendered_name }} — имени релиза, по которому провайдер helm называет собственные ресурсы рабочей нагрузки, поэтому кластер примет его, как бы ни назывался компонент. Поле ссылается на существующий ServiceAccount и не создаёт его. Сопутствующие ресурсы RBAC (сам объект ServiceAccount, а также Role / RoleBinding / ClusterRole / ClusterRoleBinding) следует поставлять по одному из двух каналов:
artifacts:сущности Recipe — когда RBAC неотъемлемо присущ этому Recipe (Recipe знает, что ему нужна определённая Role для определённой задачи).- Features с генерацией ресурсов — когда RBAC является сквозным (FeatureRecipe для Workload-Identity, привязывающий связанные с IAM ServiceAccount к каждому компоненту с определённой меткой).
Если задать serviceAccount:, не обеспечив существование указанного ServiceAccount, это приведёт к ошибке K8s во время выполнения при применении, а не к ошибке сборки: валидация схемы рабочей нагрузки не проверяет существование ServiceAccount (во время компиляции нет доступа к состоянию кластера согласно инварианту чистоты AOT).
Провайдер compose игнорирует serviceAccount: с предупреждением; в Compose нет эквивалентного понятия привязки идентичности.
podSecurityContext
podSecurityContext содержит примитивы безопасности уровня пода — UID, GID, fsGroup, supplementalGroups, — которые применяются к каждому контейнеру в поде:
apiVersion: aggrega.ai/v1beta1kind: WorkloadpodSecurityContext: runAsUser: 1000 runAsGroup: 3000 fsGroup: 2000 supplementalGroups: [4000, 5000]containers: app: { image: "..." }Семантика полей. Все четыре поля — целые числа (числовые UID/GID, а не строки); runAsUser и runAsGroup задают эффективные UID/GID процессов контейнера; fsGroup задаёт группу-владельца для томов, монтируемых в под; supplementalGroups добавляет дополнительные GID к группе процессов каждого контейнера.
Трансляция Provider. Провайдер helm передаёт блок без изменений в отрисованную спецификацию pod. У провайдера compose нет эквивалента для fsGroup или supplementalGroups, и он опускает каждый из них с предупреждением; runAsUser/runAsGroup транслируются в форму Compose user: 1000:3000 на каждом сервисе, который создаёт Workload, включая sidecar-контейнеры и init-контейнеры, а runAsGroup без runAsUser рядом опускается с предупреждением. Каждый контейнер и init-контейнер также несёт собственный securityContext — runAsUser, runAsGroup, runAsNonRoot, readOnlyRootFilesystem, allowPrivilegeEscalation и capabilities.add / capabilities.drop. Провайдер helm выводит его на контейнере; провайдер compose выводит readOnlyRootFilesystem как read_only, capabilities.add / capabilities.drop как cap_add / cap_drop, а runAsUser / runAsGroup — как собственный user контейнера, который заменяет значение пода; он опускает runAsNonRoot, allowPrivilegeEscalation и runAsGroup, записанный без runAsUser, выдавая предупреждение для каждого, а также предупреждает, когда собственный runAsUser контейнера оставляет без внимания runAsGroup пода. Сопоставление по полям приведено в providers/compose.md.
Рабочие нагрузки с GPU и устройствами
Рабочая нагрузка, которой требуется специализированное оборудование — GPU или другое устройство от поставщика, — выражает две независимые задачи: среду выполнения уровня пода, которую предоставляет узел с устройством (runtimeClassName), и количество устройства на контейнер, которое запрашивает рабочая нагрузка (ключ расширенного ресурса в resources контейнера). Типичная рабочая нагрузка с GPU объявляет и то и другое, но каждое из них самостоятельно, и любое может присутствовать без другого.
Оба поля описывают вычисления — под и контейнер, который работает на устройстве, — поэтому им место в рабочей нагрузке, которая запускает контейнеры. У рабочей нагрузки, которая несёт только внешнюю конечную точку и не объявляет собственных контейнеров, нет ни пода, ни контейнера, к которым их можно было бы привязать: задание runtimeClassName в такой рабочей нагрузке, состоящей только из конечной точки, останавливает сборку с указанием runtimeClassName и сущности Recipe, чья сущность Workload его объявила, а без контейнеров запрос ресурса устройства разместить негде.
runtimeClassName
runtimeClassName — это одна строка с именем RuntimeClass, под которым работает под, — среды выполнения контейнеров, которую предоставляет узел с устройством, например среды выполнения GPU с именем nvidia. Это селектор уровня пода: он применяется ко всем контейнерам рабочей нагрузки. Компилятор передаёт имя дословно как детерминированный указатель; кластер сопоставляет его с RuntimeClass, настроенным администратором, во время планирования. Aggrega не проверяет существование подходящего RuntimeClass — во время компиляции у него нет доступа к состоянию кластера, — поэтому имя без настроенного RuntimeClass проявляется как ошибка планирования во время применения, а не как ошибка сборки.
Ключи расширенных ресурсов
Поля resources.requests и resources.limits контейнера содержат обычные количества cpu и memory, а наряду с ними — ключи расширенных ресурсов: количества устройств в области поставщика или домена, ключом для которых служит полностью квалифицированное имя вида <domain>/<name>, например nvidia.com/gpu или amd.com/gpu. Сегмент домена содержит хотя бы одну точку, и именно эта точка отличает расширенный ключ (nvidia.com/gpu) от простых количеств cpu и memory. Каждое значение — это строковое количество ("1", "2"), которое компилятор передаёт дословно, а провайдер helm проверяет его форму перед выводом (см. Количества ресурсов); плагин устройств кластера разрешает и выделяет устройство во время планирования.
Подробный пример — рабочая нагрузка инференса на GPU
apiVersion: aggrega.ai/v1beta1kind: WorkloadruntimeClassName: nvidiacontainers: inference: image: "{{ .values.image }}" resources: requests: cpu: "2" memory: "8Gi" nvidia.com/gpu: "1" limits: nvidia.com/gpu: "1"Рабочая нагрузка выбирает для своего пода среду выполнения nvidia и запрашивает один GPU для контейнера inference. Количество GPU указано и в requests, и в limits: устройство нельзя переподписать, поэтому его запрос и лимит устанавливаются в одно и то же значение.
Трансляция провайдером. Это понятия, присущие Kubernetes. Провайдер helm выводит runtimeClassName в отрисованную спецификацию пода, а каждый ключ расширенного ресурса — дословно в resources.requests / resources.limits контейнера, так что они попадают в кластер через вывод для Kubernetes. Провайдер compose резервирует количество nvidia.com/gpu как столько же GPU NVIDIA в сервисе контейнера (см. Compose Provider → Ресурсы контейнера); у отдельного хоста нет понятия класса среды выполнения и нет аналога для любого другого ключа расширенного ресурса, поэтому рабочая нагрузка, объявляющая runtimeClassName или другой ключ, отрисовывается для цели compose без него.
Работа в сети узла
По умолчанию workload работает в собственном сетевом пространстве имён: его контейнеры видят только
собственные интерфейсы, а трафик доходит до них через трансляцию адресов целевой платформы. hostNetwork: true
запрашивает другое устройство: workload работает в собственном сетевом пространстве имён узла, поэтому он
видит интерфейсы узла, а порты, которые открывают его контейнеры, доступны на собственных адресах
узла без промежуточной трансляции.
Именно это нужно целому классу программ. Медиа в реальном времени, телефония, виртуальные частные сети и подобный трафик передают адрес собеседника внутри полезной нагрузки, поэтому адрес, переписанный в пути, приходит, указывая туда, куда собеседник добраться не может; работа на адресах узла и сохраняет их согласованность.
apiVersion: aggrega.ai/v1beta1kind: WorkloadhostNetwork: truecontainers: media: image: "{{ .values.image }}" ports: rtp: port: 7881 protocol: UDPЧто он объявляет и чего не объявляет
hostNetwork выбирает сетевое пространство имён, и только это.
- Он не объявляет портов. Порты, которые открывает workload, по-прежнему объявляются в
containers.<name>.portsточно так же, как без него, и означают то же самое. ОбъявлениеhostNetworkне добавляет порт и не отменяет необходимость его объявить. - Он не объявляет количество портов. Приложение, которому нужно много смежных портов, — например, медиасервер, подбирающий размер диапазона по числу процессоров машины, — настраивает этот диапазон в собственном теле конфигурации на основе значений, которые задаёт его оператор, так же, как настраивает всё остальное, что читает при запуске. Это настройка приложения, а не workload, и контракту workload она не принадлежит.
- Ничего не выводится. Компилятор не вкладывает в значение никакого смысла и не выводит его ни из чего другого: ни из имени порта, ни из типа или меток компонента, ни из количества объявленных портов. Workload работает в сети узла тогда и только тогда, когда он это указывает.
Поскольку hostNetwork описывает вычисления, он относится к workload, запускающему контейнеры. Workload,
содержащий только внешнюю конечную точку, не объявляет контейнеров, поэтому ему нечего выбирать в качестве сетевого пространства имён:
объявление hostNetwork на workload, содержащем только конечную точку, останавливает сборку с указанием hostNetwork и
сущности Recipe, чья сущность Workload его объявила.
Трансляция в Provider
Провайдер helm выводит hostNetwork: true в отрисованную спецификацию pod — так Kubernetes
выражает тот же выбор. Объявление попадает только в спецификацию pod и больше никуда: выводимые
Services одинаковы с ним и без него.
Провайдер compose выводит network_mode: host в собственный сервис workload. Из того, как compose
моделирует сети, следует одно последствие: сервис в этом режиме не подключается к сети
границы, поскольку compose считает подключение к сети и использование пространства имён хоста
альтернативами, а не дополнениями. Поэтому его соседи обращаются к нему по собственным адресам хоста, а не
по имени сервиса — что и означает сеть хоста на любой целевой платформе, — а все остальные сервисы
границы не затрагиваются.
На этой целевой платформе с ним сочетаются две формы. Sidecar-контейнер следует за основным сервисом в
сеть хоста, ничего не объявляя, поскольку получает пространство имён основного сервиса, ссылаясь на него
по имени. Init-контейнер так не делает: он становится сервисом, которого ждёт основной
сервис, поэтому подключается к сети границы самостоятельно, а не принимает пространство имён, из-за которого
это ожидание стало бы циклическим. Поэтому workload, объявляющий и hostNetwork, и initContainers, запускает
свой сервис в сети узла, а его init-сервисы остаются в сети границы — это более
узкое устройство, чем единое общее пространство имён, которое даёт форма pod, и провайдер compose
называет его в предупреждении unsupported-field, а не оставляет обнаруживать во время выполнения.
Рабочая нагрузка, не объявляющая hostNetwork, не несёт такого ключа в своём выводе: ключ отсутствует, а не выводится как false.
Интеграция вложений с featuresSchema сущности Component
Блок containers.<name>.attachments сущности Workload ссылается на слоты учётных данных, объявленные в featuresSchema сущности Component, — или, для записи, указывающей подключение, на слот, который объявляет сокет этого подключения (см. Доставка учётных данных, которые несёт подключение); новых слотов он не объявляет. Описание написания featuresSchema см. в ../entities/component.md. from называет слот; это не имя сгенерированного Secret.
Запись containers.<name>.attachments отрисовывается в ссылку на ресурс Secret — Kubernetes secretKeyRef (для as: env) или том на основе секрета (для as: file), — и оба указывают на Secret по имени. Синтезатор определяет это имя и ключ данных из предоставляемых значений (provides) слота: отрисованное secretKeyRef.name записи — это .features.<slot>.provides.name слота, а ключ данных — .features.<slot>.provides.key. Автор сущности Recipe пишет только from: <slot> и as: env; синтезатор читает разрешённые provides и не выводит имя заново. Это то же чтение .features.<slot>.provides.<key>, которое исходная сущность Recipe использует для existingSecret: один слот учётных данных одинаково питает и потребителя в исходной сущности Recipe, и потребителя в синтезированной сущности Workload (симметрия source/workload).
Интеграцией управляют четыре правила проверки:
- Каждое значение
attachments.<KEY>.fromдолжно совпадать с именем слота, объявленного вfeaturesSchemaсущности Component, — или, для записи, указывающей подключение, в сокете этого подключения. Неизвестное имя слота — ошибка времени загрузки. - Механизм доставки
as:(envилиfile) должен присутствовать в списке разрешённыхinject:слота, объявленном сущностью Component. Объявление в сущности Workloadas: fileдля слота, чья запись вfeaturesSchemaзадаётinject: [env], — ошибка времени загрузки. - Слоты, помеченные
inject: [](доставка «чёрным ящиком») вfeaturesSchemaсущности Component, вообще не могут появляться в блокахattachments:сущности Workload. Такие слоты доставляются внутренними механизмами сущности Recipe (например, параметромexistingSecretчарта Helm), а не через Workload. - Слот, на который ссылаются, должен быть ссылаемым: его заполнение должно публиковать локатор
provides(name,key) для ресурса Secret — того, который выводит его реализация, или уже существующего. Слоту, заполненному учётными данными с доставкой через inject (они записывают значение в канал inject и не публикуют локатор), не на что указывать; ссылка на него из записиattachments:сущности Workload — ошибка времени загрузки. Учётные данные с доставкой через inject попадают в контейнер через канал inject слота (записьvariables, читающая.context.inject.env.<KEY>), а не через записьattachments:.
Provider note. Helm формирует описанную выше ссылку secretKeyRef/на том секрета. У провайдера compose нет собственного примитива для передачи секрета в переменную окружения; запись вложения as: env в сущности Workload, нацеленной на compose, выводится как запись окружения с пустым значением и предупреждением, называющим эту запись (см. страницу провайдера compose), при этом правило ссылаемости (агностичное по отношению к возможностям провайдера) по-прежнему действует.
Пример:
# In the Component catalog entityspec: featuresSchema: db_password: required: true inject: [env, file] # transparent: Workload may dictate delivery root_password: required: true inject: [] # blackbox: Recipe handles internally
# In the Recipe's Workloadworkload: | containers: main: attachments: DB_PASSWORD: # OK — db_password slot allows env inject from: db_password as: env # ROOT_PASSWORD: ... # rejected at load time: blackbox slotДоставка учётных данных, которые несёт подключение
Сокет сущности Component может объявить в usesSchema.<socket>.featuresSchema слоты, которые заполняет каждое подключение через него, — так компонент, обращающийся к нескольким целям, хранит по одним учётным данным на подключение, а не одни на все. Такое вложение не входит в собственные .features компонента; оно находится под его подключением, в .context.uses.<alias>.features.<slot>. Запись сущности Workload доставляет его, указывая подключение рядом со слотом:
- в записи
attachmentsконтейнера —connection: <alias>рядом сfrom: <slot>; - в записи
envFromконтейнера —connection: <alias>рядом сsecret: <slot>;connectionдопускается только рядом сsecret.
Обе формы допускаются в каждом контейнере и каждом init-контейнере. <alias> — имя, под которым подключение записано в блоке uses компонента, в сущности Aggregate или в сущности Release, — ключ, по которому сущность Recipe читает подключение в .context.uses, — а <slot> — слот, который объявляет сокет, через который проведено это подключение.
Прежде чем какое-либо из правил выше прочитает Workload, каждая запись, указывающая подключение, переписывается на имя, которое вложение этого подключения в данном слоте получает в компоненте: псевдоним, точка и слот (gpt.credential). Затем каждое правило применяется к переписанной записи точно так же, как к записи, указывающей один из собственных слотов сущности Component: список разрешённых inject: слота сокета управляет as:, на слот сокета, объявляющий inject: [], ссылаться нельзя, заполняющее его вложение должно быть ссылаемым, а провайдер определяет имя и ключ данных Secret из разрешённых provides этого вложения — поэтому запись каждого подключения ссылается на собственные учётные данные этого подключения. Слот сокета, объявляющий sensitive: true, читается для записи точно так же, как объявление слота сущности Component. Провайдер получает переписанную запись; ключ connection до него не доходит.
Отклоняются три вида записей, и в каждом случае называется то, что запись указала:
- запись, указывающая подключение, которого компонент не использует, — отказ называет подключение, слот и подключения, которые компонент использует;
- запись, указывающая слот, который сокет подключения не объявляет, — отказ называет слот, подключение, сокет и объявленные им слоты;
- запись, сама пишущая составное имя (
from: gpt.credential). Слот подключения указывается через указание подключения, поэтому составное имя никогда не служит вторым способом до него добраться.
Подключение, не несущее вложения в этом слоте, оставляет записи не на что ссылаться, и правило ссылаемости её отклоняет. Сущность Workload, которую отрисовывает сущность FeatureRecipe, ограничена слотами, объявленными реализуемой ею сущностью Feature, а они не достигают ни одного подключения компонента-хоста, поэтому такая запись, указывающая подключение, отклоняется как указывающая подключение, которого компонент не использует.
Пример:
# In the Component catalog entityspec: usesSchema: models: featuresSchema: credential: sensitive: true inject: [env]
# In the Recipe's Workload — the component draws connections `gpt` and `nim`# through the `models` socket, each carrying its own `credential`workload: | containers: main: attachments: MODEL_KEY_GPT: from: credential connection: gpt as: env MODEL_KEY_NIM: from: credential connection: nim as: envВ helm MODEL_KEY_GPT отрисовывается как secretKeyRef, называющий Secret, опубликованный учётными данными подключения gpt, а MODEL_KEY_NIM — Secret, опубликованный учётными данными подключения nim. В compose запись as: env, указывающая подключение, выводится с пустым значением и тем же предупреждением о частичной поддержке, что и запись, указывающая один из собственных слотов сущности Component.
Поверхность валидации
Каждая сущность Workload проходит валидацию во время загрузки Recipe, до запуска какого-либо рендеринга. Валидация состоит из двух этапов:
- Валидация по схеме. Значение Workload унифицируется со встроенной схемой Workload
aggrega.ai/v1beta1. Ошибки содержат путь к полю и нарушенное ограничение (например,.containers.main.health.ready: multiple oneOf branches matched (branches [0, 1] of 3): expected exactly one). Валидация по схеме проверяет каждый тип, перечисление, диапазон и дизъюнкцию, объявленные в схеме, — включая закрытое множество значенийformконтроллера (одно изstateless,stateful,daemon,scheduled,task,reference), закрытое множество значенийtypeсервиса (одно изClusterIP,Headless,NodePort,LoadBalancer,Loopback), целочисленный диапазон портов (1..65535), дизъюнкцию форм проб (ровно одна изhttp,tcp,exec) и дизъюнкцию вариантов томов (ровно один изephemeral,configmap,secret,persistent,persistentTemplate). - Валидация перекрёстных ссылок. Ссылки вложений Workload проверяются по
featuresSchemaсущности Component — а для записи, называющей соединение, по слотам, которые объявляет сокет этого соединения, — (принадлежность слоту, список допустимых способов доставкиas:, исключение доставки «чёрным ящиком») и по разрешённым provides каждого указанного слота (возможность ссылки — заполнение должно публиковатьname/key). Это проверки между сущностями, которые валидация только по схеме выполнить не может.
Оба этапа выдают сообщения одинаковой формы с префиксом CATALOG_ERROR; при ошибках сборка останавливается до того, как будет получен какой-либо результат рендеринга. Авторы Recipe получают точную обратную связь с указанием именно того поля, которое не прошло проверку, и ограничения, которое его отклонило.
Сквозные поля в форме K8s (scheduling.affinity, scheduling.tolerations, scheduling.topologySpreadConstraints, списки items внутри томов ConfigMap и Secret, хуки жизненного цикла httpGet) проверяются только структурно: схема Aggrega ограничивает их наличие и внешнюю форму, но за внутреннюю форму этих значений, определённых API K8s, отвечает провайдер (провайдер helm передаёт их в спецификацию пода K8s дословно; провайдер compose отклоняет их или упрощает по ситуации). Workload с некорректным значением affinity проходит валидацию Aggrega, и ошибка проявляется уже при синтезе в провайдере.
Количества ресурсов для схемы точно так же являются строками: ни один из этапов не проверяет их формат. Это делает синтезирующий провайдер на вычисленной сущности Workload и останавливается на значении, не соответствующем формату количества, — см. Количества ресурсов.
Вспомогательные ресурсы размещаются вне Workload
Workload описывает только форму рабочей нагрузки — контейнеры, тома, сервисы, реплики, планирование, контекст безопасности, сервисную учётную запись. В нём нет поля additionalResources и нет встроенных объявлений ConfigMap / Secret / CRD.
Авторы сущностей Recipe создают вспомогательные ресурсы через два канала вне Workload:
artifacts:на уровне Recipe — для ресурсов, присущих данному Recipe (конкретный ConfigMap, на который ссылается Workload этого Recipe, разовая регистрация CRD, необходимая Recipe). Поле представляет собой словарь именованных записей; каждая запись задаётся встроенно или загружается через$import:для отдельной записи. Три режима создания описаны в разделе Artifacts Mechanism в ../../architecture/16-recipe-input-composition.md.- Features с генерацией ресурсов — для сквозных задач, подключаемых через селекторы Release (Feature ServiceMonitor, подключаемый к каждому компоненту с открытыми метриками, Feature NetworkPolicy, подключаемый к каждой production-нагрузке). Описание создания сущности FeatureRecipe см. в ../entities/featurerecipe.md.
Workload остаётся сосредоточенным на форме рабочей нагрузки; у сквозных и присущих Recipe вспомогательных манифестов есть собственные места для их создания.
Типовые шаблоны Workload
Схема Workload охватывает многое: HTTP-серверы из одного контейнера, шаблоны с sidecar-контейнерами, цепочки init-контейнеров, пакетные задания и сервисы с состоянием и постоянными томами. Три шаблона встречаются настолько часто, что писать шаблонный код с нуля для каждого Recipe расточительно. Приведённые ниже блоки — шаблоны для копирования, которые авторы Recipe могут адаптировать к конкретным компонентам.
Шаблон, общий для нескольких Recipes, можно один раз опубликовать как запись WorkloadLibrary и импортировать с помощью $import: <Library>#/workloads/<entry>; приведённые здесь заготовки — отправные точки, которые можно адаптировать или опубликовать таким образом.
Шаблон 1 — сервер с публикацией метрик
Типичное веб-приложение, которое обслуживает трафик приложения на одном порту и публикует метрики для сбора Prometheus на отдельном порту. Два сервиса в Workload — один для приложения, другой для метрик — позволяют чисто разделить политики service mesh и конфигурацию балансировщика нагрузки.
apiVersion: aggrega.ai/v1beta1kind: Workloadreplicas: {{ optional .infra `replicas` 2 }}containers: app: image: "{{ .values.image }}" ports: web: {{ optional .values `port` 8080 }} metrics: {{ optional .values `metrics_port` 9090 }} variables: LOG_LEVEL: "{{ optional .values `log_level` "info" }}" health: ready: http: /healthz timeoutSeconds: 5 live: http: /healthz timeoutSeconds: 5services: http: type: ClusterIP ports: web: {{ optional .values `port` 8080 }} metrics: type: ClusterIP ports: metrics: {{ optional .values `metrics_port` 9090 }}Сервис метрик обычно получает аннотацию для обнаружения Prometheus через подключение Feature на уровне Release (например, feature.aggrega.ai/prometheus-scrape: "true"); сам Workload остаётся свободным от специфичных для провайдера аннотаций сбора метрик.
Шаблон 2 — пакетное задание
Рабочая нагрузка, которая выполняется до завершения, а не обслуживает трафик бессрочно. Шаблон задаёт form: task, полностью опускает services: — пакетные задания не открывают порты — и полагается на форму задачи целевого провайдера (Kubernetes Job в провайдере helm; у провайдера compose нет формы задачи, и он останавливает сборку на form: task). Провайдер helm фиксирует допустимый для Job restartPolicy пода (Never, если контейнер не объявляет OnFailure), поскольку под Job не может использовать значение по умолчанию Always.
apiVersion: aggrega.ai/v1beta1kind: Workloadform: taskcontainers: worker: image: "{{ .values.image }}" command: ["{{ .values.entrypoint }}"] args: - "--config" - "/etc/config/job.yaml" variables: JOB_ID: "{{ .context.instance_id }}-{{ .metadata.release_name }}" volumeMounts: - name: config path: /etc/configvolumes: config: configmap: source: "{{ .context.instance_id }}-config"Том конфигурации ссылается на ConfigMap, который Recipe, как ожидается, выпускает вместе с Workload через artifacts: (см. «Вспомогательные ресурсы находятся вне Workload» выше), — сам Workload объявляет только сторону потребления. Имя ему даёт идентификатор в провайдере, который называет рабочую нагрузку по идентификатору, как это делает compose; в helm, который называет ресурсы рабочей нагрузки по имени релиза, стройте имя ConfigMap — здесь и в артефакте — из {{ .context.rendered_name }}, чтобы кластер принял его независимо от названия компонента.
Шаблон 3 — пара с sidecar
Под из двух контейнеров, в котором основной контейнер выполняет логику приложения, а sidecar отвечает за сквозную задачу (терминирование TLS, отправку логов, прокси service mesh, AI-ограничители). Порядок в containers: имеет значение: провайдер helm выпускает контейнеры в объявленном порядке; первый ключ (здесь main) становится контейнером по умолчанию для kubectl logs и подобных инструментов.
apiVersion: aggrega.ai/v1beta1kind: Workloadreplicas: {{ optional .infra `replicas` 2 }}containers: main: image: "{{ .values.app_image }}" ports: app: {{ optional .values `app_port` 8080 }} variables: UPSTREAM_URL: "http://localhost:{{ optional .values `app_port` 8080 }}" sidecar: image: "{{ .values.sidecar_image }}" ports: proxy: {{ optional .values `proxy_port` 9000 }} variables: PROXY_TARGET: "http://localhost:{{ optional .values `app_port` 8080 }}"services: external: type: ClusterIP ports: proxy: {{ optional .values `proxy_port` 9000 }}Service открывает порт sidecar (а не основного контейнера), направляя внешний трафик через sidecar к основному контейнеру через localhost. Два контейнера разделяют сетевое пространство имён пода, поэтому localhost:<port> напрямую достигает соседнего контейнера. Для sidecar, которым нужна инъекция учётных данных (канонический шаблон AI-ограничителя), учётные данные обычно находятся в блоке attachments: sidecar, а не основного контейнера, — так они ограничены границей процесса sidecar.
Выбор шаблона
Три шаблона соответствуют разным задачам формы поставки:
- Сервер с метриками — долгоживущие сервисы, которые кластер поддерживает в работе; несколько публикаций Service для разделения трафика.
- Пакетное задание — ограниченное выполнение; без публикации Service; входные данные берутся из ConfigMap, выпущенного Recipe, или из внешнего состояния.
- Пара с sidecar — многоконтейнерный под с общим сетевым пространством имён; Service sidecar открывает сквозную функцию.
Четвёртый шаблон — сервер с состоянием и постоянным томом — задаёт form: stateful и объявляет хранилище для каждой реплики через volumes.<name>.persistentTemplate; провайдер helm выпускает StatefulSet для формы с состоянием (см. providers/helm.md). По форме шаблон идентичен «серверу с метриками» с form: stateful, дополнительным томом persistentTemplate и ровно одним сервисом type: Headless для управления StatefulSet (без него сборка останавливается); авторам, которым он нужен, следует адаптировать шаблон 1 со всеми тремя объявлениями.
Перекрёстные ссылки
- ../../architecture/16-recipe-input-composition.md — архитектурная роль вида Workload и полная поверхность схемы.
- ../entities/recipe.md — как
workload:сочетается с двумя другими видами входных данных Recipe. - ../entities/component.md — составление
featuresSchema, на которую ссылаются блокиattachments:в Workload. - ../entities/featurerecipe.md — вспомогательные ресурсы уровня Feature, которые размещаются рядом с Workloads.
- ../vocabulary/data-pillars.md — контракт доступа к опорам данных при вычислении шаблонов.
- ../templates/expansion-matrix.md — место вычисления Workload в матрице вычисления шаблонов.