Перейти к содержимому
AggregaAggrega
Выберите язык: Русский
Эта страница переведена машинным способом. Читать оригинал на английском.

aggrega push

aggrega push публикует сущность каталога в реестре OCI, откуда другие рабочие пространства могут разрешить её с помощью aggrega pull.

Что делает команда

aggrega push читает один YAML-файл сущности, упаковывает его для передачи и отправляет по адресу <registry>/<kind>/<metadata.name>:<metadata.version>, приводя путь репозитория к нижнему регистру; сущность Recipe или FeatureRecipe добавляет свой spec.capability, а сущность Plugin — свой metadata.pluginType в виде сегмента между видом и именем. Выполните aggrega push --list-kinds, чтобы получить виды сущностей, которые публикует установленный бинарный файл: по одному виду в строке, в отсортированном порядке и ничего больше, так что скрипт может читать вывод напрямую. Этот набор охватывает виды сущностей для авторинга каталога, а также Aggregate — повторно используемый модуль — и Plugin — адресуемую по содержимому ссылку на артефакт WebAssembly, который компилятор маршрутизирует, а среда выполнения исполняет. Сущность Plugin — это структурный публикуемый артефакт, а не вид сущности для авторинга каталога. Возможность публикации — свойство самой сущности, а не способа её использования: сущность Aggregate публикуема независимо от того, будет ли на неё впоследствии ссылаться spec.aggregate верхнего уровня сущности Release или она будет вложена в блок aggregates: другой сущности Aggregate. Release и Manifest — входные данные со стороны развёртывания, а не артефакты каталога, и они отклоняются.

Упаковка

При публикации отправляется документ сущности и файлы рядом с ним, которые называет сама сущность, — и ничего больше из её каталога. Сущность называет следующие файлы:

  • для сущности Recipe или FeatureRecipe — её локальный source: (каталог передаётся со всеми файлами внутри него, которые сохраняют правила игнорирования, записанные в её entity.lock, как описано в разделе Какие файлы поставляются с сущностью); каждый файл, который её записи valuesMapping:, workload: и artifacts: импортируют через $import:; а также entity.lock рядом с ней;
  • для сущности Component или Feature — каждый файл схемы, который её spec.schema, опора или сокет usesSchema импортирует через $import:, включая каждый файл, который в свою очередь импортирует импортированный файл.

Сущности Aggregate, Plugin и библиотечные виды не называют никаких файлов рядом со своим документом. Заметка, README, файлы другой сущности или результат сборки, лежащие в каталоге, не публикуются, как бы они ни назывались. Символическая ссылка среди файлов, которые называет сущность, отклоняется, а не разыменовывается — A symbolic link sits among the files an entity carries (Среди файлов сущности находится символическая ссылка), — как и путь, который сущность называет через каталог, являющийся ссылкой за пределы каталога сущности, ещё до какой-либо упаковки — A path names content outside the entity’s own directory (Путь указывает на содержимое вне собственного каталога сущности).

Отсюда следует форма публикации. Сущность, которая ничего не называет, публикуется как её документ без изменений с медиатипом +yaml её вида. Сущность, которая называет файл, публикуется как .tar.gz, содержащий документ и эти файлы на их местах в каталоге, с медиатипом +tar+gz её вида. Поэтому сущность Recipe, всё содержимое которой встроено, публикуется как её документ, а сущность Component, схема которой импортируется из файла, публикуется как архив. В §6 главы Catalog and Registry перечислены оба медиатипа для каждого вида.

Каждый файл в архиве имеет режим 0644 и не имеет метки времени, каковы бы ни были его биты прав на диске. Извлечение из репозитория записывает файлы со своими битами прав, а система, не хранящая бит исполнения, извлекает как обычный файл то, что другая система извлекает как исполняемый, поэтому архив не содержит режима, прочитанного с диска: два извлечения одного коммита публикуют одинаковые файлы независимо от их umask и от системы, на которой они сделаны, а изменение бита исполнения у скрипта ничего не меняет в публикуемом.

При публикации выдаётся предупреждение о каждой записи архива, которую Windows не может хранить в таком виде, — о пути с частью, названной по имени устройства, например CON, AUX или NUL, в любом регистре и с любым расширением, как aux/x.yaml, или о части, оканчивающейся точкой или пробелом, как report.. В Windows aggrega отказывается распаковывать такую запись, поэтому рабочее пространство в Windows не может использовать эту версию. Предупреждение выводится в стандартный поток ошибок на любой платформе, по одной строке на запись, перед собственным отчётом о публикации; имя файла самого документа сущности проверяется вместе с называемыми ею файлами, а сущность, которая ничего не называет, публикуется только как её документ, и предупреждение для неё никогда не выдаётся. Предупреждение ничего не блокирует: публикация выполняется или отклоняется точно так же, как без него, а --dry-run предупреждает так же. В разделе A published archive carries an entry Windows cannot use (Опубликованный архив содержит запись, которую Windows не может использовать) показана эта строка и что с ней делать.

Локальный source:, записанный как шаблон, переносит весь каталог. Шаблон вида ./charts/{{ .values.flavour }} называет каталог только после того, как его заполнит сущность Release, поэтому ни одна публикация не может знать, какой это будет каталог. Такая сущность переносит каждый файл своего каталога, который сохраняют её записанные правила игнорирования, — но никогда не её .aggregaignore, правила которого передаются внутри lock-файла, — и публикация сообщает об этом под остальными сведениями:

carries: every file in the entity's directory, because its source "./charts/{{ .values.flavour }}" is a template and the directory it names is decided by each Release that uses it

