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

Схема lockfile Aggrega для кожної сутності Release

Згенерований довідник. Не редагуйте вручну — згенеруйте повторно з опублікованої JSON Schema.

Ідентифікатор схеми: https://aggrega.ai/schemas/lockfile-v1beta1.schema.json

Машинно згенерований lockfile, що фіксує кожен URI, розв’язаний із сутності Release, для детермінованих майбутніх збірок. Розташовується у <release-stem>.lock поруч із <release-stem>.yaml; створюється командою aggrega pull --release <release>; використовується командою aggrega build --release <release>. Дві форми походження записують два різні відношення в графі залежностей: referenced_from (список рядків) з’являється в entities як шляхи до місць авторингу через крапку, що фіксують, з якого місця в Release / Aggregate / Manifest / .aggrega-config.yaml було підтягнуто кожен URI, і в plugins — як посилання на кожну сутність Plugin, через яку було досягнуто артефакт; consumers (список записів {consumer_uri, fragments}) з’являється в schema_libraries, mapping_libraries, workload_libraries і artifact_libraries, щоб фіксувати, яка сутність каталогу посилається на які фрагменти <entry-name> бібліотеки — структурована форма дає змогу простежувати різниці, спричинені оновленням версії бібліотеки для споживачів, без повторного розв’язання Release. Дисципліна еволюції схеми: додавання нового розділу верхнього рівня — це SemVer-MINOR (адитивна зміна); додавання нового поля всередині наявного розділу — SemVer-MINOR; вилучення ключа або посилення обмеження — SemVer-MAJOR.

Тип верхнього рівня: object

Властивості

