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

aggrega pin

aggrega pin <entity-path> записує у файл entity.lock поруч із сутністю Recipe або FeatureRecipe закріплення вмісту для кожного вхідного елемента, який сутність зчитує поза межами власного документа. Це крок автора сутності: виконайте його до того, як сутність буде використано чи опубліковано, і закомітьте записаний ним lock-файл.

aggrega pin catalog/recipe/helm/server/1.0.0/recipe.yaml

Що він записує

Сутність може залежати від байтів поза власним документом, і lock-файл містить по одному піну для кожного такого входу:

  • Віддалене джерело source:, координати якого ви виписали повністю — без шаблону в його kind, url, chart, module_subdir, version чи ref. Крок завантажує його й записує версію, до якої воно розв’язалося, — для git-джерела це коміт, названий його ref, — а також дайджест вмісту завантаженого.
  • Файл, який запис artifacts імпортує через $import. Крок обчислює дайджест файлу в тому стані, в якому він є у вашому робочому просторі.
  • Кожен файл джерела source:, що називає каталог або файл поруч із сутністю. Нічого не завантажується: крок обчислює дайджест кожного файлу, який джерело додає до того, що містить публікація сутності, — кожного файлу в названому каталозі, який залишають правила ігнорування сутності, або того одного файлу, — і записує його за шляхом поруч із сутністю. Файл поруч із сутністю Recipe, який джерело не додає, наприклад README, не пінується. Джерело, записане як шаблон, наприклад ./charts/{{ .values.flavour }}, називає свій каталог лише тоді, коли сутність Release його заповнює, тож воно додає кожен файл у каталозі сутності, який залишають правила, і кожен із них пінується. Збірка порівнює джерело з цими пінами, перш ніж його прочитає провайдер, тому файл, доданий, змінений чи видалений після пінування, зупиняє збірку — A local source no longer matches the pins recorded beside its Recipe (Локальне джерело більше не відповідає пінам, записаним поруч із його сутністю Recipe).
  • Самі правила ігнорування — для джерела source:, яке є каталогом. Крок записує, який плагін обслуговував можливість сутності, і точні правила, які він склав, як описано в наступному розділі.

Чого він не записує: віддалене джерело, координати якого заповнюються з шаблону, — воно називає артефакт лише тоді, коли сутність Release його заповнює, і пінується в lockfile кожної сутності Release командою aggrega pull; а також вбудований запис artifacts або запис, узятий з бібліотеки ArtifactLibrary. Сам файл описано поле за полем у схемі lock-файлу сутності.

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

Файл сутності ніколи не записується. Те, що крок виводить, розміщується поруч із сутністю; те, що ви написали, залишається саме таким, як ви це написали. Повторний запуск на незмінених входах залишає lock-файл побайтово ідентичним, а в сутності, яка перестає читати будь-що, що записує lock-файл, lock-файл видаляється. Про сутність Component, Feature або будь-якого іншого виду, що не читає таких входів, повідомляється, що в неї немає чого пінувати, і нічого поруч із нею не змінюється.

Які файли постачаються із сутністю

Сутність Recipe або FeatureRecipe, чий source: називає каталог поруч із нею — розміщений поруч chart, модуль, — під час публікації несе файли цього каталогу. Не кожен файл у ньому має там бути: каталог системи контролю версій, кеш залежностей, залишки редактора. Які файли мають там бути, визначають правила ігнорування в синтаксисі, який використовує .gitignore, і ними керуєте ви. Вони надходять із двох джерел:

  • Плагін, що рендерить можливість сутності, оголошує те, що його власна екосистема ніколи не постачає. Плагіни для chart-ів виключають каталоги систем контролю версій (.git/, .hg/, .svn/, .bzr/) і приховані файли в templates/ chart-а, а також враховують власний .helmignore chart-а: щоразу, коли обхід джерела натрапляє на такий файл, його рядки читаються як додаткові правила для каталогу, що його містить. Плагін Terraform виключає каталоги систем контролю версій і робочий каталог .terraform/ — але не файл блокування залежностей, який має переміщуватися разом із модулем, — і так само враховує .terraformignore. Плагін, який нічого не оголошує, залишає все.
  • Ваш власний .aggregaignore — один файл поруч із документом сутності, у тому самому синтаксисі. Його рядки застосовуються після правил плагіна й після кожного файлу ігнорування, який називає плагін, тож останнє слово щодо будь-якого названого вами шляху за вами: рядок на зразок .venv/ виключає каталог, про який плагін нічого не знає, а рядок на зразок !.git/ повертає каталог, який плагін виключив. Сам файл ніколи не переміщується; переміщуються його правила — всередині блокування.
catalog/recipe/helm/server/1.0.0/.aggregaignore
.venv/
*.bak
!notes.bak