То, что не названо, не передаётся, и обнаруживает это потребитель. Файл, на который сущность опирается, не называя его через одно из перечисленных выше полей, не попадает в публикацию, и сборка у потребителя завершается ошибкой с указанием отсутствующего пути внутри его слота кэша — а не ваша публикация. Называйте каждый нужный сущности файл через одно из этих полей.

Каждый опубликованный файл назван в манифесте артефакта, поэтому универсальный клиент OCI, например oras, записывает его в файл с этим именем: entity.yaml для сущности, опубликованной как её документ, entity.tar.gz для сущности, опубликованной с её файлами, а для сущности Plugin — entity.yaml для сущности рядом с entity.wasm для её исполняемого файла. Имя определяется медиатипом, а не файлом, из которого вы публикуете, поэтому одно и то же содержимое, опубликованное из переименованного файла, даёт тот же артефакт. В §6 главы Catalog and Registry перечислены все публикуемые формы и файл, в который попадает каждая.

Удалённый URL source: у сущности Recipe (ссылка на чарт OCI, URL чарта или фрагмента по HTTPS, модуль Git) сохраняется дословно в опубликованном YAML; он не скачивается и не встраивается в артефакт. Потребители разрешают и закрепляют удалённые источники самостоятельно, в момент собственного скачивания. Так распространение сущностей каталога и разрешение артефактов-источников остаются отдельными задачами.

Сущность Aggregate публикуется как один собственный документ: вложенный агрегат, на который она ссылается в aggregates:, не упаковывается в артефакт. Каждый вложенный агрегат — это отдельно опубликованная сущность Aggregate, которую потребители разрешают и закрепляют самостоятельно в момент скачивания, по идентичности, — тот же принцип раздельного распространения, что и для удалённых источников.

Одна сущность на каталог

Архив содержит файл сущности среди файлов, которые она называет, поэтому при распаковке сущность нужно снова найти. Потребитель находит её по преамбуле, которую она несёт: документ в корне пакета, чей kind: является публикуемым видом сущности, и есть сущность. Файл, в котором она написана, может называться как угодно — recipe.yaml является соглашением каталога, а не требованием, — и фрагмент compose, шаблон чарта или манифест Kubernetes рядом с сущностью не принимаются за неё, потому что они объявляют что-то другое или не объявляют вид вовсе. Документы сущностей глубже, внутри дерева source/, являются содержимым, которое сущность поставляет, а не самой сущностью, и никогда не рассматриваются.

Push отклоняет сущность, которая делит свой каталог с другой сущностью. У каждого вида есть собственный каталог, кроме Aggregate, Release и Manifest, которые корень рабочего пространства хранит рядом друг с другом. Для любого другого вида push прежде всего остального, что он делает с сущностью, — до шага закрепления, политики подписи и сборки пакета — проверяет, что в том же каталоге нет другого документа сущности, и в противном случае отказывает, называя каждую мешающую сущность, независимо от того, было ли push предписано выполнить закрепление. aggrega pin отклоняет такой же каталог теми же словами; остановка — An entity shares its directory with another entity (Сущность делит свой каталог с другой сущностью). Документ, не относящийся ни к одному виду сущности, рядом с сущностью — файл чарта, фрагмент compose, README — не мешает, как и всё, что находится в подкаталоге. Каждый документ рядом с сущностью читается только изнутри рабочего пространства или, для сущности, указанной вне его, изнутри собственного каталога сущности, поэтому документ, являющийся ссылкой, ведущей наружу, останавливает push с указанием этой ссылки, не читая её, как описывает граница рабочего пространства.

Это правило обеспечивает принадлежность одного entity.lock одной сущности: имя файла блокировки одинаково для всех сущностей, поэтому две сущности, написанные в одном каталоге, делили бы единственный файл блокировки, для которого в нём есть место. Оно проверяется только тогда, когда из каталога что-то производится, поэтому каталог с несколькими сущностями по-прежнему загружается, проходит lint и собирается.

Имя каталога не проверяется. Сущность, одна в своём каталоге, публикуется под своей metadata.version, где бы ни находился этот каталог; <name>/<version>/ — структура, которой следует каталог стандартной библиотеки, — является соглашением. Артефакт, опубликованный другим клиентом из каталога с двумя сущностями, всё равно читается безопасно: его pull останавливается с указанием обоих документов, а не отвечает одним из них; эта остановка описана в errors/fatal-halts.md.

Чтение сущности перед упаковкой

Push читает сущность Component, Feature, Recipe или FeatureRecipe так же, как её читает сборка, и отклоняет то, что отклоняет такое чтение, — по той же причине, с тем же кратким кодом, до построения пакета и до обращения к целевому реестру. Поэтому документ, не соответствующий схеме своего вида, путь, указывающий на содержимое за пределами собственного каталога сущности, и схема, которую Component или Feature импортирует через $import: и которая отсутствует или не может быть использована, отклоняются при публикации, а не публикуются. Каждый из этих случаев — сущность, которую отклонила бы первая же сборка её потребителей; путь, выходящий за пределы каталога, к тому же указывает на файл, который не попадёт в публикацию вместе с сущностью, поскольку каждый файл публикации берётся из собственного каталога сущности, — см. A path names content outside the entity’s own directory (Путь указывает на содержимое за пределами собственного каталога сущности).

Сущность Recipe или FeatureRecipe читается так при сравнении её закреплений, описанном в следующем разделе, поэтому чтение выполняется независимо от того, запрошено ли закрепление при push и есть ли у сущности что закреплять. Каждый из четырёх видов также читается так непосредственно перед построением своего пакета, поскольку именно это чтение определяет, какие файлы он называет. Сущность Aggregate и библиотека не называют файлов и так не читаются. Сущность Plugin тоже не называет файлов и проверяется по схеме своего вида до чтения её .wasm, как описано в разделе Публикация Plugin.

