Перейти до вмісту
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 — кожен файл схеми, який імпортують через $import: її spec.schema, стовп або сокет usesSchema, включно з кожним файлом, який у свою чергу імпортує імпортований файл.

Сутності 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, схему якої імпортовано з файлу, — як архів. У Catalog and Registry, §6, наведено обидва медіатипи для кожного виду.

Кожен файл в архіві має режим 0644 і не має позначки часу, незалежно від його бітів дозволів на диску. Checkout записує файли з власними бітами дозволів, а система, яка не зберігає біт виконання, отримує як звичайний файл те, що інша система отримує як виконуваний, тому архів не містить режиму, прочитаного з диска: два checkout одного коміту публікують однакові файли незалежно від їхньої 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 для її виконуваного файлу. Ім’я визначається медіатипом, а не файлом, з якого ви публікуєте, тож той самий вміст, опублікований із перейменованого файлу, дає той самий артефакт. У Catalog and Registry, §6, наведено кожну форму публікації та файл, яким вона стає.

Віддалена URL-адреса source: у сутності Recipe (посилання на OCI-чарт, HTTPS-адреса чарту чи фрагмента, модуль Git) зберігається дослівно в опублікованому YAML; її не завантажують і не вбудовують в артефакт. Споживачі розв’язують і закріплюють віддалені джерела самостійно під час власного завантаження. Так поширення сутностей каталогу та розв’язання артефактів-джерел залишаються окремими завданнями.

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

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

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

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

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

Назва каталогу не перевіряється. Сутність, сама у своєму каталозі, публікується з версією metadata.version, хоч би де цей каталог розташовувався; <name>/<version>/ — структура, якої дотримується каталог стандартної бібліотеки, — є домовленістю. Артефакт, який інший клієнт опублікував із каталогу з двома сутностями, однаково читається безпечно: отримання його зупиняється з назвами обох документів, а не повертає будь-який із них; це описано в 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: якщо для опублікованої версії вони відрізняються, push буде відхилено. З --pin-sources це дайджест каталогу в його поточному стані, як описано в розділі Закріплення перед публікацією.

Завершення публікації, яку попередній push залишив неповною

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

  • Підпис, якщо цей push підписує. Його прикріплюють, коли версія не має підпису, що зараховується як підпис цієї публікації. Якщо ваша конфігурація закріплює політику довіри для хоста призначення — public_key або trusted_identities, а для hub.aggrega.ai вбудований базовий рівень, — підпис зараховується, коли він проходить перевірку за цією політикою, тож підпис, який політика не допускає, ніколи не вважається власним підписом публікації. Якщо політика не закріплює жодного з них, жоден підпис не може пройти перевірку за нею, тож зараховується будь-який підпис версії, і push підписує лише версію, яка не має жодного; оцінювання за перевіркою в такому разі прикріплювало б ще один підпис під час кожного запуску.
  • Дата публікації, якщо правило щодо дат її вимагає — зчитана з щойно прикріпленого підпису або з уже зарахованого, — і версія не має жодного referrer 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.

Підпис долучається після того, як вміст опубліковано, тому невдале долучення таки залишає вміст опублікованим без підпису. Долучення є записом і повторюється так, як описано в розділі Коли реєстр не виконує запис. Якщо воно все одно не вдається, команда завершується з ненульовим кодом, називаючи підпис, який не вдалося долучити, а споживач, чий реєстр вимагає підписів, відхиляє цю версію, доки підпис не буде долучено. Повторний запуск тієї самої публікації долучає його, як описано в розділі Завершення публікації, яку попередній push залишив частковою; 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 робочого процесу з навколишньої кінцевої точки runner. Для іншого неінтерактивного / 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 дати публікації — з назвою published-at.json для загального клієнта OCI, — що містить одну позначку часу RFC 3339 в UTC з точністю до секунди, зчитану з власного годинника машини, яка публікує. Він не підписаний: це заява видавця, і читач фіксує його саме як таку. Про нього повідомляє рядок Publication date attached:.

Як і підпис, referrer дати публікації — це сусідній маніфест, що вказує на опублікований, тож він не змінює жодного дайджесту й жодного тегу, і перевірка під час публікації поверх наявної версії від нього не залежить. Повторний push того самого вмісту прикріплює дату лише до версії, яка її не має, зазначаючи час власного годинника — див. Completing a publication an earlier push left partial (Завершення публікації, яку попередній 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 для безключового підписування.