Перейти до вмісту
AggregaAggrega
Обрати мову: Українська
Цю сторінку перекладено машинним способом. Читати оригінал англійською.

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: приймає одне джерело — див. ../vocabulary/cross-document-ref.md, щоб дізнатися про ширшу відмінність між $ref: і $import:.

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 — сплощений ідентифікатор екземпляра вузла; префікс імен ресурсів, які видає provider, що називає синтезовані ресурси за ідентичністю.
  • .context.rendered_name — ім’я, яке дає синтезованим ресурсам provider, що сам виводить для них ім’я, наприклад ім’я release у helm; присутнє лише там, де provider його повідомляє. Див. ../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, відображає форму на власну нативну форму:

formKubernetes (helm)Compose
statelessDeploymentсервіс (без постійного тому)
statefulStatefulSetсервіс + іменований том
daemonDaemonSetзупиняє збирання
scheduledCronJobзупиняє збирання
taskJobзупиняє збирання

Провайдери terraform і cloudformation рендерять Recipes із джерелом і Recipes лише з артефактами та не синтезують Workload: Recipe, що оголошує workload: і прив’язаний до будь-якого з них, зупиняє збирання із зазначенням видів вхідних даних, які підтримує провайдер.

Якщо цільовий provider не має чистого відображення для форми, збірка явно зупиняється, а не перетворює робоче навантаження на форму, яка спотворює намір: вибір форми, яку цільова межа не може виразити, — це помилка під час збірки, а не тихе погіршення. Provider compose зупиняється на daemon, scheduled і task. Provider helm створює CronJob для scheduled (див. schedule нижче) і зупиняється лише тоді, коли розклад відсутній або некоректний.

apiVersion: aggrega.ai/v1beta1
kind: Workload
form: stateful
containers:
db: { image: "postgres:16", ports: { db: 5432 } }
volumes:
data:
persistentTemplate:
size: "20Gi"
services:
headless:
type: Headless
ports:
db: 5432

schedule

schedule — це розклад cron для робочого навантаження form: scheduled, супутнє поле, яке надає повторюваній формі її періодичність. Це один рядок в одному канонічному форматі:

  • стандартний 5-польовий вираз crontab — хвилина, година, день місяця, місяць, день тижня (наприклад, 0 0 * * * — щодня опівночі, */15 * * * * — кожні п’ятнадцять хвилин), або
  • один із макросів @hourly, @daily, @weekly, @monthly, @yearly.

schedule є обов’язковим, коли form: scheduled, і має сенс лише тоді. Робоче навантаження form: scheduled без розкладу, розклад, який не є ні 5-польовим виразом, ні розпізнаним макросом (6-польовий вираз із секундами на початку, нерозпізнаний @-токен або поле з неприпустимими символами), або schedule, заданий для будь-якої іншої форми, зупиняють збірку з повідомленням, що називає виправлення. Provider helm передає значення дослівно в spec.schedule створеного CronJob.