Публикация сущности Plugin

Сущность Plugin публикуется вместе со своим .wasm, указанным в --plugin, и push проверяет оба до того, как будут опубликованы какие-либо байты или установлено соединение с реестром. --dry-run проверяет их точно так же, как публикация.

Сначала сущность проверяется по схеме своего вида — так же, как её читает загрузка каталога, — и только затем читается .wasm. Поэтому metadata.version, не являющийся семантической версией (например, голый коммит 415148e), отклоняется по условию самой схемы с указанием поля; так же отклоняется и любое другое отступление от схемы, например отсутствующий spec.abiVersion. Семантической версией здесь считается то, что соответствует шаблону самой схемы для metadata.version; push не добавляет собственных правил.

Затем .wasm загружается и сверяется с сущностью. То, что он сообщает о предоставляемых возможностях, должно совпадать с заявленным в сущности, записанные в сущности набор команд и функции хоста должны ему соответствовать, а версия, которую он сообщает о собственной сборке, должна быть равна metadata.version — см. A Plugin entity’s recorded version does not match the plugin (Записанная в сущности Plugin версия не совпадает с плагином).

.wasm, собранный из рабочего дерева с незакоммиченными изменениями, отклоняется. Такая сборка несёт метку -dirty в конце сообщаемой версии — 1.0.0-dirty, 1.0.0-3-g1a2b3c4-dirty. Это допустимая семантическая версия, но она указывает на коммит, который не содержит собранного, поэтому никто не смог бы пересобрать опубликованное по версии, под которой оно опубликовано. Push отклоняет её, указывая версию и способ исправления: соберите плагин из чистого checkout коммита, на который указывает тег релиза, чтобы он сообщал саму версию релиза (а чтобы выпустить изменение, сначала закоммитьте его с metadata.version сущности, равным новому релизу, и поставьте тег на этот коммит), вместо того чтобы копировать в сущность версию, которую сообщает пересборка. Версия разработки, собранная из коммита, например 1.0.0-3-g1a2b3c4, и предварительный выпуск, например 1.0.0-rc.1, публикуются. Отказ: A plugin was built from a working tree with uncommitted changes (Плагин собран из рабочего дерева с незакоммиченными изменениями).

Закрепление перед публикацией

Сущность Recipe или FeatureRecipe хранит закрепления для входных данных, которые она читает, — удалённого source:, записанного полностью, файла, импортируемого записью artifacts, файлов локального source: рядом с ней, — в файле entity.lock рядом с ней, и push публикует этот файл вместе с сущностью. Закрепление — это шаг, который выполняется перед публикацией, aggrega pin, после чего нужно закоммитить записанный им lock-файл.

Push отклоняет сущность, lock-файл которой не содержит этих закреплений. Прежде чем собрать пакет, push вычисляет, что записал бы для сущности шаг закрепления, и сравнивает это с файлом entity.lock рядом с ней. Если закрепление отсутствует или lock-файл содержит закрепление, которому входные данные больше не соответствуют, push останавливается до сборки какого-либо архива и до обращения к какому-либо реестру. Отказ называет сущность и все такие входные данные — каждое как remote source, imported file или local source file — и что следует запустить: aggrega pin для сущности, --pin-sources для только что выполненного push или pin_sources_at_push для каждого push в рабочем пространстве. Это тот же отказ, который pull выдаёт для того же lock-файла, An entity reads an input the lock beside it records no pin for (Сущность читает входные данные, для которых lock-файл рядом с ней не содержит закрепления), но со способами исправления, присущими push. Поэтому сущность Recipe или FeatureRecipe, публикуемая push, несёт внутри своего пакета lock-файл, содержащий все закрепления, которые шаг записал бы на момент публикации.

Два вида сущностей не требуют закрепления и публикуются без изменений: сущность, которая не читает удалённых источников, не импортирует файлов и не называет локальных источников, и сущность Recipe, координаты удалённого источника которой заполняются из шаблона. Такой источник указывает на артефакт, только когда сущность Release заполняет шаблон, поэтому его закрепление принадлежит lock-файлу каждой сущности Release, и push не требует его рядом с сущностью. Сущности Component, Feature, библиотека, Aggregate или Plugin не читают ничего, что записывается в lock-файл, и здесь никогда не отклоняются.

Сравнение закрепления удалённого источника означает загрузку этого источника, как это делает aggrega pin, поскольку несоответствие закрепления видно только по сравнению с тем, что источник отдаёт сейчас. Поэтому push сущности с таким источником обращается к хосту источника раньше, чем к реестру. Сравнение читает сущность Recipe или FeatureRecipe так же, как шаг закрепления, — через каталог, поэтому сущность, которую каталог отказывается читать (например, документ, не соответствующий схеме своего вида), здесь отклоняется с причиной, указанной каталогом.

Если рабочее пространство не найдено и не указано, push, которому для сравнения нужно загрузить удалённый источник, отклоняется до загрузки, так же как aggrega pin. Сравнение загружает каждый удалённый источник, который сущность записывает полностью, в кеш артефактов — точно так же, как шаг закрепления, — а кеш, записанный в папке, от которой не было найдено рабочее пространство, сделал бы эту папку рабочим пространством. Поэтому, когда ничто не задаёт корень и ничто его не обозначает — начиная с папки, в которой вы запускаете push, или, для сущности, указанной абсолютным путём, с собственной папки сущности, — push сущности Recipe или FeatureRecipe с таким источником останавливается до загрузки источника, включая пробный запуск и --pin-sources, и называет источник, папку и два выхода: укажите рабочее пространство с помощью --workspace-root или AGGREGA_WORKSPACE_ROOT либо поместите в эту папку файл .aggrega-config.yaml с блоком workspace:. Для двух видов сущностей, описанных выше, и для сущности с локальным источником сравнение ничего не загружает, поэтому каждая из них сравнивается со своим lock-файлом и публикуется там так же, как в любом другом месте; а все остальные виды не проверяются по lock-файлу и по этой причине не отклоняются. В разделе Конфигурация перечислены другие команды, к которым это относится.