ВластивістьТипОбов’язковаОпис
entitiesobject[]ніСутності каталогу, досяжні з цієї сутності Release: Component, Feature, Recipe, FeatureRecipe, Plugin, Aggregate, власні Aggregate і Manifest цієї сутності Release, а також сутність Manifest, яку розширює ця сутність Manifest. Кожен запис ідентифікується своїм kind разом зі своїм канонічним URI, тож дві сутності різних видів з однаковим іменем — скажімо, сутності Aggregate і Manifest, обидві з іменем imported/flow, — є двома записами, кожен з яких звіряється з власним дайджестом. Кожен фіксує розв’язану версію, дайджест того, що містить сутність, і місця походження в авторському коді (referenced_from), які додали URI до замикання залежностей Release. Файл lockfile, записи якого не містять жодного kind, застарів: aggrega pull --release <release> записує його знову. Типово: []
external_inputsExternalInput[]ніВіддалені вхідні дані, закріплені у сховищі вхідних даних з адресацією за вмістом під час отримання, — вміст поза робочим простором, який споживає рендеринг плагіна-провайдера, наприклад віддалені документи схем або невендорені залежності чартів. Кожен запис закріплює одну URL-адресу за дайджестом, що іменує її байти у сховищі. Збірка видає закріплені вхідні дані зі сховища й читає цей розділ без доступу до мережі. Типово: []
generated_atstringтакПозначка часу RFC 3339 операції pull, яка створила цей lockfile; шаблон утримує значення в цьому форматі під час завантаження lockfile. Діагностичне походження — фіксує момент розв’язання за настінним годинником. Навмисно змінюється між операціями pull; не входить до гарантії побайтової ідентичності lockfile. Шаблон: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$.
mapping_librariesLibraryEntry[]ніЗаписи MappingLibrary, яких замикання залежностей Release досягає через місця valuesMapping: { $import: ... } у Recipe / FeatureRecipe. Список consumers кожного запису фіксує, яка сутність каталогу посилається на які фрагменти <entry-name> бібліотеки, — структурований запис, що робить відстежуваними відмінності впливу від підвищення версії бібліотеки без повторного розв’язання Release. Типово: []
mutatorsobject[]ніРозв’язані прив’язки governance з роллю перетворення в авторському порядку. Плагін із роллю перетворення (label-transform, який переписує мітки вузлів, або annotation-transform, який вставляє анотації перед розгортанням) формує байти результату рендерингу, тому набір прив’язок — упорядкований список, а також для кожної прив’язки роль, координата плагіна й функція експорту — є вхідними даними, що визначають байти, і закріплюється тут. Збірка читає цей розділ — ніколи не .aggrega-config.yaml — щоб відтворити набір, порядок, роль і функцію експорту, тож результат збірки інваріантний щодо зміни plugins.governance, зробленої після pull (вона набуває чинності лише з наступним pull). Порядок є СЕМАНТИЧНИМ: кожен виконавець перетворень застосовує прив’язки своєї ролі в порядку списку, тому, на відміну від відсортованих за URI розділів plugins / providers, цей список ніколи не перевпорядковується. Дайджест вмісту плагіна тут НЕ дублюється: його єдине джерело — розділи plugins і entities, на які цей запис указує за ідентичністю. Типово: []
pluginsobject[]ніПлагіни Wasm, чиї байти формують відрендерений вивід, кожен закріплений дайджестом вмісту свого .wasm: плагін керування, під’єднаний у ролі перетворення (label-transform, annotation-transform) у .aggrega-config.yaml plugins.governance, а також будь-які вбудовані URI плагінів із Recipes / FeatureRecipes / Providers, на які є посилання. Плагін керування, під’єднаний у ролі вердикту (ir-verdict, render-verdict), і під’єднання plugins.linter повертають вердикт і не формують жодних байтів виводу, тому жоден із них не закріплюється: жоден не з’являється ні тут, ні в entities, а файли правил, які читає під’єднання вердикту, записуються в verdict_inputs. Типово: []
providersobject[]ніРозв’язані вибори провайдера для кожної можливості. Кожен запис закріплює одну можливість (наприклад, helm) за OCI-ідентичністю без дайджесту плагіна рендерингу провайдера, який її рендерить; її розв’язують під час pull зі списку plugins.providers у .aggrega-config.yaml (коли можливість обслуговується неоднозначно) або з єдиного плагіна, що її обслуговує (коли однозначно). Збірка читає цей розділ — ніколи не .aggrega-config.yaml — щоб вибрати провайдера, тож результат збірки інваріантний щодо змін конфігурації робочого простору, зроблених після pull. Дайджест вмісту плагіна тут НЕ дублюється: його єдине джерело — розділи plugins і entities, на які цей запис указує за ідентичністю. Співіснування версій зберігається: цей запис вибирає репозиторій плагіна для кожної можливості; конкретні версії містяться в entities (один запис на кожну розв’язану версію плагіна), а закріплення версії spec.capability кожного Recipe вибирає серед них під час рендерингу. Типово: []
releasestringтакШлях до сутності Release, якій відповідає цей lockfile, розв’язаний відносно власного каталогу lockfile (наприклад, ./release-prod.yaml). Домовленість про іменування для кожної сутності Release розміщує <release-stem>.lock поруч із <release-stem>.yaml; відносний шлях робить lockfile самоописовим без абсолютних шляхів, специфічних для машини. Це поле іменує сутність Release; те, що містила сутність Release під час розв’язання, фіксується в release_documents.
release_documentsobject[]ніФайли сутностей Release, які прочитало розв’язання, кожен зафіксований дайджестом вмісту своїх байтів: спочатку сутність Release, якій належить цей lockfile, потім кожна сутність Release, яку вона розширює, у порядку обходу ланцюжка extends. Усе, що запитує сутність Release, розв’язується з того, що вона містить, тож сутність Release, відредагована після pull, більше не відповідає своєму зафіксованому дайджесту, і збірка — або aggrega pull --verify — зупиняється ще до будь-якого рендерингу, називаючи файл і пропонуючи як виправлення aggrega pull --release <release>. Дайджест охоплює байти як є, без жодної нормалізації, — те саме правило, якого дотримуються закріплення Aggregate і Manifest: редагування коментаря чи пробілів вважається зміною. Lockfile без цього розділу не фіксує жодного файлу Release, і збірка з таким lockfile повідомляє, що сутність Release не зафіксовано. Файл, який сутність Release імпортує через parameters, тут не фіксується.
schema_librariesLibraryEntry[]ніЗаписи SchemaLibrary, яких замикання залежностей Release досягає через місця $ref і $import: у вмісті schema: / usesSchema: / featuresSchema: сутностей. Список consumers кожного запису фіксує, яка сутність каталогу посилається на які фрагменти <entry-name> бібліотеки, — структурований запис, що робить відстежуваними відмінності впливу від підвищення версії бібліотеки без повторного розв’язання Release. Типово: []
source_artifactsSourceArtifactEntry[]ніВихідні артефакти, отримані з полів spec.source у Recipe / FeatureRecipe під час pull. Кожен запис ідентифікує унікальну ідентичність {kind, url, chart, pinned_version} із дайджестом вмісту, типом медіа та структурованими зворотними вказівниками referenced_by:, що називають кожну сутність каталогу, яка розв’язалася до цього артефакту. url — це авторська URL-адреса ідентичності; розв’язане розташування артефакту для джерела helm у корені репозиторію фіксується окремо в resolved_url: як походження. Кілька Recipes, що закріплюють той самий чарт у тій самій версії, дедуплікуються в один запис із кількома записами referenced_by:. Перелік kind охоплює чотири види джерел, які розв’язуються, і terraform-module-oci, який не обслуговує жоден адаптер джерела: Recipe або FeatureRecipe, що його називає, відхиляється під час читання, тож жоден pull не записує запис цього виду. Типово: []
toolchainobjectніВерсії інструментарію, який створив цей lockfile: власна версія компілятора та версія кожного основного плагіна, який несе компілятор. Фіксуються, щоб lockfile згодом відповідав, який компілятор і які основні плагіни розв’язали й відрендерили збірку, — на це питання закріплені розділи не завжди можуть відповісти, бо основний плагін провайдера, що обслуговується зсередини бінарного файлу компілятора, залишається незакріпленим і тому не має власної зафіксованої версії. Лише версії: позначка ніколи не фіксує, звідки взялися байти плагіна, тож дві машини, які закріпили те саме замикання залежностей тим самим компілятором, записують ту саму позначку. Ніщо не порівнює цей розділ, не попереджає про нього й не відмовляє у збірці через нього, а його відсутність у lockfile мовчазна: інструментарій не входить до замикання залежностей, яке закріплює lockfile. З тієї самої причини цей розділ виключається з порівняння побайтової ідентичності між двома pull тих самих вхідних даних — на тих самих засадах, що й generated_at.
verdict_inputsobject[]ніЗовнішні вхідні дані правил, які під’єднання керування з роллю вердикту (ir-verdict / render-verdict) читає під час компіляції, — файл правил Kyverno / Rego, переданий через with.sources під’єднання. Записуються як дайджест вмісту для кожного джерела, для аудиту та видимості розбіжностей між pull: дайджест, що сформував вердикт, можна порівнювати між pull, тож змінений файл правил проявляється як різниця в lockfile. Цей розділ — ПОХОДЖЕННЯ, а не вхідні дані збирання: на відміну від mutators.sources, він не містить content, і збирання його НЕ читає — плагін вердикту кешується, а не закріплюється, і читає свої вхідні дані правил наживо (вердикт не формує жодних байтів виводу, тож ніщо з того, що lockfile закріплює заради детермінованого виводу, його не містить). Оскільки плагін вердикту не закріплюється, його немає в розділах entities / plugins; тому цей запис ідентифікує під’єднання за його авторським URI — самостійно, а не через посилання на ці розділи. Запис дайджесту робить вхідні дані, що визначили рішення прийняти/відхилити, придатними для аудиту та відтворюваними без їх фіксації у збиранні. Типове значення: []
versionconst 1такВерсія схеми lockfile: 1. Зміна схеми рівня SemVer-MAJOR збільшує її. Константа: 1
workload_librariesLibraryEntry[]ніЗаписи WorkloadLibrary, яких замикання залежностей Release досягає через місця workload: { $import: ... } у сутностях Recipe. Список consumers кожного запису фіксує, яка сутність каталогу посилається на які фрагменти <entry-name> бібліотеки, — структурований запис, що дає змогу простежити вплив підвищення версії бібліотеки без повторного розв’язання Release. Типове значення: []
artifact_librariesLibraryEntry[]ніЗаписи ArtifactLibrary, яких замикання залежностей Release досягає через місця artifacts.<name>: { $import: ... } у сутностях Recipe / FeatureRecipe. Список consumers кожного запису фіксує, яка сутність каталогу посилається на які набори <entry-name> бібліотеки, — структурований запис, що дає змогу простежити вплив підвищення версії бібліотеки без повторного розв’язання Release. Типове значення: []