apiVersion: aggrega.ai/v1beta1
kind: Workload
form: scheduled
schedule: "0 2 * * *" # daily at 02:00
containers:
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/v1beta1
kind: Workload
form: scheduled
schedule: "0 2 * * *" # documents when it would run; nothing starts it while suspended
suspend: true
containers:
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 — це проста мапа рядок → рядок для змінних середовища. Мапа поєднує два різні джерела даних через шаблонні вирази Go: літерали стовпа розробника (записи, шаблонні вирази яких читають .values / .infra / .locals — дані, що походять зі стовпів сутності Component) і дані міжкомпонентного каналу (записи, шаблонні вирази яких читають .context.inject.env.<KEY> — дані, що походять із provides: іншого компонента й передаються через канал топології). Обидва джерела потрапляють у ту саму мапу variables; автори вибирають одне для кожного запису залежно від того, чи значення локальне для компонента, чи похідне з іншого компонента. Типові шаблони: LOG_LEVEL: "{{ .values.log_level }}" — стовп розробника (локально для компонента); DB_HOST: "{{ .context.inject.env.DB_HOST }}" — міжкомпонентний канал (значення походить із provides.host цільового компонента й передається через оголошення uses[].inject.env.DB_HOST викликача). Обидві форми компілюються в єдиний список Kubernetes env: у згенерованому 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Примітки про втрати
ephemeralemptyDir: { sizeLimit }запис tmpfs: на рівні сервісу, що вказує шлях монтування (у пам’яті)Compose tmpfs розміщується в RAM; emptyDir у helm за замовчуванням розміщується на диску вузла — семантична розбіжність у базовому носії зберігання. sizeLimit не потрапляє в жодну частину виводу compose: згенерований запис — це лише шлях монтування. Заданий sizeLimit спричиняє попередження unsupported-field, що його називає; воно повідомляється разом зі збиранням, а не записується в згенерований файл.
configmapПосилання на том ConfigMap (використовує ресурс ConfigMap, згенерований через artifacts: сутності Recipe або сутністю Feature)Посилання configs: на рівні сервісу, що називає configmap і монтується за шляхом монтування тому; відповідний запис configs: верхнього рівня походить з artifacts: сутності RecipeОбидві цілі посилаються на configmap за іменем, і жодна не читає його вміст, тож форма авторингу симетрична. Compose втрачає семантику оновлення під час розгортання, притаманну K8s ConfigMap: конфігурація compose фіксується на вмісті, який згенерувало збирання. Посилання, яке не розв’язується жодним записом верхнього рівня, зупиняє збирання, а не генерує монтування, що було б висячим під час виконання.
secretПосилання на том Secret (використовує Secret, який називає приєднання облікових даних, — той, що генерує його FeatureRecipe, або той, що вже існує)env_file: для секретів у формі змінних середовища або bind-змонтований файл секрету для секретів у формі шляхуCompose не має повноцінної семантики Kubernetes Secret. Секрет у формі шляху навмисно не йде маршрутом configs: варіанта configmap: вбудований запис конфігурації записав би значення секрету у згенерований файл compose відкритим текстом, а компілятор ніколи не розв’язує секрет у відкритий текст. Джерело bind — це шлях, який оператор робить доступним на хості compose, поза будь-яким життєвим циклом CRD для отримання зі сховища секретів.
persistentРесурс PVC + volume.persistentVolumeClaimІменований томІменовані томи compose — це пласка абстракція на боці хоста; PVC у helm підтримує оголошення класу сховища, режиму доступу та ємності, які compose ігнорує.
persistentTemplateStatefulSet.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 керівного Service: оголосіть рівно один сервіс із type: Headless у тій самій сутності Workload. Провайдер пов’язує serviceName StatefulSet з цим headless Service (він надає стабільні мережеві ідентичності кожного pod, потрібні StatefulSet). Збирання зупиняється, якщо не оголошено жодного headless-сервісу — StatefulSet не має керівного Service, який можна назвати, — або якщо їх оголошено більше одного, через що керівний Service стає неоднозначним. Робоче навантаження 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Досяжністьhelmcompose
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, а не через ім’я, яке може розв’язатися в ::1. Оголошений транспорт записується в записі так само, як для будь-якого опублікованого порту, наприклад 127.0.0.1:5514:5514/udp.

Якщо два записи називають той самий порт, перемагає ширша досяжність: порт, який публікує запис NodePort або LoadBalancer, публікується на всіх інтерфейсах, навіть якщо його називає й запис Loopback, незалежно від того, котрий із двох оголошено першим.

У helm запис Loopback зупиняє збірку, а не відтворюється як щось, чим він не є. Kubernetes Service не має типу, що прив’язується до loopback-адреси хоста — те, на яких адресах вузлів слухає Service NodePort, є налаштуванням усього кластера, а не окремого Service, — тож Service 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: імена Kubernetes Service обмежені 63 символами, а синтезована форма <release name>-<service-key> може перевищити цю межу, коли обидва сегменти довгі. Компілятор Aggrega не перевіряє цю межу; збирання виводить Service, а Kubernetes відхиляє його під час застосування. Авторам із глибоко вкладеними ID екземплярів (наприклад, data-layer.regional.eu-west.primary) і довгими ключами сервісів слід тримати сумарну довжину в межах 63 символів. Те саме стосується Workload вкладення: складену ідентичність, задовгу для цілі, скорочують, але доданий до неї ключ сервісу — ні, тож Service вкладення з довгим ключем однаково може перевищити 63 символи й зібратися без зупинки.