aggrega push --pin-sources сначала сам выполняет этот шаг. Шаг выполняется до сборки пакета, поэтому записанный им lock-файл попадает в опубликованный артефакт и учитывается в опубликованном дайджесте; кроме того, он выполняется раньше всех остальных отказов, оценивающих сущность, поэтому оценивается уже закреплённая сущность. Раньше выполняется только описанное выше правило о каталоге, поскольку шаг записывает единственный lock-файл, который содержится в каталоге. Шаг записывает те же байты, что и aggrega pin, поэтому описанный выше отказ при таком запуске никогда не срабатывает: только что записанный lock-файл содержит ровно то, с чем сравнивал бы отказ. Ключ рабочего пространства pin_sources_at_push делает это поведением по умолчанию для каждого push, а --pin-sources=false пропускает шаг для одного запуска, что возвращает отказ. Шаг записывает рядом с сущностью, для чего нужно доступное для записи расположение, — и у push оно всегда есть, поскольку он публикует указанный вами документ.

--dry-run отвечает так же, как ответила бы публикация. Без --pin-sources он отклоняет незакреплённую сущность точно так же, как публикация, поэтому пакет, о котором сообщает пробный запуск, этот отказ пропустил бы. С --pin-sources шаг выполняет закрепление в пробном режиме: выводит lock-файл, который записал бы, и ничего не записывает, а последующие сведения о пакете описывают каталог в текущем состоянии, без этого lock-файла, — поэтому дайджест соответствует публикации без него, а если lock-файл был бы новым, то и размер, и, для сущности, не указывающей ничего другого, тип носителя. Отказ не срабатывает, поскольку публикация сначала выполнила бы закрепление.

Лучшая практика: изменение уже опубликованной версии оформляется как новая версия, после чего выполняется закрепление. Скопируйте сущность в каталог новой версии, внесите изменение там, закрепите её и опубликуйте. Половина этого, которую обеспечивает продукт, описана в следующем разделе: публикация другого содержимого под уже опубликованной версией отклоняется. Вторая половина — не перезакреплять уже опубликованную версию после её редактирования в собственном рабочем пространстве — остаётся за вами; локально это ничем не отклоняется, поскольку перезакрепление допустимо для сущности, которую вы ещё не опубликовали.

Реестр, тег и адресация по содержимому

Целевой реестр — это --registry <ref>, если он указан, иначе default_registry рабочего пространства (по умолчанию hub.aggrega.ai). Тег — это metadata.version сущности, а путь репозитория выводится из её вида и имени, поэтому место, куда попадает опубликованная версия, не зависит от каталога, из которого она была опубликована.

default_registry может содержать путь репозитория, и публикация через него попадает по этому пути. При default_registry: ghcr.io/acme сущность Component core/api-server версии 1.0.0 публикуется в ghcr.io/acme/component/core/api-server:1.0.0 — там, откуда её получает pull через то же значение по умолчанию, поэтому подпись, прикреплённая здесь, — та самая, которую находит этот pull. --registry задаёт хост, и публикация, направленная через него, попадает на этот хост без пути. Каким бы способом ни было задано место назначения, применяются требование подписи и конфигурация подписи, заданные для его хоста: путь никогда не выбирает другую политику. Написание пути описано в разделе как записывается хост реестра.

Манифест указывает дайджест опубликованных байтов, а lock-файл записывает дайджест того, что они содержат. OCI-манифест, который записывает push, указывает дайджест опубликованного документа или архива, и aggrega pull отклоняет загрузку, которая ему не соответствует, поэтому байты, изменённые между публикацией и получением, обнаруживаются. Lock-файл, который записывает pull, фиксирует сущность по другому дайджесту: дайджесту её содержимого — путь и байты каждого файла и ничего о том, как был сжат архив или какие биты прав были у его файлов. Это тот же дайджест, который pull в собственном рабочем пространстве автора записывает для той же сущности в её каталоге, поэтому автор и каждый потребитель одной публикации записывают одно и то же значение, и сборка с любой стороны отклоняет содержимое, которое ему больше не соответствует. Два дайджеста отвечают на разные вопросы: дайджест манифеста проверяет загрузку, а дайджест lock-файла — это идентичность сущности.

Публикация поверх существующей версии

Прежде чем загрузить какие-либо байты, aggrega push определяет, что целевой реестр уже хранит по ссылке, которую команда собирается записать, и сравнивает это с имеющимся содержимым. Возможны три исхода:

  • Там ещё ничего не опубликовано — push продолжается и выполняет публикацию обычным образом.
  • То же самое содержимое — ничего не загружается, и команда сообщает, что версия уже опубликована, поэтому повторный push не является ошибкой. То, что предыдущий push не прикрепил, — подпись или дата публикации — прикрепляется сейчас, как описано в разделе Завершение публикации, которую предыдущий push оставил неполной.
  • Другое содержимое — push останавливается и называет уже опубликованный дайджест и тот, который он записал бы. Никакой флаг не позволяет выполнить его принудительно.