Додаткові властивості не дозволені.

lockfile.entities[]

ВластивістьТипОбов’язковаОпис
kindstring (enum)такВид сутності каталогу, прочитаний із місця, де сутність Release, її Aggregate або її Manifest називає її: component і feature для типу Component або Feature, який називає Aggregate, Release або зіставлення в Manifest, recipe і feature_recipe для реалізації, яку прив’язує зіставлення в Manifest, plugin для сутності Plugin, aggregate для власної сутності Aggregate сутності Release і кожної сутності Aggregate, яку вона включає, і manifest для власної сутності Manifest сутності Release і сутності Manifest, яку вона розширює. Разом з uri він ідентифікує запис: збірка порівнює кожен запис із сутністю того самого виду й URI, тож редагування будь-якої з двох однойменних сутностей різних видів буде помічено. Допустимі значення: "aggregate", "component", "feature", "feature_recipe", "manifest", "plugin", "recipe"
uristringтакКанонічний URI сутності каталогу (наприклад, hub.aggrega.ai/component/core/compute/api-server).
resolved_versionstringтакКонкретна версія, яку вибрав розв’язувач під час pull, — власна версія сутності каталогу (наприклад, 1.2.3) або порожнє значення для сутності верхнього рівня, розв’язаної за шляхом, а не за версією. Записується як один сегмент шляху, бо саме його вона й називає, тож не містить /, \ і ..: значення утворює слот кешу, з якого збирання зчитує цю сутність, а значення, що виходило б за межі каталогу кешу, вказувало б на розташування поза ним. Шаблон: ^([^/\\.]|\.[^/\\.])*\.?$.
digeststringтакДайджест того, що містить публікація сутності, у формі sha256: і 64 шістнадцяткові символи в нижньому регістрі: SHA-256 від документа сутності та кожного файлу, який вона оголошує поруч із ним, відсортованих за шляхом, де кожен додає свій шлях і SHA-256 своїх байтів. Сутність, що не оголошує жодного файлу, враховується як її єдиний документ. Більше ніщо до нього не входить — ні спосіб стиснення архіву, ні мітка часу, ні будь-який біт дозволів, зокрема біт виконання, — тож сутність записує той самий дайджест, прочитана з каталогу чи завантажена з реєстру, і з будь-якого checkout тих самих файлів у будь-якій системі. Шаблон: ^sha256:[a-f0-9]{64}$.
manifest_digeststringніДайджест маніфесту OCI розв’язаного артефакту у формі sha256: і 64 шістнадцяткові символи в нижньому регістрі. Підпис засвідчує цей дайджест, а маніфест називає дайджест опублікованих байтів, з яким звіряються завантаження та читання з кешу, перш ніж сутність перевіряють на відповідність її digest вище. Присутній лише для сутності, розв’язаної з реєстру. Шаблон: ^sha256:[a-f0-9]{64}$.
referenced_fromstring[]ніМісця походження в авторських файлах — шляхи через крапку в YAML сутностей Release / Aggregate / Manifest (наприклад, aggregate.spec.components.api.type), що фіксують, чому цей URI входить до замикання залежностей Release. Типове значення: []
signatureVerifiedSignatureніФакт перевіреного підпису, записаний, коли підпис цієї сутності було перевірено під час pull за політикою довіри реєстру, що її розв’язав.
deprecationDeprecationRecordніПеревірений ретроактивний маркер застарілості, записаний, коли під час pull на цьому артефакті виявлено підписаний довірений маркер застарілості. Маркер — це підписаний OCI referrer артефакту, який він позначає застарілим, під’єднаний після публікації без повторної публікації артефакту. Записує рівень серйозності та повідомлення маркера, а також перевіреного підписувача, який його створив. Збирання читає цей факт і застосовує політику застарілості лише на основі lockfile; воно ніколи не виявляє й не перевіряє маркер повторно.

