aggrega inspect
aggrega inspect は、あらゆる Aggrega エンティティ(カタログの Component、作成済みのエンティティファイル、レジストリに公開されたエンティティ、または完全に解決された Release)を人間が読める形式で表示します。コンパイラが何を生成するかを理解するための標準的なデバッグ手段であり、どの Components がどのベースを拡張しているか、各型にどの Recipe が対応するか、各ノードにどの Features がアタッチされるか、そして各 Feature の寄与が正確にどこから来たかを確認できます。
各エンティティ種別には、それぞれ自然な「契約」ビューがあります。inspect はその契約を表示します。Component が公開するスキーマ、Manifest が宣言するマッピング、Aggregate が構築するトポロジー、Release が解決するノードごとの Feature アタッチメントです。チュートリアルや概念的な説明は別の場所にあります。inspect は「このエンティティは実際に何に解決されるのか」に答えます。
単一の位置引数は、内容の形に応じて振り分けられます。サブコマンドは必要ありません。コマンドは次のヒューリスティックに従って振り分けを行います。
| 識別子の形 | 振り分け先 | 出力 |
|---|---|---|
./、../、/ で始まる、または .yaml / .yml で終わる | ファイル分岐 | ファイルの kind: ヘッダーに基づくファイルごとの検査。 |
oci:// で始まる | レジストリ分岐 | その座標に公開されたエンティティを、レジストリから読み取り、同じ種別のファイルと同じビューで表示します。公開されたエンティティの読み取りを参照してください。 |
| それ以外 | カタログ分岐 | すべてのエンティティ種別にわたってカタログ検索スタックから識別子を検索し、extends: チェーンを解決して、一致した種別固有のビューで表示します。 |
3 つの詳細レベル
--list、デフォルト、--detail は、すべての種類が従う統一された 3 段階の詳細度の体系を構成します。--list と --detail は相互に排他的です。両方を指定すると、暗黙に解決されるのではなく拒否されます。
--list— 識別子のみ。Component はその名前と uses ソケット名を一覧表示し、MappingLibrary はそのマッピング名を一覧表示し、Aggregate はそのコンポーネント名を型とともに一覧表示します。- デフォルト — 対話的な利用向けに調整された構造化された概要。エンティティの識別情報から始まり、Manifest と Release を除くすべての種類では、エンティティが説明を記述している場合はその説明が続きます。説明のないエンティティは、空行ではなく何も出力しません。残りの形は種類ごとに異なります。Component はスキーマとソケットを表示し、Aggregate はコンポーネント、その値、各接続が持つアタッチメントを伴うエッジ、および依存グラフを表示し、Release は Feature アタッチメントを伴う境界ごとのノードツリーを表示します。接続に記述された各アタッチメントは、その接続の下に一覧表示されます。
--detail— フィールドの本体をすべて表示します。その種類が持つすべてです。Component は self-inject メカニズム、必須の Features、ラベルを追加し、MappingLibrary は各マッピングのテンプレート本体全体を展開し、Recipe は workload 本体、provides、アサーションを追加します。
いくつかの種類では、これらのレベルを使って記述された本体を段階的に多く表示します。MappingLibrary は --list ではマッピング名を表示し、デフォルトのレベルでは各マッピングの合成された使用例を追加し、--detail ではテンプレート本体全体を展開します。
解決: --raw と --resolved
各種別には、それぞれ自然なデフォルトの解決深度があります(下の表を参照)。--raw と --resolved は常に使用できるオーバーライドであり、互いに排他的です。両方を渡すと、暗黙に解決されるのではなく拒否されます。
--rawはすべての解決を無効にします。エンティティはファイルから直接、記述されたとおりに出力されます。--resolvedはその種別の完全な解決深度を有効にします。
デフォルトで記述どおりに表示される種別では、--raw は何も行わず、--resolved はその種別がサポートする解決を実行します。デフォルトで解決済みとなる種別では、--raw は記述どおりの表示へのバイパスになります。
--raw はファイルをそのまま再現するため、作成者が機密と宣言した値も記述されたとおりに表示されます。これは仕様であり、欠落ではありません。自身の一部を黙って伏せる記述どおりの表示は、記述どおりとは言えないからです。--raw の出力は、その元となったエンティティファイルと同じように扱ってください。--output yaml も、Release を含むすべての種別で同じようにファイルを再現します。
Release はさらに 2 つの問いに答え、それぞれが独自のフラグを持つ別のドキュメントになります。Release が解決される先のコンパイル済みグラフは --ir-graph、その依存関係クロージャは --closure です。後述の機械可読な出力と依存関係クロージャ: --closureを参照してください。
種別ごとのデフォルト
inspect は、下の表にある、単独で検査できる種別を扱います。カタログ種別はデフォルトで記述どおりにレンダリングされます。これらのファイルは自己完結した契約だからです。インスタンス種別はデフォルトで解決済みのビューになります。記述された YAML は、カスケードやパイプラインの出発点にすぎないためです。
| 種別 | デフォルト | 「解決済み」の意味 |
|---|---|---|
| Component | 記述どおり | ファイルは自己完結した契約です。解決は Manifest のバインディングに対して行われ、--show-implements で表示されます。 |
| Feature | 記述どおり | Component と同じです。 |
| Recipe | 記述どおり | --show-implements は spec.implements の Component 参照を解決します。 |
| FeatureRecipe | 記述どおり | --show-implements は spec.implements の Feature 参照を解決します。 |
| MappingLibrary | 記述どおり | エントリは不透明な Go テンプレート文字列です。レンダリングは使用時に行われます。 |
| SchemaLibrary | 記述どおり | エントリは、使用時に解決される再利用可能なスキーマとテンプレートの定義です。 |
| WorkloadLibrary | 記述どおり | エントリは、Recipe がインポートする再利用可能な Workload 本体で、使用時に評価されます。 |
| ArtifactLibrary | 記述どおり | エントリは、Recipe がインポートする再利用可能なアーティファクトバンドルで、使用時にレンダリングされます。 |
| Plugin | 記述どおり | ファイルは自己完結したプラグイン契約です。ソケット型、エクスポートごとのケイパビリティ、ランタイム制約、署名ポインタを含みます。ファイルパス、またはカタログに対する <pluginType>/<name> 座標で指定できます。 |
| Manifest | 解決済み | extends: チェーンが適用され、解決済みの component と feature のマッピングが展開されます。 |
| Aggregate | 解決済み | トポロジーが構築されます。uses グラフと順序が計算されます。 |
| Release | 解決済み | 完全なパイプラインが実行されます。解決、アノテーションの展開、ガードの実行、トポロジーの構築、IR の構築です。 |
kind: が Workload であるファイルは拒否されます。Workload は Recipe に埋め込まれた形でのみ存在し、単独で検査できるエンティティではありません。Workload を確認するには Recipe を検査してください。
kind ごとの解決の深さ
ほとんどの kind にはパイプラインがありません。inspect はファイルを読み込んでレンダリングします。意味のある解決を行うインスタンス kind は 3 つです。
- Manifest は
extends:チェーン(ファイルインポートの追跡)を適用し、マージされた component と feature のマッピングをレンダリングします。--rawは作成されたままのファイルを表示します。 - Aggregate はトポロジーを構築します。uses グラフが構築され、依存関係の順序が計算されます。デフォルトのビューでは、値とエッジを持つ component が表示され、その後に依存関係グラフが続きます。
--rawは作成されたままのサブシステムツリーを表示します。 - Release は IR までのコンパイルパイプライン全体(解決、アノテーションの展開、ガードの実行、トポロジーの構築、IR の構築)を実行し、各ノードの Feature アタッチメントとその来歴を含む、境界ごとのノードツリーをレンダリングします。グラフを形作るガバナンスアタッチメントは、ビューのためにスキップされるのではなくこのパイプライン内で実行されるため、表示される内容はそれらが決定した結果を反映します。
label-transformアタッチメントのラベルは、何かがそれに対して照合される前に適用されており、annotation-transformアタッチメントが注入したアノテーションは、作成者が記述したアノテーションとまったく同じように Feature アタッチメントへ展開されます。このコマンドがプラグインを解決できないアタッチメントがある場合、そのプラグインの決定を欠いたグラフを残すのではなく、コマンドは停止します。別の Release を拡張する Release は、このビューでも--ir-graphでも、そのextends:チェーンが合成する Release、つまりそれをビルドするときに読み取られる Release として描画されます。そのため、親だけを指定する Release は、親の Aggregate、Manifest、境界を自身の名前の下に表示します。Release が指定する Manifest も、その Release が何かを拡張しているかどうかにかかわらず、自身のextends:チェーンを通じて合成されます。そのため、その Manifest が継承したマッピングを持つアタッチメントには、ビルドが使用する実現が表示されます。--rawはパイプラインを実行せず、Release ファイルをそのまま出力します。--closureは同じ Release について別の問いを立て、パイプラインを一切実行しません。依存関係のクロージャ:--closureを参照してください。
深さを指定する個別のフラグはありません。--raw / --resolved の切り替えが唯一の解決制御であり、各 kind の本来のデフォルトの上に重ねて適用されます。
エラー時の動作
参照先の兄弟ファイルの読み込みに失敗すると、コマンドは直ちに停止します。たとえば、存在しない Aggregate を指す Release や、検索スタック内の壊れたカタログエンティティがこれに当たります。部分的な出力をレンダリングするのではなく明確なメッセージを出して停止し、読み込み失敗に対してエラー時に続行するモードはありません。解決に必要なドキュメントが読めなくなった時点で、それ以上解決するものはないためです。名前の解決が、読み込みで拒否された 1 つのカタログドキュメントで停止した場合、メッセージはその拒否を一度だけ示します。まずカテゴリと、拒否が条件を示す場合はその短いコードを含む見出し、次にドキュメント、次にそのドキュメントの問題点を示します。種類のスキーマが拒否したドキュメントであれば、その行と違反した制約を示します。ファイルを移動するよう提案することはありません。カタログはそのファイルを読み込んでおり、だからこそ拒否されたからです。
コンパイラのチェックが構成を拒否する Release は、レンダリングされずに拒否されます。 Release を解決するとグラフが構築され、ビルドが完成したグラフに対して行うチェック(ターゲットがソケットの selector: を満たさない uses: エッジ、appliesTo: が許可しないコンポーネントにアタッチされた Feature など)もここで行われ、同じドキュメントのビルドが出力するものと同じ診断が出されます。拒否は最初の検出で停止せず、1 回の実行ですべての検出結果を示すため、1 回の実行で修正すべき一覧の最初の項目だけでなく全体を確認できます。これにより、このコマンドはデプロイメントについて正直であり続けます。ビルドが拒否する構成をレンダリングするビューは、問題のあるワークスペースを問題なしと報告してしまうからです。何も解決しない選択肢は影響を受けません。--raw、--output yaml、--closure は、グラフを構築せずに、記述した内容を再現または解決します。
ロックファイルが解決結果と一致しなくなった Release は、aggrega build が表示する停止とともに拒否されます。Release の横にロックファイルがある場合、Release を解決するすべての選択——デフォルトのビュー、--resolved、--ir-graph、--closure——は、ビルドがレンダリング前に実行するドリフト比較によって、ロックファイルを Release の解決結果と照合します。一致しなくなったロックファイルは、ビルドの E0130 拒否でコマンドを停止させます。ドリフトしたすべてのエントリを示し、続いてそれを解消する aggrega pull --release <release> を示します。標準出力には何も書き込まれず、コマンドは 0 以外の終了コードで終了します。現状のカタログから描いた図は、その Release のどのビルドもレンダリングしないものを示してしまうからです。--raw と --output yaml は単独ではロックファイルもカタログも読み込まないため、この照合の対象になりません。横にロックファイルがない Release は、現状のカタログに対して解決されます。
kind: が認識されないファイルは、不明な種類とその取得元ファイルを報告します。Workload ファイルは、その種類が埋め込み専用であることを報告し、埋め込み先のエンティティを示します。読み取れない oci:// 識別子は、その理由を示す条件とともに拒否されます。それらの条件は公開されたエンティティの読み取りに一覧があります。
カタログの解決
カタログ検索スタックは、階層化された優先順位で組み立てられます。まず --catalog フラグ(指定順に先頭へ追加)、次に .aggrega-config.yaml にあるワークスペースの catalog_dirs(Release に対して設定が workspace.releases の下にその Release 独自のディレクトリを与えている場合は、その Release のものが代わりに使われます)、最後にワークスペースのルートにある catalog ディレクトリです。このディレクトリは、何かがそれを指定しているかどうかに関係なく読み込まれます。catalog_dirs が空のリストとして書かれたワークスペースは、ローカルカタログを一切読み込みません。スタックは先勝ちです。あるエンティティの識別子を最初に宣言したディレクトリがそれを所有し、後のディレクトリにあるコピーはシャドウされます。カタログ分岐は、このスタックに対して識別子をすべてのエンティティ種別にわたり固定の優先順位で解決し、最初に一致したものをその種別自身のビューで表示します。ファイル分岐とリリース分岐は、Manifest のマッピングや extends: の親を解決する必要がある場合に、参照されたカタログエンティティをこのスタックから読み込みます。スタックが保持していない extends: の親は、ビルドが読み取るのと同じ場所、つまりアーティファクトキャッシュから、Release のロックファイルがそれについて記録しているピンの下で読み取られます。そのロックファイルとは、指定された Release のもの、または何も指定されていない場合はワークスペースが保持する各 Release のものです。そのため、レジストリに公開されたベースは、aggrega pull がそれをフェッチしてピン留めした時点でここで解決され、それまではコマンドが aggrega pull --release <release> を示して拒否されます。何もフェッチされません。
Release の条件で名前を検索する
単独で指定された名前は、ワークスペース自身のスタックで検索されます。その横に --release <release-path> を指定すると、名前は代わりにその Release のスタック(ワークスペース設定がその Release に与えるディレクトリに、指定された --catalog を先頭に追加したもの)で検索されます。これは、その Release のビルドが読み込むものと同じです。したがって、Release ごとにカタログのバリアントを 1 つずつ保持し、それぞれが同じエンティティを宣言しているワークスペースでは、名前に対してその Release がビルドに使うバリアントが返されます。
aggrega inspect core/datastore/mariadb --release release-helm-synth.yamlその Release のスタックで解決できない名前は拒否され、ローカルエンティティの読み込み元についての説明では、その Release の workspace.releases 配下のエントリが示されます。検索が読み込んだのがそのエントリだからです。--release は名前を検索するスタックを選ぶものなので、単独の名前にのみ適用されます。ファイルパスとレジストリ参照はそのまま読み込まれ、このフラグを拒否します。存在しないファイルやディレクトリを指定する --release は、検索が行われる前に拒否されます。
公開済みエンティティの読み取り
aggrega inspect oci://<host>/<repository>:<tag> は、その座標に公開されたエンティティを読み取ります。:<tag> の代わりに @<digest> を指定すると、1 つのマニフェストを正確に指定します。これは、レジストリにのみ存在するエンティティを確認する方法です。リポジトリは、Catalog and Registry §6 で説明されているとおり、種類のセグメントにエンティティの識別子が続くものです。aggrega push は公開先の参照を出力し、その前に oci:// を付けるとここで読み取れます。
表示されるのは、公開されたときのままのエンティティです。 宣言するファイルとともに公開されたエンティティ(ローカルのチャートやロックを持つ Recipe、スキーマをインポートする Component など)はアーカイブとして配布され、エンティティはそこから展開されます。展開されるのは、アーカイブのルートにある、公開可能な種類を宣言するドキュメントです。そのため、その横に同梱されたチャートテンプレートや compose フラグメントがエンティティと取り違えられることはありません。ファイルを宣言しないエンティティはドキュメントがそのまま配布され、Plugin のエンティティは、ともに公開された実行ファイルではなくそのマニフェストから読み取られます。その後ドキュメントは、その種類のファイルと同じビューで、同じ詳細レベル、同じ --raw と --output yaml で表示されます。継承は適用されません。ビューは公開者がその座標に置いたものを示します。読みやすいレイアウトの末尾には、読み取った内容が示されます。座標、エンティティがアーカイブとして格納されていたかドキュメントそのものとして格納されていたか、マニフェストが宣言するメディアタイプ、そしてそのマニフェストのダイジェストです。このダイジェストを :<tag> の代わりに @<digest> として書くと、同じバイト列を再び読み取ります。--output yaml はドキュメントのみを出力し、その後には何も出力しません。
検査する内容と、検査しない内容。 取得したバイト列は、アーティファクト自身のマニフェストが記録するダイジェストと照合され、それらがそのマニフェストの指すバイト列であることが確認されます。これはレジストリが返したものに対する検査であり、事前に記録された何かに対する検査ではありません。アーティファクトに添付された署名は検証されず、それに対して記録された撤回も報告されません。何も書き込まれない(キャッシュエントリもロックファイルも作成されない)ため、座標を読み取っても、後のビルドが解決する内容は何も変わりません。
ネットワークにアクセスします。 レジストリへは、このマシンがそのレジストリ用に保持している認証情報を使って接続します。認証情報は aggrega push と aggrega pull が読むのと同じストアから取得され、このマシン上のレジストリには平文の HTTP で接続します。オフラインのワークスペースでは、接続する前に読み取りが拒否されます。
応答できない読み取りは非ゼロで終了し、標準出力には何も出力しません。 以下の各失敗は、その条件と対処方法を示します。まったく到達できないレジストリは、読み取りを止めたネットワークエラーとともに報告されます。
| 発生した事象 | 条件 |
|---|---|
| 参照の下に何も公開されていない | E0137 |
| レジストリが認証情報を拒否した、またはそのレジストリ用の認証情報が保存されていない | E0138 |
| ワークスペースがオフラインである | E0125 |
| アーティファクトが展開できないアーカイブである | E0300 |
| アーカイブのルートにエンティティドキュメントがない | E0298 |
| アーカイブのルートに複数のエンティティドキュメントがある | E0299 |
| ドキュメントがレジストリの公開する種類のエンティティではない | E0301 |
各コードはエラーリファレンスに記載されています。リポジトリを指定しない参照、またはタグもダイジェストも指定しない参照は、代わりに書くべき形式を示して拒否されます。--ir-graph と --closure は、レジストリが公開する種類に Release は含まれないため、何かを取得する前に拒否されます。
非推奨と取り下げの通知
公開者は、アーティファクトの公開後にそのアーティファクトに対してマーカーを記録し、公開済みのバージョンが非推奨または取り下げであることを示せます。カタログ分岐がエンティティを解決すると、inspect はそのようなマーカーをエンティティ自身のビューの下に報告します。これは Component に限らず、名前で解決するすべての種類が対象です。
通知には、公開者が記録した重大度(warning、error、retracted のいずれか)とともに、マーカーが記録されたバージョン、理由、代替が指定されている場合はその代替、発行日が示されます。3 つの重大度はすべて報告されます。これは、ビルドの解決先を変える集合よりも広い範囲です。retracted とマークされたバージョンはバージョン選択から除外されますが、warning と error は助言にとどまり、引き続き選択されます。inspect は公開者が述べた内容を示すものであり、何が得られるかを決めるものではありません。
通知は、エンティティの解決元であるレジストリのローカルインデックスから読み取られます。このインデックスは aggrega registry update が構築するため、ネットワークを必要とせず、オフラインのワークスペースでも動作します。インデックスはスナップショットであるため、通知の末尾にはそのスナップショットがいつ取得されたかが示され、それを更新するコマンドが示されます。インデックスが構築されていないワークスペースでは何も報告されません。したがって、通知がないことは「何も記録されていない」ではなく「このスナップショットには何も記録されていない」ことを意味します。
マーカーは、その署名がレジストリの信頼ポリシーが認める署名者に対して検証される場合にのみ報告されます。署名のないマーカーや、署名が検証されないマーカーは報告されません。認証できない主張は事実として提示されません。
通知は人間が読むためのビューに付随します。--output yaml も --ir-graph も通知を付加しないため、いずれかを解析する利用側はドキュメントだけを受け取ります。
実例
カタログの Component の参照
$ aggrega inspect core/server:1.0.0 --catalog ./catalog
Component: core/server:1.0.0Schema: | values: { port?: int | *8080 }Uses sockets: db: selector="component.aggrega.ai/type=stateful-server"デフォルトのビューは、Component が説明を記述している場合はその説明を表示し、続いて解決済みのスキーマ(extends: によるマージの後)と、宣言された uses ソケットを表示します。上の Component は説明を記述していないため、出力はスキーマからすぐに始まります。--detail を指定すると、自己注入メカニズム、必須の Features、ラベルが追加されます。--list は Component の識別子とソケット名のみを表示します。
Feature
$ aggrega inspect ./features/metrics.yaml
Feature: core/metrics:1.0.0Schema: | values: { port?: int | *9090 }Uses sockets: backend: selector="component.aggrega.ai/type=stateful-server" inject: [env]Secret slots: token (required)Targeting: appliesTo: component.aggrega.ai/type=serverLabels: feature.aggrega.ai/category: observability--show-implements を指定した Recipe
Recipe のデフォルトのビューは、宣言している入力モードごとに 1 つのセクション、ケーパビリティ、値のマッピングを表示します。--show-implements は spec.implements の参照をカタログに対して解決し、バインドされた Component を、その Component が必要とするアタッチメントとともに表示します。
$ aggrega inspect ./recipes/api-server-recipe.yaml --show-implements --catalog ./catalog
Recipe: core/api-server-recipe:1.0.0Implements: core/api-server:1.0.0Capability: helm## Synthesized workload: inlinevaluesMapping: (none)Implements Component: core/api-server:1.0.0 requires attachment (observability): core/metrics複数の入力モードを宣言する Recipe
Recipe の入力モードは加算によって合成されます。レンダリングする source:、合成する workload:、artifacts: マップはそれぞれ出力に寄与し、Recipe はこれらを任意の組み合わせで宣言できます。inspect は 1 つを選ぶのではなく、Recipe が宣言するすべてのモードを報告するため、表示されるのは記述したとおりのセットです。
$ aggrega inspect ./recipes/api-server-composed.yaml
Recipe: core/api-server-composed:1.0.0Implements: core/api-server:1.0.0Capability: helm## Sourced source: oci://charts.example.com/api-server:2.1.0## Synthesized workload: inlinevaluesMapping: inline templateArtifacts: 2 - servicemonitor.yaml - networkpolicy.yamlセクションは source: → workload: → artifacts: の順に並びます。これは、ビルドが Recipe を単一のモード名に解決するときや、バインドされたプロバイダーが対応できない宣言済みモードを報告するときに用いる順序と同じです。そのため、このビューとビルドの診断はモードを同じ順序で示します。source: も workload: も宣言しない Recipe は artifacts のみとして報告され、これがビューが単一のモードを示す唯一のケースです。
Manifest(デフォルトで解決済み)
$ aggrega inspect ./prod-manifest.yaml
Manifest: prod-manifest:1.0.0
Component Mappings: Type → Recipe core/compute/api-server helm-api-server-synthesized-with-artifacts:1.0.0 core/compute/web-ui helm-web-ui-synthesized-with-artifacts:1.0.0 core/datastore/postgres helm-postgres-synthesized-with-artifacts:1.0.0
Feature Mappings: Type → FeatureRecipe core/k8s-dns-resolver k8s-dns-patcher:1.0.0
Annotation Bindings: (none)デフォルトのビューは Manifest の extends: チェーンを適用し、解決済みのコンポーネントとフィーチャーのマッピング、およびアノテーションのバインディングを表示します。--raw は、extends の解決前の、記述されたままのファイルを表示します。
Aggregate(デフォルトで解決済み)
$ aggrega inspect ./fullstack-app.yaml
Aggregate: fullstack-app:1.0.0
Components: backend (type: core/compute/api-server) Values: (none) Uses: databases: - data.main-db frontend (type: core/compute/web-ui) Values: (none) Uses: apis: - my-api → backend main-db (type: core/datastore/postgres) Values: database_name: app_production Uses: (none)
Dependency Graph: data.main-db ↑ backend backend ↑ frontendデフォルトのビューはトポロジーを構築し、各コンポーネントをその値と uses エッジとともに表示し、続いて算出された依存グラフを表示します。サブシステムのツリーは入れ子で表示されます。--flat はノードごとに 1 つのセクションを表示し、それぞれをドット区切りの完全なパスでキー付けします。
長い形式で記述された接続の後には、その接続が運ぶアタッチメントが続きます。各アタッチメントは、消費側コンポーネント上での名前(接続のエイリアスとスロットをドットで結合したもの)の下に、指定する Feature の型と、埋めるスロットおよび宣言済みの機密情報を扱うかどうかを示す句とともに表示されます。
gateway (type: conn/gateway) Values: region: eu Uses: models: - gpt → model - gpt.credential (feature.conn/token) [slot: credential, sensitive]スロットとマークは、この Aggregate をデプロイする Release のビルドがそのアタッチメントについて記録する事実であり、Release のビューと同じ方法で読み取られます(アタッチメントの接続、スロット、機密性の句を参照)。これらはソケットのスロット宣言と Feature 自身の宣言から得られるため、どの Release が Aggregate をデプロイするかには依存しません。Aggregate は Manifest を指定しないため、Release の Manifest がアタッチメントに対して選ぶ実現方法はここには表示されません。このビューはコンポーネントの接続とそれが運ぶものを一覧表示します。コンポーネント自身のブロックのアタッチメントは Release のビューに表示されます。
Release(デフォルトで解決済み)
Release のビューは最も重要度の高いインスペクションです。完全なパイプラインを実行し、境界ごとに、すべての Component ノード、その uses エッジ、そのノードにアタッチされたすべての Feature(接続上に記述されたものはその接続のエッジの下)を表示します。それぞれに、埋めるアタッチメントスロット、宣言済みの機密情報を扱うかどうか、それを実現する FeatureRecipe、さらにアタッチメントの由来を示すプロベナンスブラケットが付きます。
$ aggrega inspect ./prod-release.yaml --catalog ./catalog
Release: prod-release:1.0.0
Boundary: backend-ns Directory: ./dist/backend Annotations (provider-consumed): aggrega.ai/namespace: backend-zone Component: backend (type: core/compute/api-server:1.0.0) Uses: data.main-db → data.main-db [cross-boundary] Features: (none)
Boundary: frontend-ns Directory: ./dist/frontend Annotations (provider-consumed): aggrega.ai/namespace: frontend-zone Component: frontend (type: core/compute/web-ui:1.0.0) Uses: my-api → backend [cross-boundary] Features: - cross-namespace-routing (core/k8s-dns-resolver:1.0.0) [free, realization: k8s-dns-patcher:1.0.0] [explicit]
Boundary: data-ns Directory: ./dist/data Annotations (provider-consumed): aggrega.ai/namespace: database-zone Component: data.main-db (type: core/datastore/postgres:1.0.0) Features: (none)各境界には、出力ディレクトリとプロバイダーが消費するアノテーションが付きます。境界の下の各コンポーネントには、Aggregate のコンポーネント型、uses エッジ(境界をまたぐエッジにはマーク付き)とそれぞれに続くその接続が運ぶアタッチメント、そして自身の Feature アタッチメントが付き、すべてのアタッチメントに事実の句とプロベナンスブラケットが付きます。--flat は境界のツリーを、完全なパスでキー付けした境界ごとに 1 つのセクションにまとめます。--raw はパイプラインを実行せず、Release ファイルをそのまま出力します。
YAML 出力
$ aggrega inspect core/server:1.0.0 --output yaml --catalog ./catalog
apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: core/server version: 1.0.0 labels: component.aggrega.ai/type: serverspec: usesSchema: db: selector: component.aggrega.ai/type=stateful-server schema: values: port: {type: integer, default: 8080}カタログから名前で指定された Component は、カタログが解決したエンティティとして出力されます。そのため extends: によるマージの後は、作成されたファイルではなくマージ後のエンティティが表示されます。Component のファイルは作成されたとおりに出力されます。
機械可読な出力
機械可読な出力を生成するフラグは 2 つあり、それぞれ異なる問いに答えます。--output は、このコマンドがもともとレンダリングするドキュメントの形式を選びます。--ir-graph は、それに加えて別のドキュメント、つまり Release が解決されるコンパイル済みグラフを要求します。両者は独立しており、両方を渡すと、グラフと記述どおりの YAML がそれぞれ 1 回ずつ得られます。
--output yaml はエンティティを記述どおりに出力し、パイプ処理や差分比較に適しています。この出力は記述内容そのままであり、作成者が機密と宣言した値も含まれます。入力を再現すると称する出力が、その一部を伏せたまま再現であり続けることはできません。この出力は、元となったエンティティファイルと同じように扱って、パイプ処理、保存、共有してください。
コンパイル済みグラフ: --ir-graph
aggrega inspect <release> --ir-graph は、実行時に解決されたグラフを JSON として標準出力に書き出し、その後にコマンドが通常どおりレンダリングするビューが続きます。JSON ドキュメントは 1 つで、末尾に改行が 1 つ付くため、ストリームをデコードするコンシューマはグラフを読み取った時点で停止します。
このフラグは Release に適用されます。グラフに解決される種類は Release だけだからです。それ以外の種類や、名前で指定したカタログエンティティに対して要求した場合、コマンドはそのエンティティ自身のビューをレンダリングして要求を黙って無視するのではなく、拒否してその旨を伝えます。
コンパイラのチェックで却下される構成からはグラフは生成されません。エラー時の動作で説明する拒否は、このストリームに何かが書き込まれる前に行われます。そのため、このストリームを読むパイプラインが、同じドキュメントのビルドで拒否されるはずのグラフを受け取ることはありません。受け取るのは、ビルドが報告するのと同じ検出結果と、ゼロ以外の終了コードです。
同じフラグが同じ意味で aggrega build と aggrega validate にもあります。いずれも、そのコマンドが生成する他の出力に加えて、その実行で計算したグラフを返します。エディタ統合は、デーモンのプロトコル経由で同じグラフを読み取ります。
**--output yaml はグラフを出力しません。**他のすべての種類と同様に、記述された Release をそのまま再現します。グラフが必要なパイプラインは代わりに --ir-graph から読み取り、YAML ではなく JSON を受け取ります。
**グラフは値を伏せます。**グラフは誰かが書いたファイルではなく、Aggregate、Release、カタログからコンパイルが計算したものです。そのため、守るべき「記述どおり」という取り決めはなく、読みやすいレイアウトを支配するのと同じ宣言がグラフにも適用されます。作成者が機密と宣言したリーフをグラフが含む箇所では、その値は、伏せられたことを示す単一キーのオブジェクトに置き換えられます。
"values": { "secretName": "db-creds", "vault": { "token": { "aggrega_withheld": "declared" } }}キーは残るため、ノードとそのアタッチメントがどのリーフを持つかはグラフから引き続き分かります。失われるのは値だけです。同じペイロード内の宣言されていない兄弟要素は記述どおりに出力されます。上の secretName は作成者が宣言しなかった公開のロケータであり、出力されます。マーカーに付く理由は、値がない理由を示します。declared は宣言の対象となるリーフの場合、unreadable はこのコマンドが読み取れない形でペイロードが届いた場合で、後者ではペイロードの一部を推測するのではなく、ペイロード全体が伏せられます。
接続自身の設定も同じように伏せられます。Aggregate が uses エントリーに記述する接続ごとの values と、Release がそこに記述する接続ごとの infra は、消費側コンポーネントのソケット、つまりそのソケットが宣言する valueSchema と infraSchema(その設定の検証に使われるコントラクト)が支配し、ターゲットの宣言が支配することはありません。いずれかのコントラクトが sensitive: true と宣言したリーフは、エッジの values と infra の中、および作成者が記述したとおりの値を持つ消費側ノードの uses エントリーの中で、マーカーに置き換えられます。各エッジは、伏せたリーフを sensitive_payload_leaves の下に列挙します。これはノードが自身のリーフに使うのと同じフィールドです。ソケットがそれを読み取り可能と宣言している接続上の同名のリーフは、記述されたとおりに出力されます。
パイプラインが本当に値を必要とする場合は --unredacted を渡し、その出力はエンティティファイルそのものと同じように扱ってください。aggrega build と aggrega validate も --ir-graph と併せて同じフラグを同じ条件で受け付けます。このフラグを渡さない限り、返されるグラフは値を伏せます。
デーモンのプロトコルも同じ規則で同じグラフを提供します。aggrega/irGraph はこれらの値を伏せて応答し、unredacted フィールド(このフラグのプロトコル上の表記)を設定したリクエストに対してのみ値を平文で返します。そのため、エディタのパネルが描画する内容も同じ宣言に従い、値を表示するクライアントは、それを要求したからこそ表示しています。
依存クロージャ: --closure
aggrega inspect <release> --closure は、Release の依存クロージャを報告します。つまり、その Release が到達するすべてのカタログエンティティとそれぞれが解決されたバージョン、さらに 2 つのポインタが解決された Aggregate と Manifest の識別情報、およびそれらのエンティティが参照する共有ドキュメントです。何もレンダリングされず、成果物も生成されません。クロージャはビルドされるのではなく解決されるため、それに答えるためにプロバイダがロードされることはありません。
クロージャと解決済みビューは別のドキュメントであり、どちらからももう一方を復元することはできません。 解決済みビュー(このコマンドが Release に対してデフォルトでレンダリングするもの)は、デプロイメントがどのような姿かを示します。つまり、その境界、コンポーネントノード、何が何に接続されているか、各ノードに何がアタッチされているかです。クロージャは、それをビルドするために何がどのバージョンで取り込まれたかを示します。エンティティは一度もノードとして現れずに到達されることがあります。Manifest があるコンポーネントタイプをマッピングする先の Recipe は、すべてのビルドで到達されますが、どのビルドでもノードにはなりません。また、ノードは宣言されたコンポーネントタイプを記録し、そのタイプが解決されたバージョンは記録しません。したがって、「なぜこのバージョンが変わったのか」「この共有ドキュメントを変更すると何に影響するのか」「このデプロイメントは実際に何に依存しているのか」を問う読者が求めているのはクロージャであり、解決済みビューを手にしている読者は、それをいくら丹念に読んでもクロージャを得ることはできません。
同じ言葉は、どの入り口でも同じドキュメントを求めます。 ここでの --closure、デーモンのプロトコル上の aggrega/releaseClosure(aggrega serve の「クロージャはグラフではない」を参照)、アシスタントツールプロトコル上の describe ツールの release モードは、いずれも Release についてのこの問いに答えます。どれに対しても Release 名は同じ解決に到達するため、3 つが Release の依存先について食い違うことはありません。Release の解決結果ともはや一致しないロックファイルに対しては、このコマンドと describe ツールはビルドのドリフト停止で拒否します。一方、編集中のエディターに応えるデーモンは応答を返します。
これは 1 つのドキュメントなので、単独で要求します。 --closure は解決済みビューの代わりにクロージャを選択し、--raw、--resolved、--output、--ir-graph とは組み合わせられません。これらはそれぞれ同じ Release について別のドキュメントを求めるものであり、2 つの要求を受け付けるコマンドは、そのうち一方に黙って答えるしかなくなるためです。組み合わせた場合は、その組を示したうえで拒否されます。
これは Release にのみ適用され、それ以外には適用されません。 カタログエンティティ、Aggregate ファイル、Manifest はいずれもクロージャを解決しないため、その対象自身のビューをレンダリングして要求を捨てるのではなく、要求は拒否されます。捨てられた要求は、呼び出し側にはクロージャが空の対象とまったく同じに見えてしまいます。
それぞれの結果は区別されます。 解決できる Release には一覧で応答します。ファイルを指していない Release パスは、ファイルが存在しないことを示して拒否されます。存在するもののクロージャを解決できない Release は、何を解決できなかったか、その参照がどこから来たかを示し、続いてカタログのロードで拒否されたファイルを挙げて拒否されます。拒否されたファイルは、Release が到達するエンティティが見つからなくなる通常の原因だからです。Release の隣にあるプラグイン信頼記録が存在するものの読み取れない場合は、何を読み取れなかったかを示して拒否されます。それを読み飛ばした一覧は、何もチェックできなかったところで、撤回されたプラグインはないと報告することになるためです。ロックファイルがその解決結果ともはや一致しない Release は、エラー時の動作で説明するとおり、ビルドが出力するドリフト停止とともに拒否されます。一覧に挙がるバージョンは、その Release のどのビルドも使わないものになるためです。いずれに対しても空の一覧が答えになることはありません。それでは、打ち間違えたパスや壊れたワークスペースを、何にも依存しない Release として報告することになるためです。
3 つの詳細レベルは、他のすべての種類と同様に適用されます。--list は参照のみを 1 行に 1 つずつ出力し、パイプ処理に使えます。デフォルトでは、解決された識別情報、各参照が解決されたバージョン、参照された共有ドキュメント、マッピング先がマッピングされたタイプを実装していない Manifest マッピング、および Release が依存するものに対して記録された非推奨化や撤回の通知(ロックファイル内でピン留めされた参照に対して記録されたもの、およびその隣にあるプラグイン信頼記録内で、受理または拒否の判定を返すロールでアタッチされたプラグインに対して記録されたもの)が、aggrega build が同じマーカーについて出力するのと同じ文言で加わります。--detail は、参照箇所が種類を記録している場合に各参照の種類を加えます。ドキュメント内の位置には、指す対象の種類を示すものとそうでないものがあるため、種類は名前の形から推測するのではなく、判明している場合に報告されます。
$ aggrega inspect ./release.yaml --catalog ./catalog --closure
Release: prod-release:1.0.0 Aggregate: fullstack-app Manifest: prod-manifest Environment: production
Entities (11): ./aggregate.yaml ./manifest.yaml core/compute/api-server (1.0.0) core/compute/web-ui (1.0.0) core/datastore/postgres (1.0.0) core/k8s-dns-resolver (1.0.0) db-module (1.0.0) helm-api-server-synthesized-with-artifacts:1.0.0 (1.0.0) helm-postgres-synthesized-with-artifacts:1.0.0 (1.0.0) helm-web-ui-synthesized-with-artifacts:1.0.0 (1.0.0) k8s-dns-patcher:1.0.0 (1.0.0)ワークスペースが Release の解決先バージョンを記録している場合、その記録が解決の起点となるため、報告されるバージョンは、カタログがたまたま現在保持しているものではなく、このデプロイメントが実際にビルドされているものになります。そのような記録のないワークスペースでは、現状のカタログに対して解決されます。
アタッチメントの接続、スロット、機密性の句
Release ビューの各 Feature アタッチメントには、コンパイラがアタッチメント自体について記録する事実を示す句が付きます。どのアタッチメントスロットを埋めるか、宣言済みの機密情報を扱うかどうか、そしてそれを実現する FeatureRecipe です。さらに、コンポーネントの接続の 1 つに記述されたアタッチメントについては、記述された接続も示します。この句はアタッチメント名とその来歴ブラケットの間に置かれ、以下の両方の来歴形式で同じように表示されます。
接続に記述されたアタッチメントは、Features: の下ではなく、Uses: 内のその接続の行の下に一覧表示されます。そのため Features: にはコンポーネント自身のアタッチメントだけが含まれます。その上の行は接続をエイリアスと到達先のコンポーネントで示し、残りはアタッチメント自身の句が示します。
[socket: <socket>]— 接続が配線されるソケットで、接続の行には示されません。後続の読み方を変えるため、句の先頭に置かれます。続くスロット部分は、コンポーネントが自身のアタッチメント用に宣言するスロットではなく、接続のソケットが宣言するスロットを示します。[connection: <alias> through socket <socket>]—Uses:ブロックに行が表示されない接続を持つアタッチメントについての同じ事実です。このアタッチメントはFeatures:の下に一覧表示され、ここで接続を示します。いずれの場合も、接続はアタッチメントごとに一度だけ示され、二度示されることはありません。[slot: <name>]— アタッチメントが<name>というスロットを埋めます。スロットは、そのスロット自身の名前で Feature をアタッチすることで埋められます。そのため<name>はアタッチメントが記述された名前であり、宣言済みのスロットと照合されます。自身のアタッチメントであればホスト Component のfeaturesSchema、接続に記述されたアタッチメントであれば接続のソケットが宣言するfeaturesSchemaと照合されます。[free]— アタッチメントはどの宣言済みスロットも埋めません。解決された Component がその名前のfeaturesSchemaスロットを宣言していません。これは所見であり、診断ではありません。自由形式のアタッチメントは受け入れられます。これを禁止したいオペレーターは、ツールによる拒否に頼るのではなく、ガバナンスポリシーとして表現します。[sensitive]— アタッチメントは、作成者が機密と宣言した情報を扱います。アタッチされた Feature が機密リーフを宣言しているか、埋めるスロットがsensitive: trueを宣言しているか、またはその両方によります。[realization: <name>:<version>]— Release の Manifest がこのアタッチメントにバインドする FeatureRecipe です。Manifest がアタッチメント自身の名前をマップしている場合はその名前(接続に記述されたアタッチメントでは、エイリアスとスロットをドットで連結したもの)により、そうでない場合は Feature 型によります。これは同じドキュメントのビルドがアタッチメントのレンダリングに使う実現であり、コンパイル済みグラフがアタッチメント上にrealizationとして持つ値と同じです(--ir-graphを参照)。そのため、このビューとグラフが異なるものを示すことはありません。句の最後に置かれます。
複数の事実が当てはまる場合は 1 つの句にまとめられます。core/storage/s3-object-store は sensitive: true が付いた secret_access_key スロットを宣言しているため、その名前でアタッチされた認証情報は両方の事実を報告します。一方、Component がスロットを宣言していない名前でアタッチされた Feature は、スロットも機密性も報告しません。各 Feature 型を FeatureRecipe にマップする Manifest を使うと、各行は実現も示します。
Features: - secret_access_key (core/generated-secret:1.0.0) [slot: secret_access_key, sensitive, realization: generated-secret:1.0.0] [explicit] - cross-namespace-routing (core/k8s-dns-resolver:1.0.0) [free, realization: k8s-dns-patcher:1.0.0] [explicit]models ソケットが sensitive: true 付きの credential スロットを宣言し、それを埋める接続をエイリアス gpt で配線するコンポーネントは、そのアタッチメントを接続の下に一覧表示します。コンポーネント自身の認証情報は Features: の下に残ります。
Uses: gpt → model - gpt.credential (feature.conn/token:1.0.0) [socket: models, slot: credential, sensitive, realization: conn-token-compose:1.0.0] [explicit] Features: - db_password (feature.conn/token:1.0.0) [slot: db_password, sensitive, realization: conn-token-compose:1.0.0] [explicit]接続に記述されたアタッチメントが [free] を報告することはありません。ソケットは宣言したスロットのみを受け入れ、それ以外の名前を持つ接続はビルドの読み込み時に拒否されます。
どの事実も当てはまらない場合、句は完全に省略されます。また、各部分は個別に省略されます。
- ソケットまたは接続の部分がない場合、アタッチメントはコンポーネント自身のブロックに記述されたか、より広いスコープから、またはアノテーション駆動の展開によって到達したことを意味します。
- スロット部分がない場合、ホスト Component の宣言済みスロットの集合を解決できなかったことを意味します。たとえば、その型がどのカタログエンティティにも一致しない場合です。これは意図的に
[free]と区別されています。[free]は「その名前のスロットは宣言されていない」という答えですが、部分がないことは、その問いにまったく答えられなかったことを意味します。 sensitiveがないことは、どの宣言もアタッチメントに印を付けなかったことを記録します。これはアタッチメントが秘密を何も含まないという判定よりも狭い意味です。この軸は宣言を報告するものであり、フィールドの名前や値から推測されるものは何もありません。- 実現の部分がない場合、Manifest がアタッチメントをカタログ内のどの FeatureRecipe にもバインドしていないことを意味します。
宣言名が文字どおり free であるスロットも [free] と表示され、自由形式のアタッチメントと区別できません。スロット名前空間に対してこの語を予約する仕組みはありません。
IR の来歴ブラケットの文法
Release ビューの各 Feature アタッチメントには来歴ブラケットが付きます。ブラケットはコンパクト形式(アタッチメントの来歴がすべてのリーフで一様な場合に Feature ごとに 1 つのブラケット)またはリーフごとの形式(アタッチメントのリーフが異なるソースに由来する場合にリーフごとに 1 つのブラケット)をとります。ブラケットの本体は 3 種類あり、どちらの形式にも同じように適用されます。
3 種類のブラケット本体
-
[explicit]— Feature アタッチメントは作成者が宣言したものです。Aggregate または Release が、対象のノードでその Feature を明示的に指定しています。明示的なアタッチメントは最も優先度の高いソースであり、同じリーフにおいてアノテーション駆動の寄与に常に優先します。 -
[annotation: <key> from <source>]— Feature アタッチメントはアノテーション駆動です。<source>上のアノテーションが、この Feature を宣言する Manifest のバインディングに一致したため、コンパイラがアタッチメントを合成しました。<key>はバインディングを発火させたアノテーションキー(例:business.aggrega.ai/team)で、<source>はそのアノテーションを持っていたエンティティ(aggregate、release、component、またはmanifest)です。合成されたアタッチメントは構造的に明示的なものと同一であり、下流のレンダリングは両者を同じように扱いますが、デバッグで判別できるように来歴ブラケットが両者を区別します。 -
[explicit; overrides annotation: <key> from <source>]— あるリーフにおける作成者による明示的な宣言が、本来なら同じリーフを設定していたはずのアノテーションによる寄与を抑制している場合に現れる、リーフごとの形式です。このケースはサイドをまたいだ合成で生じます。たとえば Aggregate のアノテーションが Feature のvalues:ピラーを、Release のアノテーションがそのinfra:ピラーを供給し、同じ Feature に対する Release の明示的な宣言が infra のリーフの 1 つを上書きする場合です。リーフのブラケットには、明示的な作成者と抑制されたアノテーションの両方が記録されます。抑制されたアノテーションはレンダリング出力には寄与しませんが、どのアノテーションがどこで上書きされたかをオペレーターが確認できるよう、inspect ビューにはその存在が表示されます。
コンパクト形式とリーフごとの形式
コンパイラは、アタッチメントのリーフごとの来歴をたどって一様性を確認することで、コンパクト形式とリーフごとの形式のどちらでレンダリングするかを選びます。アタッチメントの来歴が一様であるとは、値が設定されたすべてのリーフ(Feature の values: と infra: の両ピラーにわたる)が同じ起源(明示的かアノテーションか)、アノテーション駆動の場合は同じアノテーションキー、同じソースエンティティを共有し、かつ「overrides annotation」マーカーを持つリーフが 1 つもない場合を指します。来歴が一様な場合、コンパイラはアタッチメントごとに 1 つのブラケットを出力します。
- core/rate-limiter [annotation: business.aggrega.ai/team from aggregate]来歴が分岐する場合(典型的なのは、同じ Feature に対して Aggregate のアノテーションが values: を、Release のアノテーションが infra: を供給する、サイドをまたいだ合成です)、コンパイラは値が設定されたリーフごとに 1 つのブラケットを出力します。
- core/pii-redaction values.fields_to_mask: ["ssn", "card_number"] [annotation: compliance.aggrega.ai/data-class from aggregate] values.classifier_endpoint: "redact-v2" [explicit; overrides annotation: compliance.aggrega.ai/data-class from aggregate] infra.audit_bucket: "s3://..." [annotation: compliance.aggrega.ai/audit-bucket from release]たどる順序は、まず values ピラー(作成者の記述順)、次に infra ピラー(同じ規律)です。ピラーのプレフィックス(values. / infra.)とピラー内のドット区切りのパスによって、各ブラケットがどのリーフに注釈を付けているかが正確に特定されます。
機密として宣言された値
スキーマが sensitive: true を宣言しているリーフは、値の代わりに固定テキスト <redacted> を出力します。キー、ピラーのプレフィックス、来歴ブラケットはすべて保持され、置き換えられるのは値だけです。そのため、レイアウトからは引き続き、エンティティがどのリーフを持ち、それぞれがどこから来たかがわかります。影響を受ける可読な出力面は 2 つあります。Aggregate のノードごとの Values: ブロックと、解決済み Release のリーフごとのアタッチメントブロックです。後者には接続に記述され、その接続の行の下に出力されるアタッチメントも含まれ、これは同じ Feature をコンポーネント自身が保持する場合に秘匿されるリーフとまったく同じリーフを秘匿します。--ir-graph での Release のコンパイル済みグラフは、機械可読な出力で説明する構造化形式で同じリーフを秘匿します。
Components: app (type: core/app) Values: appName: demo dbPassword: <redacted> tuning.poolSize: 25 tuning.adminToken: <redacted>秘匿されるのは宣言されたリーフだけであり、アタッチメントレベルの [sensitive] 句は秘匿の指示ではありません。この句は、アタッチメントが秘密情報を扱うことを示すものであり、どのリーフがそれを持つかを示すものではありません。認証情報 Feature の公開ロケーター(リソース名とデータキー)は公開情報であり、標準ライブラリのカタログでは意図的に宣言されていません。そのため、秘匿される情報の横に平文で出力されます。
- credentials (feature.test/db-credential) values.secretName: db-creds [explicit] values.literalPassword: <redacted> [annotation: feature.test/pw from aggregate.yaml:components.app.annotations.feature.test/pw]フィールド名から推論されることはありません。宣言のない password という名前のフィールドは値を出力し、宣言された key という名前のフィールドは出力しません。秘匿はツールが出力するものを対象とし、レンダリングされた成果物には及びません。dist/ はレンダリングが生成したとおりに出力されます。キーワードと、それを宣言することで達成できることの上限の全体は、vocabulary/compact-form-authoring.md の「Declaring a leaf sensitive」にあります。
秘匿された値を表示する
--unredacted は、機密として宣言された値を秘匿せずに出力します。これはすべての inspect の出力面に一度に適用され、上記の可読なレイアウトにも Release のコンパイル済みグラフにも同様に適用されます。このフラグが存在するのは、秘匿された値そのものが調査対象になる場合があるためです。誤ったアタッチメントから届いた認証情報は、両方が秘匿として表示されると正しいものと見分けがつきません。
このフラグの効果は、渡されたコマンドに限定されます。aggrega build と aggrega validate もこのフラグを受け付けますが、その場合は --ir-graph が返すグラフにのみ適用され、それ以外には及びません。また、グラフが要求されていない場合はこのフラグを拒否します。aggrega build --trace-unredacted はビルドのトレースファイルに対する同じ考え方であり、ビルドの 2 つのフラグはいずれも互いの出力には及びません。dist/ 以下のレンダリングされた成果物はこれらのいずれの影響も受けません。何が渡されても、レンダリングが生成したとおりに出力されるためです。
その場合、出力が届く先(ターミナル、パイプ、ファイル、画面録画、貼り付けられたバグレポート)には、それらの値が平文で含まれます。秘匿なしで取得されたことを示すヘッダーでそれぞれ始まるトレースファイルとは異なり、ターミナルへの出力にはそのような表示はありません。フラグが渡されたことを示すのはコマンドラインだけです。
inspect を使う場面
- 「なぜこの Feature がここにあるのか」のデバッグ — アノテーション駆動のアタッチメントは Aggregate や Release の YAML ファイルには現れません(アノテーションはありますが、それらが合成する Feature アタッチメントは IR の中にしか存在しません)。inspect はそれらを出所とともに表示します。
- スキーマ継承の検証 —
aggrega inspect <ComponentName>はextends:チェーンの解決後にマージされたスキーマを表示します。作成されたファイルだけでは、ローカルの差分しかわかりません。 - サイドをまたぐ合成の予期しない結果の診断 — Aggregate のアノテーションと Release のアノテーションの両方が同じ Feature にピラーのペイロードを与える場合、解決されたリーフを頭の中で再構成するのは難しいことがあります。リーフごとのブラケット形式は、その解決を明示します。
- デプロイ前の検証チェック —
aggrega inspect ./prod-release.yamlは、aggrega buildがアーティファクトを生成する前に、すべての Component 上のすべての Feature を一覧表示します。オペレーターは、レンダリングされたマニフェストを GitOps にコミットする前に、トポロジーが意図どおりであることを確認できます。
根底にある仕組み — アノテーションがどのようにカスケードするか、サイド対ピラーの区分がアノテーションの値をどのように Feature のピラーへ振り分けるか、明示的なアタッチメントが優先されるという規律がアノテーション駆動の寄与とどのように相互作用するか — については、providers/well-known-annotations.md と entities/manifest.md の「Annotation-Driven Feature Bindings」を参照してください。
概要
aggrega inspect [identifier] [flags]説明
Render a readable view of any Aggrega entity — a catalog entity by name, anauthored entity file by path, an entity published in a registry, or afully-resolved Release.
It answers "what does this entity actually resolve to?": which entities extendwhich bases, which Recipe maps to each type, which Features attach to each node,and where each Feature's contributions came from.
A single argument routes by its shape. A path — anything starting with ./, ../or /, or ending in .yaml or .yml — is read as a file and inspected by its ownkind: header. A registry reference — oci://<host>/<repository>:<tag>, or@<digest> in place of :<tag> — is read from the registry that publishes it.Anything else is looked up by name in the catalog search stack: theworkspace's own, or, with --release, the one the workspace configurationgives that Release, so a name several catalog variants declare, one perRelease, resolves to the variant that Release builds with.
A registry reference shows the entity exactly as it was published: unpackedfrom the archive its kind is published as where it is one, and rendered by thesame view a file of that kind gets. Reading it reaches the network, using thecredentials this machine holds for that registry, and an offline workspacerefuses it. The fetched bytes are checked against the digest the artifact'sown manifest records for them, which establishes that they are the bytes thatmanifest names and nothing more: no signature attached to the artifact isverified, no withdrawal recorded against it is reported, and nothing iswritten — no cache entry and no lockfile.
Three verbosity levels apply to every kind: --list for identifiers only, thedefault for a structured overview, and --detail for full field bodies. --listand --detail are mutually exclusive. Resolution depth has its own pair, --rawfor the entity exactly as authored and --resolved for the kind's full depth,also mutually exclusive.
Note that --raw reproduces the file as written, so a value the author declaredsensitive appears as authored. That is what as-authored means; handle suchoutput as you would the entity file itself. --output yaml reproduces the filethe same way for every kind, a Release included.
A Release answers two further questions, and each has its own flag becauseneither answer contains the other. --ir-graph asks for the IR graph a Releaseresolves to — what the Release looks like, as JSON on stdout in addition towhatever else this command produces. --closure asks for the Release's dependencyclosure — every catalog entity it reaches and the version each resolved to,which is what was pulled in to build the Release. An entity can be reachedwithout appearing as a node, and a node does not carry the version its typeresolved to, so holding one of the two is not holding the other.
--ir-graph is orthogonal to --output, which picks the format of the command'sown view. Values an author declared sensitive are withheld from the graph, asthey are from the readable layouts. Pass --unredacted to print them instead.フラグ
| フラグ | デフォルト | 説明 |
|---|---|---|
--catalog | [] | カタログディレクトリです。複数回指定できます。各 —catalog <dir> はカタログ検索スタックの先頭に追加されます(最初に一致したものが優先されます)。スタックはワークスペースの catalog_dirs、またはワークスペース設定が workspace.releases の下で独自のディレクトリを与えている Release の場合はその Release のディレクトリで構成され、ワークスペースルートに catalog という名前のディレクトリがある場合はそれで終わります。空として書かれた catalog_dirs リストは、ローカルカタログをまったく読み込みません。 |
--closure | false | 解決済みノードのビューの代わりに、Release の依存クロージャ — それが到達するすべてのカタログエンティティと、それぞれが解決されたバージョン — を報告します。クロージャを解決する唯一の種類である Release に適用されます。それ以外の種類は、要求を黙って無視するのではなく拒否します。 |
--color | auto | 出力に色を付けます:auto|always|never。 |
--detail | false | フィールドの本体を完全に表示します。 |
--flat | false | ツリー状のエンティティ(Aggregate、Release)をフラットなリストとして表示し、各ノードの先頭に完全なドット区切りのパスを付けます。表形式の種類には影響しません。 |
--ir-graph | false | このコマンドがすでに出力するすべてに加えて、この実行で計算された IR グラフを JSON として stdout にも書き出します。作成者が sensitive と宣言した値はそこから秘匿されます。代わりに表示するには —unredacted を渡します。グラフに解決される唯一の種類である Release に適用されます。それ以外の種類は、要求を黙って無視するのではなく拒否します |
--list | false | 識別子のみを表示します。 |
--no-color | false | 色付き出力を無効にします(—color=never のエイリアス)。 |
--output, -o | text | 出力形式:text|yaml。 |
--plugin | — | 生の <file.wasm> アーティファクトへのファイルシステムパスです。aggrega plugin sync がそれらを Plugin エンティティに記録する前に、そのアーティファクトがインポートするホスト関数を導出して表示します。識別子の引数は取りません。 |
--raw | false | エンティティを解決せずに、作成されたとおりに表示します。 |
--release | — | この Release ファイルの条件でカタログ名を検索します。ワークスペース設定がその Release に与えるカタログディレクトリを使い、その先頭に —catalog を追加します。名前に適用されます。ファイルやレジストリ参照はそのまま inspect され、このフラグを拒否します。相対パスは、ワークスペースルートではなく、コマンドを実行したディレクトリを基準に解決されます。そのディレクトリがどのワークスペースにも属さず、ルートも指定されていない場合、絶対パスは Release 自身のフォルダからワークスペースを見つけます |
--resolved | false | エンティティを完全に解決して表示します。 |
--show-implements | false | Recipe または FeatureRecipe の場合、spec.implements をカタログに対して解決し、バインドされた Component または Feature を表示します。 |
--unredacted | false | 作成者が sensitive と宣言した値を、秘匿せずに表示します。その場合、出力が到達するもの — ターミナル、パイプ、ファイル、画面録画 — はすべて、それらの値を平文で含みます。 |