Примітка для конкретного Provider (compose). Провайдер compose автоматично виводить depends_on з ребер використання в 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-портом.

Поведінка за цілями.

ЦільПорт без оголошеного транспортуОголошений транспорт
helmcontainerPort і порт 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: /pathhttpGet.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 має одну перевірку стану, тож якщо 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 внутрішні значення передаються дослівно до специфікації pod, згенерованої helm.

scheduling

scheduling групує чотири нативні для K8s примітиви планування — nodeSelector, affinity, tolerations, topologySpreadConstraints — в один блок, упорядкований за призначенням. Кожне підполе має точно таку форму, як відповідне поле специфікації pod у Kubernetes:

apiVersion: aggrega.ai/v1beta1
kind: Workload
scheduling:
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: ScheduleAnyway
containers:
app: { image: "..." }

Трансляція Provider. Провайдер helm передає кожне підполе дослівно в згенеровану специфікацію pod. Провайдер compose не транслює жодного з чотирьох: він пропускає весь блок scheduling, і попередження його називає.

serviceAccount

serviceAccount — це простий рядок з іменем ServiceAccount, під яким працює робоче навантаження:

apiVersion: aggrega.ai/v1beta1
kind: Workload
serviceAccount: "{{ .context.rendered_name }}-runner"
containers:
app: { image: "..." }

Ім’я будується з {{ .context.rendered_name }} — імені релізу, за яким helm-провайдер називає власні ресурси робочого навантаження, тож кластер прийме його незалежно від назви компонента. Поле посилається на наявний ServiceAccount; воно його не створює. Супровідні ресурси RBAC (сам об’єкт ServiceAccount, а також Role / RoleBinding / ClusterRole / ClusterRoleBinding) слід постачати одним із двох каналів:

  • Recipe artifacts: — коли RBAC є невід’ємною частиною цього Recipe (Recipe знає, що йому потрібна певна Role для певного завдання).
  • Features з генерацією ресурсів — коли RBAC є наскрізним (FeatureRecipe для Workload-Identity, що прив’язує пов’язані з IAM ServiceAccounts до кожного компонента з певною міткою).

Встановлення serviceAccount: без забезпечення існування названого ServiceAccount призводить до помилки K8s під час виконання, на етапі apply, а не до помилки збірки — валідація схеми робочого навантаження не перевіряє існування ServiceAccount (згідно з інваріантом AOT-чистоти, під час компіляції немає доступу до стану кластера).

Compose-провайдер ігнорує serviceAccount: з попередженням; у Compose немає відповідного поняття прив’язки ідентичності.

podSecurityContext

podSecurityContext містить примітиви безпеки рівня pod — UID, GID, fsGroup, supplementalGroups, — які застосовуються до кожного контейнера в pod:

apiVersion: aggrega.ai/v1beta1
kind: Workload
podSecurityContext:
runAsUser: 1000
runAsGroup: 3000
fsGroup: 2000
supplementalGroups: [4000, 5000]
containers:
app: { image: "..." }

Семантика полів. Усі чотири поля є цілими числами (числові UID/GID, а не рядки); runAsUser і runAsGroup задають ефективні UID/GID процесів контейнера; fsGroup задає групу-власника для томів, змонтованих у pod; 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 контейнера, що заміняє значення pod; він пропускає runAsNonRoot, allowPrivilegeEscalation і runAsGroup, записаний без runAsUser, з попередженням для кожного, а також попереджає, коли власний runAsUser контейнера залишає поза увагою runAsGroup pod. Відповідність поле за полем наведено в providers/compose.md.

Робочі навантаження з GPU та пристроями

Робоче навантаження, якому потрібне спеціалізоване обладнання — GPU або інший пристрій від постачальника, — виражає дві незалежні потреби: середовище виконання рівня pod, яке надає вузол із пристроєм (runtimeClassName), і кількість пристроїв на контейнер, яку заявляє робоче навантаження (ключ розширеного ресурсу в resources контейнера). Типове робоче навантаження з GPU оголошує обидва разом, але кожне з них самостійне, і будь-яке може з’являтися без іншого.

