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

aggrega inspect

aggrega inspect відображає зручне для читання подання будь-якої сутності Aggrega — сутності Component з каталогу, авторського файлу сутності, сутності, опублікованої в реєстрі, або повністю розв’язаної сутності Release. Це канонічний засіб налагодження, який допомагає зрозуміти, що створить компілятор: які сутності Components розширюють які базові, яка сутність Recipe відповідає кожному типу, які сутності Features приєднано до кожного вузла і звідки саме походять внески кожної сутності Feature.

Кожен вид сутності має природне подання «контракту». inspect показує цей контракт — схему, яку публікує сутність Component, зіставлення, які оголошує сутність Manifest, топологію, яку будує сутність Aggregate, приєднання сутностей Feature до кожного вузла, до яких розв’язується сутність Release. Навчальні та концептуальні матеріали розміщено в інших розділах; inspect відповідає на запитання «до чого насправді розв’язується ця сутність?»

Єдиний позиційний аргумент спрямовується залежно від форми вмісту; підкоманда не потрібна. Команда виконує диспетчеризацію за такою евристикою:

Форма ідентифікатораДиспетчеризаціяВивід
Починається з ./, ../ або / чи закінчується на .yaml / .ymlГілка файлуПеревірка окремого файлу на основі заголовка kind: цього файлу.
Починається з oci://Гілка реєструСутність, опублікована за цією координатою, зчитана з її реєстру й відображена в поданні, яке отримує файл її виду. Див. Читання опублікованої сутності.
Будь-що іншеГілка каталогуПошук ідентифікатора в стеку пошуку каталогу серед усіх видів сутностей; розв’язання ланцюжків extends:; відображення власного подання знайденого виду.

Три рівні деталізації

--list, типовий рівень і --detail утворюють єдину трирівневу систему детальності, якої дотримується кожен вид сутності. --list і --detail взаємовиключні — якщо передати обидва, команда відмовиться виконуватися, а не розв’яже конфлікт мовчки.

  • --list — лише ідентифікатори. Сутність Component виводить свою назву та назви сокетів uses; сутність MappingLibrary — назви своїх зіставлень; сутність Aggregate — назви своїх компонентів з їхніми типами.
  • типовий рівень — структурований огляд, налаштований для інтерактивного використання. Він починається з ідентичності сутності та — для всіх видів, крім сутностей Manifest і Release, — її опису, якщо сутність його містить; для сутності без опису нічого не виводиться, навіть порожній рядок. Решта вигляду залежить від виду: сутність Component показує свою схему та сокети; сутність Aggregate показує компоненти, їхні значення та ребра з вкладеннями, які несе кожне з’єднання, а також граф залежностей; сутність Release показує дерево вузлів за межами з вкладеннями Feature, причому кожне вкладення, записане на з’єднанні, наводиться під цим з’єднанням.
  • --detail — повні тіла полів. Усе, що містить вид: сутність Component додає свої механізми самоін’єкції, обов’язкові Features і мітки; сутність MappingLibrary розгортає повне тіло шаблону кожного зіставлення; сутність Recipe додає тіло робочого навантаження, provides та твердження.

Деякі види використовують ці рівні, щоб поступово показувати більшу частину написаного тіла. Сутність MappingLibrary на рівні --list показує назви зіставлень; на типовому рівні вона додає синтезований приклад використання кожного зіставлення; на рівні --detail вона розгортає повне тіло шаблону.

Розв’язання: --raw і --resolved

Кожен вид має природну глибину розв’язання за замовчуванням (див. таблицю нижче). --raw і --resolved — це перевизначення, доступні завжди, і вони взаємовиключні: передавання обох відхиляється, а не розв’язується мовчки:

  • --raw вимикає будь-яке розв’язання — сутність виводиться так, як її написано, безпосередньо з файлу.
  • --resolved вмикає повну глибину розв’язання для цього виду.

Для видів, які за замовчуванням виводяться як написано, --raw нічого не змінює, а --resolved запускає те розв’язання, яке підтримує вид. Для видів, які за замовчуванням розв’язуються, --raw — це обхід, що показує сутність як написано.

--raw відтворює файл, тож значення, яке автор оголосив чутливим, з’являється в ньому точно так, як його написано. Це контракт, а не прогалина: подання «як написано», яке непомітно приховувало б частину себе, не було б поданням «як написано». Поводьтеся з виводом --raw так само, як із файлом сутності, з якого його отримано. --output yaml так само відтворює файл для кожного виду, зокрема для сутності Release.

Сутність Release відповідає ще на два запитання, і кожна відповідь — окремий документ із власним прапорцем. Скомпільований граф, до якого розв’язується сутність Release, — це --ir-graph; її залежнісне замикання — це --closure. Див. Машиночитаний вивід і Залежнісне замикання: --closure нижче.

Типові значення для кожного виду

inspect знає види, які можна інспектувати окремо, наведені в таблиці нижче. Види каталогу за замовчуванням відображаються в авторському вигляді — їхні файли є самодостатніми контрактами. Види екземплярів за замовчуванням мають розв’язане подання, оскільки їхній авторський YAML — лише відправна точка для каскаду або конвеєра.

ВидЗа замовчуваннямЩо означає «розв’язаний»
Componentв авторському виглядіФайл є самодостатнім контрактом; розв’язання виконується відносно прив’язки Manifest і показується через --show-implements.
Featureв авторському виглядіТак само, як для Component.
Recipeв авторському вигляді--show-implements розв’язує посилання spec.implements на Component.
FeatureRecipeв авторському вигляді--show-implements розв’язує посилання spec.implements на Feature.
MappingLibraryв авторському виглядіЗаписи — непрозорі рядки шаблонів Go; рендеринг відбувається під час використання.
SchemaLibraryв авторському виглядіЗаписи — багаторазові визначення схем і шаблонів, що розв’язуються під час використання.
WorkloadLibraryв авторському виглядіЗаписи — це повторно використовувані тіла Workload, які імпортує сутність Recipe; вони обчислюються в момент використання.
ArtifactLibraryв авторському виглядіЗаписи — це повторно використовувані набори артефактів, які імпортує сутність Recipe; вони рендеряться в момент використання.
Pluginв авторському виглядіФайл є самодостатнім контрактом плагіна: типи сокетів, можливості для кожного експорту, обмеження середовища виконання та вказівник на підпис. Його можна адресувати за шляхом до файлу або за координатою <pluginType>/<name> у каталозі.
Manifestрозв’язанийЗастосовується ланцюжок extends:; викладаються розв’язані зіставлення компонентів і функцій.
Aggregateрозв’язанийБудується топологія — обчислюються граф використань і порядок.
Releaseрозв’язанийВиконується весь конвеєр: розв’язання, розгортання анотацій, запуск перевірок, побудова топології, побудова IR.

Файл, у якого kind: має значення Workload, відхиляється: сутність Workload існує лише вбудованою в Recipe і не є окремою сутністю для інспектування. Щоб побачити її Workload, інспектуйте Recipe.

Глибина розв’язання для кожного виду