Таким образом, уже опубликованная версия по-прежнему обозначает байты, опубликованные под ней. Изменившееся содержимое публикуется под новым metadata.version; aggrega lint --pre-publish отвечает на следующий вопрос — насколько должна измениться версия, — классифицируя изменение относительно ранее опубликованной версии.

--dry-run выводит дайджест, который записал бы push, рядом со ссылкой, по которой он был бы записан:

aggrega push (dry-run): <reference>:<tag> (<digest>)

Это тот же дайджест, который сам push сравнивает с уже опубликованным; он вычисляется тем же способом только по содержимому, и его вывод не обращается ни к какому реестру. Поэтому имеющееся у вас содержимое можно сверить с дайджестом, под которым была опубликована версия, ещё до того, как что-либо будет отправлено: если для опубликованной версии они различаются, push будет отклонён. С --pin-sources это дайджест каталога в его текущем состоянии, как описано в разделе Закрепление перед публикацией.

Завершение публикации, которую предыдущий push оставил неполной

Push сначала записывает содержимое, а затем прикрепляет подпись и дату публикации, поэтому push, который завершился сбоем на одном из этих прикреплений — после повторных попыток, — оставляет содержимое опубликованным без него и завершается с ненулевым кодом, указывая, что не удалось прикрепить. Повторный запуск того же push завершает эту публикацию. Он обнаруживает, что содержимое уже опубликовано, выводит строку Already published:, ничего не загружает и прикрепляет то, чего версии ещё не хватает, — каждое в той строке, которую выводит для него первая публикация:

  • Подпись, если этот push подписывает. Она прикрепляется, когда у версии нет подписи, которая считается подписью этой публикации. Если ваша конфигурация закрепляет политику доверия для хоста назначения — public_key или trusted_identities, либо для hub.aggrega.ai встроенный базовый уровень, — подпись засчитывается, когда она проходит проверку по этой политике, поэтому подпись, которую политика не допускает, никогда не принимается за собственную подпись публикации. Если политика не закрепляет ни того, ни другого, никакая подпись не может пройти проверку по ней, поэтому засчитывается любая подпись версии, и push подписывает только версию, у которой подписи нет; при оценке по проверке в этом случае при каждом запуске прикреплялась бы ещё одна подпись.
  • Дата публикации, если правило для дат её требует — по только что прикреплённой подписи или по уже засчитанной, — и у версии нет никакого реферера published-at. Push, который не подписывает, должен прикрепить дату так же, как неподписанная публикация, независимо от того, какие подписи были прикреплены к версии позже. Указываемая дата берётся по собственным часам этого push: это время завершения публикации, которое позже времени первого появления содержимого, поскольку ничто из отдаваемого реестром этот момент не фиксирует.

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

Когда реестр не выполняет запись

Публикация записывает данные в реестр поэтапно: сначала содержимое (для сущности Plugin — саму сущность и её .wasm), затем манифест, который на него ссылается, затем тег версии, затем подпись и дату публикации рядом с ним. Каждый шаг записи повторяется, если он завершился сбоем, при котором последующая попытка может оказаться успешной: реестр отвечает ошибкой сервера (любой статус 5xx, кроме 503 с Retry-After) или 408 Request Timeout, либо соединение превышает время ожидания, сбрасывается или обрывается посреди ответа. Каждый шаг выполняется не более трёх раз: перед второй попыткой выдерживается пауза в полсекунды, перед третьей — в секунду.

Реестр, который просит замедлиться, публикация пережидает, и это не расходует ни одной из этих попыток. При ответе 429 Too Many Requests или 503 с Retry-After каждый запрос к этому реестру — как чтение, так и запись — ждёт столько, сколько попросил реестр, а затем отправляется снова; шаг, содержимое которого было отклонено, начинается заново как новая загрузка, без фиксированного числа попыток, пока реестр в течение пяти минут не будет отвечать ничем, кроме «помедленнее». Реестр, который просит замедлиться описывает ожидание и отказ, которым оно завершается.

Каждая попытка — это новая загрузка тех же байтов, а не повторная отправка неудавшегося запроса. Реестр, который уже принял тело загрузки, может отклонить тот же запрос во второй раз, а новую загрузку он принимает. Содержимое, которое в реестре уже есть, считается загруженным, а повторённый шаг записывает то же, что записала бы первая попытка, поэтому попытка, которая дошла до реестра, но ответ на которую был потерян, ничего не записывает дважды: манифест сохраняет свой дайджест, а у версии остаются одна подпись и одна дата публикации.

Любой другой сбой сразу завершает шаг: отклонённые учётные данные (401, 403 или отсутствие сохранённых учётных данных для реестра), любой другой ответ реестра, полностью недоступный реестр или прерванная вами публикация. Если шаг по-прежнему завершается сбоем после последней попытки, команда завершается с ошибкой, и в сообщении об ошибке указан этот шаг — содержимое, манифест, тег, подпись или дата публикации. То, что опубликовали предыдущие шаги, остаётся опубликованным; что это означает для версии, описано в разделах Подпись и Дата публикации.

При таких сбоях повторяются только операции записи. Чтение того, что реестр уже хранит для версии, перед загрузкой чего-либо не повторяется, хотя, как и любой запрос, оно выжидает столько, сколько требует реестр, который просит замедлиться.

Подпись

aggrega push может подписывать артефакт при публикации и прикреплять подпись как OCI referrer — пакет Sigstore (совместимый с cosign) на неизменяемом дайджесте манифеста артефакта. Подпись — это соседний манифест, поэтому подписание никогда не отправляет повторно и не изменяет опубликованные байты. Referrer называет свой пакет signature.json, поэтому универсальный OCI-клиент, получающий referrer по его дайджесту, записывает пакет в этот файл.