Обидва поля описують обчислення — pod і контейнер, що працює на пристрої, — тому вони належать робочому навантаженню, яке запускає контейнери. Робоче навантаження, що містить лише зовнішню кінцеву точку й не оголошує власних контейнерів, не має pod чи контейнера, до яких їх можна прив’язати: задання runtimeClassName для такого робочого навантаження лише з кінцевою точкою зупиняє збирання з указанням runtimeClassName і сутності Recipe, чия сутність Workload його оголосила, а без контейнерів запит ресурсу пристрою нікуди розмістити.

runtimeClassName

runtimeClassName — це один рядок з іменем RuntimeClass, під яким працює pod, — середовища виконання контейнерів, яке надає вузол із пристроєм, наприклад середовище GPU з іменем nvidia. Це селектор рівня pod: він застосовується до кожного контейнера робочого навантаження. Компілятор передає ім’я без змін як детермінований вказівник; кластер зіставляє його з 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/v1beta1
kind: Workload
runtimeClassName: nvidia
containers:
inference:
image: "{{ .values.image }}"
resources:
requests:
cpu: "2"
memory: "8Gi"
nvidia.com/gpu: "1"
limits:
nvidia.com/gpu: "1"

Робоче навантаження вибирає середовище nvidia для свого pod і заявляє один GPU для контейнера inference. Кількість GPU вказано і в requests, і в limits: пристрій не допускає надмірного розподілу, тому його запит і ліміт мають однакове значення.

Трансляція провайдером. Це концепції, притаманні Kubernetes. Провайдер helm виводить runtimeClassName у відрендерену специфікацію пода, а кожен ключ розширеного ресурсу — дослівно в resources.requests / resources.limits контейнера, тож вони потрапляють до кластера через вивід для Kubernetes. Провайдер compose резервує кількість nvidia.com/gpu як стільки ж GPU NVIDIA на сервісі контейнера (див. Compose Provider → Ресурси контейнера); окремий хост не має концепції класу середовища виконання й аналога для будь-якого іншого ключа розширеного ресурсу, тому робоче навантаження, що оголошує runtimeClassName або інший ключ, рендериться на цілі compose без нього.

Запуск у мережі вузла

За замовчуванням робоче навантаження працює у власному мережевому просторі імен: його контейнери бачать лише власні інтерфейси, а трафік надходить до них через трансляцію адрес цільового середовища. hostNetwork: true запитує інше влаштування — робоче навантаження працює у власному мережевому просторі імен вузла, тож воно бачить інтерфейси вузла, а порти, які відкривають його контейнери, доступні на власних адресах вузла, без жодної трансляції між ними.

Саме це потрібно цілому класу програмного забезпечення. Медіа в реальному часі, телефонія, віртуальні приватні мережі та подібний трафік передають адресу співрозмовника всередині корисного навантаження, тож адреса, переписана під час передавання, приходить, описуючи місце, якого співрозмовник не може досягти; саме робота на адресах вузла зберігає їх узгодженими.

apiVersion: aggrega.ai/v1beta1
kind: Workload
hostNetwork: true
containers:
media:
image: "{{ .values.image }}"
ports:
rtp:
port: 7881
protocol: UDP

Що це оголошує, а що ні

hostNetwork обирає мережевий простір імен, і це все.

  • Це не оголошує портів. Порти, які відкриває робоче навантаження, і далі оголошуються в containers.<name>.ports, точно так само, як і без нього, і означають те саме. Оголошення hostNetwork не додає порту й не скасовує потреби його оголошувати.
  • Це не оголошує кількості портів. Застосунок, якому потрібно багато суміжних портів, — скажімо, медіа- сервер, що визначає розмір діапазону за кількістю процесорів машини, — налаштовує цей діапазон у власному тілі конфігурації, зі значень, які надає його оператор, так само, як налаштовує будь-що інше, що читає під час запуску. Це налаштування застосунку, а не робочого навантаження, і контракт робочого навантаження — не те місце, де воно живе.
  • Нічого не виводиться. Компілятор не вкладає в значення жодного змісту й не виводить його ні з чого іншого: ні з назви порту, ні з типу чи міток компонента, ні з кількості оголошених портів. Робоче навантаження працює в мережі вузла тоді й лише тоді, коли саме це заявляє.

