コンテンツにスキップ
AggregaAggrega
言語の選択: 日本語
このページは機械翻訳されています。英語の原文を読む。

aggrega push

aggrega push はカタログエンティティを OCI レジストリに公開します。公開されたエンティティは、他のワークスペースから aggrega pull で解決できます。

動作

aggrega push は単一のエンティティ YAML を読み込み、転送用にバンドルして、<registry>/<kind>/<metadata.name>:<metadata.version> にプッシュします。リポジトリパスは小文字に変換されます。Recipe または FeatureRecipe はその spec.capability を、Plugin はその metadata.pluginType を、kind と name の間のセグメントとして持ちます。インストール済みのバイナリが公開するエンティティの kind を確認するには aggrega push --list-kinds を実行します。1 行に 1 つの kind がソートされて出力され、それ以外は何も出力されないため、スクリプトから直接読み取れます。この集合は、カタログのオーサリング用の kind に加えて、再利用可能なモジュールである Aggregate と、コンパイラがルーティングしランタイムが実行する WebAssembly アーティファクトへのコンテンツアドレス参照である Plugin を含みます。Plugin はカタログのオーサリング用の kind ではなく、構造的な公開可能アーティファクトです。公開可能かどうかはエンティティの性質であり、使われ方によるものではありません。Aggregate は、後で Release のトップレベルの spec.aggregate として参照される場合も、別の Aggregate の aggregates: ブロックにネストされる場合も公開可能です。Release と Manifest はデプロイ側の入力であり、カタログのアーティファクトではないため、拒否されます。

バンドル

push は、エンティティのドキュメントと、エンティティ自身がその隣に指定するファイルを公開し、そのディレクトリ内のそれ以外のものは公開しません。 エンティティが指定するファイルは次のとおりです。

  • Recipe または FeatureRecipe の場合は、そのローカルの source:(ディレクトリは、Which files ship with an entity(エンティティとともに配布されるファイル) で説明するとおり、その entity.lock に記録された ignore ルールが残す配下のすべてのファイルとともに運ばれます)、その valuesMapping:、workload:、artifacts: の各エントリが $import: でインポートする各ファイル、および隣にある entity.lock。
  • Component または Feature の場合は、その spec.schema、ピラー、または usesSchema ソケットが $import: でインポートする各スキーマファイル。インポートされたファイルがさらにインポートするすべてのファイルも含みます。

Aggregate、Plugin、およびライブラリの各種別は、ドキュメントの隣にあるファイルを指定しません。ディレクトリ内にあるメモ、README、別のエンティティのファイル、ビルドの出力は、名前が何であれ公開されません。エンティティが指定するファイルの中にシンボリックリンクがあると、たどられずに拒否されます(A symbolic link sits among the files an entity carries(エンティティが運ぶファイルの中にシンボリックリンクがあります))。また、エンティティのディレクトリの外へ通じるリンクであるディレクトリを経由してエンティティが指定するパスも、何かがパックされる前に同様に拒否されます(A path names content outside the entity’s own directory(パスがエンティティ自身のディレクトリ外のコンテンツを指定しています))。

形式はそこから決まります。 何も指定しないエンティティは、そのドキュメントがそのまま、その種別の +yaml メディアタイプで公開されます。ファイルを指定するエンティティは、ドキュメントとそれらのファイルをディレクトリ内の位置に保持した .tar.gz として、その種別の +tar+gz メディアタイプで公開されます。したがって、内容がすべてインラインの Recipe はドキュメントとして公開され、スキーマをファイルからインポートする Component はアーカイブとして公開されます。Catalog and Registry の §6 に、すべての種別について両方のメディアタイプが記載されています。

アーカイブ内の各ファイルは、ディスク上のパーミッションビットにかかわらず、モード 0644 を持ち、タイムスタンプを持ちません。 チェックアウトはそれ自身のパーミッションビットでファイルを書き込み、実行ビットを記録しないシステムは、別のシステムが実行可能としてチェックアウトするものを通常のファイルとしてチェックアウトします。そのため、アーカイブはディスクから読み取ったモードを持ちません。同じコミットの 2 つのチェックアウトは、umask やどのシステムで作成されたかにかかわらず同じファイルを公開し、スクリプトの実行ビットを切り替えても公開されるものは何も変わりません。