Подписание выполняется по схеме «подпись до отправки»: дайджест манифеста известен до публикации, поэтому aggrega push создаёт подписывающий объект и подписывает дайджест до того, как какие-либо байты попадут в реестр. Если подписывающий объект не удаётся создать или подписание завершается ошибкой, отправка отклоняется до того, как что-либо будет загружено, — ничего не публикуется, поэтому неудачное подписание никогда не оставляет неподписанное содержимое в реестре. Прежде чем отклонить отправку, вызов подписания, завершившийся временной ошибкой — любой ошибкой, при которой повторяется запись в реестр, или сообщением центра сертификации keyless о том, что он не смог обработать токен идентификации, — выполняется снова, всего до трёх попыток с теми же паузами. Внутри вызова бесключевого подписания запрос, на который центр сертификации, журнал прозрачности или служба меток времени отвечает 429 Too Many Requests или ошибкой сервера, сначала отправляется этой службе повторно, как описано в aggrega sign.

Подпись прикрепляется после того, как содержимое загружено, поэтому неудачное прикрепление действительно оставляет содержимое опубликованным без неё. Прикрепление — это запись, которая повторяется, как описано в разделе Когда реестр не выполняет запись. Если оно всё равно завершается ошибкой, команда завершается с ненулевым кодом и называет подпись, которую не удалось прикрепить, а потребитель, чей реестр требует подписей, отклоняет версию, пока подпись не будет прикреплена. Повторный запуск той же отправки прикрепляет её, как описано в разделе Завершение публикации, которую предыдущая отправка оставила частичной; aggrega sign прикрепляет подпись к опубликованной версии по ссылке.

Публикация требует подписи, когда собственный блок signing целевого реестра задаёт required: true или когда это делает блок signing верхнего уровня для всех реестров, — каждый из них ограничен видами, перечисленными в его kinds, если они там перечислены. Такая публикация по умолчанию подписывается, а --sign явно запрашивает подписание. Флага для отправки неподписанного содержимого там, где требуется подпись, нет — такая отправка всегда останавливается.