Додаткові властивості не дозволені.

lockfile.mutators[]

ВластивістьТипОбов’язковаОпис
pluginstringтакРозв’язана координата плагіна з роллю перетворення — ідентичність <pluginType>/<name> сутності Plugin (наприклад, governance/tag-injector). З’єднується за ідентичністю з розділами plugins і entities для зафіксованого дайджесту та набору версій.
rolestring (enum)такРоль перетворення, до якої прив’язане це під’єднання, записана дослівно з авторського запису plugins.governance, тож збірка запускає під’єднання саме в цій ролі, а не виводить її: label-transform переписує мітки вузлів під час побудови топології; annotation-transform додає анотації перед розгортанням, під час розв’язання. Допустимі значення: "label-transform", "annotation-transform"
functionstringніПеревизначення експорту, яке називає під’єднання. За відсутності вибирається типовий експорт ролі (mutate для label-transform, transform_annotations для annotation-transform).
settingsobjectніДовільний об’єкт налаштувань, оголошений під’єднанням, зафіксований у авторському вигляді й переданий плагіну дослівно. Збирання читає налаштування звідси — ніколи не з поточної конфігурації, — тож зміна налаштувань після pull не змінює виводу збирання. Відсутній, якщо під’єднання їх не оголошує.
sourcesobject[]ніАдресовані за вмістом фіксації оголошених під’єднанням файлів джерел, упорядковані за базовим ім’ям. Збирання реконструює джерело, яке читає плагін, із записаного вмісту кожної фіксації, а не з поточного читання на хості, тож вивід збирання не залежить від зміни файлу джерела після pull. Відсутній, якщо під’єднання їх не оголошує.

Додаткові властивості не дозволені.

lockfile.mutators[].sources[]
ВластивістьТипОбов’язковаОпис
contentstringтакВміст файлу джерела, що зберігається дослівно, щоб збирання реконструювало вхідне джерело плагіна з lockfile.
digeststringтакАдреса вмісту записаного вмісту у формі sha256: і 64 шістнадцяткові символи в нижньому регістрі. Повторний pull порівнює вихідний файл із цим дайджестом, щоб виявити розбіжність. Шаблон: ^sha256:[a-f0-9]{64}$.
pathstringтакБазове ім’я файлу джерела — ніколи не абсолютний шлях на хості, тож фіксація переносна й детермінована.

Додаткові властивості не дозволені.

lockfile.plugins[]

ВластивістьТипОбов’язковаОпис
uristringтакГола ідентичність артефакту .wasm плагіна Wasm — шлях <pluginType>/<name> (наприклад, governance/aggrega-security-baseline). Перший сегмент — це тип плагіна (provider, linter, pipeline-step, governance, cli, parser, importer); наступний сегмент — ім’я плагіна. Тип і ім’я разом утворюють ідентичність плагіна: те саме ім’я під двома типами — це два плагіни. Фізичне розташування для завантаження виводиться з цієї ідентичності та налаштованого реєстру й ніколи не зберігається в lockfile.
resolved_versionstringтакДайджест вмісту, до якого розв’язався артефакт Wasm, у формі sha256:, за яким іде 64 шістнадцяткові символи в нижньому регістрі. Артефакт плагіна адресується за вмістом, а не за назвою версії — .wasm міститься безпосередньо в маніфесті свого плагіна й закріплюється дайджестом своїх байтів, — тому це поле записує цей дайджест, який також є digest нижче. З нього будується слот кешу, з якого збірка зчитує артефакт, тому він не містить /, \ і .., що форма sha256: і так виключає. Шаблон: ^sha256:[a-f0-9]{64}$.
digeststringтакДайджест вмісту розв’язаного артефакту Wasm у формі sha256:, за яким іде 64 шістнадцяткові символи в нижньому регістрі, — у тій формі, у якій адреса вмісту записується всюди, де її порівнюють. Шаблон: ^sha256:[a-f0-9]{64}$.
manifest_digeststringніДайджест маніфесту OCI розв’язаного артефакту Wasm у формі sha256:, за яким іде 64 шістнадцяткові символи в нижньому регістрі. Підпис засвідчує саме цей дайджест; дайджест вмісту digest вище — це переносна ідентичність, що використовується для закріплення в кеші та перевірки цілісності. Присутній лише для артефакту, розв’язаного з реєстру. Шаблон: ^sha256:[a-f0-9]{64}$.
referenced_fromstring[]ніЧому цей артефакт входить до замикання залежностей Release: посилання на кожну сутність Plugin, через яку його було досягнуто, у тому вигляді, у якому розділ entities записує цю сутність (наприклад, governance/label-injector:1.0.0). Типово: []
signatureVerifiedSignatureніФакт перевіреного підпису, записаний, коли підпис цього плагіна було перевірено під час pull за тією самою політикою довіри для кожного реєстру, що й для сутностей каталогу.
deprecationDeprecationRecordніПеревірений ретроактивний маркер застарілості, записаний, коли під час pull на цьому артефакті виявлено підписаний довірений маркер застарілості. Маркер — це підписаний OCI referrer артефакту, який він позначає застарілим, під’єднаний після публікації без повторної публікації артефакту. Записує рівень серйозності та повідомлення маркера, а також перевіреного підписувача, який його створив. Збирання читає цей факт і застосовує політику застарілості лише на основі lockfile; воно ніколи не виявляє й не перевіряє маркер повторно.