Кожне правило читається відносно каталогу, якому воно належить. Правило, оголошене плагіном, читається від кореня каталогу джерела; рядок .helmignore — від каталогу, що містить цей файл; рядок вашого .aggregaignore — від власного каталогу сутності. Правило без скісної риски або лише з кінцевою скісною рискою відповідає імені на будь-якій глибині; кінцева скісна риска відповідає лише каталогу; початковий ! повертає те, що виключило попереднє правило. У каталог, який правило виключає, обхід не заходить, тож файл усередині нього повертається лише тоді, коли повертається сам каталог: сам лише !.git/HEAD не повертає файл, поки .git/ виключено, а !.git/ повертає.

Правила читаються з того плагіна, який обслуговує можливість у вашому робочому просторі на момент закріплення: з прив’язки провайдера вашого робочого простору для цієї можливості або, якщо її немає, з плагіна, вбудованого в aggrega. Крок записує в entity.lock цей плагін за назвою, як-от provider/terraform, без версії, і точні правила, які він склав; повторне закріплення з новішою версією aggrega, плагін якої оголошує ті самі правила, залишає блокування незмінним. Відтоді кожне читання каталогу застосовує записані правила й жодних інших: публікація сутності, порівняння з блокуванням під час pull або push, рядок сутності у lockfile, порівняння під час збирання, рендеринг, що передає каталог провайдеру, і aggrega pull --verify. Тож ви публікуєте саме те, що рендерить ваше власне збирання, а змінена прив’язка, відредагований .aggregaignore чи новіша версія aggrega нічого не змінюють, доки ви не закріпите знову, — і тоді diff блокування покаже, що змінилося. Файл, який плагін називає файлом ігнорування, як-от .helmignore, сам є одним із файлів джерела й закріплюється, як і будь-який інший, якщо його не виключає правило, тож редагування цього файлу без повторного закріплення виявить наступний pull або наступне збирання. Блокування, яке не записує жодних правил, залишає всі файли в каталозі.

Споживач рендерить файли, які залишили ваші правила. Плагін може рендерити сутність Recipe, опубліковану для його можливості, якщо він підтримує ту саму версію ABI, його контракт відповідає заяві його сутності і йому не потрібен жоден файл поза опублікованим набором. Плагін, якому потрібен файл, виключений із набору, має явно провалити своє збирання й назвати цей файл; роль хоста — відмовляти в будь-якому пакуванні чи читанні файлу, якого набір не містить, називаючи його. Якщо плагін, прив’язаний у робочому просторі споживача для цієї можливості, оголошує інші правила, ніж записані у вашому блокуванні, aggrega pull споживача повідомляє про це попередженням, у якому названо обидва плагіни й різницю, і продовжує роботу.

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

Куди записується lock

Lock записується поруч із документом, який ви вказуєте, у тому самому каталозі, тому сутності потрібне місце, доступне для запису: документ у вашому каталозі. Сутність, яку pull отримав із кешу вмісту, такого місця не має і ніколи нічим не закріплюється.

Один каталог — одна сутність. Каталог містить один entity.lock, тому крок відхиляє сутність Recipe або FeatureRecipe, яка ділить свій каталог із будь-якою іншою сутністю, незалежно від того, чи має котрась із них що закріплювати, і називає кожну сутність, що заважає, — це відмова An entity shares its directory with another entity (Сутність ділить свій каталог з іншою сутністю). Кожен вид має власний каталог, окрім Aggregate, Release і Manifest, які можуть лежати поруч; push застосовує те саме правило до сутності, яку публікує, як описано в розділі Одна сутність на каталог. Крок оцінює лише те, для чого записує lock, тож про сутність Component чи будь-який інший вид, для якого йому нічого закріплювати, повідомляється, що закріплювати нічого, а відмова досягає такої сутності під час її публікації. Файл поруч із сутністю, який не є документом сутності, — файл чарту, сам імпортований файл — не заважає. Кожен документ поруч із сутністю читається лише зсередини робочого простору або, для документа, який ви вказуєте поза ним, зсередини його власного каталогу — де зберігається й lock, — тож документ, що є посиланням назовні, зупиняє крок, який називає це посилання, не прочитавши його, як описано в розділі межа робочого простору.

Хто фіксує і коли

Фіксація — обов’язок автора. Сутність, вхідні дані якої не зафіксовано, ще не готова до використання, тому за замовчуванням pull не записує жодної фіксації: для сутності Recipe або FeatureRecipe в одному з ваших каталогів, яку збирає Release, він порівнює те, що записав би цей крок, із тим, що містить lock-файл, і зупиняється, коли фіксація відсутня або більше не відповідає своїм вхідним даним. Зупинка називає сутність, кожен вхід і те, чи це віддалене джерело, імпортований файл чи файл локального джерела, а також цю команду. Це An entity reads an input the lock beside it records no pin for (Сутність читає вхідні дані, для яких lock-файл поруч не записує фіксації). Push піддає сутність, яку публікує, тому самому порівнянню і відмовляє з тією самою зупинкою, тож сутність не може потрапити до реєстру через aggrega push із незаписаною фіксацією — це описано в розділі Фіксація перед публікацією. Локальне джерело розглядається як один набір файлів: lock-файл, що не записує жодного з них, зупиняє pull або push, так само як і файл, доданий, змінений або видалений після фіксації, — як і будь-яка інша відсутня чи застаріла фіксація.

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