push は、アーカイブが運ぶエントリのうち Windows が書かれたとおりに保持できないものについて、それぞれ警告します。 これは、CON、AUX、NUL などのデバイス名を持つ部分を含むパス(大文字小文字を問わず、どの拡張子が続いても該当し、aux/x.yaml などが例です)、またはピリオドやスペースで終わる部分(report. など)を含むパスです。Windows では aggrega がそのようなエントリの展開を拒否するため、Windows のワークスペースではそのバージョンを使用できません。警告はすべてのプラットフォームで標準エラーに、エントリごとに 1 行ずつ、公開自体の報告より前に書き出されます。エンティティのドキュメント自身のファイル名は、それが指定するファイルとともに判定されます。何も指定しないエンティティはドキュメントのみとして公開され、警告されることはありません。この警告は何も拒否しません。push は警告がない場合とまったく同じように進行または拒否され、--dry-run も同じように警告します。A published archive carries an entry Windows cannot use(公開されたアーカイブに Windows で使用できないエントリが含まれています) に、その行と対処方法が示されています。

テンプレートとして書かれたローカルの source: は、ディレクトリ全体を運びます。 ./charts/{{ .values.flavour }} のようなテンプレートは、Release が値を埋めて初めてディレクトリを指定するため、公開時にはそれがどのディレクトリになるかを判断できません。このようなエンティティは、記録された ignore ルールが残す自身のディレクトリ内のすべてのファイルを運びます(ただし .aggregaignore は運びません。そのルールはロックの中で運ばれます)。push はそのことを他の情報の下に表示します。

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

指定されていないものは運ばれず、それに気づくのは利用者です。 エンティティが上記のいずれかのフィールドで指定せずに依存しているファイルは公開物に含まれず、利用者側のビルドが、キャッシュスロット内で欠けているパスを示して失敗します。push が失敗するわけではありません。エンティティが必要とするすべてのファイルを、これらのフィールドのいずれかで指定してください。

公開される各ファイルはアーティファクトのマニフェストに名前が記載されるため、oras のような汎用 OCI クライアントはそれをその名前のファイルに書き込みます。ドキュメントとして公開されたエンティティは entity.yaml、ファイルとともに公開されたエンティティは entity.tar.gz、Plugin の場合はエンティティが entity.yaml、その実行可能ファイルが entity.wasm となります。名前は公開元のファイルではなくメディアタイプから決まるため、名前を変えたファイルから同じ内容を公開しても同じアーティファクトが公開されます。Catalog and Registry の §6 に、公開されるすべての形式と、それぞれが配置されるファイルが記載されています。

Recipe のリモートの source: URL(OCI チャート参照、HTTPS のチャートまたはフラグメントの URL、Git モジュール)は、公開される YAML にそのまま保持されます。取得されてアーティファクトにベンダリングされることはありません。利用者は、自身の pull 時にリモートソースを独立して解決し、ピン留めします。これにより、カタログエンティティの配布とソースアーティファクトの解決が別々の関心事として保たれます。

Aggregate は、それ自身の単一のドキュメントとして公開されます。aggregates: で参照するサブアグリゲートはアーティファクトにバンドルされません。各サブアグリゲートは個別に公開された Aggregate であり、利用者は pull 時にアイデンティティによって独立して解決し、ピン留めします。これは、リモートソースに適用されるのと同じ、配布を分離する原則です。

ディレクトリごとに 1 つのエンティティ

アーカイブは、エンティティファイルをそれが指定するファイルとともに保持するため、取り出す際にエンティティをあらためて見つける必要があります。利用者は、エンティティが持つプリアンブルによってそれを見つけます。バンドルの先頭にあり、kind: が公開可能なエンティティ種別であるドキュメントがエンティティです。エンティティを記述するファイルの名前は何でも構いません。recipe.yaml はカタログの慣例であり、要件ではありません。また、エンティティの横に置かれた compose フラグメント、チャートテンプレート、Kubernetes マニフェストがエンティティと取り違えられることはありません。これらは別のものを宣言しているか、種別をまったく宣言していないためです。さらに下層の source/ ツリー内にあるエンティティドキュメントは、エンティティそのものではなくエンティティが同梱するコンテンツであり、考慮されることはありません。