Додаткові властивості не дозволені.

lockfile.providers[]

ВластивістьТипОбов’язковаОпис
capabilitystringтакМожливість, для якої це прив’язування обирає провайдера, — гола назва можливості, яку Recipe прив’язує через spec.capability (наприклад, helm, compose).
pluginstringтакГола ідентичність розв’язаного плагіна рендерингу провайдера (ідентичність сутності Plugin — її metadata.pluginType і metadata.name, з’єднані скісною рискою, наприклад provider/helm). Зіставляється за ідентичністю з розділами plugins і entities, що містять закріплений дайджест і набір версій.

Додаткові властивості не дозволені.

lockfile.release_documents[]

ВластивістьТипОбов’язковаОпис
digeststringтакДайджест вмісту байтів файлу Release на момент їх зчитування під час розв’язання у формі sha256:, за яким іде 64 шістнадцяткові символи в нижньому регістрі. Шаблон: ^sha256:[a-f0-9]{64}$.
pathstringтакШлях до файлу Release відносно каталогу, що містить сутність Release, якій належить цей lockfile, із прямими скісними рисками (наприклад, release-prod.yaml, ../shared/base-release.yaml) — ніколи не абсолютний шлях на хості, тож запис переносний і детермінований.

Додаткові властивості не дозволені.

lockfile.toolchain

Версії інструментарію, який створив цей lockfile: власна версія компілятора та версія кожного основного плагіна, який несе компілятор. Фіксуються, щоб lockfile згодом відповідав, який компілятор і які основні плагіни розв’язали й відрендерили збірку, — на це питання закріплені розділи не завжди можуть відповісти, бо основний плагін провайдера, що обслуговується зсередини бінарного файлу компілятора, залишається незакріпленим і тому не має власної зафіксованої версії. Лише версії: позначка ніколи не фіксує, звідки взялися байти плагіна, тож дві машини, які закріпили те саме замикання залежностей тим самим компілятором, записують ту саму позначку. Ніщо не порівнює цей розділ, не попереджає про нього й не відмовляє у збірці через нього, а його відсутність у lockfile мовчазна: інструментарій не входить до замикання залежностей, яке закріплює lockfile. З тієї самої причини цей розділ виключається з порівняння побайтової ідентичності між двома pull тих самих вхідних даних — на тих самих засадах, що й generated_at.

ВластивістьТипОбов’язковаОпис
compiler_versionstringтакВерсія компілятора, що записав цей lockfile, у формі без «v», яку повідомляє кожна поверхня Aggrega (1.2.0, а не v1.2.0). Збірка з позначкою версії записує цю версію — збірка тегованого випуску записує свій тег, — а збірка без позначки версії записує позначку (devel), щоб lockfile, створений компілятором без позначки, не сприймався як результат випуску. Записується як один сегмент шляху, тому не містить /, \ і ... Шаблон: ^([^/\\.]|\.[^/\\.])*\.?$.
core_pluginsobject[]такВерсія кожного базового плагіна, який містить компілятор, по одному запису на плагін, упорядковано за координатою плагіна. Базовий плагін публікується під власним тегом компілятора з тією самою версією, тому ці версії однакові незалежно від того, чи компілятор надав плагін із себе, чи завантажив його з реєстру, — саме це звільняє позначку від залежних від машини подробиць. Порожній для збірки, що не містить базових плагінів. Типове значення: []

Додаткові властивості не дозволені.

lockfile.toolchain.core_plugins[]
ВластивістьТипОбов’язковаОпис
pluginstringтакКоордината базового плагіна — ідентичність <pluginType>/<name> сутності Plugin (наприклад, provider/helm), та сама ідентичність, за якою плагін називають розділи providers і mutators.
versionstringтакВерсія цього базового плагіна у формі без «v», яку повідомляє кожна поверхня Aggrega. Записується як один сегмент шляху, тому не містить /, \ і ... Шаблон: ^([^/\\.]|\.[^/\\.])*\.?$.

Додаткові властивості не дозволені.

lockfile.verdict_inputs[]

ВластивістьТипОбов’язковаОпис
pluginstringтакАвторський URI плагіна вердиктного підключення, як записано в .aggrega-config.yaml plugins.governance (наприклад, governance/aggrega-security-baseline:1.0.0). Визначає, якому підключенню належать записані вхідні дані правил; вердиктний плагін кешується, а не закріплюється, тому не має запису в розділах plugins / entities, з яким можна було б зіставитися.
rolestring (enum)такВердиктна роль, до якої прив’язане це підключення, — ir-verdict (під час статичного аналізу, над графом IR) або render-verdict (під час рендерингу, над відрендереними артефактами). Розрізняє той самий плагін, підключений на обох етапах вердикту, кожен потенційно зі своїми вхідними даними правил. Допустимі значення: "ir-verdict", "render-verdict"
sourcesobject[]ніДайджести вмісту оголошених у підключенні файлів вхідних даних правил, упорядковані за базовим ім’ям. Відсутні, коли підключення не оголошує джерел.

Додаткові властивості не дозволені.

