Перейти к содержимому
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, поэтому он вносит каждый файл в каталоге сущности, оставленный правилами, и каждый из них пинится. Сборка сравнивает источник с этими пинами до того, как его прочитает provider, поэтому файл, добавленный, изменённый или удалённый после пиннинга, останавливает сборку — A local source no longer matches the pins recorded beside its Recipe (Локальный источник больше не соответствует пинам, зафиксированным рядом с его Recipe).
  • Сами правила игнорирования — для source:, являющегося каталогом. Шаг фиксирует, какой plugin обслуживал capability сущности, и точные правила, которые он составил, как описано в следующем разделе.

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

Release не нужен. Полностью записанный источник указывает на один и тот же артефакт для каждого Release, который когда-либо будет использовать сущность, поэтому для его разрешения не требуется ничего, что предоставляет Release. Именно это позволяет автору пинить сущность в рабочем пространстве, где нет ни одного Release.

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

Какие файлы поставляются вместе с сущностью

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

  • Плагин, который рендерит возможность сущности, объявляет то, что его собственная экосистема никогда не поставляет. Плагины чартов исключают каталоги систем контроля версий (.git/, .hg/, .svn/, .bzr/) и скрытые файлы в templates/ чарта, а также учитывают собственный .helmignore чарта: где бы обход источника его ни встретил, его строки читаются как дополнительные правила для содержащего его каталога. Плагин 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, и ничего на диске не меняется. Блокировка, которую шаг оставил бы побайтово идентичной, не выводится. Разрешение выполняется точно так же, как и в обычном режиме, поэтому кэш содержимого всё равно заполняется