Більшість видів не мають конвеєра — inspect читає файл і відображає його. Змістовно розв’язуються три види екземплярів:

  • Manifest застосовує свій ланцюжок extends: — слідування за імпортом файлів — і відображає об’єднані зіставлення компонентів і функцій. --raw показує файл у тому вигляді, у якому його написано.
  • Aggregate будує свою топологію: створюється граф використання й обчислюється порядок залежностей. Подання за замовчуванням показує компоненти з їхніми значеннями та ребрами, а після них — граф залежностей. --raw показує написане дерево підсистем.
  • Release виконує весь конвеєр компіляції аж до IR — розв’язання, розгортання анотацій, запуск guard-перевірок, побудова топології, побудова IR — і відображає дерево вузлів для кожної межі з приєднаннями Feature кожного вузла та їхнім походженням. Приєднання керування, що формують граф, виконуються в цьому конвеєрі, а не пропускаються заради подання, тож те, що ви читаєте, відображає їхні рішення: мітки приєднання label-transform вже встановлено до того, як із ними щось зіставляється, а анотації, впроваджені приєднанням annotation-transform, розгортаються в приєднання Feature точно так само, як написана вами анотація. Приєднання, плагін якого ця команда не може розв’язати, зупиняє її, замість того щоб залишити вам граф, побудований без рішень цього плагіна. Release, що розширює інший, відображається — у цьому поданні та в --ir-graph — як Release, до якого складається його ланцюжок extends:, тобто той, який читає його збірка, тож Release, що називає лише свого батька, показує Aggregate, Manifest і межі цього батька під власною назвою. Manifest, який називає Release, також складається через власний ланцюжок extends: незалежно від того, чи розширює Release щось, тож приєднання, відображення якого успадковує цей Manifest, показує реалізацію, яку використовує збірка. --raw виводить файл Release дослівно, без конвеєра. --closure ставить інше запитання щодо того самого Release і не запускає конвеєра взагалі; див. Замикання залежностей: --closure.

Окремого прапорця глибини немає; перемикач --raw / --resolved — єдиний засіб керування розв’язанням, що накладається на природне значення за замовчуванням кожного виду.

Поведінка в разі помилок

Сусідній файл, на який є посилання і який не вдається завантажити, одразу зупиняє команду — сутність Release, що вказує на відсутню сутність Aggregate, пошкоджена сутність каталогу в стеку пошуку. Команда зупиняється зі зрозумілим повідомленням, а не виводить часткові результати, і режиму продовження після помилки завантаження немає: щойно документ, потрібний для розв’язання, неможливо прочитати, розв’язувати далі нічого. Якщо розв’язання імені зупиняється на одному документі каталогу, який завантаження відхиляє, повідомлення називає цю відмову один раз: заголовок із категорією і, якщо відмова називає умову, її коротким кодом, потім документ, потім те, що з ним не так — для документа, який відхиляє схема його виду, рядок і обмеження, яке він порушує. Повідомлення не пропонує перемістити файл — каталог прочитав його, саме тому його й відхилено.

Сутність Release, композицію якої відхиляють перевірки компілятора, відхиляється, а не відображається. Розв’язання сутності Release будує граф, і перевірки, які збірка виконує над готовим графом, — ребро uses:, ціль якого не задовольняє selector: свого сокета, сутність Feature, приєднана до компонента, якого не допускає її appliesTo:, та інші — виконуються й тут, з тією самою діагностикою, яку виводить збірка тих самих документів. Відмова називає всі знахідки за один запуск, а не зупиняється на першій, тож один прохід показує вам увесь список того, що слід виправити, а не лише його перший пункт. Саме це робить команду чесною щодо розгортання: подання, яке відобразило б композицію, що її відхиляє збірка, повідомляло б, що робочий простір у порядку, хоча це не так. Вибори, які нічого не розв’язують, це не зачіпає — --raw, --output yaml і --closure відтворюють або розв’язують написане вами без побудови графа.

Release, чий файл блокування більше не відповідає тому, у що він розв’язується, відхиляється із зупинкою, яку виводить aggrega build. Якщо поруч із сутністю Release лежить файл блокування, кожен вибір, що розв’язує Release, — типове подання, --resolved, --ir-graph і --closure — звіряє цей файл із тим, у що розв’язується Release, за допомогою порівняння дрейфу, яке збірка виконує перед рендерингом. Файл блокування, що більше не відповідає, зупиняє команду відмовою збірки E0130: кожен запис, що зазнав дрейфу, а потім aggrega pull --release <release>, що це усуває. Нічого не записується в стандартний вивід, і команда завершується з ненульовим кодом, бо картина, побудована з каталогу в його поточному стані, показала б те, чого не рендерить жодна збірка цієї сутності Release. --raw і --output yaml самі по собі не читають ні файлу блокування, ні каталогу і не звіряються з ним. Release без файлу блокування поруч розв’язується за каталогом у його поточному стані.

Файл, чий kind: не розпізнано, повідомляє про невідомий вид і файл, з якого він походить. Файл Workload повідомляє, що цей вид лише вбудовуваний, і називає сутність, у яку він вбудовується. Ідентифікатор oci://, який неможливо прочитати, відхиляється з умовою, що пояснює причину; їх перелічено в розділі Читання опублікованої сутності.

Розв’язання каталогу

Стек пошуку каталогу збирається з багаторівневим пріоритетом: спершу йдуть прапорці --catalog (додаються на початок, у заданому порядку), потім catalog_dirs робочого простору з .aggrega-config.yaml — для сутності Release, якій конфігурація задає власні каталоги в workspace.releases, на їхньому місці стоять каталоги цієї сутності Release, — а потім каталог catalog у корені робочого простору, який читається незалежно від того, чи його щось називає. Робочий простір, у якому catalog_dirs записано як порожній список, не читає жодного локального каталогу. Стек працює за принципом «перший виграє»: найраніший каталог, що оголошує ідентичність сутності, володіє нею; копію з пізнішого каталогу затінено. Гілка каталогу розв’язує ідентифікатор за цим стеком для всіх видів сутностей у фіксованому порядку пріоритету і відображає перший збіг через власне подання відповідного виду; гілки файлу та релізу завантажують із нього сутності каталогу, на які є посилання, коли потрібно розв’язати відображення сутності Manifest або батьківську сутність extends:. Батьківська сутність extends:, якої стек не містить, читається там, де її читає збірка: із кешу артефактів, за закріпленням, яке lock-файл сутності Release записує для неї, — названої сутності Release або, коли жодної не названо, кожної сутності Release у робочому просторі. Тож базу, опубліковану в реєстрі, тут можна розв’язати, щойно aggrega pull завантажить і закріпить її, а до того команду буде відхилено із зазначенням aggrega pull --release <release>. Нічого не завантажується.

Пошук імені в умовах сутності Release