lockfile.verdict_inputs[].sources[]
ВластивістьТипОбов’язковаОпис
digeststringтакАдреса вмісту байтів файлу вхідних даних правил на момент pull у формі sha256:, за яким іде 64 шістнадцяткові символи в нижньому регістрі. Повторний pull обчислює її заново, тож змінений файл правил проявляється як різниця в lockfile. Шаблон: ^sha256:[a-f0-9]{64}$.
pathstringтакБазове ім’я файлу вхідних даних правил — ніколи не абсолютний шлях на хості, тож запис переносний і детермінований.

Додаткові властивості не дозволені.

Визначення

DeprecationRecord

Перевірений ретроактивний маркер застарілості, записаний, коли під час pull на цьому артефакті виявлено підписаний довірений маркер застарілості. Маркер — це підписаний OCI referrer артефакту, який він позначає застарілим, під’єднаний після публікації без повторної публікації артефакту. Записує рівень серйозності та повідомлення маркера, а також перевіреного підписувача, який його створив. Збирання читає цей факт і застосовує політику застарілості лише на основі lockfile; воно ніколи не виявляє й не перевіряє маркер повторно.

ВластивістьТипОбов’язковаОпис
messagestringтакЗрозуміле людині повідомлення про застарілість, яке несе маркер, — зазвичай вказівка на шлях міграції.
severitystring (enum)такРівень серйозності маркера, упорядкований як warning < error < retracted. Збирання зупиняється, коли цей рівень досягає налаштованого порогу зупинки або перевищує його, а інакше видає попередження. Допустимі значення: "warning", "error", "retracted"
signerVerifiedSignatureніПеревірений підписант маркера, записаний так само, як підписант підпису артефакту: суб’єкт/видавець сертифіката для безключового підпису або відбиток закріпленого ключа для підпису з ключем. Маркер сам є підписаним артефактом, тож його підписант має ту саму форму, що й підпис артефакту, — а bundle_digest тут називає власний пакет підпису маркера, а не пакет застарілого артефакту.

Додаткові властивості не дозволені.

ExternalInput

Один закріплений зовнішній вхід: URL, який запитав рендеринг, закріплення SHA-256, що називає його байти в адресованому за вмістом сховищі входів (sha256/<digest>), розмір корисного навантаження та походження споживачів, яким він був потрібен. Закріплення є авторитетним: закріплений URL завжди обслуговується зі сховища, а повторне заповнення сховища перевіряється за цим дайджестом, перш ніж байти потраплять до рендерингу.

ВластивістьТипОбов’язковаОпис
required_bystring[]такПоходження — місця рендерингу, які запитали цей вхід. Сортуються й дедуплікуються засобом запису lockfile.
sha256stringтакЗакріплення SHA-256 у шістнадцятковому записі малими літерами. Для входу https — дайджест байтів корисного навантаження; для входу oci — дайджест маніфесту, до якого розв’язалося посилання. Називає блоб сховища за адресою sha256/<digest>. Шаблон: ^[0-9a-f]{64}$.
sizeintegerтакРозмір закріпленого корисного навантаження в байтах. Кількість байтів ніколи не буває від’ємною. Мінімум: 0.
urlstringтакURL входу в тому вигляді, як його записано в місці рендерингу, — ключ пошуку, що зіставляє запит під час рендерингу з його закріпленням.

Додаткові властивості не дозволені.

LibraryEntry

Спільна форма записів schema_libraries, mapping_libraries, workload_libraries і artifact_libraries. Список consumers фіксує зв’язок у графі каталогу — яка сутність каталогу посилається на які фрагменти <entry-name> цієї бібліотеки, — що дає змогу будувати структуровані diff впливу, коли змінюється дайджест бібліотеки. Бібліотека є таким самим артефактом OCI, як і будь-який інший, тож вона записує ті самі перевірені факти, що й сутність каталогу: дайджест маніфесту, до якого прив’язаний її підпис, сам перевірений підпис і будь-який перевірений ретроактивний маркер застарілості, виявлений під час pull.

ВластивістьТипОбов’язковаОпис
uristringтакКанонічний URI сутності бібліотеки.
resolved_versionstringтакКонкретна версія, розв’язана під час pull (вибір мінімальної версії за графом залежностей бібліотек), — власна версія бібліотеки. Записується як один сегмент шляху, бо з неї будується слот кешу, з якого збирання зчитує бібліотеку, тож вона не містить /, \ і ..: значення, що виходить за межі каталогу кешу, називало б розташування поза ним. Шаблон: ^([^/\\.]|\.[^/\\.])*\.?$.
digeststringтакДайджест вмісту розв’язаного артефакту бібліотеки у форматі sha256: і 64 шістнадцяткові символи в нижньому регістрі — у тій формі, у якій адреса за вмістом записується всюди, де її порівнюють. Шаблон: ^sha256:[a-f0-9]{64}$.
manifest_digeststringніДайджест маніфесту OCI розв’язаного артефакту бібліотеки у форматі sha256: і 64 шістнадцяткові символи в нижньому регістрі. Підпис прив’язаний до цього дайджесту; дайджест вмісту digest вище є переносною ідентичністю, що використовується для закріплення в кеші та перевірки цілісності. Присутній лише для бібліотеки, розв’язаної з реєстру. Шаблон: ^sha256:[a-f0-9]{64}$.
signatureVerifiedSignatureніФакт перевіреного підпису, записаний, коли підпис цієї бібліотеки було перевірено під час pull за тією самою політикою довіри для кожного реєстру, що й для сутностей каталогу.
deprecationDeprecationRecordніПеревірений ретроактивний маркер застарілості, виявлений на цій бібліотеці під час pull. Збирання повідомляє про нього і, якщо в робочому просторі налаштовано поріг зупинки, якого досягає записаний рівень серйозності, зупиняється — тож про бібліотеку, відкликану після закріплення версії, повідомляється під час кожного збирання, а не лише під час вибору версії, який явно закріплена версія оминає.
consumersobject[]ніЗаписи про те, яка сутність каталогу посилається на цю бібліотеку і на які фрагменти <entry-name>. Фіксують fan-in: багато споживачів на бібліотеку, кожен із яких може посилатися на багато фрагментів. Кожен запис містить URI споживача та набір фрагментів, які цей споживач підтягує. Типово: []

