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

ラベルとアノテーション

Aggrega のエンティティは、構造的によく似た 2 つのメタデータの仕組み metadata.labels と metadata.annotations を持ち、さらに境界のカスケードと feature のアタッチの各サーフェスにアノテーションを持つフィールドが散在しています。6 つの異なるサーフェスがアノテーションやラベルの内容を記述または保持しており、それぞれカスケードの規則、利用者、プレフィックスの慣例が異なります。このページでは、これらのサーフェスを 1 か所にまとめて説明し、ランタイムのテンプレートコンテキストが公開する 3 つのセマンティックなバケットを定義し、作成者が従うべきプレフィックスの規律を示し、さらに 5 つの Feature アタッチのサーフェスを並べて説明することで、より広いラベル/アノテーションの語彙とあわせて把握できるようにします。

アノテーションとラベルを持つ 6 つの画面

作成者は、6 つの異なる画面でラベルとアノテーションに出会います。それぞれ適用範囲、カスケード規則、利用者が異なります。

#画面適用範囲カスケード規則主な利用者
1カタログエンティティの metadata.labelsエンティティごとの識別情報(Component、Feature、Aggregate)インスタンスにはカスケードせず、カタログエンティティ自体に保持されますComponents と Features については aggrega search -l。Aggregate のラベルはそのドキュメントに保持され、それを読み取るコマンドはありません
2Component の metadata.labels(固有)Component インスタンスごとのプロパティ(component.aggrega.ai/type など)label-transform による変更の後、IR のノードごとの .context.labels にカスケードしますセレクタのマッチング(usesSchema の selector: 宣言。合成された JSON Schema では x-aggrega-selector: として保持されます)、Recipe テンプレートのロジック
3Component の metadata.annotationsArchitect が作成する、Component インスタンスごとの特性IR のノードごとの .context.annotations.catalog バケットにカスケードしますガバナンス判定ロール(固有特性のポリシー)、Recipe テンプレートのロジック
4Aggregate / Subsystem の annotations:Aggregate 側の認知的メタデータIR のノードごとの .context.annotations.aggregate バケットにカスケードします認知的ルーティングのための Recipe の valuesMapping:
5Release 境界の annotations:Ops 側の物理的メタデータ(aggrega.ai/* の既知アノテーションを含む)IR のノードごとの .context.annotations.release バケットにカスケードしますProviders(helm は aggrega.ai/namespace を読み取り、compose は同じキーからネットワーク名を導出します)、境界をまたぐルーティングのための FeatureRecipe の injectMapping:
6Manifest の features.annotations バインディングアノテーション駆動の Feature アタッチメントのための、ピラー単位でグループ化されたサブキールーティング(maps.infra / maps.values)を伴う、アノテーションキーから Feature タイプへのバインディング解決処理のアノテーション展開サブフェーズが、Release 境界(外側から内側へ)と Aggregate サブシステム(外側から内側へ)を走査します。コンポーネントごとのオーバーライドと、値全体 / サブキーごとの null によるオプトアウトが適用されます。サイドとピラーの対応チェックにより、作成側ごとにどのピラーが発火するかが制御されますアノテーション駆動の Feature 展開(合成された Feature アタッチメント。IR グラフに origin: annotation として記録されます)

画面 4 と 5 は同じ YAML の形(カスケードする境界にある annotations: マップ)を共有しますが、それぞれ別の IR バケットにカスケードします。このバケットの区別が、ランタイムが公開する要となる規則です。画面 6 は構造的に別物です。Aggregate / Release の内容ではなく Manifest エンティティ上に存在し、その利用はアノテーション駆動の展開パスによって制御されます。

3 つのバケットからなる .context.annotations.* のセマンティクス

レンダラーが Recipe テンプレートを評価するとき、ノードごとの .context.annotations フィールドには名前付きのバケットが 3 つ含まれます。各バケットはアノテーション名をキーとするフラットな string → string マップであり、バケットによって、そのアノテーションを誰が記述したか、またその意図が何であるかが決まります。

  • .context.annotations.release — Release 境界のアノテーション(画面 5)。物理的な実態を管理するために使われ、レンダラーは必要に応じてこれらを infra: フィールドに振り分けます。aggrega.ai/* の既知のアノテーションはこのバケットに置かれます。
  • .context.annotations.catalog — Component メタデータのアノテーション(画面 3)。Architect が記述する不変の固有特性であり、主に Wasm ポリシープラグインが利用します。
  • .context.annotations.aggregate — Aggregate サブシステムのアノテーション(画面 4)。認知的メタデータであり、レンダラーは必要に応じてこれらを values: ペイロードに振り分けます。

3 つのバケットの分離は社会契約です

コンパイラはバケットの境界を強制しません。3 つのバケットは同じフラットな string → string の形をしており、Recipe のテンプレートは 3 つすべてを読み取れます。Release 境界のアノテーションが認知的メタデータのフィールドとして解釈されることも、カタログのアノテーションが infra: に振り分けられることも、妨げるものはありません。この分離は記述上の規律であり、コンパイラによる保証ではありません。

規律の目標、つまり各バケットが表現することを意図している内容は次のとおりです。

  • release = 「このコンポーネントがどこで実行されるか。Ops が管理する」
  • catalog = 「このコンポーネントが何であるか。Architect が記述する」
  • aggregate = 「このコンポーネントが何をするか。Developer が記述する」

作成者が分離を守れば、下流のツールは適切な関心事に対して適切なバケットを読み取れます。作成者が分離に反した場合(たとえば Release ファイルが便利だからという理由で認知的メタデータを release アノテーションに入れた場合)も、ランタイムは動作しますが、バケットの意図はあいまいになります。

リンターソケット — バケットをまたぐ読み取りの指摘

リンタープラグイン(帯域外の助言的なもの。配置の基準については plugins/plugin-contract.md を参照)は、Recipe のテンプレートが、振り分け先のフィールドと意図が一致しないバケットから値を取得している、バケットをまたぐ読み取りを指摘できます。基準は次のとおりです。

  • values: フィールドを埋めるために .context.annotations.release を読み取る — 指摘します(認知的メタデータは aggregate バケットから取得すべきです)。
  • infra: フィールドを埋めるために .context.annotations.aggregate を読み取る — 指摘します(物理的メタデータは release バケットから取得すべきです)。
  • values: または infra: を埋めるために .context.annotations.catalog を読み取る — 通常は助言のみです(カタログのアノテーションは固有特性であり、それをピラーに振り分けるのは一般的ではありませんが、常に誤りとは限りません)。

公開用リンターにはこの基準のためのルールはなく、ビルドもこれをチェックしません。独自のリンタープラグインであれば、aggrega lint が実行するリンターソケットを通じてチェックできます。この規律は、バケットの意図に関する慣例に従うレビュー担当者と作成者によって維持されます。

プレフィックスの規律

アノテーションとラベルのキーは、一様な <namespace>/<name> の形に従います。以下のプレフィックスファミリーは、それぞれの下で誰がキーを作成するか、またそれぞれがどのように維持されるかを示します。1 つのプレフィックスは予約されており、その内部で Manifest のバインディングや Recipe の出力ラベルが新しいキーを主張するとビルドが停止します。それ以外はカタログの慣例であり、キーを拒否するものはありません。 両者の違いはビルドが停止するかどうかなので、他の列より先に中央の列を読んでください。

プレフィックスここでキーを作成する者維持のされ方目的例
aggrega.ai/Aggrega プラットフォームのみ予約済みで、強制されます。 ここのキーはプラットフォームが定義し、定義されたキーを記述します。たとえば Release 境界上の aggrega.ai/namespace です。このプレフィックス内で新しいキーを主張するとビルドが停止します。素のプレフィックス直下の Manifest features.annotations バインディングも、outputLabels: または outputComponentLabels: 内でその下に置かれた Recipe の出力ラベルキーも同様です。プラットフォームが定義していないアノテーションをその下に記述しても拒否されません。ビルドはそれを保持し、それが Release 上にある場合、それを処理しないターゲットは警告でその旨を伝えます。errors/fatal-halts.md の「A Manifest annotation binding claims the reserved aggrega.ai/ prefix(Manifest のアノテーションバインディングが予約済みのプレフィックスを主張しています)」および「An output-label key uses a reserved namespace(出力ラベルのキーが予約済みの名前空間を使用しています)」を参照してください。プロバイダーが直接消費するプラットフォームネイティブのアノテーションaggrega.ai/namespace, aggrega.ai/region, aggrega.ai/environment
feature.aggrega.ai/公式標準ライブラリ慣例。 ここでキーを拒否するものはありません。この語彙はチェックによってではなく、合意によって標準ライブラリのものとなっています。Manifest の features.annotations でバインドされる Feature アノテーションのショートカットfeature.aggrega.ai/prometheus-exporter, feature.aggrega.ai/data-masking
component.aggrega.ai/公式標準ライブラリ慣例。 ここでキーを拒否するものはありません。Component 固有の特性ラベル(component.aggrega.ai/type セレクターキーはここにあります)component.aggrega.ai/type
aggregate.aggrega.ai/公式標準ライブラリ慣例。 ここでキーを拒否するものはありません。Aggregate のモジュールレベルの識別ラベルaggregate.aggrega.ai/tier, aggregate.aggrega.ai/compliance
<role>.aggrega.ai/公式標準ライブラリ、および独自カタログを持つエンタープライズ慣例。 ここでキーを拒否するものはありません。ケイパビリティラベル。usesSchema セレクターや Feature の appliesTo が判別に用いる振る舞いの次元です。<role> は、その次元が属する関心事を表します。コンポーネントのロール、または複数のロールが共有する横断的な関心事のいずれかです。model.aggrega.ai/capability, datastore.aggrega.ai/engine, gateway.aggrega.ai/intelligence, dataplane.aggrega.ai/request-mirroring
<any-other-domain>/エンタープライズ / コミュニティオープン。 自身が管理するドメインの下で作成します。カスタムアノテーションとラベルacme.com/billing-tier, corp/cost-center

カスタムアノテーションを作成する場合は、自身が管理するドメイン(通常は逆 DNS 形式)を使用します。aggrega.ai/ の直下に(サブプレフィックスなしで)作成することはプラットフォーム用に予約されています。Manifest の features.annotations バインディングも aggrega.ai/ の直下にキーをバインドすることはできません。entities/manifest.md の「aggrega.ai/ Prefix Reservation」を参照してください。

ケイパビリティプレフィックスの命名

ケイパビリティキーは <role>.aggrega.ai/<dimension> であり、判断を要するのは <role> の部分です。 これには 3 つのルールがあり、最初のルールが最も逆に 取り違えられがちです。

  • 最初にそれを持つことになったコンポーネントの種類ではなく、関心事を命名します。 次元が複数のコンポーネントの種類で共有されるものを表す場合、プレフィックスは 共有される関心事を命名し、次にそれを獲得する種類が並行する語彙を作らずに 既存の語彙を再利用できるようにします。component.aggrega.ai/hosting は関心事、 つまり基盤リソースを誰が運用するかであり、データベースとモデル API を 同じ言葉で表します。dataplane.aggrega.ai/* はトラフィック経路上の位置を命名するため、 プロキシ、イングレスゲートウェイ、サービスメッシュが同じように自身を表します。 本当に 1 つのロールに固有の次元は、model.aggrega.ai/capability のように、そのロールの名前を取ります。
  • プレフィックスは小文字の 1 語とし、ハイフンは使いません。 ハイフンは <dimension> 側に置きます。そこでは複合語が自然に読めます(request-mirroring、 data-class、upstream-licensing)。
  • 次元はセレクターが必要とするときに追加し、宣言する各値にはそれを持つコンポーネントが存在します。 ここにある語はどれも、カタログ作成者が覚える必要があり、Feature 作成者が出会う可能性のあるものです。そのため次元は、usesSchema や appliesTo が実際に問う何かを判別することで存在価値を得ます。どのコンポーネントも持たない値は、値が存在しないことよりも悪い結果になります。その値を指定したセレクターは解析に成功し、何にもマッチせず、何も報告しないからです。そのため、カタログが実証できない値は、それを持つコンポーネントが現れるまで語彙から外されます。値が製品の特性ではなく、エステートが自身のコンポーネントをどのように使うかについての表明であるキーは例外であり、compliance.aggrega.ai/data-class がそれに当たります。コンポーネントのデータがどのクラスに属するかはエステートによるコンポーネントの使い方に依存するため、標準ライブラリの Component はその値をいずれも持たず、標準ライブラリのソケットや Feature もそれを選択しません。このキーとその値は、エステート独自の Components とそれに付与するポリシーが 1 つの綴りを共有するために宣言されています。値を指定したセレクターやポリシーは、その値を持つ Components のあるカタログでのみマッチします。policy-data-class-route は、そのような Component とそれを読むポリシーの例を示しています。

予約とプラットフォーム定義のキーは同じものではない

予約の対象は素の aggrega.ai/ ルートです。その下にある各 <scope>.aggrega.ai/ 名前空間は、プラットフォームが所有しない独立したキー空間であり、これによってカタログの語彙は拡張可能に保たれます。エンタープライズのカタログは、ビルドが刻印するものと競合することなく acme.aggrega.ai/team を作成できます。

それでも、これらのオープンな名前空間内のいくつかのキーはプラットフォームによって定義され、ビルドによって読み取られます。ただし、それによってその名前空間が予約されるわけではありません。

  • component.aggrega.ai/type はすべての Component の metadata.labels で必須であり、固定された値の集合のいずれかを取ります。セレクターはこれにマッチしますが、コンパイラはその値によって分岐しません。
  • features.aggrega.ai/requiredType.<label> は Component の metadata.annotations に記述し、指定された型の Feature を付与する必要があることを宣言します。ビルドは各ノードの確定した付与集合に対してこの要求を検査し、それを満たすものがない場合は停止します。errors/fatal-halts.md の「Required feature not attached(必須の Feature が付与されていません)」を参照してください。複数形に注意してください。features.aggrega.ai/ は独立した名前空間であり、上の表にある単数形の feature.aggrega.ai/(Manifest のバインディングショートカットを扱う)とは別物です。

違いは次のように捉えてください。予約されたプレフィックスは、その内部に定義しようとしたキーを拒否します。一方、プラットフォーム定義のキーは、ビルドが認識している名前付きのキー 1 つであり、それ以外は自由に作成できる名前空間に置かれています。component.aggrega.ai/、features.aggrega.ai/ などの下にあるその他のキーはすべて、ビルドが解釈せずに運ぶメタデータです。

Component の metadata.annotations にあるそのようなキーのうち 1 つは、ビルドではなく標準の公開リンターによって読み取られます。observability.aggrega.ai/metrics-credential は製品のメトリクスがどのように認証されるかを示します。none は認証情報なしで提供されること、target-key は Component がすべての呼び出し元に要求するキーを取ること、separate-token は独自のトークンを取ることを表します。ビルドはこれを他のアノテーションと同様に運びます。リンターはこれを読み取り、スクレイプ接続の認証情報をターゲットの呼び出し元キーと比較するかどうかを判断し、Component が宣言する metrics_credential_required provides キーと一致することを求めます。cli/aggrega-lint.md の「The discipline rules」を参照してください。

レンダリング出力に付与される来歴ラベル

プロバイダーが消費する入力側のアノテーションに加えて、Aggrega は helm プロバイダーがレンダリングするすべての Kubernetes マニフェストと、出力されるすべての compose サービスに来歴ラベルを付与します。また helm-chart プロバイダーは、$import: で読み込む各アーティファクトに、helm プロバイダーと同じ方法で同じラベルセットを書き込みます。このラベルセットにより、下流のツール(コストダッシュボード、オブザーバビリティスタック、GitOps コントローラー)は、ランタイムのリソースをそれを生成したカタログのコンテンツまでたどることができます。helm-chart のサブチャート自身のテンプレートは作成者が書いたとおりにコピーされるため、その作成者が書いたラベルがそのまま付きます。

helm と compose のプロバイダーが出力するセットです。helm では、表に示すとおり、3 つのキーがラベルではなくアノテーションとして書き込まれます。

ラベルソース常に付与されるか
app.kubernetes.io/nameComponent の識別子 — 記述した名前、またはインポートされた Aggregate が提供する component の場合はモジュール区切りを書き出した修飾名(下記参照)、あるいは FeatureRecipe が出力するリソースの場合はそのアタッチメントについて導出された識別子Kubernetes マニフェストでは付与されます。compose サービスには付与されません(この標準ラベルは K8s 固有です)
aggrega.ai/component-idComponent の識別子 — 記述した名前、またはインポートされた Aggregate が提供する component の場合はモジュール区切りを書き出した修飾名(下記参照)、あるいは FeatureRecipe が出力するリソースの場合はそのアタッチメントについて導出された識別子はい
aggrega.ai/recipe-uri生成元の Recipe(FR が出力したリソースの場合は生成元の FeatureRecipe)の <recipe-name>:<recipe-version>生成元のエンティティに名前とバージョンの両方が設定されている場合。helm ではアノテーション
aggrega.ai/boundary-pathコンポーネントのルーティング先の境界パス境界パスが空でない場合。helm ではアノテーション
aggrega.ai/aggregate-nameAggregate の metadata.name設定されている場合
aggrega.ai/compiler-versionビルド時に刻印されるコンパイラのバージョン設定されている場合
aggrega.ai/providerリソースをレンダリングしたプロバイダー(helm、helm-chart、compose)はい
aggrega.ai/provider-versionその provider のバージョンはい
aggrega.ai/environmentRelease の metadata.environmentはい — すべての Release がこれを宣言します
aggrega.ai/sync-wave境界ごとの syncWave 整数。GitOps ツールがリソースを適用する順序です0 でない場合。helm ではアノテーションとして argocd.argoproj.io/sync-wave と並べて書き込まれます

集約名、環境、コンパイラのバージョン、プロバイダーの名前とバージョンは、利用者またはビルドが選んだ文字列であり、そのいずれも、書き込まれる箇所で Kubernetes のラベル値の規則に従うことは求められません。helm では、値がすでに有効なラベル値である場合 — 英字、数字、-、_、. からなり、両端が英字または数字で、最大 63 文字 — これらの各ラベルは書かれたとおりの値を持ちます。そうでない場合は有効な値に書き換えられた値を持ち、元のままの値が同じキーの下にアノテーションとして追加されます。imported/flow という名前の Aggregate には、ラベル aggrega.ai/aggregate-name: imported-flow とアノテーション aggrega.ai/aggregate-name: imported/flow が付与されます。すでに適合している値はアノテーションを追加しません。Compose は元のままの値をラベルとして持ちます。書き換えの規則は providers/well-known-annotations.md の「プロバイダーが出力する来歴ラベル」に記載されています。

FeatureRecipe が出力するリソースでは、aggrega.ai/component-id の値はホストコンポーネントの名前ではなくアタッチメントから構築されます。これは、FeatureRecipe がワークロードを合成する場合、独立したアーティファクトセットを出力する場合、作成者が用意したチャートやフラグメントをレンダリングする場合のいずれでも同じです。そのため、識別子でアタッチメントのリソースを選択するクエリはそのすべてを返し、ホストコンポーネント自身が出力したリソースと区別できないものはありません。値の構築方法は Feature のアタッチ先によって異なりますが、いずれの場合も結果は有効な Kubernetes ラベル文字列になります。

インポートされた Aggregate が提供するコンポーネントの場合、識別子はそのコンポーネントの修飾名であり、モジュールとコンポーネントをつなぐ区切りは書き出されます。data-layer.main-db は data-layer-zdmain-db として刻印されます。ドットはリソース名やクラスターアドレスが安全に含められる文字ではないためです。区切りを含まない、記述した名前はバイト単位でそのまま刻印されます。

識別子は、リソースが何に属するかを示します。これはリソースが何と呼ばれるかとは別の問いであり、ある配信方法では両者の答えが異なります。

  • FeatureRecipe がワークロードを合成する場合、Aggrega はそれらのリソースを自ら構築するため、識別子に基づいて名前も付けます。識別子はラベルだけでなく、metadata.name、セレクターラベル、出力されるファイル名にも反映されます。これはラベルであるだけでなく、クラスター内の名前でもあります。
  • FeatureRecipe が作成者の書いたチャートやフラグメントを配信する場合、名前はそれを書いた人に属します。それらのテンプレートのレンダリングに使われる Helm リリース名、およびそのレンダリングが出力するファイルのプレフィックスは、ホストコンポーネントのもののままです。チャートはリソースにリリース名に基づく名前を付けることが多いため、これを変えると、チャートとは無関係の理由で、チャート自身が宣言するリソースを、すでにデプロイ済みのクラスター内で改名することになります。ラベルには引き続きアタッチメント自身の識別子が含まれ、これによってアタッチメントのリソースを見つけられる状態が保たれます。
  • Feature が境界にアタッチされている場合、代わりとなるホストコンポーネントの名前がないため、合成された識別子がラベルであると同時に命名の基礎にもなります。

いずれの場合も、値は記述した部分を -- で連結し、そのどちらであるかを示す固定の先頭部分の後ろに置いて合成されます。使用される先頭部分は 2 つあり、記述するコンポーネント識別子はどちらで始めることもできません。これにより、記述した名前と Aggrega が合成した名前が互いに取り違えられることはありません。

Feature がコンポーネントにアタッチされている場合、各部分は固定の先頭部分 cfr、Feature のアタッチ先コンポーネントの識別子、アタッチに使われたキーです。コンポーネント api に mon としてアタッチされた Feature は cfr--api--mon になります。ホストコンポーネントが値に含まれるのは、1 つの Feature 名を複数のコンポーネントにアタッチすると、それぞれに別々のリソースセットが出力され、各セットに固有の識別子が必要になるためです。mon を api と worker の両方にアタッチすると、両方に共通の 1 つの値ではなく、cfr--api--mon と cfr--worker--mon になります。同じ理由で、ホストするコンポーネントとまったく同じ名前のアタッチメントも、そのコンポーネント自身の値とは異なる値になります。mon にアタッチされた mon は cfr--mon--mon になります。

Feature が境界にアタッチされている場合(compose-bridge ゲートウェイサービスが代表例です)、各部分は固定の先頭部分 bfr、続いて境界パスの各セグメントを外側から順に、最後に Feature のアタッチに使われた名前です。bridge の境界上の gateway という名前の Feature は bfr--bridge--gateway になり、prod/eu の境界上の同じ Feature は bfr--prod--eu--gateway になります。

値に含められない文字は置き換えではなく書き換えられます。また、この値はラベルであると同時にクラスター内の名前でもあるため、あらゆる種類の Kubernetes リソース名が受け入れる文字、つまり小文字、数字、ハイフンに制限されます。そのため、書いたハイフンはハイフンのまま、小文字や数字はそのまま残り、それ以外の文字(ラベル値では受け入れられるがリソース名では拒否される大文字を含む)は短いエスケープになります。my_zone という名前のアタッチメントは my-zuzone となり、アタッチメント worker を持つコンポーネント myApi は cfr--my-zx000041pi--worker になります。このエスケープされた値が、すべてのターゲットでアタッチメントのリソースにラベルとして付けられ選択に使われる値であり、アタッチメントが合成するワークロードの名前とファイル名の基になる値であり、境界アタッチメントのリリース名の導出元となる値です。リソース名の規則がラベルだけの場合に書き換える文字に追加するのは大文字だけなので、どの部分にも大文字を含まない合成値(cfr--api--mon、bfr--prod--eu--gateway)は、ラベルだけの場合と同じ値になります。したがって、区別できる 2 つのアタッチメントは、どのように名付けても、境界がどれほど深くても、必ず 2 つの値になります。-- はどの記述部分にも含まれ得ない並びなので、部分間の区切りを動かすと値が衝突するのではなく変わるからです。

合成された値の長さの上限は、Aggrega が持つ数値ではなくターゲットが決めます。リソースのレンダリング先のターゲットに問い合わせ、そのターゲットが受け入れるまで値を短縮します。Kubernetes のラベル値は最大 63 文字で、同じ識別子から導出される Helm リリース名はさらに厳しく制限されるため、同じアタッチメントでもターゲットによって短縮後の長さが異なることがあります。収まる値は合成されたとおりに出力されます。これが通常のケースであり、標準ライブラリのカタログ内のすべてのアタッチメントに当てはまります。収まらない値は短縮されます。各部分は先頭を残し、記述可能などの名前からも生じないマーカーの後ろに識別子全体の 10 文字のダイジェストが付加されます。そのため、短縮された値はそれと識別でき、収まった値と読み違えられることはありません。したがって、深くネストされた gateway アタッチメントは bfr--region-region-region-region-r--gateway-gate---ze24e3a2ba5e のようにレンダリングされることがあります。短縮された 2 つの値が一致することはきわめてまれですが、一致した場合、ビルドは 2 つに同じ名前を共有させずに停止します。

どの組み合わせで停止するか、またそれらを分ける方法については、errors/fatal-halts.md の「The same name is derived more than once inside the output(出力内で同じ名前が複数回導出されています)」を参照してください。

FR が出力したリソースの aggrega.ai/recipe-uri は、消費側の Recipe の識別子ではなく FeatureRecipe 自身の name:version に解決されます。そのため、生成元のエンティティを特定するために recipe-uri を読む下流のツールは、コンポーネントが出力したものと FR が出力したものの両方について正しい来歴を得られます。

プロバイダーごとの付与の詳細(レンダリング出力のどこにラベルが置かれるか、各プロバイダーがそれをどうシリアライズするか)については、providers/well-known-annotations.md の「Provenance labels emitted by providers」を参照してください。

Recipe が宣言する出力ラベル

コンパイラが所有する来歴ラベルのセットに加えて、Recipe の作成者は Recipe.spec.outputLabels: を使って、Recipe のレンダリング出力に刻印する独自のラベルを宣言できます。これらは来歴ラベルと同じ出力経路に乗ります。つまり同じラベルセットにマージされ、来歴ラベルが付与される場所すべてに付与されますが、コンパイラではなく作成者が所有します。想定される用途は 実現特性 です。これは特定の Recipe がコンポーネントをどのように実現するかを表すプロパティで(たとえば、同じコンポーネントタイプに対するマネージドサービスの Recipe とセルフホスト型チャートの Recipe における hosting: managed と hosting: self-hosted)、出力上に表れるため、コスト、ポリシー、インベントリのツールがそれをクエリできます。

aggrega.ai/ と app.kubernetes.io/ の名前空間は来歴ラベルのセット用に予約されています。いずれかのプレフィックス配下のキーは、読み込み時に拒否されます。これは outputLabels: でも、outputComponentLabels:(コンポーネントラベルのキーを指定し、コンポーネント自身が宣言する値を刻印する対のブロック)でも同様です。そのため、検証済みの出力ラベルセットは常に来歴キーと重複せず、マージされた出力上で両者が衝突することはありません。判定はルートそのものに対して行われます。component.aggrega.ai/hosting のようなスコープ付きのキーは独自の名前空間にあり、そのまま記述することも昇格させることもできます。プロバイダごとの表出先(合成時は helm のオブジェクトと pod-template、ソースレンダリングとアーティファクトではオブジェクト、compose のサービスラベル、.tf.json アーティファクト本体での terraform のリソースごとのタグ)は来歴ラベルの配置と一致しており、詳細は Recipe エンティティのページの「outputLabels: フィールド」および「outputComponentLabels: フィールド」に記載されています。

Feature のアタッチ — 5 つのサーフェス

Features は 5 つの異なるオーサリングサーフェスを通じて Components にアタッチされます。各サーフェスは、5 層オニオンモデル内での適用範囲、想定ユーザー、順序の優先順位がそれぞれ異なります。アタッチの完全な順序とオニオンモデル自体は architecture/10-compilation-pipeline.md に記載されています。以下の表は 5 つのサーフェスを並べて列挙したものです。

ティア画面記述者適用範囲カスケード規則
1Aggregate のコンポーネントの features: ブロック開発者コンポーネントインスタンス単位(細粒度)なし — 記述者が直接指定
2Aggregate のサブシステムの features: ブロック開発者サブシステム範囲(Aggregate 内で横断的)サブシステム内のすべてのコンポーネントにカスケード
3Release バウンダリの components.<id>.features運用担当者コンポーネントインスタンス単位(細粒度、運用側)なし — 記述者が直接指定
4Release バウンダリの features: ブロック運用担当者バウンダリ範囲(バウンダリ内で横断的)バウンダリ内のすべてのコンポーネントにカスケード
5Manifest の features.annotations 展開プラットフォームオペレーターアノテーション駆動(合成アタッチ)バウンダリツリー(Release 側)またはサブシステムツリー(Aggregate 側)を通じてカスケード。コンポーネント単位のオーバーライドとサブキー単位の null によるオプトアウトが適用されます

5 つのサーフェスは累積します。いずれかのサーフェスに存在するアタッチは、Component の解決済み feature セットに寄与します。同じ Feature インスタンス名が複数のサーフェスに現れる場合、それらの寄与は互いを置き換えるのではなく 1 つのアタッチにマージされます。両者の間で型が一致しない場合、feature-merge-conflict エラーでビルドが停止します。

5 つのサーフェスは冗長なものではなく、アーキテクチャの関心の分離 — 開発者(ティア 1-2)、運用担当者(ティア 3-4)、プラットフォームオペレーター(ティア 5)— に従った意図的なものです。記述者は、アタッチを誰が所有し、どの適用範囲で行うかに合ったサーフェスを選びます。

Feature が適用されるかどうかを決めるラベル

Feature は spec.appliesTo と spec.appliesToAnyOf でアタッチ可能な場所を宣言し、ビルドはその宣言をアタッチ先ノードの確定済みラベルに照らして判定します。それらのラベルが満たさないノードに Feature をアタッチすると、ビルドが停止します。どちらのサーフェスも宣言しない Feature は要件を持たず、どこにでも適用されます。

確定済みラベルセットは 2 つのステップで組み立てられますが、どちらも記述者が最もよく想定するものではありません。

  1. **ノードは、その type: が指定する Component カタログエンティティからラベルを取得します。**ラベルはインスタンスではなくコンポーネントの型の属性です。Aggregate はコンポーネントインスタンスにラベルを付けられず、Release も同様です。Aggregate 自身の metadata.labels は再利用可能なモジュールとしての Aggregate を記述するもので、その中のコンポーネントにはカスケードしません。したがって、同じ型の 2 つのインスタンスは同一のラベルを持ち、ノードのラベルを変えるには、参照先の型を変えるか、その型のエンティティを変える必要があります。
  2. **その後、label-transform アタッチがラベルを書き換えることがあります。**ワークスペース設定が label-transform ロールでガバナンスプラグインをアタッチしている場合、そのプラグインはトポロジー構築時に実行され、何かがラベルに照らして判定される前にノードラベルを追加、変更、削除できます。それ以外には一切触れられないため、ラベルはプラグインが動かせるノードの唯一の部分であり、まさに適用可否が依存する部分です。

**したがって、単一のドキュメントが宣言するラベルに基づく提案は近似であり、予測ではありません。**Component エンティティの metadata.labels を読めば、その型のノードが最初に持つラベルがわかります。これは有用な程度には正しいことが多いものの、2 つの点で誤ります。ノードと名前が同じだけのドキュメントは異なるラベルを持つ別の対象であり、また label-transform アタッチはどのドキュメントからもセットを変えてしまう可能性があります。ソースのみからアタッチの候補を提示するツールはその近似に基づいて動作しており、ビルドが行う判定は確定済みセットに対するものです。

アタッチメントの優先順位

2 つの寄与が同じアタッチの同じフィールドを提供する場合、レンダリング出力がどちらを持つかは 4 つのルールで決まります。ルールはこの順序で適用され、この順序によって結果が予測可能になります。

  1. **由来。**明示的に記述された寄与は、どちらがどの適用範囲で宣言されたかにかかわらず、アノテーション駆動の寄与に優先します。features: ブロックにフィールドを書くことが、アノテーションが寄与したはずの値を記述者がオーバーライドする方法であり、アノテーションが手書きの内容を暗黙に置き換えることはありません。コンパイラは抑制されたアノテーションを採用された値とともに記録して勧告として報告するため、オーバーライドは不可解なものではなく可視化されます。
  2. **ピラーの所有。**各ドメインはそれぞれ自身のピラーを埋めます。Aggregate のサーフェスは values に、Release のサーフェスは infra に寄与します。両側が同じピラーに書き込むことはないため、開発者の寄与と運用担当者の寄与が同じフィールドを争うことはなく、開発者と運用担当者のどちらが優先かという問題は生じません。
  3. **合成の権限。**デプロイする Aggregate 内の宣言は、それが合成する Aggregate 内の宣言より優先されます。合成される Aggregate がより狭い適用範囲で宣言していても同様です。合成は権限を保ちます。モジュールは、より狭い適用範囲を選ぶだけでそれを利用する Aggregate を打ち負かすことはできません。
  4. 具体性。同じオーサリングレベルかつ同じピラー内では、狭い適用範囲が広い適用範囲をフィールド単位で洗練します。コンポーネント範囲のアタッチは、同じインスタンス名のサブシステム全体またはバウンダリ全体のアタッチをオーバーライドしますが、それは実際に言及したフィールドに限られます。狭い適用範囲が省略したフィールドは広い適用範囲の値を保持するため、共有アタッチが共通の設定を提供しつつ、単一のコンポーネントがその 1 フィールドだけを調整できます。同じ適用範囲の 2 つの寄与は記述順で解決され、後のものが採用されます。これにより、内側のサブシステムが外側のサブシステムを、深いバウンダリが浅いバウンダリを洗練できます。

優先順位はフィールドの値を決めるものです。評価の順序は変えません。コンパイラがサーフェスを畳み込む順序や、各アタッチのレンダリング前の injectMapping を実行する順序は、architecture/10-compilation-pipeline.md に記載された固定の 5 ティアの順序です。アタッチに記述された inject ブロックは、上記の適用範囲の順位ではなくこの評価順序に従うため、1 つのアタッチが競合する 2 つの順序を持つことはありません。

metadata.labels と metadata.annotations を持つ種別

metadata.labels は Component、Feature、Aggregate、および 4 つのライブラリ種別にあり、metadata.annotations は Aggregate を除く同じ種別にあります。Manifest、Release、Recipe、FeatureRecipe、Plugin はどちらも持ちません。

カスケードの概要

コンパイラが評価する、6 つのサーフェスにわたるカスケード規則は次のとおりです。

  1. カタログエンティティのラベル(Surface 1) はカタログエンティティ上にとどまります。インスタンスには流れず、利用側はカタログの内容を直接調べて読み取ります。
  2. Component の metadata.labels(Surface 2) は、トポロジー構築時の任意の label-transform パスを経た後、ノードごとの .context.labels に流れます。
  3. Component の metadata.annotations(Surface 3) は、ノードごとの .context.annotations.catalog バケットに流れます。
  4. Aggregate / Subsystem の annotations:(Surface 4) は、サブシステム階層を通じて外側のサブシステムから内側へ蓄積されながらカスケードし、ノードごとの .context.annotations.aggregate バケットに入ります。
  5. Release の境界の annotations:(Surface 5) は、境界階層を通じて外側の境界から内側へカスケードし、ノードごとの .context.annotations.release バケットに入ります。
  6. Manifest の features.annotations(Surface 6) は、ノードごとの IR データに直接カスケードしません。解決フェーズのアノテーション駆動展開サブフェーズがバインディングを消費してノードごとの Feature アタッチメントを合成し、IR グラフ(--ir-graph)はそれを origin: annotation として記録します。合成されたアタッチメントは、解決以降ではその来歴を介さない限り明示的なアタッチメントと構造的に区別できません。展開の詳しい解説は providers/well-known-annotations.md を、カタログ読み込み時および inspect 時の仕組みは architecture/13-catalog-and-registry.md の §「Annotation-driven Feature expansion」を参照してください。

カスケードするアノテーションの正式な設計については、architecture/06-data-taxonomy-and-composition.md の §2(Flow 5)を参照してください。

相互参照