Ім’я, задане саме по собі, шукається у власному стеку робочого простору. Якщо поруч задати --release <release-path>, ім’я натомість шукається у стеку цієї сутності Release — у каталогах, які конфігурація робочого простору задає для цієї сутності Release, з усіма --catalog, доданими на початок, — і саме це читає збірка цієї сутності Release. Тож робочий простір, що тримає по одному варіанту каталогу на кожну сутність Release, кожен з яких оголошує ту саму сутність, відповідає на ім’я тим варіантом, з яким збирається ця сутність Release:

aggrega inspect core/datastore/mariadb --release release-helm-synth.yaml

Ім’я, яке стек цієї сутності Release не розв’язує, відхиляється, а пояснення, звідки читаються локальні сутності, називає запис цієї сутності Release у workspace.releases, оскільки саме цей запис прочитав пошук. --release вибирає стек, у якому шукається ім’я, тому застосовується лише до самого імені: шлях до файлу та посилання на реєстр читаються як є і відхиляють цей прапорець. --release, що вказує на неіснуючий файл або на каталог, відхиляється ще до будь-якого пошуку.

Читання опублікованої сутності

aggrega inspect oci://<host>/<repository>:<tag> читає сутність, опубліковану за цією координатою; @<digest> замість :<tag> точно називає один маніфест. Так можна переглянути сутність, яка існує лише в реєстрі: репозиторій — це сегмент виду, за яким іде ідентичність сутності, як описано в Catalog and Registry §6, а aggrega push виводить посилання, за яким опублікувала сутність, і тут воно читається з oci:// попереду.

Ви бачите сутність такою, якою її було опубліковано. Сутність, опублікована разом із файлами, які вона оголошує, — сутність Recipe з її локальним чартом або lock-файлом, сутність Component зі схемою, яку вона імпортує, — постачається як архів, і сутність розпаковується з нього: це документ у корені архіву, що оголошує вид, придатний до публікації, тож шаблон чарту чи фрагмент compose, постачений поруч, не плутається з нею. Сутність, яка не оголошує жодного файлу, постачається як її незмінений документ, а сутність Plugin читається з її маніфесту, а не з виконуваного файлу, опублікованого разом із нею. Потім документ відображається тим самим поданням, що й файл цього виду, з тими самими рівнями деталізації та тими самими --raw і --output yaml. Успадкування не застосовується: подання показує те, що видавець розмістив за цією координатою. Читабельні макети завершуються відомостями про прочитане: координата, чи містила вона сутність як архів чи як сам документ, тип медіа, який оголошує її маніфест, і дайджест цього маніфесту, що знову читає ті самі байти, якщо записати його як @<digest> замість :<tag>; --output yaml виводить документ і нічого після нього.

Що перевіряється, а що ні. Отримані байти перевіряються на відповідність дайджесту, який для них записує власний маніфест артефакту, що встановлює, що це саме ті байти, які називає маніфест. Це перевірка щодо того, що віддав реєстр, а не щодо чогось записаного заздалегідь: жоден підпис, прикріплений до артефакту, не перевіряється, і жодне записане щодо нього відкликання не повідомляється. Нічого не записується — ні запису в кеші, ні lock-файлу, — тож читання координати не змінює нічого з того, що визначить пізніша збірка.

Команда звертається до мережі. З реєстром встановлюється з’єднання з обліковими даними, які ця машина має для нього, з того самого сховища, яке читають aggrega push і aggrega pull, а з реєстром на цій машині з’єднання встановлюється через звичайний HTTP. Робочий простір у режимі офлайн відхиляє читання ще до будь-якого з’єднання.

Читання, яке не може дати відповіді, завершується з ненульовим кодом і нічого не виводить у стандартний вивід. Кожна наведена нижче помилка називає свою умову разом із тим, що з нею робити; про реєстр, до якого взагалі неможливо дістатися, повідомляється з мережевою помилкою, яка зупинила читання:

Що сталосяУмова
За посиланням нічого не опублікованоE0137
Реєстр відхилив облікові дані, або для нього їх не збереженоE0138
Робочий простір у режимі офлайнE0125
Артефакт є архівом, який неможливо розпакуватиE0300
Архів не містить документа сутності в кореніE0298
Архів містить більше одного документа сутності в кореніE0299
Документ не є сутністю виду, який публікує реєстрE0301

Кожен код наведено в довіднику помилок. Посилання, яке не називає репозиторію або не містить ні тегу, ні дайджесту, відхиляється із зазначенням форми, яку слід написати натомість. --ir-graph і --closure відхиляються ще до будь-якого отримання, бо жоден вид, який публікує реєстр, не є сутністю Release.

Повідомлення про застарілість і відкликання

Видавець може після публікації артефакту записати щодо нього позначку про те, що опублікована версія застаріла або відкликана. Коли гілка каталогу розв’язує сутність, inspect повідомляє про будь-яку таку позначку під власним поданням сутності — для кожного виду, який вона розв’язує за іменем, а не лише для сутності Component.

Повідомлення називає рівень серйозності, який записав видавець, — warning, error або retracted, — разом із версією, для якої записано позначку, причиною, заміною, якщо її вказано, і датою видачі. Повідомляється про всі три рівні. Це ширше, ніж набір, що змінює результат розв’язання збірки: версія з позначкою retracted виключається з вибору версій, тоді як warning і error мають рекомендаційний характер і версія все одно обирається. inspect показує вам, що сказав видавець; він не вирішує, що ви отримаєте.

Повідомлення зчитується з локального індексу реєстру, з якого розв’язується сутність, а цей індекс будує aggrega registry update, — тож мережа не потрібна, і це працює в офлайн-робочому просторі. Оскільки індекс є знімком, повідомлення завершується зазначенням того, коли зроблено цей знімок, і називає команду, що його оновлює. Робочий простір без побудованого індексу нічого не повідомляє, тому відсутність повідомлення означає «у цьому знімку нічого не записано», а не «нічого не записано».

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

Повідомлення супроводжує подання, призначені для читання людиною. Ні --output yaml, ні --ir-graph його не додають, тож споживач, що розбирає будь-який із цих виводів, отримує документ і нічого більше.

Робочі приклади

Пошук сутності Component у каталозі

$ aggrega inspect core/server:1.0.0 --catalog ./catalog
Component: core/server:1.0.0
Schema:
|
values: { port?: int | *8080 }
Uses sockets:
db: selector="component.aggrega.ai/type=stateful-server"

Типове подання показує опис сутності Component, якщо його задано, далі розв’язану схему (після злиття extends:) і оголошені uses-сокети. Сутність Component вище не має опису, тому стенограма починається одразу зі схеми. --detail додає механізми self-inject, необхідні Features і мітки; --list показує лише ідентифікатор сутності Component та назви її сокетів.

Feature

$ aggrega inspect ./features/metrics.yaml
Feature: core/metrics:1.0.0
Schema:
|
values: { port?: int | *9090 }
Uses sockets:
backend: selector="component.aggrega.ai/type=stateful-server"
inject: [env]
Secret slots:
token (required)
Targeting:
appliesTo: component.aggrega.ai/type=server
Labels:
feature.aggrega.ai/category: observability

Recipe з --show-implements