Дві команди виконують цей самий крок замість вас і записують ті самі байти:

  • aggrega pull --pin-sources виконує його для сутностей, які збирає Release, замість зупинки.
  • aggrega push --pin-sources виконує його для сутності перед її пакуванням, тож записаний lock-файл стає частиною опублікованого, замість відмови.

Кожна має ключ робочого простору, що робить фіксацію її поведінкою за замовчуванням, — pin_sources_at_pull і pin_sources_at_push; обидва за замовчуванням вимкнені, і кожен керує лише своєю командою. Прапорець перевизначає свій ключ в обох напрямках: --pin-sources фіксує для одного запуску незалежно від значення ключа, а --pin-sources=false — ні. Тож у робочому просторі, налаштованому на фіксацію, можна повернути зупинку для одного pull. Збірка, що заповнює власний lock-файл, є pull, тому вона дотримується pin_sources_at_pull. Ключі описано в довіднику з конфігурації.

Зміна опублікованої сутності

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

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

Той самий крок на інших інтерфейсах

Демон виконує цей крок як aggrega/pin (aggrega serve), а протокол інструментів — як інструмент pin (aggrega mcp); обидва записують ті самі байти, що й ця команда. Через HTTP-слухача інструмент записує всередині робочого простору й звертається до хостів, які називають джерела сутності, тому для його виклику потрібна область дозволу workspace-write — той самий дозвіл, що потрібен для pull.

Див. також

  • aggrega-pull.md — блокування сутності, що збірка порівнює з ним, і зупинка.
  • aggrega-push.md — публікація сутності та одноразова публікація версії.
  • configuration.md — pin_sources_at_pull і pin_sources_at_push.

Синтаксис

aggrega pin <entity-path> [flags]

Опис

Record, in the entity.lock beside a Recipe or FeatureRecipe, the content pin for every input
the entity reads from outside its own document: a remote source: whose coordinates you wrote out
in full, a file an artifacts entry imports with $import, and each file of a local source:.
Pinning is the entity author's step. Run it on an entity before it is consumed — before you
publish it, and after every change to one of its inputs — and commit the entity.lock it writes
beside the entity. A pull over an entity whose lock does not record these pins halts and names
this command, and so does a push of it; so does one whose local source has had a file added,
changed or removed since it was pinned.
No Release is needed. A source whose coordinates carry no template names one artifact for every
Release that uses the entity, so it is resolved and pinned here, with nothing supplied. A remote
source whose coordinates are filled in from a template is not pinned here: which artifact it names is
decided by each Release, and each identity it resolves to is pinned in that Release's lockfile.
A source that names a directory beside the entity is not fetched: each file it contributes to what
a publication of the entity carries is digested as it stands and pinned by its path, so a build
refuses a file added, changed or removed after the pin. A local source written as a template
contributes every file in the entity's directory, so each of those is pinned.
Which files a source directory contributes is decided here, once, and recorded. The step reads the
ignore rules the plugin serving the entity's capability declares — this workspace's provider binding
for that capability, or else the plugin built into aggrega — together with the ignore files that
plugin names inside the source, such as a chart's .helmignore, and the .aggregaignore beside the
entity, in gitignore syntax, whose lines come last and so have the final say. It records the plugin
and the composed rules in the entity.lock, and every publication, pull, build and render of the
entity applies the recorded rules and no others, so a changed binding or a newer binary moves
nothing until you pin again. A symbolic link among the files is refused rather than followed.
The step writes beside the entity, so the entity needs a writable home: the document you name is
read from its own directory and the lock lands next to it. The entity file itself is never
written to. Re-running over unchanged inputs leaves the lock byte-identical; an entity that reads
nothing a lock records has its lock removed. A Component, a Feature or any other kind that reads
no such input is reported as having nothing to pin, and nothing beside it is touched.
A directory holds one entity.lock, so the step refuses a Recipe or FeatureRecipe that shares its
directory with any other entity, naming the entity in the way, whether or not either has anything
to pin. Every kind has a directory of its own except Aggregate, Release and Manifest, which may sit
side by side; a push holds the entity it publishes to the same rule.
aggrega pull --pin-sources and aggrega push --pin-sources run this same step on your behalf, and
write the same bytes.

Прапорці

ПрапорецьЗа замовчуваннямОпис
--dry-runfalseРозв’язати вхідні дані сутності й вивести entity.lock, який записав би цей крок, замість того щоб записувати його: його шлях і вміст, який він містив би, виводяться в stdout, і на диску нічого не змінюється. Блокування, яке крок залишив би побайтово ідентичним, не виводиться. Розв’язання виконується так само, як і без цього прапорця, тож кеш вмісту однаково заповнюється