Aggregate
Концептуальна роль сутності Aggregate (Домен 1 — декларативний план топології від розробника) описана в architecture/04-entity-taxonomy.md. Шаблони композиції (підсистеми, вкладені агрегати, домовленість Zero-Port, підняття параметрів) описані в architecture/06-data-taxonomy-and-composition.md. Ця сторінка охоплює поверхню створення каталогу сутностей Aggregate — зокрема, створення багаторазових модулів Aggregate для розповсюдження через каталог.
Область видимості Component: підсистема за замовчуванням
Сутність Aggregate організовує компоненти в підсистеми — іменовані групи для наскрізних аспектів (рівень даних, периферійний рівень), які мають власний каскад анотацій. Більшість сутностей Aggregates мають одну групу, тож вона не потребує жодних формальностей.
Одна область (за замовчуванням). Описуйте компоненти безпосередньо в spec.components: і пропустіть блок subsystems::
spec: components: api: type: core/server:1.0.0 worker: type: core/worker:1.0.0Компілятор згортає їх у синтезовану підсистему default. Ідентичність вузлів не змінюється — api лишається api, а не default.api, — тому сутність Aggregate, описана таким чином, взаємозамінна з явною формою з однією підсистемою, а для звертання до неї (у цілях uses:, у діагностиці) використовується простий шлях spec.components.<name>. Синтезована область чесно фіксується в експортованому IR (з позначкою синтезованої підсистеми), але ніколи не з’являється в шляхах, які автор пише або читає.
Кілька областей. Коли компоненти розподіляються на окремі наскрізні групи, оголосіть іменовані підсистеми в subsystems:. Кожна підсистема має власні компоненти й каскад анотацій і може містити вкладені підсистеми.
Взаємовиключність. spec.components: і spec.subsystems: є взаємовиключними в корені сутності Aggregate — використовуйте одне або інше, але ніколи обидва. Документ, що оголошує обидва, зупиняється під час завантаження з помилкою конверта. (Підсистема, яку розробник явно назвав default, є звичайною оголошеною підсистемою, до якої звертаються за її кваліфікованим шляхом spec.subsystems.default.components.<name>, — пропуск синтезованої області залежить від походження, а не від імені.)
Багаторазові модулі Aggregate
Сутності Aggregates виконують роль і кореневої сутності Aggregate, яку збирає Release, і багаторазових модулів. Батьківська сутність Aggregate може оголосити дочірню сутність Aggregate точно так само, як компонент, передаючи в неї parameters. Щоб уникнути тісного зв’язування, дочірні сутності Aggregates надають контракт exportedComponents:, що встановлює стабільне ім’я публічного інтерфейсу. Батьківська сутність досягає компонентів модуля лише через цей інтерфейс: ціль uses: — це ім’я модуля, крапка та один з його експортованих псевдонімів, а компілятор підключає ребро до внутрішнього компонента, який називає псевдонім. Ціль, що сягає всередину модуля під будь-яким іншим ім’ям — ім’ям компонента всередині модуля або шляхом у вкладений у нього модуль, — зупиняє збірку, називаючи модуль і псевдоніми, які він експортує; див. A uses target names a module’s component the module does not export (Ціль називає компонент модуля, який модуль не експортує).
Навіщо явний список exportedComponents:. Автори модуля вирішують, які з його компонентів утворюють публічний інтерфейс, а які залишаються деталлю реалізації. Оскільки батьківська сутність може назвати лише те, що публікує список, нутрощі модуля можна рефакторити — перейменувати компонент, розділити один компонент на два, замінити worker керованим сервісом, — не ламаючи жодної батьківської сутності, доки кожне опубліковане ім’я й далі вказує на компонент. Список коштує один запис на кожен опублікований компонент, і компонент можна опублікувати під його власним ім’ям (store: store), якщо саме це ім’я мають використовувати ті, хто імпортує. Те саме правило діє всередині композиції: модуль досягає модуля, який імпортує, через експортовані псевдоніми цього модуля. Release може з’єднати два компоненти одного модуля між собою, оскільки таке з’єднання не перетинає інтерфейсу жодного модуля.
Повторний експорт інтерфейсу вкладеного модуля. Запис exportedComponents: може вказувати на експортований псевдонім вкладеного підагрегата, а не на безпосередньо оголошений компонент — тобто модуль повторно публікує частину імпортованого модуля під назвою власного інтерфейсу і, за бажання, під новою назвою. Ребро uses:, що націлене на такий повторно експортований псевдонім, транзитивно розв’язується через ланцюжок до конкретного внутрішнього вузла, тож модуль складає глибші модулі у свій публічний інтерфейс, не розкриваючи їхньої внутрішньої структури, а споживачеві ніколи не потрібно знати, наскільки глибоко вкладено ціль. Дисципліна стабільного інтерфейсу діє на кожному кроці: кожен модуль повторно експортує лише те, що вирішив опублікувати. Повторно експортована ціль, що не розв’язується в жоден внутрішній вузол, явно зупиняє збірку так само, як пряма висяча ціль, а ланцюжок повторного експорту, що замикається сам на себе, відхиляється, а не обходиться нескінченно.
Оголошення модуля перевіряються так само, як оголошення Aggregate. Документ модуля читається лише тоді, коли збирається композиція, що його імпортує, і його оголошення перевіряються з цього моменту на будь-якій глибині вкладення. Власний блок inject: компонента модуля підпорядковується списку дозволених spec.inject його типу, а також правилам, що забороняють двічі заявляти один ключ доставки та читати ключ, якого тип не публікує. Приєднання, записане в одній із власних підсистем модуля, може називати лише сокет, який оголошує його сутність Feature, і так само приєднання, яке сутність Release записує для компонента, наданого модулем.
Приєднання підсистем модуля поширюються на його компоненти. Feature, яку модуль приєднує в одній із власних підсистем, каскадно поширюється на кожен компонент, який модуль оголошує під цією підсистемою, включно з вкладеними підсистемами, точно так само, як приєднання підсистеми в Aggregate, — і лише на ці компоненти, ніколи на компонент імпортувального Aggregate під підсистемою з тією самою назвою. Воно обчислюється одразу після власних приєднань компонента, зовнішні підсистеми перед внутрішніми. Для поля, яке записують обидва, перемагає власне однойменне приєднання компонента, а поля, які воно пропускає, зберігають значення підсистеми. Кожен компонент, якого воно досягає, перевіряє його за appliesTo сутності Feature. Знахідка щодо власних оголошень модуля називає модуль і ключ у його документі — наприклад, .spec.subsystems.<subsystem>.features.<attachment>, — тож зміну вносять у модулі, де розташоване оголошення, а не в Aggregate, що його імпортує.
Розташування в каталозі
Багаторазовий модуль Aggregate розміщується в каталозі виду aggregate/ за шляхом, який посегментно задає його metadata.name, з каталогом версії на кінцевому рівні:
aggrega-catalog/└── aggregate/ └── {module-name}/ # the module's metadata.name, segment for segment └── {version}/ # the module's metadata.version └── aggregate.yaml # The module definitionНазва модуля може мати початковий сегмент {publisher}, що називає постачальника або автора — core для стандартної бібліотеки, acme для підприємства, — і опубліковані модулі стандартної бібліотеки названо саме так: core/agenta розміщується в aggregate/core/agenta/1.0.0/aggregate.yaml. Назва з одного токена розміщується на рівень вище, у aggregate/{module-name}/{version}/aggregate.yaml. Обидві форми коректні; назву пише автор, а каталог її віддзеркалює. Це віддзеркалення — домовленість каталогу, а не те, що перевіряє компілятор: модуль знаходять за назвою, яку він оголошує, а не за тим, де лежить його файл.
OCI URI: hub.aggrega.ai/aggregate/{module-name}:{version}, у нижньому регістрі — тож модуль із назвою core/agenta публікується в hub.aggrega.ai/aggregate/core/agenta:1.0.0, а модуль db-module — у hub.aggrega.ai/aggregate/db-module:1.0.0.
Шаблон модуля
Дочірній модуль (aggregate/child-database-module/1.0.0/aggregate.yaml, опублікований як hub.aggrega.ai/aggregate/child-database-module:1.0.0):
apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: child-database-module version: 1.0.0spec: components: internal-pg-primary: type: core/postgres:1.0.0
exportedComponents: # The Public Contract (Written once by the module author) primary_db: "internal-pg-primary"Батьківська сутність Aggregate:
apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: parent-app version: 1.0.0spec: aggregates: finance-db-subsystem: type: child-database-module:1.0.0
components: billing-api: type: core/python-worker:1.0.0 uses: databases: - finance-db-subsystem.primary_dbМітки модуля
Коли сутність Aggregate публікують у каталозі як багаторазовий модуль, вона може мати metadata.labels у своїй YAML-оболонці — наприклад, aggregate.aggrega.ai/tier: infrastructure або aggregate.aggrega.ai/compliance: pci-dss. Ці мітки описують ідентичність модуля і зберігаються в опублікованому документі модуля; поки що жодна команда їх не читає. Пошук у каталозі не індексує сутності Aggregates, а граф збірки не містить ні міток модуля, ні його імені в каталозі, тож політика управління не може вибирати компоненти модуля за модулем, з якого вони походять.
Ключова відмінність. Мітки Aggregate описують ідентичність багаторазового модуля в каталозі. Вони не каскадуються вниз на дочірні вузли компонентів. Мітки компонентів походять виключно з каталожної сутності Component у Домені 2. Якщо розробник імпортує модуль із міткою aggregate.aggrega.ai/tier: infrastructure, окремі компоненти всередині цього модуля зберігають лише власні мітки, визначені в каталозі (напр., component.aggrega.ai/type: stateful-server). Мітка Aggregate ніколи не вставляється в словник labels вузла IR.
Повне обговорення складених сутностей Aggregates і шаблону модуля (зокрема правило про відсутність підкомпонентів для сутностей Components), а також механізм наскрізного групування subsystems див. у architecture/06-data-taxonomy-and-composition.md §6. Поверхню створення типізованого контракту parameters див. у vocabulary/data-pillars.
Типізовані контракти параметрів
Блок spec.parameters: сутності Aggregate оголошує типізований контракт для параметрів, які заповнює сутність Release. Кожен слот параметра має оголошений type, необов’язковий description, необов’язковий default, необов’язкові обмеження простору значень і (для слотів об’єктного типу) вкладену структуру. Під час розв’язання компілятор перевіряє кожне значення, надане сутністю Release, на відповідність контракту, ще до інтерполяції параметрів.
apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: web-app version: 1.0.0spec: parameters: region: type: string description: Cloud region the deployment targets enum: [us-east-1, us-west-2, eu-west-1, ap-northeast-1] default_locale: type: string description: Default UI locale presented to end users enum: [en-US, en-GB, fr-FR, ja-JP] default: en-US enable_debug: type: boolean description: Toggle verbose request logging default: false feature_flags: type: object description: Per-feature enablement map valuesType: { type: boolean } default: {} allowed_hosts: type: array description: Hostnames the ingress accepts items: { type: string, format: hostname } min: 1 default: ["web-app.example.com"]
components: web: type: core/web-server:1.0.0 values: default_locale: "{{ .parameters.default_locale }}" region: "{{ .parameters.region }}" debug: {{ .parameters.enable_debug }}Лапки в кожному посиланні поставлено навмисно: саме вони визначають тип, з яким надходить піднесене значення. Див. templates/parameters-context.md.
Словник слотів параметрів
Типізований блок parameters: приймає словник компактної форми: type, description, default, enum, min, max, pattern, minLength, maxLength, format, validate і validateMessage (власна перевірка та повідомлення, яке вона видає), items (для масивів), properties (для об’єктів), valuesType (для мап типізованих значень) і required: true (позначка для окремого слота). Три з цих ключових слів приймають як значення контракт, а не просте налаштування, — items, valuesType і кожен запис у properties, — і в слоті параметра такий вкладений контракт записується в тій самій типізованій формі, що й слот навколо нього: valuesType: { type: boolean }, а не valuesType: boolean. Перед інтерполяцією компілятор безпосередньо перевіряє об’єднану мапу параметрів на відповідність цим оголошенням: параметр, який не оголошено жодним слотом, відхиляється; слот із позначкою required: true, який не заповнює сутність Release і не забезпечує default, зупиняє збірку; кожне надане значення перевіряється на відповідність оголошеному type свого слота, належність до enum, межі minLength і maxLength, регулярний вираз pattern і format у рядковому слоті, а також межі min і max — значенню числового слота, довжині рядкового слота й кількості елементів слота-масиву. Слоти об’єктів і масивів перевіряються рекурсивно: кожен запис у properties і кожен елемент щодо items перевіряється так само, контракт valuesType керує ключами, яких не називає properties, а вкладений ключ, якого не називає жодне оголошення, відхиляється. Повний словник ключових слів див. у vocabulary/compact-form-authoring.md, зокрема там, де стовп schema: записує ці ключові слова інакше.
Наведені нижче ключові слова також перевіряються в самому оголошенні, ще до читання будь-якого значення сутності Release, тож слот, який не міг би нічого обмежити, зупиняє збірку, навіть якщо жодна сутність Release його не заповнює:
- Межі довжини — нуль або більше. Від’ємний
minLengthабоmaxLengthу власному оголошенні параметра відхиляє схема сутності Aggregate під час завантаження сутності Aggregate, називаючи параметр і ключ. Усередині вкладеного контракту — уitems,propertiesабоvaluesType— межа довжини читається так, як записана, і під час завантаження сутності Aggregate не перевіряється на цю нижню межу, тож і там записуйте її як нуль або більше: від’ємнийminLengthнічого не обмежує, а від’ємнийmaxLengthвідхиляє будь-яке значення. minіmaxмають щось обмежувати. У логічному чи об’єктному слоті ця пара нічого не обмежує, тожminабоmax, записані там, відхиляються під час завантаження сутності Aggregate з указанням параметра й ключа.- Шаблон має компілюватися. Кожен
patternкомпілюється як регулярний вираз під час читання контракту параметрів — у самому слоті та всередині будь-якого вкладеного контракту, на будь-якій глибині, — а той, що не компілюється, відхиляється з указанням параметра, шаблону та причини. Контракт читається під час кожної збірки, отримання (pull) і перевірки сутності Release, що доходить до сутності Aggregate, — чи то власної сутності Aggregate цієї сутності Release, чи модуля, який вона імпортує. Потім перевірка значень зіставляє кожне надане значення з тим самим скомпільованим виразом. - Формат має бути таким, який перевіряє компілятор.
formatназиває один із форматівemail,uri,hostname,ipv4,ipv6,uuid,date-timeіdate, записаних так, як їх записує JSON Schema. Будь-яка інша назва — помилка в написанні, як-отemial, або назва, якої JSON Schema не визначає, як-отpassword, — відхиляється під час завантаження сутності Aggregate з указанням параметра та переліком підтримуваних назв: у самому слоті — схемою сутності Aggregate, а всередині вкладеного контракту, на будь-якій глибині, — під час читання контракту параметрів. Наданий рядок, що не має названого формату, потім відхиляється з указанням параметра, значення та формату. Що саме перевіряє кожна назва, описано вvocabulary/compact-form-authoring.md.
Параметри об’єктного типу та типу масиву
Слоти параметрів приймають будь-який тип, який підтримує компактна форма, зокрема вкладені об’єкти та масиви типізованих елементів:
spec: parameters: database_config: type: object description: Database connection configuration properties: host: { type: string, required: true } port: { type: integer, min: 1, max: 65535, default: 5432 } ssl_mode: { type: string, enum: [disable, require, verify-full], default: require } pool_size: { type: integer, min: 1, max: 100, default: 10 }
metric_labels: type: array description: Custom Prometheus labels to attach to scraped metrics items: type: object properties: name: { type: string, required: true } value: { type: string, required: true }Сутність Release заповнює параметри об’єктного типу структурованим YAML; компілятор перевіряє структуру на відповідність оголошеній схемі перед інтерполяцією. Шаблони, що посилаються на поля об’єкта, використовують стандартний синтаксис шаблонів Go: {{ .parameters.database_config.host }}, {{ .parameters.database_config.port }} тощо.
Перевірка контракту параметрів
Спершу перевіряється сам контракт, коли його зчитують, — це перевірки меж довжини та шаблонів, описані вище в розділі «Словник слотів параметрів». Потім під час обробки параметрів компілятор виконує три підкроки:
- Заповнення значень за замовчуванням — слоти, для яких визначено
default:і не надано значення з сутності Release, отримують своє значення за замовчуванням. Параметри з вкладеними об’єктами мають три варіанти семантики для батьківських слотів: пропущений, явно порожній і частково заповнений. Якщо батьківський слот пропущено, заповнюються значення за замовчуванням дочірніх елементів; якщо батьківський слот задано як{}, явна порожнеча зберігається (значення за замовчуванням дочірніх елементів не застосовуються); якщо батьківський слот задано як непорожню мапу, заповнюються лише ті дочірні елементи, яких не надала сутність Release. Приклади YAML і посібник «коли використовувати кожну форму» див. уtemplates/parameters-context.md. - Перевірка контракту — кожне значення в об’єднаній мапі, надане сутністю Release або заповнене з
default:, перевіряється на відповідність оголошеним обмеженнямtype/enum/min/max/pattern/ вкладеної структури. У разі невдалої перевірки збірка зупиняється з чіткою помилкою, яка називає проблемний слот, надане значення та порушене обмеження. Відсутні обов’язкові параметри безdefault:спричиняють аналогічну зупинку з назвою слота. - Інтерполяція — компілятор обчислює весь текст сутності Aggregate як шаблон, перш ніж прочитати його як YAML, і замінює кожне посилання
{{ .parameters.<slot> }}— зазвичай у рядкахvalues:компонента / функції / вкладеного агрегату — на розв’язане значення; будь-яке інше{{у тексті також читається як синтаксис шаблону, тож у значенні, що містить власні подвійні фігурні дужки, — наприклад, в експортованому визначенні платформи потоків, — кожне{{записують як{{"{{"}}, як описано в розділі Текст, що містить власні подвійні фігурні дужки. Після цього проходу поверхні шаблонів значень отримують уже інтерпольовані літерали й не отримують.parametersу своєму контексті шаблону.
Об’єднана мапа параметрів залишається доступною протягом рендерингу, щоб підтримувати обчислення шаблонів шляхів. Шаблони directory: і subDirectory:, які оператор задає на межах сутності Release, читають .parameters.<slot> безпосередньо під час рендерингу відповідно до закритого списку дозволених змінних; для формування шляхів потрібен словник регіонів / середовищ, щоб розкладати артефакти за середовищами, а асиметричний доступ залишає це операторське питання в межах операторської поверхні без проходження через values сутності Aggregate. Мапа залишається доступною для читання, доки не завершаться всі фази рендерингу, і доступна лише з тієї компіляції, для якої її розв’язано; рецепти, що споживають задані розробником values:, бачать рядки після інтерполяції, тоді як шаблони шляхів бачать живі дані .parameters протягом рендерингу. Матрицю доступності шаблонів шляхів див. у рядку 3 templates/expansion-matrix.md, а список дозволених змінних шаблонів шляхів — у path-template-variables.md.
Ширший контрольний список підйому параметрів (оголошення в сутності Aggregate → посилання у values → заповнення в сутності Release → споживання в сутності Recipe) і механіку між стовпами див. у vocabulary/data-pillars.md, §«Parameters» і §«The parameter-hoisting checklist». Поля контексту шаблону, доступні під час інтерполяції, і виняток для шаблонів шляхів див. у templates/parameters-context.md.
Ребро uses — це виклик, який оголошує сутність Aggregate
Ребро uses — це твердження сутності Aggregate про те, що один компонент викликає інший. Компілятор передає значення, які публікує ціль, у компонент, що її викликає, і нічого не обмежує: саме по собі ребро ні допускає того, хто викликає, ні відмовляє будь-кому іншому, а робоче навантаження, яке досягає адреси цілі без ребра, однаково її досягає.
Обмеження того, хто може викликати компонент і що він може викликати, — це рішення оператора, яке ухвалюється для кожного середовища в сутності Release. Якщо сутність Release прикріплює до компонента Feature core/caller-allowlist з каталогу стандартної бібліотеки, збірка записує мережеву політику, яка допускає саме ті компоненти, чиї ребра uses вказують на нього, власні поди цього компонента та джерела, які називає прикріплення. Її вихідний відповідник, core/egress-allowlist, дозволяє компоненту, до якого його прикріплено, досягати лише компонентів, на які вказують його власні ребра uses, його власних подів, DNS кластера та діапазонів адрес, які перелічує сутність Release. Виклик, який сутність Aggregate не оголошує як ребро, кластер тоді може відхилити на будь-якому з кінців — скрізь, де його мережевий плагін застосовує мережеву політику. Тож записуйте ребро для кожного виклику, який роблять ваші компоненти, зокрема для того, що не впроваджує жодного значення: відсутнє ребро — це виклик, який захищений компонент може відхилити. model-server-caller-allowlist показує сервер моделі, доступний лише через шлюз перед ним.
Власні прикріплення з’єднання: features у записі uses
З’єднання, яке компонент описує в розгорнутій формі uses:, є окремим записом, і поруч із target, inject та values воно може містити прикріплення під features:. Кожне з них має ключ — слот, який оголошує сокет: споживаюча сутність Component перелічує в featuresSchema сокета слоти, які може заповнити кожне з’єднання, підключене через цей сокет (див. Сокети топології). Саме так один компонент тримає окремі облікові дані для кожного компонента, до якого звертається, — шлюз, що викликає дві моделі з двома ключами, або агент, що надає моделі власний ключ.
spec: parameters: openai_key_secret: { type: string } components: router: type: core/gateway/litellm # its `models` socket declares a `credential` slot values: { model: gpt } # the alias it publishes as its model uses: models: gpt: target: gpt features: credential: type: core/referenced-secret values: origin: "{{ .parameters.openai_key_secret }}" key: api-key plain: target: plain # this connection carries no attachment gpt: type: core/ai-model/openai values: { model: gpt-4o-mini } plain: type: core/ai-model/ollama values: { model: llama3.1 }Прикріплення на з’єднанні містить type (обов’язково), необов’язковий description і values для сутності Feature. Воно не містить ні uses, ні inject: прикріплення на з’єднанні не вкладаються, а те, як його матеріал доходить до споживача, вирішує Recipe споживаючого компонента, а не блок inject. Документ, у якому записано будь-який із цих ключів, відхиляється під час завантаження з указанням ключа.
Лише слоти, які оголошує сокет. Прикріплення під ім’ям, якого немає у featuresSchema сокета, зупиняє збірку під час завантаження з указанням з’єднання, сокета, компонента та слотів, які сокет оголошує, — а якщо ім’я відрізняється від одного з них на одну правку, то й цього слота як імовірно задуманого написання. Далі заповнений слот на кожному з’єднанні перевіряється на відповідність власному оголошенню слота: selector, якому не відповідають мітки Feature, зупиняє збірку на цьому записі, а слот required, залишений порожнім на будь-якому з’єднанні, зупиняє її з указанням цього з’єднання. Сокет, що не оголошує слотів, не допускає прикріплень на своїх з’єднаннях, як і ситуативний сокет — той, який Aggregate підключає без оголошення в сутності Component, — адже він не оголошує жодних слотів. Компонент, який додає підмодуль, підпадає під те саме правило, і повідомлення вказує на власний документ підмодуля. Див. A connection carries an attachment under a name its socket declares no slot for (З’єднання містить прикріплення під ім’ям, для якого його сокет не оголошує слота).
З’єднання, яке описує Feature, прикріплень не містить. Власний блок uses: прикріпленої сутності Feature — на компоненті чи на підсистемі — записується в тій самій формі, але відхиляє features: під час завантаження документа. Облікові дані, потрібні такому з’єднанню, заповнюють слот, який Feature оголошує у власній featuresSchema, і прикріплюються поруч із Feature; див. Власні облікові дані Feature.
Ім’я, яке отримує прикріплення. Кожне прикріплення з’єднання стає прикріпленням споживаючого компонента з ім’ям <alias>.<slot> — псевдонім, під яким записано з’єднання, крапка і слот: вище це gpt.credential. Крапка — роздільник, зарезервований для імен, які складає компілятор, і жоден псевдонім, слот чи ім’я прикріплення в Aggregate не може її містити, тож складене ім’я ніколи не збігається з іменем, записаним у власному блоці features: компонента; сутність Release, яка вказує його на компоненті чи межі, відхиляється (див. Конфігурація з’єднань для окремих ребер). Це ім’я, за яким рівень окремих екземплярів сутності Manifest визначає ключ прикріплення (див. Плоске відображення URI), ім’я, під яким його показують діагностика та граф IR, і значення, яке FeatureRecipe прикріплення читає як .attachment_name (див. Імена, похідні від прикріплення з’єднання).
Далі воно розв’язується як будь-яке прикріплення: Manifest пов’язує його тип Feature з FeatureRecipe, його values перевіряються за схемою Feature — про помилку повідомляється на записі з’єднання, що їх записав, — а його FeatureRecipe рендериться з власними values та infra прикріплення. Від власних прикріплень компонента його відрізняють дві речі:
- Його немає в
.featuresспоживаючого Recipe. Ця частина містить лише прикріплення, записані у власному блоці компонента, тож Recipe, який шукає в.featuresвласні прикріплення за типом, ніколи не отримає облікових даних з’єднання. Recipe читає прикріплення з’єднання із самого з’єднання, за адресою.context.uses.<alias>.features.<slot>, у тій формі, у якій їх містить.features, — разом із розв’язанимиprovides(див. Прикріплення з’єднання). - Воно потрапляє лише до споживача. Відрендерений вивід цільового компонента однаковий, хоч би що містили з’єднання, які до нього ведуть.
Копія написаного блоку в графі. Граф IR зберігає блок uses: кожного компонента в тому вигляді, у якому його написано, і там прикріплення з’єднання зберігає свої type та description, але жодного зі своїх values. Значення з’являються один раз — на прикріпленні, яке має споживач, де значення, яке Feature оголошує чутливим, приховується.
Сутність Release може задати розмір оголошеного тут прикріплення через infra або прикріпити власне на з’єднанні, до якого вона має доступ, — див. Конфігурація з’єднань для окремих ребер.
Вимкнення компонента або модуля: active:
Екземпляр компонента і модуль субагрегату приймають перемикач active:, який визначає, чи входить ця сутність до скомпільованої топології взагалі. Якщо його пропустити, сутність присутня; це типова поведінка і звичайний випадок.
spec: parameters: enable_cache: type: boolean default: false components: api: type: core/server:1.0.0 redis: type: core/redis:1.0.0 active: "{{ .parameters.enable_cache }}" aggregates: reporting: type: my-catalog/reporting-module:1.0.0 active: falseЗапишіть булеве значення безпосередньо або шаблон над .parameters, що обчислюється до нього. Саме шаблонна форма є причиною існування перемикача: вона дає змогу сутності Release визначати присутність сутності, задаючи параметр, тож один Aggregate охоплює середовища, що відрізняються тим, які частини вони розгортають, — і Release не оголошує нічого, чого не оголосив Aggregate.
Що видаляє хибний перемикач. Сутність відсікається до побудови графа, і відсікання поширюється каскадно: компонент забирає із собою власні ребра uses: і приєднані Features, а модуль — усе, що він додав: свої компоненти, їхні ребра, їхні приєднання. Нічого з того, що принесла відсічена сутність, не рендериться. Чого відсікання не торкається, то це посилання на неї з місця, яке вціліло, — про це наступний абзац.
Уцілілий компонент, що досі вказує на відсічений, зупиняє збірку. Якщо api оголошує ребро uses: на redis, а redis вимкнено, збірка зупиняється, а не дає ребру зникнути, бо тоді впроваджені значення api непомітно залишилися б порожніми під час розгортання. Вирішіть, який із двох належить до цього середовища: увімкніть ціль знову, обмежте споживача тим самим параметром, щоб пара зникала разом, або приберіть ребро з блоку uses: споживача.
Перемикач, який записано, має набувати булевого значення, а порожнє значення таким не є. Перемикач зчитується строго після підстановки його шаблону, і літерал, що не розбирається як булеве значення, зупиняє збірку замість того, щоб набути будь-якого значення за замовчуванням. Випадок, на який варто зважати, — перемикач, що зчитує параметр без значення: він не набуває жодного значення, а якби відсутність значення читалася як «присутній», було б розгорнуто саме ту сутність, яку ви поставили в залежність від цього параметра. Тож записати active: без нічого після нього — це не те саме, що пропустити ключ: лише перемикач, якого ніхто не записав, за замовчуванням означає присутність. Задайте параметру default: у spec.parameters, щоб кожне середовище мало відповідь, або заповніть його в сутності Release. Щоб сутність була присутня безумовно, видаліть ключ active:, а не залишайте його порожнім. Цю зупинку описано під назвою «An active: toggle does not resolve to true or false (Перемикач active: не набуває значення true або false)» у довіднику умов зупинки.
Вимкнений компонент можна й далі називати із сутності Release. Release може й далі називати його в межі, і це навмисно: вимкнення компонента — це дія автора, і не очікується, що Release, який його налаштовує, буде переписано в тому самому редагуванні.
Анотації на підсистемах і компонентах
І підсистеми, і екземпляри компонентів мають поле annotations:. Анотації, які розробник пише на поверхні Aggregate, запускають каскад анотацій на боці Aggregate: анотація підсистеми поширюється на кожну вкладену підсистему та кожен компонент, що в ній міститься, а ближчий рівень перевизначає значення з точністю до окремого ключа. Мапа mappings.features.annotations у сутності Manifest оголошує прив’язки, які під час збирання перетворюють ключі анотацій на синтетичні приєднання Feature. Інваріант «Aggregate як поверхня авторингу» дозволяє цим анотаціям маршрутизуватися лише через шляхи maps.values прив’язки; прив’язка, що оголошує лише шляхи maps.infra, спрацьовує з боку Release, а не з боку Aggregate.
Форми значень
Кожен ключ анотації має одну з чотирьох форм, що розрізняють «я мовчу», «я оголошую значення» — скаляр або структурований об’єкт — та «я відмовляюся»:
- Відсутній ключ — область не оголошує значення для цієї анотації. Вкладені підсистеми та компоненти, що в ній містяться, успадковують будь-яку прив’язку від області-предка.
- Скалярний рядок — одне значення. Прив’язка в Manifest має оголошувати рівно один шлях загалом; скаляр маршрутизується до цього шляху.
- Структурований об’єкт — мапа з підключів у підзначення. Кожен підключ об’єкта маршрутизується через
mapsприв’язки в Manifest до відповідного поля схеми Feature в оголошеному стовпі. - Явний YAML
null— область вилучає зі свого піддерева будь-яку успадковану прив’язку для цього ключа. Сусідні компоненти та сусідні підсистеми зберігають своє успадкування; прив’язку втрачає лише та область, що відмовилася.
spec: subsystems: data: annotations: feature.myco/db-pool: "shared-pool" # scalar value — propagates to api and worker components: api: type: core/server:1.0.0 # inherits feature.myco/db-pool: "shared-pool" worker: type: core/server:1.0.0 annotations: feature.myco/db-pool: null # opts out for this component only special: type: core/server:1.0.0 annotations: feature.myco/db-pool: "vip-pool" # closer-level overrideСтруктуровані значення для багатопольових Features
Feature з кількома полями, що налаштовуються, природно приймає структуроване значення анотації: один ключ анотації несе значення для кількох полів схеми Feature в одному оголошенні. Бік Aggregate запускає лише ті підключі, чий стовп у мапі прив’язки — values; підключі, що маршрутизуються до infra, належать до анотацій на боці Release.
spec: subsystems: data: annotations: feature.myco/db-pool: db_name: "prod-db" read_replicas: 5 components: api: type: core/server:1.0.0 annotations: feature.myco/db-pool: db_name: "api-override" # closer-level override at subkey granularity # read_replicas not listed → inherits 5 from parent analytics: type: core/server:1.0.0 annotations: feature.myco/db-pool: read_replicas: null # per-subkey opt-outСтруктуровані значення каскадуються з глибоким злиттям на рівні підключів: підключі ближчого рівня перевизначають батьківські підключі; явний null на підключі пригнічує успадкований підключ для цієї області, тоді як сусідні підключі залишаються. Повний опис структурованих значень — композицію між боками з підключами infra на боці Release, перевірку типів для кожного підключа, пом’якшену дисципліну типових значень для полів схеми без оголошеного type — див. у providers/well-known-annotations.md §«Structured annotation values».
Незалежність ключів
Кожен ключ анотації успадковується, перевизначається та скасовується незалежно. Компонент, що оголошує annotations.feature.myco/db-pool: null, відмовляється лише від цього ключа; інші ключі, успадковані від охопної підсистеми, і далі поширюються на цей компонент. Сусідні компоненти в тій самій підсистемі незалежно зберігають власні мапи анотацій — відмова одного компонента не впливає на сусідів.
Анотації компонентів верхнього рівня
Компоненти верхнього рівня (оголошені безпосередньо в spec.components, а не всередині підсистеми) не мають успадкованого каскаду. Їхнє поле annotations: оголошує значення безпосередньо в області компонента; розгортання синтезує приєднання Feature з кожної оголошеної анотації, для якої Manifest має відповідну прив’язку.
Правило каскаду на боці Aggregate, застосоване до прив’язок, розподіл «бік — стовп» і наскрізний приклад того, як прив’язки перетворюють анотації на синтетичні приєднання Feature, див. у providers/well-known-annotations.md §«Aggregate-side annotation cascade».
Шаблони якорів YAML (блок defs:)
Схема сутності Aggregate приймає необов’язковий блок defs: на кореневому рівні — список рядків YAML, який слугує лише місцем для стандартних якорів YAML (&anchor) і посилань (*anchor). Компілятор ніколи не читає вміст цього блоку; він існує для того, щоб автори могли оголошувати визначення якорів в одному місці й посилатися на них в решті сутності Aggregate, уникаючи повторення значень (DRY) і не втрачаючи плаского словника O(1), який перебирає компілятор. Цей механізм дзеркально повторює аналогічний блок defs: у сутності Manifest.
apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: anchored-app version: 1.0.0defs: - &default_log_level "info"spec: components: primary: type: core/compute/api-server:1.0.0 values: log_level: *default_log_level secondary: type: core/compute/python:1.0.0 values: log_level: *default_log_levelЯкорі розв’язуються під час розбору YAML, тож на момент, коли компілятор читає блок значень, *default_log_level уже є рядком "info". Блок defs: — місце для визначень якорів за домовленістю; YAML дозволяє оголошувати якорі будь-де, але їх розміщення в одному місці зберігає решту сутності Aggregate зручною для читання. Блок необов’язковий — сутності Aggregates, яким якорі не потрібні, повністю його пропускають.