Додаткові властивості не дозволені.

LibraryEntry.consumers[]

ВластивістьТипОбов’язковаОпис
consumer_uristringтакКанонічний URI сутності каталогу, що посилається на цю бібліотеку: Component або Feature для бібліотеки схем, Recipe або FeatureRecipe для бібліотеки зіставлень, робочих навантажень чи артефактів або інша бібліотека того самого виду, записи якої посилаються на цю.
fragmentsstring[]такНабір фрагментів <entry-name>, на які цей споживач посилається в бібліотеці (наприклад, ["#/schemas/PortSpec", "#/schemas/EndpointSpec"]). Засіб запису канонізує порядок лексикографічно.

Додаткові властивості не дозволені.

SourceArtifactEntry

Одна фіксація вихідного артефакту: ідентичність {kind, url, chart, module_subdir, pinned_version}, дайджест вмісту, що перевіряє завантаження, канонічний mediatype і структуровані зворотні вказівники на кожну сутність каталогу, яка розв’язалася в цей артефакт. chart і module_subdir — два терміни-селектори: кожен називає те, чого не називає сам URL, для тих видів, яким це потрібно.

ВластивістьТипОбов’язковаОпис
kindenumтакВид джерела. Визначає, який адаптер розв’язав артефакт і який mediatype очікується. terraform-module-oci належить до набору, і жоден адаптер джерела його не обслуговує: Recipe або FeatureRecipe, що його називає, відхиляється під час читання. Дозволені значення: "helm-oci-chart", "helm-https-chart", "compose-https-fragment", "git-repository", "terraform-module-oci"
urlstringтакНаписаний автором URL — URL ідентичності так, як його записано в spec.source.url сутності Recipe. Для helm-https-chart це корінь репозиторію (форма repo-root) або прямий .tgz (пряма форма) точно так, як написано; build відтворює цей самий URL офлайн, тож це стабільна ідентичність, за якою ключується фіксація. Для git-repository — URL репозиторію, який можна клонувати. Для helm-oci-chart — посилання на реєстр. Для compose-https-fragment — HTTPS URL фрагмента. Розв’язане розташування артефакту для helm-джерела repo-root записується окремо в resolved_url: як походження.
chartstringніНазва чарту для helm-джерела repo-root (spec.source.chart сутності Recipe), частина ідентичності {kind, url, chart, module_subdir, pinned_version}, щоб два чарти, які віддаються з одного кореня репозиторію з однаковою версією, фіксувалися в різних записах. Відсутня для прямого .tgz, OCI, compose чи git-джерела, жодне з яких не вибирає чарт у межах URL.
module_subdirstringніКаталог у репозиторії з git-джерела, який є артефактом (spec.source.module_subdir сутності Recipe), частина ідентичності {kind, url, chart, module_subdir, pinned_version}, щоб два каталоги одного репозиторію на тому самому коміті фіксувалися в різних записах. Відсутній, коли артефактом є весь репозиторій, а також для кожного виду, що досягає свого артефакту за URL, а не спускаючись у клон.
pinned_versionstringтакКонкретна версія, зафіксована під час pull. Для видів helm-* — версія чарту. Для git-repository — коміт, у який розв’язалося написане автором посилання (НЕ початкове посилання tag/branch — воно записується в requested_ref: у кожному записі referenced_by:, щоразу коли Recipe містить spec.source.ref:). Build знаходить цей запис за тим, що написано в Recipe: за написаним ref:, якщо він є, зіставленим із записаним requested_ref:, а інакше — за цим зафіксованим значенням; тож Recipe, що називає тег, розв’язується в коміт, на якому цей тег було зафіксовано, без появи коміту в Recipe. Записується як один сегмент шляху, оскільки з нього будується слот кешу, з якого build зчитує артефакт, тому не містить /, \ і ... Шаблон: ^([^/\\.]|\.[^/\\.])*\.?$.
resolved_urlstringніЛише походження: конкретне розташування артефакту, у яке розв’язався написаний автором URL під час pull. Для helm-джерела repo-root це прямий URL .tgz, у який індекс репозиторію розв’язав chart+version; записується для діагностики і НЕ є частиною ідентичності артефакту. Відсутнє, коли розв’язане розташування збігається з написаним URL (прямий .tgz, OCI, compose чи git-джерело).
digeststringтакДайджест вмісту розв’язаного архіву .tar.gz у форматі sha256:, за яким іде 64 шістнадцяткові символи в нижньому регістрі. Перевірка під час build зчитує байти слота кешу, повторно обчислює дайджест і порівнює його з цим полем; розбіжність зупиняє збірку з повідомленням про розбіжність дайджесту вмісту. Шаблон: ^sha256:[a-f0-9]{64}$.
manifest_digeststringніДайджест маніфесту OCI розв’язаного артефакту у форматі sha256:, за яким іде 64 шістнадцяткові символи в нижньому регістрі. Маніфест — незалежний корінь довіри, відносно якого перевіряється кешований архів; дайджест вмісту digest вище — це переносна ідентичність, що використовується для фіксації в кеші та перевірки цілісності. Присутній лише для джерела, що розповсюджується через OCI (helm-oci-chart). Шаблон: ^sha256:[a-f0-9]{64}$.
mediatypestringтакКанонічний тип медіа, оголошений реєстром (або типовий для виду, якщо вид не має метаданих реєстру). Записується як діагностичні відомості про походження.
referenced_bySourceArtifactReference[]такСутності каталогу, що розв’язалися в цей артефакт, відсортовані за (uri, field) для детермінованого виводу. Запис існує лише тому, що його завантажив Recipe або FeatureRecipe, тож список ніколи не буває порожнім. Щонайменше 1 запис.