push は、別のエンティティとディレクトリを共有するエンティティを拒否します。 Aggregate、Release、Manifest はワークスペースのルートに並べて置かれますが、それ以外のすべての種別は専用のディレクトリを持ちます。それ以外の種別では、push はエンティティに対して他の処理を行う前、つまり pin ステップ、署名ポリシー、バンドルの前に、同じディレクトリに他のエンティティドキュメントが存在しないことを確認し、存在する場合は妨げとなる各エンティティを示して拒否します。これは push に pin が指示されているかどうかにかかわりません。aggrega pin も同じディレクトリを同じ文言で拒否します。この停止は An entity shares its directory with another entity(エンティティが別のエンティティとディレクトリを共有しています) です。エンティティの横にあるエンティティ種別でないドキュメント(チャートファイル、compose フラグメント、README など)は妨げにならず、サブディレクトリ内のものも同様です。エンティティの横にある各ドキュメントはワークスペース内からのみ、またはワークスペース外で指定したエンティティの場合はエンティティ自身のディレクトリ内からのみ読み込まれます。そのため、外部を指すリンクであるドキュメントがあると、ワークスペースの境界で説明しているとおり、push はそれを読み込まずにリンクを示して停止します。

この規則によって、1 つの entity.lock が 1 つのエンティティに属する状態が保たれます。ロックのファイル名はすべてのエンティティで同じであるため、1 つのディレクトリで 2 つのエンティティを記述すると、そこに置ける 1 つのロックを共有することになってしまいます。この判定はディレクトリから何かが生成されるときにのみ行われるため、複数のエンティティを含むディレクトリでもロード、lint、ビルドは引き続き可能です。

ディレクトリの名前は判定されません。 ディレクトリ内で単独のエンティティは、そのディレクトリがどこにあっても metadata.version で公開されます。標準ライブラリのカタログが従うレイアウトである <name>/<version>/ は慣例です。別のクライアントが 2 つのエンティティを含むディレクトリから公開したアーティファクトも安全に読み込まれます。その pull は、どちらか一方で応答するのではなく両方のドキュメントを示して停止します。これは errors/fatal-halts.md に記載されています。

バンドル前のエンティティの読み込み

push は Component、Feature、Recipe、FeatureRecipe をビルドと同じ方法で読み込み、その読み込みが拒否するものを拒否します。拒否は同じ理由、同じ短いコードで、バンドルが構築される前、かつ送信先レジストリに接続する前に行われます。そのため、種類のスキーマに適合しないドキュメント、エンティティ自身のディレクトリ外のコンテンツを指すパス、Component または Feature が $import: でインポートするスキーマのうち存在しないものや使用できないものは、公開されるのではなく公開時に拒否されます。これらはいずれも、利用者の最初のビルドで拒否されるエンティティです。また、ディレクトリの外に出るパスは、エンティティとともに配布されないファイルを指すことにもなります。公開物に含まれるすべてのファイルはエンティティ自身のディレクトリから取得されるためです。A path names content outside the entity’s own directory(パスがエンティティ自身のディレクトリ外のコンテンツを指しています)を参照してください。

Recipe または FeatureRecipe は、次のセクションで説明するピンの比較の際にこの方法で読み込まれます。そのため、この読み込みは push にピン留めが指示されているかどうか、またエンティティにピン留めするものがあるかどうかにかかわらず行われます。4 つの種類はいずれも、バンドルが構築される直前にもこの方法で読み込まれます。どのファイルを指すかを示すのがこの読み込みであるためです。Aggregate とライブラリはファイルを指さないため、この方法では読み込まれません。Plugin もファイルを指しませんが、Publishing a Pluginで説明するとおり、.wasm より先に種類のスキーマに照らして読み込まれます。

Plugin の公開