Оскільки hostNetwork описує обчислення, він належить до робочого навантаження, яке запускає контейнери. Робоче навантаження, що містить лише зовнішню кінцеву точку, не оголошує контейнерів, тож йому немає з чого вибирати простір імен мережі: оголошення hostNetwork на робочому навантаженні лише з кінцевою точкою зупиняє збирання, називаючи hostNetwork і Recipe, чий Workload його оголосив.

Трансляція в Provider

Провайдер helm виводить hostNetwork: true у відрендерену специфікацію пода — саме так Kubernetes виражає той самий вибір. Оголошення потрапляє до специфікації пода й нікуди більше — виведені Services однакові з ним і без нього.

Провайдер compose виводить network_mode: host у власний сервіс робочого навантаження. Один наслідок випливає з того, як compose моделює мережі: сервіс у цьому режимі не під’єднаний до мережі межі, бо compose розглядає під’єднання до мережі та перейняття простору імен хоста як альтернативи, а не доповнення. Тому його співрозмовники досягають його на власних адресах хоста, а не за назвою сервісу, — що й означає мережа хоста на будь-якому цільовому середовищі, — а всі інші сервіси межі це не зачіпає.

На цьому цільовому середовищі з ним поєднуються дві форми. Контейнер-sidecar слідує за основним сервісом у мережу хоста без жодних оголошень, бо переймає простір імен основного сервісу, називаючи його. Init-контейнер — ні: він стає сервісом, на який чекає основний сервіс, тож приєднується до мережі межі самостійно, а не переймає простір імен, що зробило б це очікування циклічним. Тому робоче навантаження, яке оголошує і hostNetwork, і initContainers, запускає власний сервіс у мережі вузла, тоді як його init-сервіси залишаються в мережі межі, — це вужче влаштування, ніж єдиний спільний простір імен, який дає форма пода, і провайдер 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. Сутність Workload, що оголошує as: 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. Helm рендерить описане вище посилання secretKeyRef/secret-том. Compose-провайдер не має власного примітива env-from-secret; запис вкладення as: env у сутності Workload, націленій на compose, рендериться як запис середовища з порожнім значенням і попередженням, що називає цей запис (див. сторінку compose-провайдера), тоді як правило посилальності (незалежне від можливостей) однаково застосовується.

Приклад:

# In the Component catalog entity
spec:
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 Workload
workload: |
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 entity
spec:
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 — той, що опублікували облікові дані з’єднання 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:, виключення blackbox) і щодо розв’язаних provides кожного слота, на який є посилання (придатність до посилання — заповнення має публікувати name/key). Це міжсутнісні перевірки, яких не може виконати валідація лише за схемою.

Обидва етапи створюють повідомлення однакової форми з префіксом CATALOG_ERROR; збої зупиняють збірку до створення будь-якого результату рендерингу. Автори сутностей Recipe отримують точний відгук, що визначає конкретне поле, яке не пройшло перевірку, і обмеження, що його відхилило.

Наскрізні поля у формі K8s (scheduling.affinity, scheduling.tolerations, scheduling.topologySpreadConstraints, списки items у томах ConfigMap і Secret, хуки життєвого циклу httpGet) проходять лише структурну валідацію — схема Aggrega обмежує їхню наявність і зовнішню форму, але за внутрішню форму цих значень, визначених K8s API, відповідає провайдер (провайдер 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 у ../../architecture/16-recipe-input-composition.md.
  • Features із генерацією ресурсів — для наскрізних аспектів, що приєднуються через селектори сутності Release (Feature ServiceMonitor, приєднаний до кожного компонента, що експонує метрики, Feature NetworkPolicy, приєднаний до кожного робочого навантаження в продакшені). Поверхню створення 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/v1beta1
kind: Workload
replicas: {{ 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: 5
services:
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/v1beta1
kind: Workload
form: task
containers:
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/config
volumes:
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/v1beta1
kind: Workload
replicas: {{ 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 з усіма трьома оголошеннями.

Перехресні посилання