Додаткові властивості не дозволені.

SourceArtifactReference

Один зворотний вказівник «сутність каталогу → вихідний артефакт». entity + uri разом ідентифікують сутність каталогу; field називає шлях на боці джерела в spec сутності, де було оголошено артефакт. Необов’язковий requested_ref: зберігає написаний у Recipe spec.source.ref: і записується щоразу, коли Recipe його містить (теги/гілки git-repository → SHA коміту).

ВластивістьТипОбов’язковаОпис
entityenumтакВид сутності каталогу, що містить цей зворотний вказівник. Дозволені значення: "recipe", "feature_recipe"
uristringтакКанонічний URI сутності Recipe або FeatureRecipe (наприклад, hub.aggrega.ai/recipe/helm/mariadb-bitnami:1.0.0).
fieldstringтакШлях на боці джерела в spec сутності, де було оголошено артефакт. Значення — spec.source.
requested_refstringніНеобов’язкове — написаний у Recipe spec.source.ref:, записується щоразу, коли Recipe його містить. Для Recipe з git-repository, що містить ref: v1.0.0, зберігає "v1.0.0", тоді як pinned_version: містить коміт, у який розв’язалося це посилання. Відсутнє, коли Recipe не містить ref:, а це кожен вид, чий резолвер фіксує написану версію дослівно (helm-, compose-). Воно виконує дві функції одночасно, і саме безумовний запис не дає їм виключати одна одну. Build з’єднує за ним, щоб знайти цей запис із Recipe, що називає посилання, а не коміт. А pull, який не є оновленням, утримує кожне записане посилання на його зафіксованій версії: посилання, що змінилося у віддаленому репозиторії, зупиняє запуск замість того, щоб бути прийнятим.

Додаткові властивості не дозволені.

VerifiedSignature

Факт перевіреного підпису, що записується, коли підпис артефакту було перевірено під час pull за політикою довіри реєстру, який його розв’язує. Кожен артефакт, який можна підписати, — сутність каталогу, бібліотека, плагін Wasm, — записує його однаково, бо всі вони проходять перевірку одним шляхом, а не окремим для кожного виду. Записує режим перевірки, keyless-ідентичність/видавця, що збіглися (для keyless), і адресований за вмістом дайджест пакета підпису в кеші вмісту. Збірка не виконує перевірку повторно. Перш ніж щось буде відрендерено, вона читає цей факт у кожному записі, з якого будує, у кожному розділі: повторно обчислює хеш кешованого пакета й порівнює результат із bundle_digest, зупиняючись, якщо блоб відсутній або відрізняється; а для запису, який надав кеш вмісту, вона читає з цього пакета, для якого артефакту створено підпис, і зупиняється, якщо його створено для іншого артефакту, ніж той, що збірка прочитала для запису, — тож signature, скопійований з одного запису в інший, відхиляється незалежно від вимоги щодо підпису. Збірка не перевіряє жодного підпису, тому пакет, записаний у кеш вручну й оформлений для власного артефакту запису, неможливо відрізнити від того, який перевірив pull. А якщо конфігурація довіри робочого простору вимагає підпису для запису, який надав кеш вмісту, — це вимога, яку pull застосовує під час отримання артефакту, тож пропуски та реєстр advisory, що дозволяють pull прийняти артефакт без підпису, дозволяють і збірці прийняти його запис, — запис без цього факту зупиняє збірку. Запис, прочитаний із каталогу, з копії всередині бінарного файлу компілятора або з місця поруч із сутністю Release, ніколи не підлягає цій вимозі.

ВластивістьТипОбов’язковаОпис
bundle_digeststringтакДайджест SHA-256 кешованого блоба пакета підпису у форматі sha256:, за яким іде 64 шістнадцяткові символи в нижньому регістрі. Він іменує блоб кешу, тому утворює шлях і не містить /, \ і .. — що вже виключає форма sha256:, — і в записі будь-якого розділу саме з ним збірка порівнює повторно обчислений хеш цього блоба. Шаблон: ^sha256:[a-f0-9]{64}$.
identitystringніПеревірений підписувач підпису: суб’єкт сертифіката підпису для keyless-підпису або keyed:sha256:, за яким іде SHA-256 PEM-тексту закріпленого відкритого ключа, для підпису з ключем.
issuerstringніПеревірений видавець OIDC для keyless-підпису. Порожнє для підпису з ключем.
modestring (enum)такРежим перевірки, який прийняв підпис. Допустимі значення: "keyless", "keyed"

Додаткові властивості не дозволені.