Типове подання сутності Recipe показує по одному розділу на кожен оголошений нею режим введення, її можливість і зіставлення значень. --show-implements розв’язує посилання spec.implements за каталогом і відображає прив’язану сутність Component разом із вкладеннями, яких ця сутність Component потребує:

$ aggrega inspect ./recipes/api-server-recipe.yaml --show-implements --catalog ./catalog
Recipe: core/api-server-recipe:1.0.0
Implements: core/api-server:1.0.0
Capability: helm
## Synthesized
workload: inline
valuesMapping: (none)
Implements Component: core/api-server:1.0.0
requires attachment (observability): core/metrics

Recipe, що оголошує кілька режимів введення

Режими введення сутності Recipe поєднуються додаванням: source: для відображення, workload: для синтезу та мапа artifacts: — кожен додає свій вивід, і сутність Recipe може оголосити будь-яку їх комбінацію. inspect показує кожен режим, оголошений сутністю Recipe, а не вибирає один, тож ви бачите саме той набір, який написали:

$ aggrega inspect ./recipes/api-server-composed.yaml
Recipe: core/api-server-composed:1.0.0
Implements: core/api-server:1.0.0
Capability: helm
## Sourced
source: oci://charts.example.com/api-server:2.1.0
## Synthesized
workload: inline
valuesMapping: inline template
Artifacts: 2
- servicemonitor.yaml
- networkpolicy.yaml

Розділи впорядковано так: source: → workload: → artifacts: — у тому самому порядку, який застосовує збірка, коли зводить сутність Recipe до назви одного режиму і коли повідомляє, який оголошений режим прив’язаний провайдер не може підтримати, — тож це подання й діагностика збірки називають режими в одному порядку. Сутність Recipe, що не оголошує ні source:, ні workload:, показується як artifacts-only; це єдиний випадок, коли подання називає один режим.

Manifest (типово розв’язаний)

$ aggrega inspect ./prod-manifest.yaml
Manifest: prod-manifest:1.0.0
Component Mappings:
Type → Recipe
core/compute/api-server helm-api-server-synthesized-with-artifacts:1.0.0
core/compute/web-ui helm-web-ui-synthesized-with-artifacts:1.0.0
core/datastore/postgres helm-postgres-synthesized-with-artifacts:1.0.0
Feature Mappings:
Type → FeatureRecipe
core/k8s-dns-resolver k8s-dns-patcher:1.0.0
Annotation Bindings:
(none)

Типове подання застосовує ланцюжок extends: сутності Manifest і викладає розв’язані зіставлення компонентів і функцій, а також прив’язки анотацій. --raw показує файл у написаному вигляді, до розв’язання extends.

Aggregate (типово розв’язаний)

$ aggrega inspect ./fullstack-app.yaml
Aggregate: fullstack-app:1.0.0
Components:
backend (type: core/compute/api-server)
Values: (none)
Uses:
databases:
- data.main-db
frontend (type: core/compute/web-ui)
Values: (none)
Uses:
apis:
- my-api → backend
main-db (type: core/datastore/postgres)
Values:
database_name: app_production
Uses: (none)
Dependency Graph:
data.main-db
↑ backend
backend
↑ frontend

Типове подання будує топологію й показує кожен компонент із його значеннями та uses-ребрами, а далі — обчислений граф залежностей. Дерево підсистем відображається з вкладенням; --flat відображає по одному розділу на вузол, кожен із ключем — повним шляхом через крапку.

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

gateway (type: conn/gateway)
Values:
region: eu
Uses:
models:
- gpt → model
- gpt.credential (feature.conn/token) [slot: credential, sensitive]

Слот і позначка — це факти, які збірка сутності Release, що розгортає цю сутність Aggregate, записує для вкладення, і читаються вони так само, як у поданні Release (див. Attachment connection, slot and sensitivity clause); вони походять з оголошення слота сокета та власного оголошення Feature, тож не залежать від того, яка сутність Release розгортає Aggregate. Сутність Aggregate не називає жодного Manifest, тому реалізацію, яку Manifest сутності Release обирає для вкладення, тут не показано. Це подання перелічує з’єднання компонента та те, що вони несуть; вкладення власного блоку компонента з’являються в поданні Release.

Release (типово розв’язаний)

Подання Release — найвідповідальніша інспекція. Воно запускає повний конвеєр і відображає для кожної межі кожен вузол Component, його uses-ребра та кожну Feature, вкладену в цей вузол, — вкладену в з’єднання показано під ребром цього з’єднання, — кожну з слотом вкладення, який вона заповнює, ознакою, чи обробляє вона матеріал, оголошений чутливим, і FeatureRecipe, що її реалізує, а також дужкою походження, яка показує, звідки взялося вкладення:

$ aggrega inspect ./prod-release.yaml --catalog ./catalog
Release: prod-release:1.0.0
Boundary: backend-ns
Directory: ./dist/backend
Annotations (provider-consumed):
aggrega.ai/namespace: backend-zone
Component: backend (type: core/compute/api-server:1.0.0)
Uses:
data.main-db → data.main-db [cross-boundary]
Features: (none)
Boundary: frontend-ns
Directory: ./dist/frontend
Annotations (provider-consumed):
aggrega.ai/namespace: frontend-zone
Component: frontend (type: core/compute/web-ui:1.0.0)
Uses:
my-api → backend [cross-boundary]
Features:
- cross-namespace-routing (core/k8s-dns-resolver:1.0.0) [free, realization: k8s-dns-patcher:1.0.0] [explicit]
Boundary: data-ns
Directory: ./dist/data
Annotations (provider-consumed):
aggrega.ai/namespace: database-zone
Component: data.main-db (type: core/datastore/postgres:1.0.0)
Features: (none)

Кожна межа містить свій вихідний каталог і анотації, які споживає провайдер; кожен компонент у межі містить свій тип компонента Aggregate, свої uses-ребра (міжмежові ребра позначено), за кожним із яких ідуть вкладення цього з’єднання, і власні вкладення Feature, кожне вкладення — з клаузою фактів і дужкою походження. --flat згортає дерево меж до одного розділу на межу з ключем — повним шляхом. --raw виводить файл Release дослівно, без конвеєра.

Вивід YAML

$ aggrega inspect core/server:1.0.0 --output yaml --catalog ./catalog
apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/server
version: 1.0.0
labels:
component.aggrega.ai/type: server
spec:
usesSchema:
db:
selector: component.aggrega.ai/type=stateful-server
schema:
values:
port: {type: integer, default: 8080}

Сутність Component, названа з каталогу, друкується як сутність, у яку її розв’язав каталог, тож після злиття extends: ви бачите об’єднану сутність, а не написаний файл; файл сутності Component друкується так, як його написано.

Машинозчитуваний вивід

Машинозчитуваний вивід дають два прапорці, і вони відповідають на різні запитання. --output вибирає формат для документа, який ця команда вже рендерить; --ir-graph запитує інший документ — скомпільований граф, до якого розв’язується сутність Release, — на додачу до нього. Вони незалежні: якщо передати обидва, ви отримаєте граф і YAML у вигляді, як його написано, кожне по одному разу.

