Перейти к содержимому
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 добавляет свои механизмы self-inject, обязательные 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в разрешённом видеСтроится топология — вычисляются граф uses и порядок.
Releaseв разрешённом видеВыполняется полный конвейер: разрешение, раскрытие аннотаций, запуск guard-проверок, построение топологии, построение IR.

Файл, у которого kind: равен Workload, отклоняется: сущность Workload существует только внутри сущности Recipe и не является отдельно просматриваемой сущностью. Чтобы увидеть её Workload, просмотрите сущность Recipe.

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

У большинства видов нет конвейера — inspect читает файл и отображает его. Содержательно разрешаются три вида экземпляров:

  • Manifest применяет свою цепочку extends: — следуя импортам файлов — и отображает объединённые сопоставления компонентов и функций. --raw показывает файл в авторском виде.
  • Aggregate строит свою топологию: создаётся граф использования и вычисляется порядок зависимостей. Представление по умолчанию показывает компоненты с их значениями и рёбрами, а за ними — граф зависимостей. --raw показывает авторское дерево подсистем.
  • Release выполняет весь конвейер компиляции вплоть до IR — разрешение, раскрытие аннотаций, запуск проверок, построение топологии, построение 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:, которого нет в стеке, читается там же, где его читает сборка: из кэша артефактов, под закреплением, которое lockfile сущности 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> точно указывает один манифест. Так можно посмотреть на сущность, которая существует только в реестре: репозиторий — это сегмент вида, за которым следует идентичность сущности, как описано в §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 добавляет механизмы самовнедрения, обязательные 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 к одному имени режима и когда сообщает, какой объявленный режим связанный provider не может поддержать, — поэтому это представление и диагностика сборки называют режимы в одном порядке. 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 (см. Соединение, слот и пояснение о чувствительности вложения). Они берутся из объявления слота в сокете и из объявления самой 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)

Каждая граница содержит свой выходной каталог и аннотации, потребляемые provider; каждый компонент под границей содержит свой тип компонента 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 и раздел «Annotation-Driven Feature Bindings» в entities/manifest.md.

Синтаксис

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Выводить значения, которые автор объявил чувствительными, вместо того чтобы скрывать их. Всё, куда попадает вывод, — терминал, конвейер, файл, запись экрана — тогда содержит эти значения в открытом виде.