Plugin は --plugin で指定した .wasm と一緒に公開され、push はバイトが公開される前、またレジストリに接続する前に、この 2 つを検査します。--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 はこれを拒否し、バージョンと修正方法を示します。修正方法は、リリースのタグが指すコミットのクリーンなチェックアウトからプラグインをビルドし、リリースバージョンそのものを報告させることです(変更をリリースするには、まずエンティティの 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 であり、それが書き出すロックをコミットします。

push は、ロックにそれらのピンが記録されていないエンティティを拒否します。 バンドルを構築する前に、push はピン留めステップがそのエンティティについて記録する内容を算出し、隣にある entity.lock と比較します。ピンが欠けている場合、またはロックが保持するピンに入力がもはや一致しない場合、push はアーカイブの構築やレジストリへの接続を行う前に停止します。この拒否は、エンティティと該当するすべての入力(それぞれ remote source、imported file、local source file のいずれか)、および実行すべきもの、すなわちエンティティに対する aggrega pin、直前に実行した push への --pin-sources、またはワークスペース内のすべての push に対する pin_sources_at_push を示します。これは pull が同じロックに対して発生させる拒否 An entity reads an input the lock beside it records no pin for(エンティティが、隣にあるロックにピンが記録されていない入力を読み込んでいます) と同じものであり、push 固有の対処法が付きます。したがって、push が公開する Recipe または FeatureRecipe は、公開時点でステップが記録したはずのすべてのピンを記録したロックをバンドル内に持ちます。

ピン留めするものがなく、そのまま公開されるエンティティは 2 種類あります。リモートソースを読まず、ファイルをインポートせず、ローカルソースを指定しないエンティティと、リモートソースの座標がテンプレートから埋められる Recipe です。そのソースは Release がテンプレートを埋めて初めてアーティファクトを指すため、そのピンは各 Release のロックファイルに属し、push はエンティティの隣にピンを求めません。Component、Feature、ライブラリ、Aggregate、Plugin はロックが記録するものを何も読まないため、ここで拒否されることはありません。

リモートソースのピンを比較するには、aggrega pin と同様にソースを取得する必要があります。一致しなくなったピンは、ソースが現在提供する内容と照らし合わせて初めて判明するためです。そのため、このようなソースを持つエンティティに対する push は、レジストリに到達する前にソースのホストに接続します。比較はピン留めステップと同じくカタログを通じて Recipe または FeatureRecipe を読み込むため、カタログが読み込みを拒否するもの(たとえば種類のスキーマに適合しないドキュメント)は、ここでカタログ自身の理由とともに拒否されます。

ワークスペースが見つからず、指定もされていない場合、比較のためにリモートソースを取得することになる push は、aggrega pin と同様に、取得前に拒否されます。 比較では、エンティティが完全に書き出す各リモートソースを、ピン留めステップとまったく同じようにアーティファクトキャッシュに取得します。ワークスペースが見つからなかったフォルダにキャッシュを書き込むと、そのフォルダがワークスペースになってしまいます。そのため、ルートを指定するものも、ルートを定めるもの(push を実行するフォルダから、または絶対パスで指定されたエンティティについてはエンティティ自身のフォルダから)もない場合、このようなソースを持つ Recipe または FeatureRecipe の push は、ドライランや --pin-sources を含め、ソースの取得前に停止し、ソース、フォルダ、および 2 つの対処法を示します。--workspace-root または AGGREGA_WORKSPACE_ROOT でワークスペースを指定するか、そのフォルダに workspace: ブロックを持つ .aggrega-config.yaml を置いてください。上記の 2 種類のエンティティや、ソースがローカルであるエンティティについては比較で何も取得しないため、それらはそこでも他の場所と同様にロックと比較されて公開されます。また、その他の種類はロックの対象ではなく、この理由で拒否されることはありません。これが当てはまる他のコマンドは Configuration に記載されています。

aggrega push --pin-sources は、同じステップを最初に実行します。 このステップはバンドルの構築前に実行されるため、書き出されたロックは公開されるアーティファクトに含まれ、公開されるダイジェストもそれを対象とします。また、エンティティを判定する他のどの拒否よりも先に実行されるため、判定されるのはピン留め後のエンティティです。ステップはディレクトリが保持する唯一のロックを書き込むため、これより先に来るのは上記のディレクトリの規則だけです。ステップは aggrega pin と同じバイト列を書き込むため、その実行で上記の拒否が発生することはありません。ステップが書き込んだばかりのロックは、拒否が比較対象とする内容をそのまま記録しているからです。ワークスペースキー pin_sources_at_push はこれをすべての push のデフォルトにし、--pin-sources=false は 1 回の実行でステップをスキップして拒否を復活させます。ステップはエンティティの隣に書き込むため書き込み可能な場所が必要ですが、push は指定したドキュメントを公開するので、常にそれを持っています。

--dry-run は公開時と同じように応答します。 --pin-sources がない場合、ピン留めされていないエンティティを公開時とまったく同じように拒否するため、バンドルを報告するドライランは、この拒否を通過するものです。--pin-sources がある場合、ステップはドライランとしてピン留めします。書き込むはずのロックを表示して何も書き込まず、続くバンドルの情報はそのロックを含まない現状のディレクトリを記述します。そのため、ダイジェストはロックを含まない公開のものとなり、ロックが新規になる場合はサイズも、他に何も指定しないエンティティではメディアタイプも同様です。公開時には先にピン留めされるため、拒否は発生しません。

ベストプラクティス: すでに公開したバージョンへの変更は新しいバージョンに入れ、その後ピン留めします。 エンティティを新しいバージョンのディレクトリにコピーし、そこで変更を加え、ピン留めしてから公開します。このうち製品が強制する半分は次のセクションの内容で、すでに公開されたバージョンで異なる内容を公開することは拒否されます。もう半分、つまり公開済みのバージョンを自分のワークスペースで編集した後に再ピン留めしないことは、利用者自身が守るものです。未公開のエンティティの再ピン留めは正当であるため、ローカルではこれを拒否するものはありません。

レジストリ、タグ、コンテンツアドレッシング

ターゲットレジストリは、指定された場合は --registry <ref>、それ以外の場合はワークスペースの default_registry(デフォルトは hub.aggrega.ai)です。タグはエンティティの metadata.version であり、リポジトリパスはその kind と名前から導出されます。そのため、公開されたバージョンの配置先は、公開元のディレクトリに依存しません。

default_registry はリポジトリパスを含むことができ、それを通じた公開はそのパスの下に配置されます。 default_registry: ghcr.io/acme の場合、バージョン 1.0.0 の Component core/api-server は ghcr.io/acme/component/core/api-server:1.0.0 に公開されます。これは同じデフォルトを通じた pull の取得元と同じ場所であるため、ここで付与された署名はその pull が見つける署名になります。--registry はホストを指定し、それによって指示された公開はパスなしでそのホストに配置されます。宛先がどの方法で指定されても、適用される署名要件と署名設定はそのホストに対して保持されているものです。パスによって別のポリシーが選択されることはありません。パスの書き方はレジストリホストの書き方で説明しています。

マニフェストは公開されたバイト列のダイジェストを示し、ロックファイルはその内容のダイジェストを記録します。 push が書き込む OCI マニフェストは公開されたドキュメントまたはアーカイブのダイジェストを示し、aggrega pull はそれに一致しないダウンロードを拒否します。そのため、公開から pull までの間に改変されたバイト列は検出されます。pull が書き込むロックファイルは、エンティティを別のダイジェストで記録します。それはその内容のダイジェストであり、各ファイルのパスとそのバイト列から成り、アーカイブの圧縮方法やファイルのパーミッションビットは一切含みません。これは作成者自身のワークスペースでの pull が、カタログディレクトリ内の同じエンティティについて記録するダイジェストと同じです。そのため、1 つの公開について作成者とすべての利用者が同じ値を記録し、どちら側のビルドも、それに一致しなくなった内容を拒否します。2 つのダイジェストは異なる問いに答えます。マニフェストのダイジェストはダウンロードを検証し、ロックファイルのダイジェストはエンティティの同一性を表します。

既存のバージョンへの公開

aggrega push は、バイトをアップロードする前に、書き込もうとしている参照でターゲットレジストリがすでに保持しているものを解決し、手元のコンテンツと比較します。結果は次の 3 通りです。

  • そこにはまだ何も公開されていない — 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 は、それを欠いたままコンテンツを公開した状態にし、添付できなかったものを示して 0 以外の終了コードで終了します。同じ push を再度実行すると、その公開が完了します。push はコンテンツがすでに公開されていることを検出し、Already published: 行を出力し、何もアップロードせず、バージョンにまだ欠けているものを、初回の公開時にそれぞれについて出力される行とともに添付します。

  • 署名(この push が署名する場合)。 バージョンに、この公開のものとみなされる署名がない場合に添付されます。設定で公開先のホストに対する信頼ポリシー(public_key または trusted_identities、hub.aggrega.ai の場合は組み込みのベースライン)が固定されている場合、署名はそのポリシーで検証されたときにみなされます。そのため、ポリシーが認めない署名がその公開自身の署名と見なされることはありません。ポリシーがどちらも固定していない場合、署名はそれに対して検証できないため、バージョンが持つどの署名もみなされ、push は署名を持たないバージョンにのみ署名します。この場合に検証で判断すると、実行のたびに別の署名が添付されてしまいます。
  • 公開日。日付の規則によって公開日が必要とされ(添付したばかりの署名、またはすでにみなされた署名から読み取られます)、かつバージョンに published-at の referrer がまったくない場合に添付されます。署名しない push は、その後バージョンにどのような署名が添付されていても、署名なしの公開と同様に日付が必要です。記載される日付はこの push 自身の時計によるもので、公開が完了した時刻です。レジストリが提供するものにはコンテンツが最初に置かれた時点が記録されていないため、これはその時点より後になります。

すでに完了している公開には、push を何度繰り返しても何も添付されません。push は何かを添付する前に、バージョンが持つ署名と日付を読み取り、必要な署名を作成します。答えられない問い(読み取れない一覧や署名、または信頼ルートを取得できないため判断できない署名)と、作成できない署名は、バージョンに何もないと見なされるのではなく、いずれも何も添付せずに 0 以外の終了コードで終了します。

レジストリが書き込みに失敗した場合

push はレジストリへ段階的に書き込みます。まずコンテンツ(Plugin の場合はエンティティとその .wasm)、次にそれを指すマニフェスト、次にバージョンタグ、最後にその横に署名と公開日を書き込みます。書き込みを行う各ステップは、後の試行で成功しうる形で失敗した場合に再試行されます。該当するのは、レジストリがサーバーエラー(Retry-After を伴う 503 を除く任意の 5xx ステータス)または 408 Request Timeout を返した場合、あるいは接続がタイムアウトした場合、リセットされた場合、応答の途中で切断された場合です。各ステップは最大 3 回試行され、2 回目の試行の前に 0.5 秒、3 回目の試行の前に 1 秒待機します。

速度を落とすよう求めるレジストリに対しては待機し、これらの試行回数は消費しません。429 Too Many Requests、または Retry-After を伴う 503 を受けると、そのレジストリへのすべてのリクエストは、読み取りも書き込みも同様に、レジストリが求めた時間だけ待機してから再度送信されます。コンテンツが拒否されたステップは新しいアップロードとしてやり直されます。試行回数に上限はなく、レジストリが 5 分間「速度を落として」以外に何も応答しなくなるまで続きます。待機と、それを終わらせる拒否については速度を落とすよう求めるレジストリで説明しています。

**各試行は同じバイト列の新しいアップロードであり、失敗したリクエストの再送ではありません。**アップロードの本文をすでに受け取ったレジストリは、同じリクエストを 2 回目には拒否することがあり、受け入れるのは新しいアップロードです。レジストリがすでに保持しているコンテンツはアップロード済みとして扱われ、再試行されたステップは最初の試行が書き込んだはずの内容を書き込みます。そのため、書き込みは完了したものの応答が失われた試行があっても、何かが二重に書き込まれることはありません。マニフェストはそのダイジェストを保ち、バージョンには署名と公開日がそれぞれ 1 つだけ付きます。

それ以外の失敗はすべて、そのステップを直ちに終了させます。該当するのは、認証情報の拒否(401、403、またはそのレジストリの認証情報が保存されていない場合)、レジストリが返すその他の応答、レジストリにまったく到達できない場合、push を中断した場合です。**最後の試行の後もステップが失敗している場合、コマンドは失敗し、エラーはそのステップ(コンテンツ、マニフェスト、タグ、署名、公開日のいずれか)を示します。**それ以前のステップで公開されたものは公開されたまま残ります。それがバージョンにとって何を意味するかは、署名と公開日で説明します。

これらの失敗で再試行されるのは書き込みのみです。何かをアップロードする前に、レジストリがそのバージョンにすでに保持している内容を読み取る処理は再試行されません。ただし、すべてのリクエストと同様に、速度を落とすよう求めるレジストリに対しては求められた時間だけ待機します。

署名

aggrega push は公開と同時にアーティファクトに署名し、その署名を OCI リファラーとして添付できます。これは、アーティファクトの不変なマニフェストダイジェストに対する Sigstore(cosign 互換)バンドルです。署名は兄弟マニフェストであるため、署名によって公開済みのバイトが再プッシュされたり変更されたりすることはありません。リファラーはバンドルに signature.json という名前を付けるため、汎用の OCI クライアントがダイジェストでリファラーを取得すると、バンドルはそのファイルに書き出されます。

署名は sign-before-push(プッシュ前の署名)です。マニフェストダイジェストは公開前に判明しているため、aggrega push は署名者を構築し、レジストリにバイトが届く前にダイジェストに署名します。署名者を構築できない場合や署名に失敗した場合、プッシュは何かがアップロードされる前に拒否されます。何も公開されないため、署名の失敗によって未署名のコンテンツがレジストリに残ることはありません。拒否する前に、一時的に失敗した署名呼び出し(レジストリへの書き込みが再試行される失敗、またはキーレス認証局が ID トークンを処理できなかったと報告した場合)は、同じ待機時間で最大 3 回まで再試行されます。キーレス署名の呼び出しの内部では、認証局、透明性ログ、またはタイムスタンプ局が 429 Too Many Requests またはサーバーエラーで応答したリクエストは、aggrega sign で説明するとおり、まずそのサービスに再送されます。

署名はコンテンツの到着後に添付されるため、添付に失敗するとコンテンツは署名なしで公開されたままになります。 添付は書き込みであり、レジストリが書き込みに失敗した場合で説明するとおり再試行されます。それでも失敗した場合、コマンドは添付できなかった署名を示して非ゼロで終了し、署名を要求するレジストリを使うコンシューマーは、署名が添付されるまでそのバージョンを拒否します。以前のプッシュで部分的に残った公開を完了するで説明するとおり、同じプッシュを再度実行すると署名が添付されます。aggrega sign は公開済みのバージョンに参照によって署名を添付します。

公開先レジストリ自身の signing ブロックで required: true が設定されている場合、またはトップレベルの signing ブロックがすべてのレジストリについてそれを設定している場合、公開には署名が必要です。いずれも、kinds に種類が列挙されていれば、その種類に限られます。そのような公開ではデフォルトで署名が行われ、--sign は署名を明示的に要求します。署名が必要な場合に未署名のコンテンツをプッシュするフラグはなく、そのプッシュは常に停止します。

署名モードは 2 つあります。

  • キーレス(デフォルト)— 短期間有効な Fulcio 証明書によって OIDC ID に紐付けられた一時的な鍵で、Rekor 透明性ログに記録されます。Fulcio と Rekor のデフォルトは公共の Sigstore インスタンス(https://fulcio.sigstore.dev、https://rekor.sigstore.dev)です。キーレスの信頼できるタイムスタンプは Rekor の透明性ログへの包含から得られます。別途 RFC3161 タイムスタンプ局を使うことは任意であり、有効にするには完全なエンドポイントを指定して --timestamp-url を渡します。対話型ターミナルでは、キーレス署名にフラグは不要です。CLI がブラウザを開き、短期間有効な OIDC ID トークンを取得します。GitHub Actions でもフラグは不要です。CLI がランナーの環境エンドポイントからワークフローの OIDC トークンを自動的に発行します。その他の非対話型 / CI での利用では、AGGREGA_IDENTITY_TOKEN(または SIGSTORE_ID_TOKEN)をエクスポートするか、--identity-token を渡します。トークンが指定されず、環境エンドポイントもターミナルもない場合、プッシュは拒否されます。CI のトークンモデルについては environment-variables.md を参照してください。
  • キー付き(--key)— オフラインで保持する ECDSA P-256 鍵(cosign 互換の PEM)で、OIDC ID プロバイダーがない環境向けのエスケープハッチです。ID プロバイダー、認証局、透明性ログのいずれにも接続しません。

キーレスのサービス URL とキー付きの鍵パスは、.aggrega-config.yaml の signing: ブロック(グローバルおよびレジストリごと)でも設定できます。フラグは設定より優先され、設定は公共のデフォルトより優先されます。OIDC ID トークンが設定フィールドになることはなく(短期間有効なシークレットであるため)、秘密鍵が設定内に直接記述されることもありません。記述できるのは鍵へのパスだけです。

公開日

マニフェストの作成時刻は固定されているため、マニフェストのダイジェストは何が公開されたかだけに依存し、いつ公開されたかには依存しません。その代わりに、バージョンが公開された日付はバージョンとは別に添えて運ばれ、その出どころは署名によって異なります。

  • キーレス署名はすでに日付を持っています。 その透明性ログのエントリには、ログが署名を取り込んだ時刻が記録され、ログの署名付きの約束がその時刻を証明します。aggrega push はそれ以上何も書き込みません。
  • 鍵付き署名、または署名なしの場合は時刻を持ちません。 そのため、エンティティと署名(ある場合)が配置された後、aggrega push は小さな published-at リファラーをマニフェストに添付します。これは汎用の OCI クライアント向けに published-at.json という名前を持ち、公開を行ったマシン自身の時計から読み取った、UTC で秒単位の RFC 3339 タイムスタンプを 1 つ保持します。これは署名されていません。公開者による申告であり、読み取る側もそのように記録します。Publication date attached: の行がこれを報告します。

署名と同様に、published-at リファラーは公開済みのマニフェストを指し返す兄弟マニフェストであるため、ダイジェストを動かすこともタグを変えることもなく、既存のバージョンへの上書き公開に対するチェックにも影響しません。同じ内容を再度プッシュした場合、日付を持たないバージョンにのみ、自身の時計による日付を添付します。以前のプッシュが部分的に残した公開の完了を参照してください。日付は最初に添付を試みる前に一度だけ時計から読み取られるため、再試行された添付(レジストリが書き込みに失敗した場合を参照)も同じ日付を示します。内容を公開したものの、それらの試行の後も日付を添付できなかったプッシュは非ゼロで終了し、添付されなかったものを示します。aggrega registry update は、各バージョンの日付を、それが 2 つの出どころのどちらから来たかとともに記録します。

オフライン

公開はネットワークの往復通信であり、そうでない形態は存在しません。そのため、オフライン設定(設定ファイルのトップレベルの offline キー、AGGREGA_OFFLINE、または --offline)の下では、aggrega push はエンティティを読み込む前に拒否します。拒否メッセージには、これら 3 つのうちどれがオフライン設定を有効にしたかが示されます。これは、本人が入力したものではなく、プロジェクトにコミットされた設定によって有効になっていた場合に必要となる情報です。

--dry-run は例外であり、その動作ゆえに例外となっています。これはバンドルを計算し、公開されるはずの参照とその公開によって配置されるはずのダイジェストを出力しますが、レジストリには一切接続しません。そのため、オフライン設定と衝突するものではなく、公開のオフラインで安全な形態であり、オフライン設定の下でも動作し続けます。ただし 1 つ条件があります。リモートの source: が完全に記述された Recipe または FeatureRecipe では、ピンを比較するためにそのソースが取得されますが、オフライン設定の下ではその取得が独自のメッセージで拒否されます。そのため、そのようなエンティティに対するドライランは、保証できないバンドルを報告するのではなく、そこで停止します。

設定がオフラインになっているワークスペースから 1 回の実行に限って公開するには、--offline=false を指定します。

環境変数

署名の入力と送信先レジストリは環境変数で指定できます。環境変数は .aggrega-config.yaml より優先されますが、フラグはそれよりもさらに優先されます:

  • AGGREGA_IDENTITY_TOKEN — キーレス方式の OIDC ID トークンです(--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 — push の前に実行すべき公開ゲート(--pre-publish)です。
  • ./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—キーレス署名に使用する Fulcio 認証局の URL です。省略した場合は、公共の Fulcio インスタンスが使用されます。
--identity-token—キーレス署名に使用する OIDC ID トークンです。対話型ターミナル(ブラウザーフローでトークンを取得します)と GitHub Actions(ワークフローの OIDC トークンが自動的に発行されます)では任意です。それ以外の非対話型/CI での使用では必須で、代わりに AGGREGA_IDENTITY_TOKEN または SIGSTORE_ID_TOKEN としてエクスポートすることもできます。
--key—オフラインの鍵付き署名に使用する、保持している ECDSA P-256 秘密鍵 PEM のパスです。省略した場合は、キーレス署名が使用されます。
--list-kindsfalse公開可能なすべてのエンティティ種別を一覧表示し、何も公開せずに終了します。出力は機械可読で、その形式は安定しています。1 行に 1 種別ずつ、ソート順で、それ以外は何も出力しません。
--pin-sourcesfalseバンドルする前にエンティティに対してエンティティ作成者のピンステップを実行し、そのステップがエンティティの隣に書き込む entity.lock を公開内容に含めます。ロックにピンが記録されていないエンティティを拒否する代わりにこの動作をとります。aggrega pin と同じステップで、同じバイト列を書き込みます。エンティティの隣に書き込むため、エンティティに書き込み可能な場所、つまり読み込み元のディレクトリにあるドキュメントがある場合にのみ実行されます。push は指定したエンティティドキュメントを公開するため、常にこの条件を満たします。ワークスペースの pin_sources_at_push を両方向に上書きします。設定の内容にかかわらず、—pin-sources はこの実行でピンを固定し、—pin-sources=false は固定しません
--plugin—Plugin エンティティのローカル .wasm アーティファクトのパスです。Plugin を公開する場合は必須です。publish は .wasm アーティファクトを push し、そのコンテンツダイジェストを計算して、エンティティを push します。
--registry—公開先のレジストリホスト(ワークスペースの default_registry を上書きします)
--rekor-url—キーレス署名に使用する Rekor 透明性ログの URL です。省略した場合は、公共の Rekor インスタンスが使用されます。
--signfalse公開したアーティファクトに署名し、その署名を OCI referrer として添付します。省略した場合、署名は公開先レジストリのポリシーに従います。
--timestamp-url—キーレス署名に使用する、任意の RFC3161 タイムスタンプ局の URL です。