--output yaml виводить сутність у тому вигляді, як її написано, придатному для передавання конвеєром і порівняння. Цей вивід дослівний, і це стосується також значень, які автор оголосив чутливими — вивід, що претендує на відтворення вхідних даних, не може приховати їх частину й при цьому залишатися відтворенням. Передавайте, зберігайте й поширюйте його так само, як файл сутності, з якого він походить.

Скомпільований граф: --ir-graph

aggrega inspect <release> --ir-graph записує граф, до якого розв’язався запуск, у стандартний вивід як JSON, перед поданням, яке команда рендерить у будь-якому разі. Один документ JSON, один завершальний символ нового рядка, тож споживач, що декодує потік, прочитує граф і зупиняється.

Він застосовується до сутності Release — єдиного типу, що розв’язується до графа. Якщо запросити його для будь-якого іншого типу або для сутності каталогу за іменем, команда відмовляє й повідомляє про це, а не рендерить власне подання цієї сутності, мовчки відкидаючи запит.

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

Той самий прапорець із тим самим значенням є в aggrega build і aggrega validate: кожна з них повертає граф, обчислений цим запуском, на додачу до всього іншого, що створює команда. Інтеграція з редактором читає той самий граф через протокол демона.

--output yaml не виводить граф. Він відтворює написану сутність Release точно так само, як і для будь-якого іншого типу. Конвеєр, якому потрібен граф, читає його натомість із --ir-graph і отримує JSON, а не YAML.

Граф приховує значення. Це не файл, який хтось написав, — це те, що компіляція обчислила із сутностей Aggregate, Release і каталогу, — тож немає зобов’язання зберігати написаний вигляд, і ті самі оголошення, що керують читабельними поданнями, керують і ним. Скрізь, де граф містить листок, який автор оголосив чутливим, значення замінюється об’єктом з одним ключем, що позначає його як приховане:

"values": {
"secretName": "db-creds",
"vault": {
"token": { "aggrega_withheld": "declared" }
}
}

Ключ зберігається, тож граф і далі показує, які листки містять вузол і його вкладення; зникає лише значення. Неоголошений сусідній елемент у тому самому корисному навантаженні виводиться так, як його написано, — secretName вище є публічним локатором, який автор залишив неоголошеним, і він друкується. Причина, що супроводжує позначку, пояснює, чому значення відсутнє: declared для листка, на який поширюється оголошення, і unreadable, коли корисне навантаження надійшло у формі, яку ця команда не змогла прочитати, — у такому разі приховується все навантаження, а не вгадується будь-яка його частина.

Власна конфігурація з’єднання приховується так само. values окремого з’єднання, які Aggregate записує в записі uses, і infra окремого з’єднання, які записує в ньому Release, підпадають під сокет компонента-споживача — оголошені ним valueSchema та infraSchema, контракти, за якими перевіряється ця конфігурація, — і ніколи не під оголошення цілі. Лист, який будь-який із контрактів оголошує як sensitive: true, замінюється маркером у values та infra ребра, а також у записі uses вузла-споживача, який містить значення так, як їх написав автор; кожне ребро перелічує приховані ним листи в sensitive_payload_leaves — полі, яке вузол використовує для власних. Лист із тією самою назвою на з’єднанні, сокет якого оголошує його читабельним, виводиться так, як написано.

Передавайте --unredacted, коли конвеєру справді потрібні значення, і поводьтеся з отриманим так само, як із самими файлами сутностей. aggrega build і aggrega validate приймають той самий прапорець поряд із --ir-graph на тих самих умовах: граф, який вони повертають, приховує значення, якщо прапорець не передано.

Протокол демона видає той самий граф за тим самим правилом. aggrega/irGraph відповідає з прихованими значеннями й повертає їх відкрито лише на запит, у якому встановлено поле unredacted — написання цього прапорця в протоколі. Тож те, що малює панель редактора, підпорядковується тим самим оголошенням, а клієнт, який показує значення, робить це, бо запросив їх.

Замикання залежностей: --closure

aggrega inspect <release> --closure повідомляє замикання залежностей сутності Release: кожну сутність каталогу, до якої вона доходить, у версії, до якої кожна з них розв’язалася, разом з ідентичностями Aggregate і Manifest, до яких розв’язалися два її вказівники, та спільними документами, на які спираються ці сутності. Нічого не рендериться й жоден артефакт не створюється — замикання розв’язується, а не збирається, тож для відповіді не завантажується жоден провайдер.

Замикання та розв’язане подання — різні документи, і жоден із них не можна відновити з іншого. Розв’язане подання — те, що ця команда за замовчуванням рендерить для Release, — показує, який вигляд має розгортання: його межі, вузли компонентів, що з чим з’єднано і що приєднано до кожного вузла. Замикання показує, що було залучено для його збирання і в яких версіях. До сутності можна дійти, хоча вона ніколи не з’являється як вузол, — Recipe, на який Manifest відображає тип компонента, досягається кожним збиранням і не є вузлом у жодному з них, — а вузол записує тип компонента, яким його оголошено, а не версію, до якої цей тип розв’язався. Тож читач, який питає «чому ця версія змінилася?», «на що вплине зміна цього спільного документа?» чи «від чого насправді залежить це розгортання?», питає про замикання, і читач, який має розв’язане подання, не отримає його, читаючи уважніше.

Те саме слово запитує той самий документ на кожній поверхні. --closure тут, aggrega/releaseClosure через протокол демона (див. aggrega serve, «Замикання — це не граф») і режим release інструмента describe через протокол інструментів асистента відповідають на це саме питання про Release; ім’я Release через будь-який із них веде до того самого розв’язання, тож ці три не можуть розійтися в тому, від чого залежить Release. Якщо lock-файл більше не відповідає тому, до чого розв’язується Release, ця команда й інструмент describe відмовляють із тією самою зупинкою через розбіжність, що й збірка; демон, який обслуговує редактор під час редагування, відповідає.

Це один документ, тому його запитують окремо. --closure вибирає замикання замість розв’язаного подання і не може поєднуватися з --raw, --resolved, --output чи --ir-graph — кожен із них запитує інший документ про той самий Release, і команда, що прийняла б два запити, мусила б мовчки відповісти лише на один. Поєднання відхиляється із зазначенням пари.

Він застосовується до Release і ні до чого іншого. Сутність каталогу, файл Aggregate, Manifest — жоден із них не розв’язує замикання, тож запит відхиляється, а не обробляється рендерингом власного подання цього об’єкта з відкиданням запиту. Відкинутий запит виглядає для того, хто викликає, точнісінько як об’єкт із порожнім замиканням.

