aggrega pin
aggrega pin <entity-path> は、エンティティが自身のドキュメントの外部から読み込むすべての入力について、そのコンテンツピンを Recipe または FeatureRecipe の隣にある entity.lock に記録します。これはエンティティ作成者が行うステップです。エンティティが利用または公開される前に実行し、書き出されたロックをコミットしてください。
aggrega pin catalog/recipe/helm/server/1.0.0/recipe.yaml記録する内容
エンティティは自身のドキュメント外のバイト列に依存することがあり、ロックはそれぞれに対して 1 つのピンを保持します。
- 座標をすべて書き出したリモートの
source:。つまりkind、url、chart、module_subdir、version、refのいずれにもテンプレートを含まないものです。このステップはそれを取得し、解決されたバージョン(git ソースの場合はrefが指すコミット)と、取得した内容のダイジェストを記録します。 artifactsエントリが$importでインポートするファイル。 このステップは、ワークスペース内にある現在の状態のファイルのダイジェストを取ります。- エンティティの隣にあるディレクトリまたはファイルを指す
source:の各ファイル。 取得は行いません。このステップは、ソースがエンティティの公開物に含める各ファイル(指定されたディレクトリ配下のファイルのうちエンティティの無視ルールが残すすべてのファイル、または指定された 1 つのファイル)のダイジェストを取り、エンティティからのパスで記録します。Recipe の隣にあってもソースが含めないファイル(README など)はピン留めされません。./charts/{{ .values.flavour }}のようにテンプレートで書かれたソースは、Release が値を埋めて初めてディレクトリが決まるため、エンティティのディレクトリ内でルールが残すすべてのファイルを含め、そのそれぞれがピン留めされます。ビルドはプロバイダーがソースを読む前にソースをこれらのピンと比較するため、ピン留め以降にファイルが追加、変更、削除されているとビルドは停止します。A local source no longer matches the pins recorded beside its Recipe(ローカルソースが Recipe の隣に記録されたピンと一致しなくなっています) を参照してください。 - ディレクトリである
source:の場合の、無視ルールそのもの。 次のセクションで説明するとおり、このステップはエンティティのケイパビリティを提供したプラグインと、そのプラグインが構成した正確なルールを記録します。
記録しないもの:座標がテンプレートから埋められるリモートソース(Release が値を埋めて初めてアーティファクトが決まり、aggrega pull によって各 Release のロックファイルにピン留めされます)、およびインラインの artifacts エントリや ArtifactLibrary から取り込まれたエントリです。ファイル自体のフィールドごとの説明は エンティティロックのスキーマ にあります。
Release は不要です。 すべて書き出されたソースは、そのエンティティを使用するあらゆる Release に対して同じアーティファクトを指すため、その解決に Release が提供するものは何も必要ありません。これにより、作成者は Release がまったくないワークスペースでもエンティティをピン留めできます。
エンティティファイルが書き換えられることはありません。 ステップが導出したものはエンティティの隣に置かれ、入力した内容は入力したとおりに残ります。入力が変わらないまま再実行してもロックはバイト単位で同一のままで、ロックが記録する対象を何も読まなくなったエンティティはロックが削除されます。Component、Feature、またはそのような入力を読まないその他の種類は、ピン留めするものがないと報告され、その隣のものには一切手が加えられません。
エンティティとともに配布されるファイル
source: が自身の隣のディレクトリ(同じ場所に置かれたチャートやモジュール)を指す Recipe または FeatureRecipe は、公開時にそのディレクトリのファイルを持ち運びます。ただし、その中のすべてのファイルが含まれるべきものではありません。バージョン管理のディレクトリ、依存関係のキャッシュ、エディタの残骸などがあります。**どのファイルを含めるかは、.gitignore と同じ構文の ignore ルールによって決まり、これは利用者が制御します。**ルールは次の 2 か所から来ます。
- エンティティのケイパビリティをレンダリングするプラグインは、自身のエコシステムで決して配布しないものを宣言します。チャートプラグインはバージョン管理のディレクトリ(
.git/、.hg/、.svn/、.bzr/)とチャートのtemplates/配下の隠しファイルを除外し、チャート自身の.helmignoreに従います。ソースの走査中にこのファイルに出会うと、その行は、そのファイルを含むディレクトリに対する追加のルールとして読み込まれます。Terraform プラグインはバージョン管理のディレクトリと.terraform/作業ディレクトリを除外し(モジュールとともに持ち運ぶことを意図した依存関係ロックファイルは除外しません)、同じように.terraformignoreに従います。何も宣言しないプラグインは、すべてを含めます。 - 利用者自身の
.aggregaignore。エンティティのドキュメントの隣に置く 1 つのファイルで、構文は同じです。その行はプラグインのルールと、プラグインが指定するすべての ignore ファイルの後に適用されるため、指定したどのパスについても利用者が最終的な決定権を持ちます。.venv/のような行はプラグインが関知しないディレクトリを除外し、!.git/のような行はプラグインが除外したディレクトリを戻します。ファイル自体は持ち運ばれませんが、そのルールはロックの中に含まれて持ち運ばれます。
.venv/*.bak!notes.bak**各ルールは、そのルールが属するディレクトリからの相対で読み込まれます。**プラグインが宣言するルールはソースディレクトリのルートから、.helmignore の行はそのファイルを含むディレクトリから、.aggregaignore の行はエンティティ自身のディレクトリから読み込まれます。スラッシュを含まない、または末尾にのみスラッシュを持つルールは任意の深さの名前に一致します。末尾のスラッシュはディレクトリにのみ一致します。先頭の ! は、それ以前のルールが除外したものを戻します。ルールが除外したディレクトリには入りません。そのため、その中のファイルが戻るのはディレクトリ自体が戻された場合のみです。.git/ が除外されている間は !.git/HEAD だけではファイルは戻らず、!.git/ なら戻ります。
ルールが読み込まれるプラグインは、ピン留めの時点でワークスペース内でそのケイパビリティを提供しているプラグインです。つまり、そのケイパビリティに対するワークスペースのプロバイダーバインディング、それがなければ aggrega に組み込まれたプラグインです。このステップは、そのプラグインを provider/terraform のように名前だけで(バージョンなしで)記録し、それが構成した正確なルールとともに entity.lock に記録します。同じルールを宣言するプラグインを持つ新しい aggrega で再度ピン留めしても、ロックは変わりません。以降、ディレクトリの読み込みはすべて、記録されたルールのみを適用します。エンティティの公開、pull や push がロックと照合する比較、lockfile 内のエンティティの行、ビルドの比較、ディレクトリをプロバイダーに渡すレンダリング、そして aggrega pull --verify です。したがって、公開されるものは自身のビルドがレンダリングするものと完全に一致し、バインディングの変更、.aggregaignore の編集、より新しい aggrega は、再度ピン留めするまで何も変えません。再度ピン留めした時点で、ロックの差分に変化した内容が表れます。.helmignore のように、プラグインが ignore ファイルとして指定するファイル自体もソースのファイルの 1 つであり、ルールが除外しない限り他のファイルと同様にピン留めされます。そのため、再度ピン留めせずに編集すると、次の pull またはビルドで検出されます。ルールを何も記録していないロックは、ディレクトリ配下のすべてのファイルを保持します。
**利用側は、ルールによって保持されたファイルをレンダリングします。**プラグインは、同じ ABI バージョンを話し、そのコントラクトがエンティティの主張と一致し、公開されたセット外のファイルを必要としない場合に、自身のケイパビリティ向けに公開された Recipe をレンダリングできます。セットが除外したファイルを必要とするプラグインは、そのファイル名を示して明示的にビルドを失敗させなければなりません。ホストの役割は、セットに含まれないファイルのパックや読み込みを、そのファイル名を示して拒否することです。利用側のワークスペースがそのケイパビリティにバインドしているプラグインが、ロックに記録されたルールとは異なるルールを宣言している場合、利用側の aggrega pull は両方のプラグインと差異を示す警告を出し、処理を続行します。
エンティティのファイル内のシンボリックリンクは拒否されます。リンク先がどこであっても、解決できるかどうかにかかわらず拒否されます。A symbolic link sits among the files an entity carries(エンティティが持ち運ぶファイルの中にシンボリックリンクがあります)を参照してください。ルールが除外したリンクは、除外された他のファイルと同様に読み飛ばされます。エンティティが指定するパスが、エンティティのディレクトリの外へ出るリンクであるディレクトリを通過する場合も、何かがピン留めされる前に拒否されます。A path names content outside the entity’s own directory(パスがエンティティ自身のディレクトリ外のコンテンツを指しています)を参照してください。
ロックの書き込み先
ロックは指定したドキュメントの隣、同じディレクトリに書き込まれます。そのため、エンティティには書き込み可能な置き場所、つまり自分のディレクトリにあるドキュメントが必要です。pull がコンテンツキャッシュから解決したエンティティにはそのような置き場所がなく、何によってもピン留めされることはありません。
1 つのディレクトリに 1 つのエンティティ。 1 つのディレクトリが保持する entity.lock は 1 つだけです。そのため、このステップは、他のエンティティとディレクトリを共有する Recipe または FeatureRecipe を、どちらかにピン留めすべきものがあるかどうかにかかわらず拒否し、妨げとなっている各エンティティを示します。この拒否は An entity shares its directory with another entity(エンティティが別のエンティティとディレクトリを共有しています) です。Aggregate、Release、Manifest は同じディレクトリに並べて置けますが、それ以外のすべての種類は専用のディレクトリを持ちます。One entity per directory で説明するとおり、push も公開するエンティティに同じ規則を適用します。このステップはロックを書き込む対象だけを判定するため、Component や、ピン留めすべきものがないその他の種類は、ピン留めするものがないと報告され、拒否はそのエンティティが公開される時点で適用されます。エンティティの隣にあるエンティティドキュメントではないファイル(チャートファイルやインポートされたファイル自体など)は妨げになりません。エンティティの隣にある各ドキュメントは、ワークスペース内から、またはワークスペース外で指定したドキュメントについてはそのドキュメント自身のディレクトリ内(ロックもそこに保持されます)からのみ読み込まれます。そのため、外部を指すリンクであるドキュメントがあると、the workspace boundary で説明するとおり、このステップはそのリンクを読み込まずに示して停止します。
誰が、いつピン留めするか
ピン留めはオーサリング側の責務です。 入力がピン留めされていないエンティティは、まだ利用できる状態ではありません。そのため、デフォルトでは pull はピンを記録しません。Release がビルドする、自分のカタログディレクトリ内の Recipe または FeatureRecipe について、このステップが記録する内容とロックが保持する内容を比較し、ピンが欠けているか入力と一致しなくなっている場合に停止します。この停止では、エンティティ、各入力とそれがリモートソース・インポートされたファイル・ローカルソースのファイルのいずれであるか、そしてこのコマンドが示されます。これは An entity reads an input the lock beside it records no pin for(エンティティが、隣のロックにピンが記録されていない入力を読み込んでいます) です。push も公開するエンティティに同じ比較を適用し、同じ停止で拒否します。そのため、ピンが未記録のまま aggrega push を通じてエンティティがレジストリに到達することはありません。詳しくは 公開前のピン留め で説明しています。ローカルソースは一つのファイル集合として扱われます。 そのいずれも記録していないロックは pull や push を停止させます。また、ピン留め以降にファイルが追加、変更、削除された場合も、他の欠落したピンや古いピンと同様に停止します。
初回の pull での停止は、利用者ではなく公開者が修正すべきものです。 他者がオーサリングしたカタログを利用している場合(たとえば自分のディレクトリにチェックアウトしている場合)に、そこにあるエンティティがピン留めされていなければ、作成者がこのステップを実行していません。対処法は相手のディレクトリを手作業で編集することではありません。以下のワークスペースキーを設定して、pull 自体がピンを記録するようにします。
2 つのコマンドが、このステップを代わりに実行し、同じバイト列を書き込みます。
aggrega pull --pin-sourcesは、停止する代わりに、Release がビルドするエンティティに対してこのステップを実行します。aggrega push --pin-sourcesは、拒否する代わりに、バンドル前のエンティティに対してこのステップを実行します。そのため、書き込まれるロックは公開内容の一部になります。
それぞれに、ピン留めをデフォルトにするワークスペースキーがあります。 pin_sources_at_pull と pin_sources_at_push で、どちらもデフォルトではオフであり、それぞれ自身のコマンドのみを制御します。フラグは両方向でキーを上書きします。--pin-sources はキーの設定にかかわらずその 1 回の実行でピン留めし、--pin-sources=false はピン留めしません。したがって、ピン留めするよう設定されたワークスペースでも、1 回の pull について停止を取り戻せます。自身のロックファイルを埋めるビルドは pull であるため、pin_sources_at_pull に従います。キーについては 設定リファレンス で説明しています。
公開済みのエンティティを変更する
ベストプラクティス: 公開済みのエンティティへの編集は新しいバージョンで行い、その後にピン留めします。すでに公開されているバージョンを再ピン留めしてはいけません。 エンティティを新しいバージョンのディレクトリにコピーし、そこで変更を加え、新しいバージョンに対して aggrega pin を実行します。公開済みのバージョンは公開時のバイト列を正確に記述し続け、新しいバージョンへ移行する利用者は意図して移行することになります。
製品が強制するのはこのうちの半分です。すでに公開されているバージョンで変更された内容を公開しようとすると拒否されるため、公開済みのバージョンが気付かれないうちに置き換えられることはありません。もう半分については、自身のワークスペース内では強制しません。編集後に既存のバージョンを再ピン留めすることが、まさに正しい場合もあります。たとえば、1 つのアプリケーション内で利用していて公開していないエンティティがそうです。そのため、何もそれを妨げることはなく、この規律を守るかどうかは利用者に委ねられています。
他のサーフェスでの同じ手順
デーモンはこの手順を 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 inputthe entity reads from outside its own document: a remote source: whose coordinates you wrote outin 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 youpublish it, and after every change to one of its inputs — and commit the entity.lock it writesbeside the entity. A pull over an entity whose lock does not record these pins halts and namesthis 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 everyRelease that uses the entity, so it is resolved and pinned here, with nothing supplied. A remotesource whose coordinates are filled in from a template is not pinned here: which artifact it names isdecided 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 whata publication of the entity carries is digested as it stands and pinned by its path, so a buildrefuses a file added, changed or removed after the pin. A local source written as a templatecontributes 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 theignore rules the plugin serving the entity's capability declares — this workspace's provider bindingfor that capability, or else the plugin built into aggrega — together with the ignore files thatplugin names inside the source, such as a chart's .helmignore, and the .aggregaignore beside theentity, in gitignore syntax, whose lines come last and so have the final say. It records the pluginand the composed rules in the entity.lock, and every publication, pull, build and render of theentity applies the recorded rules and no others, so a changed binding or a newer binary movesnothing 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 isread from its own directory and the lock lands next to it. The entity file itself is neverwritten to. Re-running over unchanged inputs leaves the lock byte-identical; an entity that readsnothing a lock records has its lock removed. A Component, a Feature or any other kind that readsno 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 itsdirectory with any other entity, naming the entity in the way, whether or not either has anythingto pin. Every kind has a directory of its own except Aggregate, Release and Manifest, which may sitside 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, andwrite the same bytes.フラグ
| フラグ | デフォルト | 説明 |
|---|---|---|
--dry-run | false | エンティティの入力を解決し、このステップが書き込む entity.lock を書き込む代わりに出力します。そのパスと保持される内容が stdout に出力され、ディスク上のものは何も変更されません。ステップによってバイト単位で同一のまま残るロックは出力されません。解決処理は通常とまったく同じように実行されるため、コンテンツキャッシュは引き続き埋められます |