Два режима подписания:

  • Keyless (по умолчанию) — эфемерный ключ, привязанный к OIDC-идентичности краткосрочным сертификатом Fulcio и записанный в журнал прозрачности Rekor. По умолчанию Fulcio и Rekor — общедоступные экземпляры Sigstore (https://fulcio.sigstore.dev, https://rekor.sigstore.dev). Доверенная метка времени в режиме keyless берётся из включения в журнал прозрачности Rekor; отдельный центр меток времени RFC3161 необязателен — чтобы включить его, укажите --timestamp-url с полным адресом конечной точки. В интерактивном терминале подписание keyless не требует флагов: CLI открывает браузер, чтобы получить краткосрочный токен идентификации OIDC. В GitHub Actions флаги тоже не нужны: CLI автоматически получает OIDC-токен рабочего процесса из окружающей конечной точки раннера. Для другого неинтерактивного / CI использования экспортируйте AGGREGA_IDENTITY_TOKEN (или SIGSTORE_ID_TOKEN) либо передайте --identity-token; если токен не передан, окружающей конечной точки нет и терминала нет, отправка отклоняется. Модель токенов для CI описана в environment-variables.md.
  • Keyed (--key) — хранимый офлайн ключ ECDSA P-256 (PEM, совместимый с cosign), запасной выход для сред без поставщика OIDC-идентичности. Обращений к поставщику идентичности, центру сертификации или журналу прозрачности нет.

URL-адреса сервисов keyless и путь к ключу для режима keyed также можно задать в .aggrega-config.yaml в блоке signing: (глобальном и для конкретного реестра); флаг переопределяет конфигурацию, а конфигурация переопределяет общедоступное значение по умолчанию. Токен идентификации OIDC никогда не бывает полем конфигурации (это краткосрочный секрет), а закрытый ключ никогда не указывается в конфигурации напрямую — только путь к нему.

Дата публикации

Время создания манифеста зафиксировано, поэтому дайджест манифеста зависит только от того, что опубликовано, и никогда — от того, когда. Вместо этого дата публикации версии хранится рядом с ней, а её источник зависит от подписи:

  • Бесключевая подпись уже содержит её. Её запись в журнале прозрачности фиксирует, когда журнал включил подпись, а подписанное обещание журнала удостоверяет это время. aggrega push больше ничего не записывает.
  • Подпись с ключом или отсутствие подписи не несут времени. Поэтому после того как сущность и подпись (если она есть) загружены, aggrega push прикрепляет к манифесту небольшой referrer с датой публикации — для обычного клиента OCI он называется published-at.json, — содержащий одну метку времени RFC 3339 в UTC с точностью до секунды, взятую с собственных часов публикующей машины. Он не подписан: это заявление издателя, и читатель записывает его именно так. О нём сообщает строка Publication date attached:.

Как и подпись, referrer с датой публикации — это соседний манифест, указывающий на опубликованный, поэтому он не меняет ни дайджест, ни тег, и не влияет на проверку при публикации поверх существующей версии. Повторный push того же содержимого прикрепляет дату только к версии, у которой её нет, указывая время по собственным часам, — см. Завершение публикации, которую предыдущий push оставил неполной. Дата считывается с часов один раз, до первой попытки прикрепления, поэтому при повторной попытке — см. Когда реестр не выполняет запись — указывается та же дата. Push, который опубликовал содержимое, но не смог прикрепить дату после этих попыток, завершается с ненулевым кодом и называет то, что не было прикреплено. aggrega registry update записывает дату каждой версии вместе с тем, из какого из двух источников она получена.

Автономный режим

Публикация — это сетевой обмен с реестром, и иной формы у неё нет, поэтому в автономном режиме — заданном ключом верхнего уровня offline в файле конфигурации, переменной AGGREGA_OFFLINE или флагом --offline — aggrega push отказывает ещё до того, как прочитает вашу сущность. В сообщении об отказе указано, какой из этих трёх источников включил режим: это то, что нужно читателю, когда режим включила закоммиченная конфигурация проекта, а не что-то, что он сам ввёл.

--dry-run — исключение, и исключение оно именно в силу того, что делает: вычисляет пакет, выводит ссылку, которую опубликовало бы, и дайджест, который дала бы эта публикация, и никогда не обращается к реестру. Поэтому это безопасная для автономного режима форма публикации, а не конфликт с ним, и она продолжает работать в этом режиме — с одной оговоркой. Для сущности Recipe или FeatureRecipe, у которой удалённый source: записан полностью, этот источник загружается, чтобы сверить его закрепление, а в автономном режиме такая загрузка отклоняется с собственным сообщением, поэтому пробный запуск над такой сущностью на этом останавливается, а не сообщает о пакете, за который не может поручиться.

Чтобы выполнить публикацию в одном запуске из рабочего пространства, конфигурация которого включает автономный режим, передайте --offline=false.

Переменные окружения

Входные данные для подписи и целевой реестр можно задать через окружение; это переопределяет .aggrega-config.yaml, но флаг по-прежнему имеет приоритет:

  • AGGREGA_IDENTITY_TOKEN — токен идентичности OIDC для подписи без ключа (аналог --identity-token в окружении). SIGSTORE_ID_TOKEN поддерживается как псевдоним для совместимости с экосистемой sigstore и имеет более низкий приоритет, чем AGGREGA_IDENTITY_TOKEN и встроенная конечная точка GitHub Actions. Токен никогда не задаётся полем конфигурации.
  • AGGREGA_SIGNING_FULCIO_URL, AGGREGA_SIGNING_REKOR_URL, AGGREGA_SIGNING_TIMESTAMP_URL — URL-адреса служб подписи без ключа.
  • AGGREGA_SIGNING_KEY_PATH — путь к PEM-файлу ключа для подписи с ключом (но никогда не сам ключевой материал).
  • AGGREGA_DEFAULT_REGISTRY — целевой реестр, если --registry не указан.

Порядок приоритета: флаг > окружение > конфигурация > значение по умолчанию. Полный список и модель приоритетов см. в environment-variables.md.

Аутентификация

aggrega push читает учётные данные реестра так же, как aggrega pull, — из конфигурации учётных данных Docker и указанных в ней помощников учётных данных. Перед отправкой в закрытый реестр выполните aggrega login <registry>, которой не нужны никакие другие инструменты, или docker login <registry>. Где читается эта конфигурация, см. в aggrega-pull.md.

См. также

  • ./aggrega-sign.md — подпись уже опубликованного артефакта задним числом (аналог --sign после публикации).
  • ./aggrega-lint.md — проверка перед публикацией (--pre-publish), которая должна предшествовать push.
  • ./aggrega-pull.md — потребляющая сторона, которая разрешает и закрепляет то, что публикует push.
  • ./aggrega-serve.md — демон предоставляет ту же публикацию как aggrega/publishEntity, так что редактор может запустить её, не покидая сеанса; она выполняется, только когда её называет запрос, и возвращает ссылку, опубликованный дайджест (при пробном запуске — дайджест, который выводит --dry-run), сведения о том, как далеко продвинулся вызов, и записи, о которых предупреждает эта команда, в виде windowsUnusableEntries.
  • ./aggrega-mcp.md — та же возможность в виде инструмента publish-entity, который может вызвать ассистент; он возвращает эти записи как windows_unusable_entries. Прочитайте, что говорится на этой странице о его разрешении, прежде чем разрешать его.
  • ../../architecture/13-catalog-and-registry.md — модель каталога, реестра и типов носителей OCI.

Синтаксис

aggrega push <entity-path> [flags]

Описание

Publish a single catalog entity to an OCI registry, where other workspaces
resolve it with "aggrega pull".
The entity is read from the path given, bundled for transport, and pushed to
<registry>/<kind>/<metadata.name>:<metadata.version>, the repository path
lowercased; a Recipe or FeatureRecipe carries its spec.capability, and a Plugin
its metadata.pluginType, as a segment between <kind> and <metadata.name>. The
tag is the entity's own metadata.version. Run "aggrega push --list-kinds" for
the kinds this binary publishes, one per line and nothing else, so a script can
read it directly. Release and Manifest are deployment-side inputs rather than
catalog artifacts and are refused.
Every kind has a directory of its own except Aggregate, Release and Manifest: an
entity of any other kind is refused when another entity sits in its directory,
before anything is pinned or bundled, and the refusal names the entity in the way.
The directory's name is not judged.
A Component, Feature, Recipe or FeatureRecipe is read the way a build reads it
before it is bundled, and one that read refuses is refused here for the same
reason: a document that fails its kind's schema, a path naming content outside
the entity's own directory, which would not travel with the entity, or a schema
a Component or Feature imports that cannot be read or used.
A Plugin is read against its kind's schema too, before its .wasm is read, so a
metadata.version that is not a semantic version is refused. Its .wasm must then
agree with the entity on what the plugin offers and on its version, and a .wasm
whose version says it was built from a working tree with uncommitted changes —
the -dirty mark a build adds — is refused. A version disagreement and a build
from uncommitted changes are both cleared by building the plugin from a clean
checkout of the commit its release tag names, never by copying the version it
reports into the entity. A development version such as 1.0.0-3-g1a2b3c4, built
from a commit, and a prerelease such as 1.0.0-rc.1 publish.
What is published is the entity document and the files the entity itself names
beside it — a Recipe's or FeatureRecipe's local source, each file an $import:
names, the entity.lock beside it, and each schema file a Component or Feature
imports — and nothing else in its directory. An entity that names nothing
publishes as its document, unchanged; one that names a file publishes as a
gzipped archive of the document and those files. A directory it names travels
with every file under it that the ignore rules recorded in its entity.lock keep:
the rules the plugin serving its capability declared, and the author's own
.aggregaignore beside it, composed when the entity was pinned. A symbolic link
among those files is refused rather than followed. A local source written as a
template names no one directory until a Release fills it in, so an entity with
one carries every such file in its own directory, and push says so.
Push warns about each file an archive carries whose path holds a part Windows
cannot hold as written: a name Windows reserves for a device — CON, PRN, AUX,
NUL, COM1 or LPT1, say, in any letter case and whatever extension follows — or a
part ending in a full stop or a space. On Windows, aggrega refuses to unpack
such a file, so a Windows workspace cannot use the version. The warning is
written to standard error on every platform, one line per file, the entity
document's own file name judged with the rest, and it refuses nothing: the push,
or its dry run, goes ahead or stops exactly as it would without it. An entity
that names nothing publishes as its document alone and is never warned about.
Each file travels with mode 0644, whatever its permission bits — the execute
bit included — in the checkout it is published from. The OCI manifest names the
digest of the published bytes, so "aggrega pull" refuses a download that does
not match it. The lockfile a pull writes records the entity by the digest of its
content — each file's path and its bytes — which is the digest a pull in the
author's own workspace records for the same entity in its catalog directory, so
a build on either side refuses content that no longer matches.
Push signs before it publishes: where signing applies, the signature is made
over the manifest digest before any bytes reach the registry, so a failed
signing refuses the push rather than leaving unsigned content published.
The manifest's creation time is pinned, so the digest depends only on what is
published and never on when. Push states when it published beside the manifest
instead, as a small published-at attachment carrying this machine's clock, in
UTC to the second — unless the signature it attached already carries a time a
transparency log attests, as a keyless signature does. So a keyed or unsigned
publication writes one, and a keyless one does not. The attachment moves no
digest and changes no tag. "aggrega registry update" records the date, with
which of the two it came from.
Push refuses to replace content already published at the same version:
publish changed content under a new version instead.
A Recipe or FeatureRecipe carries the pins for its own inputs in the entity.lock
beside it, and pinning them is a step you run before publishing: aggrega pin.
A push that does not run that step refuses an entity whose entity.lock is
missing a pin, or holds one an input no longer matches, and names the step.
Pass --pin-sources, or set pin_sources_at_push in the workspace configuration, to
have push run that same step first, so the lock it writes is part of what is
published; --pin-sources=false skips it for one run.

Флаги

ФлагПо умолчаниюОписание
--dry-runfalseВычислить пакет и вывести предлагаемые : с дайджестом, который получила бы публикация, не обращаясь к реестру. Сущность, которую публикация отклонила бы из-за отсутствующего закрепления, отклоняется и здесь
--entity—Путь к YAML-файлу публикуемой сущности (можно также передать позиционным аргументом)
--fulcio-url—URL центра сертификации Fulcio для подписи без ключа. Если не указан, используется общедоступный экземпляр Fulcio.
--identity-token—Токен идентичности OIDC для подписи без ключа. Необязателен в интерактивном терминале (токен получается через браузер) и в GitHub Actions (OIDC-токен рабочего процесса выпускается автоматически); обязателен при прочем неинтерактивном использовании и в CI, где его можно вместо этого экспортировать как AGGREGA_IDENTITY_TOKEN или SIGSTORE_ID_TOKEN.
--key—Путь к имеющемуся закрытому ключу ECDSA P-256 в формате PEM для автономной подписи ключом. Если не указан, используется подпись без ключа.
--list-kindsfalseВывести все виды сущностей, которые можно опубликовать, и завершить работу, ничего не публикуя. Вывод машиночитаем, и его формат стабилен: по одному виду на строку, в отсортированном порядке, без чего-либо ещё.
--pin-sourcesfalseВыполнить шаг закрепления автора сущности перед её упаковкой, чтобы entity.lock, который этот шаг записывает рядом с ней, вошёл в публикуемое, вместо того чтобы отклонять сущность, lock-файл которой не фиксирует её закрепления. Это тот же шаг, что и aggrega pin, и он записывает те же байты. Он пишет рядом с сущностью, поэтому выполняется, только если у сущности есть доступное для записи место: документ в каталоге, из которого он был прочитан, — а оно у push есть всегда, поскольку публикуется указанный вами документ сущности. Переопределяет pin_sources_at_push рабочего пространства в обе стороны: —pin-sources закрепляет в этом запуске, а —pin-sources=false — нет, независимо от настройки
--plugin—Путь к локальному артефакту .wasm для сущности Plugin. Обязателен при публикации Plugin: publish отправляет артефакт .wasm, вычисляет дайджест его содержимого и отправляет сущность.
--registry—Хост целевого реестра (переопределяет default_registry рабочего пространства)
--rekor-url—URL журнала прозрачности Rekor для подписи без ключа. Если не указан, используется общедоступный экземпляр Rekor.
--signfalseПодписать опубликованный артефакт и прикрепить подпись как OCI referrer. Если не указан, подпись выполняется согласно политике целевого реестра.
--timestamp-url—Необязательный URL службы меток времени RFC3161 для подписи без ключа.