Кожен результат відрізняється від інших. На Release, що розв’язується, відповіддю є перелік. Шлях до Release, що не вказує на жоден файл, відхиляється з повідомленням, що файлу немає. Release, який існує, але замикання якого не вдається розв’язати, відхиляється із зазначенням того, що не вдалося розв’язати і звідки походить посилання, а далі — усіх файлів, які відхилило завантаження каталогу, — бо відхилений файл є звичною причиною, чому зникла сутність, до якої доходить Release. Запис довіри до плагінів поруч із Release, який існує, але не може бути прочитаний, відхиляється із зазначенням того, що не вдалося прочитати, бо перелік, який би його пропустив, повідомив би про відсутність відкликаних плагінів там, де жоден не вдалося перевірити. Release, чий lock-файл більше не відповідає тому, до чого він розв’язується, відхиляється із зупинкою через розбіжність, яку виводить збірка, як описано в розділі Поведінка в разі помилок, бо перелічені версії були б такими, яких не використовує жодна збірка цього Release. Порожній перелік ніколи не є відповіддю в жодному з цих випадків: він подав би помилково введений шлях чи зламаний робочий простір як Release, що ні від чого не залежить.

Три рівні детальності застосовуються так само, як і до кожного виду. --list виводить лише посилання, по одному на рядок, для передавання конвеєром. Режим за замовчуванням додає розв’язані ідентичності, версію, до якої розв’язалося кожне посилання, використані спільні документи, кожне відображення Manifest, ціль якого не реалізує тип, на який його відображено, а також кожне повідомлення про застарілість чи відкликання, записане щодо того, від чого залежить Release, — у його lock-файлі щодо закріпленого посилання, а в записі довіри до плагінів поруч із ним щодо плагіна, приєднаного в ролі, що повертає вердикт «прийняти або відхилити», — тими самими словами, якими aggrega build друкує ту саму позначку. --detail додає вид кожного посилання там, де місце посилання його записало, — деякі позиції в документі вказують, на який вид вони посилаються, а інші ні, тож вид повідомляється там, де він відомий, а не вгадується з форми імені.

$ aggrega inspect ./release.yaml --catalog ./catalog --closure
Release: prod-release:1.0.0
Aggregate: fullstack-app
Manifest: prod-manifest
Environment: production
Entities (11):
./aggregate.yaml
./manifest.yaml
core/compute/api-server (1.0.0)
core/compute/web-ui (1.0.0)
core/datastore/postgres (1.0.0)
core/k8s-dns-resolver (1.0.0)
db-module (1.0.0)
helm-api-server-synthesized-with-artifacts:1.0.0 (1.0.0)
helm-postgres-synthesized-with-artifacts:1.0.0 (1.0.0)
helm-web-ui-synthesized-with-artifacts:1.0.0 (1.0.0)
k8s-dns-patcher:1.0.0 (1.0.0)

Якщо робочий простір записав, до яких версій розв’язується Release, цей запис слугує основою розв’язання, тож повідомлені версії — це ті, з яких збирається це розгортання, а не те, що каталог випадково містить сьогодні. Робочий простір без такого запису розв’язується за каталогом у його поточному стані.

Підключення, слот і речення про чутливість у прикріпленні

Кожне прикріплення сутності Feature у поданні Release містить речення, що називає факти, які компілятор фіксує про саме прикріплення: який слот прикріплення воно заповнює, чи обробляє воно матеріал, оголошений чутливим, і сутність FeatureRecipe, яка його реалізує, — а для прикріплення, записаного на одному з підключень компонента, ще й підключення, на якому його записано. Речення стоїть між назвою прикріплення та його дужками походження і однаково читається в обох формах походження, описаних нижче.

Прикріплення, записане на підключенні, наводиться під рядком цього підключення в Uses:, а не під Features:, тож Features: містить лише власні прикріплення компонента. Рядок над ним називає підключення за його псевдонімом і компонентом, до якого воно веде, а власне речення прикріплення повідомляє решту:

  • [socket: <socket>] — сокет, через який з’єднано підключення; рядок підключення його не називає. Ця частина йде першою в реченні, бо змінює прочитання решти: наступна частина про слот називає слот, який оголошує сокет підключення, а не той, що його компонент оголошує для власних прикріплень.
  • [connection: <alias> through socket <socket>] — той самий факт для прикріплення, для підключення якого блок Uses: не показує рядка; таке прикріплення тоді наводиться під Features: і називає своє підключення тут. У будь-якому разі підключення називається один раз на прикріплення, ніколи двічі.
  • [slot: <name>] — прикріплення заповнює слот із назвою <name>. Слот заповнюється прикріпленням сутності Feature під власною назвою слота, тож <name> — це назва, під якою записано прикріплення, зіставлена з оголошеними слотами: з featuresSchema сутності Component-хоста для її власних прикріплень і з featuresSchema, який оголошує сокет підключення, для прикріплення, записаного на підключенні.
  • [free] — прикріплення не заповнює жодного оголошеного слота: розв’язана сутність Component не оголошує слота featuresSchema з такою назвою. Це спостереження, а не діагностика. Довільне прикріплення приймається, а оператор, який хоче його заборонити, виражає це як політику управління, а не покладається на те, що інструмент його відхилить.
  • [sensitive] — прикріплення обробляє матеріал, який автор оголосив чутливим, бо прикріплена сутність Feature оголошує чутливий лист, бо слот, який воно заповнює, оголошує sensitive: true, або з обох причин.
  • [realization: <name>:<version>] — сутність FeatureRecipe, яку Manifest цієї сутності Release прив’язує до прикріплення: за власною назвою прикріплення, якщо Manifest зіставляє цю назву, — для прикріплення, записаного на підключенні, це псевдонім і слот, з’єднані крапкою, — інакше за типом Feature. Це реалізація, з якою збирання тих самих документів рендерить прикріплення, і те саме значення, яке скомпільований граф несе на прикріпленні як realization (див. --ir-graph), тож це подання і граф не можуть назвати різні реалізації. Ця частина йде останньою в реченні.

Коли застосовується кілька фактів, вони мають спільне речення. core/storage/s3-object-store оголошує слот secret_access_key, позначений sensitive: true, тож облікові дані, прикріплені під цією назвою, повідомляють обидва факти, тоді як сутність Feature, прикріплена під назвою, для якої сутність Component не оголошує слота, не повідомляє ні слота, ні чутливості. З сутністю Manifest, що зіставляє кожен тип Feature із сутністю FeatureRecipe, кожен рядок також називає свою реалізацію:

Features:
- secret_access_key (core/generated-secret:1.0.0) [slot: secret_access_key, sensitive, realization: generated-secret:1.0.0] [explicit]
- cross-namespace-routing (core/k8s-dns-resolver:1.0.0) [free, realization: k8s-dns-patcher:1.0.0] [explicit]

Компонент, чий сокет models оголошує слот credential, позначений sensitive: true, і який з’єднує під псевдонімом gpt підключення, що цей слот заповнює, наводить це прикріплення під підключенням — поруч із власними обліковими даними, які залишаються під Features::

Uses:
gpt → model
- gpt.credential (feature.conn/token:1.0.0) [socket: models, slot: credential, sensitive, realization: conn-token-compose:1.0.0] [explicit]
Features:
- db_password (feature.conn/token:1.0.0) [slot: db_password, sensitive, realization: conn-token-compose:1.0.0] [explicit]

Прикріплення, записане на підключенні, ніколи не повідомляє [free]: сокет допускає лише оголошені ним слоти, а підключення з будь-якою іншою назвою відхиляється під час завантаження збирання.

Речення повністю пропускається, коли жоден із фактів не застосовується, а кожна частина пропускається незалежно:

  • Відсутність частини про сокет або підключення означає, що прикріплення записано у власному блоці компонента або воно потрапило до нього з ширшої області чи через розгортання на основі анотацій.
  • Відсутність частини про слот означає, що набір оголошених слотів сутності Component-хоста не вдалося розв’язати — наприклад, її тип не відповідає жодній сутності каталогу. Це навмисно відрізняється від [free]: [free] відповідає «слот із такою назвою не оголошено», тоді як відсутня частина означає, що на це питання взагалі не вдалося відповісти.
  • Відсутність sensitive фіксує, що жодне оголошення не позначило прикріплення. Це вужче, ніж висновок, що прикріплення не несе нічого секретного; ця вісь повідомляє про оголошення, і нічого не виводиться з назви поля чи його значення.
  • Відсутність частини про реалізацію означає, що Manifest не прив’язує прикріплення до жодної сутності FeatureRecipe, яка є в каталозі.

Слот, оголошена назва якого буквально free, також рендериться як [free], і його неможливо відрізнити від довільного прикріплення — ніщо не резервує це слово в просторі назв слотів.

Граматика дужок походження в IR

Кожне приєднання Feature у поданні Release має дужку походження. Дужка може мати компактну форму (одна дужка на Feature, коли походження приєднання однакове для всіх листків) або форму за листками (одна дужка на листок, коли листки приєднання походять із різнорідних джерел). Існує три тіла дужок; вони однаково застосовуються до обох форм.

Три тіла дужок

  • [explicit] — приєднання Feature оголошене автором. Сутність Aggregate або Release явно назвала Feature на відповідному вузлі. Явні приєднання — джерело з найвищим пріоритетом; вони завжди мають перевагу над внесками, керованими анотаціями, у тому самому листку.

  • [annotation: <key> from <source>] — приєднання Feature кероване анотацією. Компілятор синтезував його, бо анотація на <source> збіглася з прив’язкою сутності Manifest, що оголошує цю Feature. <key> — ключ анотації, який активував прив’язку (наприклад, business.aggrega.ai/team); <source> — сутність, що несла анотацію (aggregate, release, component або manifest). Синтезоване приєднання структурно ідентичне явному — подальший рендеринг обробляє обидва однаково, — але дужка походження розрізняє їх, щоб налагодження залишалося розв’язним.

  • [explicit; overrides annotation: <key> from <source>] — форма за листками, яка спрацьовує, коли явне оголошення автора в одному листку пригнічує внесок анотації, що інакше встановив би той самий листок. Цей випадок виникає за композиції з різних сторін: анотація Aggregate може надати стовп values: для Feature, анотація Release надає її стовп infra:, а явне оголошення Release на тій самій Feature перевизначає один листок infra. Дужка листка фіксує і явного автора, і пригнічену анотацію; пригнічена анотація не впливає на відрендерений результат, але її присутність видно в поданні inspect, щоб оператор міг побачити, яку анотацію перевизначено і де.

Компактна форма та форма за листками

Компілятор обирає між компактним рендерингом і рендерингом за листками, обходячи походження приєднання за листками й перевіряючи однорідність. Походження приєднання однорідне, коли кожен заповнений листок (у стовпах values: та infra: сутності Feature) має те саме джерело (явне чи анотація), той самий ключ анотації, якщо воно кероване анотацією, ту саму сутність-джерело, і жоден листок не має позначки «overrides annotation». Коли походження однорідне, компілятор виводить одну дужку на приєднання:

- core/rate-limiter [annotation: business.aggrega.ai/team from aggregate]

Коли походження розходиться — типовий випадок — композиція з різних сторін, де анотація Aggregate надає values:, а анотація Release надає infra: на тій самій Feature, — компілятор виводить одну дужку на кожен заповнений листок:

- core/pii-redaction
values.fields_to_mask: ["ssn", "card_number"] [annotation: compliance.aggrega.ai/data-class from aggregate]
values.classifier_endpoint: "redact-v2" [explicit; overrides annotation: compliance.aggrega.ai/data-class from aggregate]
infra.audit_bucket: "s3://..." [annotation: compliance.aggrega.ai/audit-bucket from release]

Порядок обходу: спершу стовп values (у порядку автора), потім стовп infra (за тим самим принципом). Префікс стовпа (values. / infra.) і шлях через крапку всередині стовпа точно вказують, який листок анотує кожна дужка.

Значення, оголошені чутливими

Лист, схема якого оголошує sensitive: true, виводить замість свого значення фіксований текст <redacted>. Ключ, префікс стовпа та дужка походження зберігаються — замінюється лише значення, — тож макет і далі показує, які листи має сутність і звідки походить кожен. Це стосується двох читабельних поверхонь: блоку Values: для кожного вузла сутності Aggregate та блоку прикріплень для кожного листа розв’язаної сутності Release — зокрема прикріплення, записаного на з’єднанні й виведеного під рядком цього з’єднання, яке приховує саме ті листи, що їх приховує та сама сутність Feature, коли її містить сам компонент. Скомпільований граф сутності Release під --ir-graph приховує ті самі листи у структурованій формі, описаній у розділі Машиночитаний вивід.

Components:
app (type: core/app)
Values:
appName: demo
dbPassword: <redacted>
tuning.poolSize: 25
tuning.adminToken: <redacted>

Приховується лише оголошений лист, а клауза [sensitive] на рівні прикріплення не є вказівкою приховати: вона повідомляє, що прикріплення працює із секретним матеріалом, а не які з його листів його містять. Опубліковані локатори облікової сутності Feature — назва ресурсу та ключ даних — є публічними і навмисно залишені неоголошеними в каталозі стандартної бібліотеки, тому вони виводяться відкритим текстом поруч із матеріалом, який так не виводиться:

- credentials (feature.test/db-credential)
values.secretName: db-creds [explicit]
values.literalPassword: <redacted> [annotation: feature.test/pw from aggregate.yaml:components.app.annotations.feature.test/pw]

Нічого не виводиться з назви поля: поле з назвою password без оголошення виводить своє значення, а оголошене поле з назвою key — ні. Приховування стосується того, що виводить інструмент; воно ніколи не торкається відрендереного артефакту, і dist/ створюється саме таким, яким його створив рендеринг. Ключове слово та повні межі того, чого досягає його оголошення, описано в vocabulary/compact-form-authoring.md, розділ «Declaring a leaf sensitive».

Показ прихованих значень

--unredacted виводить значення, оголошені чутливими, замість того щоб їх приховувати, одразу на всіх поверхнях inspect — і в читабельних макетах вище, і у скомпільованому графі сутності Release. Цей прапорець існує тому, що приховане значення іноді саме і є предметом розслідування: облікові дані, що надходять із хибного прикріплення, виглядають так само, як правильні, коли обидва показано прихованими.

Його дія обмежена командою, якій його передано. aggrega build і aggrega validate теж його приймають, де він стосується лише графа, який повертає --ir-graph, і нічого іншого, та відхиляють його, коли граф не запитано. aggrega build --trace-unredacted — та сама ідея для файлів трасування збирання, і жоден із двох прапорців збирання не впливає на вивід іншого; відрендерений артефакт у dist/ не залежить від жодного з них, бо він створюється саме таким, яким його створив рендеринг, хоч би що було передано.

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

Коли варто використовувати inspect

  • Налагодження «чому тут цей Feature?» — прикріплення, створені анотаціями, невидимі у YAML-файлах Aggregate і Release (анотації там є, але прикріплення Feature, які вони синтезують, існують лише в IR). Inspect показує їх разом із походженням.
  • Перевірка успадкування схем — aggrega inspect <ComponentName> показує об’єднану схему після розв’язання ланцюжка extends:; сам авторський файл показує лише локальну різницю.
  • Діагностика несподіванок міжсторонньої композиції — коли анотація Aggregate і анотація Release обидві надають дані стовпів для того самого Feature, розв’язані листки буває важко відтворити подумки. Форма дужок для кожного листка робить розв’язання явним.
  • Перевірка перед розгортанням — aggrega inspect ./prod-release.yaml перелічує кожен Feature на кожному Component до того, як aggrega build створить артефакти; оператор може переконатися, що топологія відповідає задуму, перш ніж фіксувати відрендерені маніфести в GitOps.

Про базові механізми — як каскадуються анотації, як розподіл «сторона проти стовпа» спрямовує значення анотацій у стовпи Feature і як принцип «явне прикріплення перемагає» взаємодіє з внесками анотацій — див. providers/well-known-annotations.md і entities/manifest.md «Annotation-Driven Feature Bindings».

Синтаксис

aggrega inspect [identifier] [flags]

Опис

Render a readable view of any Aggrega entity — a catalog entity by name, an
authored entity file by path, an entity published in a registry, or a
fully-resolved Release.
It answers "what does this entity actually resolve to?": which entities extend
which bases, which Recipe maps to each type, which Features attach to each node,
and where each Feature's contributions came from.
A single argument routes by its shape. A path — anything starting with ./, ../
or /, or ending in .yaml or .yml — is read as a file and inspected by its own
kind: header. A registry reference — oci://<host>/<repository>:<tag>, or
@<digest> in place of :<tag> — is read from the registry that publishes it.
Anything else is looked up by name in the catalog search stack: the
workspace's own, or, with --release, the one the workspace configuration
gives that Release, so a name several catalog variants declare, one per
Release, resolves to the variant that Release builds with.
A registry reference shows the entity exactly as it was published: unpacked
from the archive its kind is published as where it is one, and rendered by the
same view a file of that kind gets. Reading it reaches the network, using the
credentials this machine holds for that registry, and an offline workspace
refuses it. The fetched bytes are checked against the digest the artifact's
own manifest records for them, which establishes that they are the bytes that
manifest names and nothing more: no signature attached to the artifact is
verified, no withdrawal recorded against it is reported, and nothing is
written — no cache entry and no lockfile.
Three verbosity levels apply to every kind: --list for identifiers only, the
default for a structured overview, and --detail for full field bodies. --list
and --detail are mutually exclusive. Resolution depth has its own pair, --raw
for the entity exactly as authored and --resolved for the kind's full depth,
also mutually exclusive.
Note that --raw reproduces the file as written, so a value the author declared
sensitive appears as authored. That is what as-authored means; handle such
output as you would the entity file itself. --output yaml reproduces the file
the same way for every kind, a Release included.
A Release answers two further questions, and each has its own flag because
neither answer contains the other. --ir-graph asks for the IR graph a Release
resolves to — what the Release looks like, as JSON on stdout in addition to
whatever else this command produces. --closure asks for the Release's dependency
closure — every catalog entity it reaches and the version each resolved to,
which is what was pulled in to build the Release. An entity can be reached
without appearing as a node, and a node does not carry the version its type
resolved to, so holding one of the two is not holding the other.
--ir-graph is orthogonal to --output, which picks the format of the command's
own view. Values an author declared sensitive are withheld from the graph, as
they are from the readable layouts. Pass --unredacted to print them instead.

Прапорці

ПрапорецьЗа замовчуваннямОпис
--catalog[]Каталог; можна повторювати. Кожен —catalog <dir> додається на початок стеку пошуку каталогів (перший збіг перемагає): catalog_dirs робочого простору або, для сутності Release, якій конфігурація робочого простору надає власні каталоги в workspace.releases, каталоги цієї Release; стек завершується каталогом з назвою catalog у корені робочого простору, якщо такий є. Порожній список catalog_dirs взагалі не читає жодного локального каталогу.
--closurefalseПоказати замикання залежностей Release — кожну сутність каталогу, якої вона досягає, у версії, до якої кожна розв’язалася, — замість подання розв’язаних вузлів. Застосовується до Release — єдиного типу, що розв’язує замикання; будь-який інший тип відхиляє запит, а не мовчки ігнорує його.
--colorautoКольоровий вивід: auto|always|never.
--detailfalseВиводити повний вміст полів.
--flatfalseВиводити деревоподібну сутність (Aggregate, Release) як плаский список, де кожен вузол має префікс свого повного шляху через крапку. Не впливає на табличні типи.
--ir-graphfalseТакож записати граф IR, обчислений цим запуском, у stdout у форматі JSON, на додачу до всього, що ця команда вже виводить. Значення, які автор оголосив чутливими, у ньому приховано; передайте —unredacted, щоб вивести їх. Застосовується до Release — єдиного типу, що розв’язується в граф; будь-який інший тип відхиляє запит, а не мовчки ігнорує його
--listfalseВиводити лише ідентифікатори.
--no-colorfalseВимкнути кольоровий вивід (псевдонім для —color=never).
--output, -otextФормат виводу: text|yaml.
--plugin—Шлях у файловій системі до сирого артефакту <file.wasm>; визначає й виводить імпортовані ним функції хоста, перш ніж aggrega plugin sync запише їх у сутність Plugin. Не приймає аргументу-ідентифікатора.
--rawfalseВиводити сутність у авторському вигляді, без розв’язання.
--release—Шукати ім’я каталогу в термінах цього файлу Release: у каталогах, які конфігурація робочого простору надає цій Release, з —catalog на початку. Застосовується до імені; файл або посилання на реєстр перевіряється як є і відхиляє цей прапорець. Відносний шлях розв’язується відносно каталогу, з якого ви запускаєте команду, а не кореня робочого простору. Якщо цей каталог не належить жодному робочому простору і корінь не вказано, абсолютний шлях знаходить робочий простір від власної теки Release
--resolvedfalseВиводити сутність повністю розв’язаною.
--show-implementsfalseДля Recipe або FeatureRecipe розв’язати spec.implements у каталозі й вивести пов’язаний Component або Feature.
--unredactedfalseВиводити значення, які автор оголосив чутливими, замість їх приховування. Усе, куди потрапляє вивід, — термінал, канал, файл, запис екрана — тоді містить ці значення у відкритому вигляді.