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

Feature

Feature エンティティの概念上の役割(Domain 2 におけるモジュール式の運用特性)は architecture/04-entity-taxonomy.md で説明しています。運用 Features と認証情報 Features(feature.aggrega.ai/kind: secret のラベルが付いたもの)の区別は architecture/08-credential-model.md で説明しています。Feature のセレクタが使用するセマンティックラベルの語彙は entities/component にあります。このページでは、Feature カタログのオーサリング面を扱います。

カタログ上の配置

Components(カテゴリのサブディレクトリを伴う 3 セグメントの URI を使用します)とは異なり、Features はフラットに編成されます。パブリッシャーの下に Feature ごとに 1 つのディレクトリがあり、その中にバージョンごとに 1 つのディレクトリを持ちます。

aggrega-catalog/
└── feature/
└── {publisher}/ # e.g., `core`, `acme`
├── secret-value/
│ └── 1.0.0/
│ └── feature.yaml # feature.aggrega.ai/kind: secret (credential Feature)
├── data-masking/
│ └── 1.0.0/
│ └── feature.yaml
└── ...

OCI URI: hub.aggrega.ai/feature/{publisher}/{feature-name}:{version}(例: hub.aggrega.ai/feature/core/data-masking:1.0.0)。

記述の契約

Features は次を宣言します。

  • metadata.labels: Feature を認証情報の Feature として示すには feature.aggrega.ai/kind: secret を使用します。このラベルは作成者、カタログサイト、ラベルセレクタのための説明的なメタデータです。これを読むコンパイラの分岐はなく、アタッチメントが何を生成するかはラベルではなく、Manifest がその型を対応付ける FeatureRecipe によって決まります。認証情報の Feature と通常の Feature は、同じアタッチメントの面で、どのスコープでも同じ方法でアタッチされます。標準ライブラリの認証情報ファミリーは結果によって分かれます。core/secret-value は値を inject パイプへ渡します。core/referenced-secret は参照可能なシークレットリソース(Kubernetes Secret、AWS Secrets Manager のシークレット、Vault のエントリ)を指定します。これはその FeatureRecipe の出力が作成するもの、または既に存在するもののいずれかであり、schema.provides の出力契約として name(リソースのプロバイダに依存しない位置指定子)と key(その中のデータフィールド)を宣言します。利用側はこれを .features.<slot>.provides.<key> として読み、リソース名を再導出せずにリソースを参照します。core/referenced-secret-set は呼び出し側が指定したデータキーの集合を持つ 1 つのリソースを実体化し、位置指定子のみを公開します。これは読み取るキー名をターゲットが既に知っている利用側のためのものです。core/secret-provided は既存のシークレットの値を公開します。core/generated-secret は何も生成しません。ターゲットエンジン自身が認証情報を生成・管理するため、values も provides も宣言せず、その FeatureRecipes はバイトを一切レンダリングしない純粋な配線です。メンバーを区別する軸は 2 つあります。素材を誰が供給するか(作成者が書くか取得元を指定するか、あるいは core/generated-secret のようにターゲットエンジンが完全に所有するか)と、アタッチメントが何をもたらすか(注入される値、参照可能なリソース、またはレンダリングされるものが何もないか)です。すべてのメンバーは同じアタッチメントの面で互いに対等であるため、認証情報のスロットは常にバインドされ、Releases の間で異なるのはそれをバインドするものです。schema.provides 契約を宣言する認証情報の Feature は、それを実装するすべての FeatureRecipe にそれらのキーの公開を義務付けます(そうでなければビルドは停止します)。また、featuresSchema スロットの selector は必要とするファミリーのメンバーを対象にします。
  • usesSchema(省略可能): Feature が利用できるトポロジー上のソケットを宣言します(例: vault を対象とする、認証情報の Feature の path / key ソケット)。Split Schema の仕組みについては architecture/13-catalog-and-registry.md §2 を参照してください。
  • schema: Feature アタッチメントの values ブロックと infra ブロックを検証します。これは、Developer が Aggregate の各アタッチメントで設定する認知的な意図(values は Developer の領域であり、Release スキーマは Feature アタッチメント上の values: を禁止しています)と、Operator が Release で環境ごとに決める容量(infra)です。default: を宣言するフィールドは、それに対して検証されるとともに、何も記述されていない場合はレンダリングされる柱に値が補完されます。Feature のスコープと記述の形 を参照してください。コンパクト形式の YAML 省略記法(デフォルト。vocabulary/compact-form-authoring.md を参照)または完全な JSON Schema YAML で表現された JSON Schema 2020-12 を受け付け、共有の形には SchemaLibrary のエントリへのドキュメント間 $ref: を使用できます(vocabulary/cross-document-ref.md を参照)。シークレットの素材を持つリーフは sensitive: true を宣言します。標準ライブラリの認証情報の Features は素材を保持するリーフに印を付け、公開する位置指定子には意図的に印を付けません。リソース名とデータキーはどちらも公開情報だからです。このキーワードと、それを宣言して達成できることの上限については、vocabulary/compact-form-authoring.md の「Declaring a leaf sensitive」にあります。
  • featuresSchema(省略可能): Feature 自身の動作に必要なアタッチメントスロットを宣言します。Feature は Component とまったく同じようにスロットを宣言するため、自身が認証情報を必要とする Feature(たとえば Datadog サイドカー Feature の API キー)は、ホストの Component のスロットに手を伸ばすのではなく、バインド先を指定します。Feature が自身のスロットを宣言し、FeatureRecipe がそれを埋めるものを読む例については Feature 自身の認証情報 を参照してください。各スロットは Component の featuresSchema スロットと同じフィールドを同じ意味で受け付けます。これには、省略可能な selector(どの Feature がスロットを埋められるかを制約する Kubernetes 形式のラベルセレクタで、usesSchema ソケットセレクタのスロット版です。ラベルがこれを満たさない充填は停止し、セレクタはアタッチされた Feature のラベルのみに対して評価されます)、省略可能な sensitive(スロットをバインドするものが何であれシークレットの素材を扱うことの宣言で、特定の充填ではなくバインド先についての記述です)、そして同じ開放性が含まれます。スロットを宣言しても、どのスロットも宣言していない名前でのアタッチメントが禁止されることはありません。完全なフィールド表、スロット単位の機密性の宣言とそれがスキーマのリーフの宣言とどう異なるか、そしてスロットを宣言する 1 つのエンティティがデプロイされる 2 つの形態は、すべて entities/component.md「Attachment Slots」 にあります。
  • appliesTo / appliesToAnyOf: Feature がどの Components にアタッチできるかを制御するラベルセレクタです。静的解析段階で、コンパイラのネイティブなラベル照合エンジンによって評価されます。セレクタ構文のリファレンスについては、後述の ラベルに基づくアタッチメント と architecture/13-catalog-and-registry.md §2「Kubernetes-Style Selectors」 を参照してください。
  • interoperability(省略可能): conflictsWith、つまりこの Feature と同じコンポーネントに届くことができない Features を持つ入れ子のブロックです。1 つのコンポーネントが両方を持つことになった場合、それぞれがどのスコープでアタッチされたかにかかわらず、ビルドはレンダリング前に停止します。詳しい説明は後述の interoperability ブロック を参照してください。

Feature の構造的なレンダリングは、対応する FeatureRecipe にバインドされます。FeatureRecipe は Feature のインターフェースを具体的なインフラストラクチャの実装に対応付けます。

ラベルベースのアタッチ

Feature スキーマ上の 2 つの applies セレクターは、Feature がどの Components にアタッチされるかを制御します。これらは静的解析ステージにおいて、コンパイラのネイティブなラベルマッチングエンジンによって評価されます。

  • appliesTo — Kubernetes スタイルのラベルセレクター文字列で、AND 合成のための仕組みです。カンマ区切りの要件はすべて満たされる必要があり、演算子の語彙をすべて使えます: key=value、key!=value、key in (v1, v2)、key notin (v1, v2)、単独の key(ラベルが存在する)、!key(ラベルが存在しない)。appliesTo: "datastore.aggrega.ai/engine=vector" を宣言した Feature は、そのキーと値のペアが正確に一致するラベルを持つ Components にのみアタッチされます。appliesTo: "component.aggrega.ai/type in (server, worker), compliance.aggrega.ai/data-class notin (restricted)" は、「制限付きデータを保持しない任意の server または worker」を 1 つのセレクター文字列で表現します。
  • appliesToAnyOf — OR 合成のための仕組みです。セレクター項目のリストで、いずれか 1 つの項目が一致すれば十分です。各項目は、文字列形式のセレクター(appliesTo と同じ文法で、文字列内の要件は AND で結合されます)か、等価一致のみを行うフラットなキーと値のマップのいずれかです。Feature が互いに無関係な複数のコンポーネント形状に適合する場合に使用します。たとえば、{ component.aggrega.ai/type: worker } または { component.aggrega.ai/type: task } のいずれかに適用される可観測性 Feature を、2 つを 1 つのセレクター文字列に押し込むことなく表現できます。

any-of 形式がなければ、Architect は Feature が適合する無関係なコンポーネント形状ごとに、同じ Feature YAML を複製する必要があります。2 つの形式は組み合わせられます。Feature は両方を宣言でき、結果は形式間で AND されます。つまり、appliesTo 文字列が満たされ、かつ少なくとも 1 つの appliesToAnyOf 項目が一致する必要があります。省略された、または空のセレクターは制約を宣言せず、すべてのラベルセットに一致します。

セレクター文字列は、Feature のアタッチが評価されるたびに 6 つの形式に照らして読み取られ、それらに当てはまらない要件は、別のセレクターとして解釈されるのではなくビルドを停止させます。対象となるのは、空の要件(先頭、末尾、または重複したカンマ、あるいは区切り文字だけの文字列)、空白や =、!、(、)、カンマのいずれかを含むキー、そして閉じられていない in ( または notin ( のセットです。これにより、本来なら意図と逆のものを黙って選択してしまう誤りが捕捉されます。Feature を frontend から外すために書かれた appliesTo: "!tier=frontend" は、! がラベルキーのみを指すため拒否されます(値を除外するには tier!=frontend と書きます)。また tier in frontend は拒否され、tier in (frontend) を使う必要があります。値は演算子の後のテキストであり、どのような文字を含んでいても値として扱われるため、tier==frontend は値が =frontend であるラベルを要求します。停止時には、Feature、そのセレクター、および読み取れなかった要件が示されます。何もアタッチしていない Feature は評価されないため、その Feature 上の不正なセレクターは、アタッチがそれを指定するまで報告されません。

セレクター構文のリファレンスについては architecture/13-catalog-and-registry.md §2「Kubernetes-Style Selectors」 を参照してください。Feature セレクターが受け付ける文法は usesSchema ソケットセレクターが受け付ける文法と同じであり、Kubernetes ユーザーが kubectl get -l でなじみのある文字列形式です。

interoperability ブロック

Feature スキーマは、オプションの spec.interoperability ブロックを宣言します。このブロックが持つ制御は 1 つだけで、この Feature が 1 つのコンポーネント上でどの他の Features と共存できるかを指定します。

interoperability.conflictsWith — 定義中の Feature と相互に排他的な Features のリストです。各エントリは、アタッチメントの type が Feature を指定するのと同じ書き方で記述します。これにより、互換性のない設定の生成を防ぎます。たとえば、TCP 専用のメッシュと HTTP 対応のプロキシの両方を同じコンポーネントにアタッチするような場合です。

1 つのコンポーネントが、この Feature と、そのリストが指定する Feature の両方を持つことになった場合、ビルドは何もレンダリングする前に停止します。判定の基準は到達範囲です。アタッチメントは、それが記述されたコンポーネントに到達し、それが記述されたサブシステムまたはバウンダリの内部にあるすべてのコンポーネント(ネストされたバウンダリを含む)に到達します。Release のコンポーネントエントリに記述されたアタッチメントや、アノテーション駆動の展開によって生成されたアタッチメントも、同じようにそのコンポーネントに到達します。したがって、宣言された競合によってビルドが停止するのは、2 つの Features が同じコンポーネントにアタッチされた場合、一方がバウンダリに、もう一方がその内部のコンポーネントにある場合、一方が外側のバウンダリに、もう一方がその内部にネストされた、コンポーネントを含むバウンダリにある場合、そして一方がサブシステムに、もう一方がそのサブシステム内のコンポーネントにある場合です。コンポーネントを共有しない兄弟バウンダリにアタッチされた 2 つの Features は出会うことがなく、コンポーネントを含まないバウンダリはどこにも到達しません。いずれの場合も停止しません。

  • 宣言は 1 つで十分です。 どちらかの Feature のリストがもう一方を指定していれば、ビルドは停止します。2 つ目の Feature が 1 つ目を逆にリストする必要はありません。
  • バージョンに関係なく名前で比較します。 各エントリと各アタッチメントの type は、バージョンを取り除いた状態で比較されます。そのため、core/fixed-replica-controller というエントリは core/fixed-replica-controller:2.0.0 というアタッチメントに一致し、バージョンを持つエントリは、それが指定する Feature のすべてのバージョンに一致します。
  • 読み取るのは名前だけです。 コンパイラは、Feature の作成者が宣言した名前を、コンポーネントが持つ Features と比較します。これは appliesTo と同じ種類の評価で、作成者が記述したデータを対象とします。2 つの Features が互換性を持たないかどうかは作成者の判断であり、リストはその判断を記録する場所です。

停止時のメッセージは、もう一方を指定するリストを持つ Feature、2 つのそれぞれがアタッチされたすべての場所(Aggregate 内のコンポーネント上、サブシステム上、パス付きの Release バウンダリ上、Release のコンポーネントエントリ上、または名前付きアノテーションのアノテーション駆動の展開によるもの)、そして両者が出会うコンポーネントを示します。複数のコンポーネントで出会うペアは、それぞれについて 1 回ずつ報告されます。メッセージについては errors/fatal-halts.md を参照してください。

例:

apiVersion: aggrega.ai/v1beta1
kind: Feature
metadata:
name: core/autoscaler
version: 1.0.0
spec:
appliesTo: "component.aggrega.ai/type=server"
schema:
values:
metric_target: { type: string, enum: [cpu, memory, custom], required: true }
infra:
min_replicas: { type: integer, min: 1, required: true }
max_replicas: { type: integer, min: 1, required: true }
interoperability:
conflictsWith:
- core/fixed-replica-controller

この Feature は server 型の Components にのみアタッチされ、レプリカを制御する別の Feature との非互換性を宣言します。いずれかのコンポーネントが両方を持つことになったビルドは、レンダリングの前に停止します。アタッチ先のコンポーネントの名前を必要とする FeatureRecipe(たとえば、オートスケーラーをそのターゲットに向ける場合)は、その名前をテンプレートコンテキストから読み取り、出力の必要な箇所に書き込みます。.context.instance_id はコンポーネントの識別子です。.context.rendered_name は、コンポーネント自身の provider がそのコンポーネントのためにレンダリングするリソースに付ける名前で、リソースをターゲットにする際に使うのはこちらです。helm の場合、これは合成されたワークロードが出力する Deployment の名前であり、チャートが自身の名前を組み立てる元となるリリース名です。

extends による継承

Feature は spec.extends: <feature-name> を宣言して、オーサリングサーフェスを継承する基底 Feature を指すことができます。この参照は、Feature が公開されるレジストリ座標ではなく、基底の metadata.name で基底を指定し、すべてのカタログ参照と同じ 3 つのバージョン形式を取ります。利用可能な最も高いリリースを表す修飾なし(core/queue)、完全一致(core/queue:1.0.0)、またはキャレット範囲(core/queue:^1.0.0)です。コンパイラはカタログのロード時に親チェーンをたどり、チェーンが非循環であることを検証したうえで、親の spec を子にマージして単一の解決済み Feature を生成します。キーが衝突した場合は子が記述したフィールドが優先されます。親の metadata.labels と metadata.annotations、appliesTo / appliesToAnyOf セレクタ、interoperability ブロック、usesSchema、featuresSchema、および schema 上の JSON Schema 2020-12 の宣言は、下方向へ自動的にマージされます。それ以外の metadata フィールドはすべて子のものがそのまま使われるため、識別情報と来歴は継承されません。

Feature の metadata: が継承するもの。 labels と annotations はチェーンに沿ってキーごとにマージされます。基底が先に適用され、共通のキーでは拡張する側の Feature の値が優先されます。これは Components が従うものと同じ規則です。metadata: のそれ以外の部分は引き継がれません。name、version、description、maintainers、license、repository、home、keywords は、拡張する側の Feature 自身のものが記述どおりに使われます。

# Base Feature — generic message queue intent
apiVersion: aggrega.ai/v1beta1
kind: Feature
metadata:
name: core/queue
version: 1.0.0
spec:
appliesTo: "component.aggrega.ai/type=worker"
schema:
values:
qos: { type: string, enum: [at-most-once, at-least-once, exactly-once], required: true }
infra:
partition_count: { type: integer, min: 1 }
---
# Child Feature — Kafka-specialized variant
apiVersion: aggrega.ai/v1beta1
kind: Feature
metadata:
name: core/kafka-queue
version: 1.0.0
spec:
extends: core/queue:1.0.0
schema:
values:
compression_codec: { type: string, enum: [none, gzip, snappy, lz4], default: none }

マージ後の core/kafka-queue は、親から appliesTo を継承し、values.qos と infra.partition_count のプロパティを継承したうえで、values.compression_codec を追加します。子が appliesTo を明示的に宣言すると、親のセレクタを丸ごと上書きします(ラベルセレクタのマージは深いマージではなく、子のセレクタが親のセレクタを置き換えます)。子の schema.values.qos は、そのプロパティに関する親の宣言を上書きします。

アタッチメントサーフェスの各部分の継承方法。 2 つのセレクタ形式は、置き換えではなく組み合わされるため、互いに独立して継承されます。存在する各形式は満たされる必要があり(appliesTo の文字列が一致し、かつ appliesToAnyOf の項目の少なくとも 1 つが一致する)、存在しない形式は何も制約しません。そのため、Feature は基底の AND セレクタを引き継ぎつつ、独自の OR セットを宣言できます。interoperability ブロックはフィールドごとに継承されます。conflictsWith リストを含まずにブロックを宣言した子は、基底が宣言したリストを引き続き持ちます。一方、独自の conflictsWith を宣言した子は、基底のリストに追加するのではなく置き換えます。3 つのいずれも宣言しない Feature は、基底がアタッチされる場所とまったく同じ場所にアタッチされます。

継承はスキーマのマージであり、インターフェースのバインディングではありません。 Feature の extends: チェーンは 1 つの解決済み Feature を生成するものであり、多態的なファミリーを生成するものではありません。Manifest のバインディングの feature: フィールドが参照するのは、チェーン上の基底 Feature の URI ではありません。Manifests は末端の Feature の URI でバインドし、解決済みのスキーマには継承されたプロパティが含まれます。FeatureRecipe が implements: する Feature の契約も同様に末端の URI です。FeatureRecipes は継承チェーンをたどりません。

aggrega pull はベースを取得します。 ベースとなる Feature は、それを拡張する Feature をアタッチするすべての Release の依存関係であり、他に何かがそれを指定しているかどうかは関係ありません。aggrega pull は各 extends: をチェーンの終端までたどり、どのカタログディレクトリにもないベースをレジストリから取得し、すべてのベースを Release のロックファイルに記録します。各ベースは、それを指定する Feature の spec.extends から参照されます。ビルドはそこからベースを読みます。

エラーモード。 循環する extends: チェーンと、どのカタログエンティティも提供しない親は、解決の起点となった Feature、extends: 行を開くべき Feature、およびそれが宣言する参照を示してビルドを停止させます。メッセージは Cyclic extends on Components or Features (Component または Feature での循環する extends) と An extends: chain cannot be assembled (チェーンを組み立てられない) にあります。

Components、Features、および資格情報 Features にわたる継承 / インターフェースに関するより広い用語については、vocabulary/inheritance-and-interface.md を参照してください。

コンポーザビリティ:純粋性の社会契約

標準ライブラリの慣例は 1 つの Feature に 1 つの内部機能 です。オブザーバビリティのサイドカーはオブザーバビリティの Feature であり、ネットワークプロキシのサイドカーはネットワークプロキシの Feature です。これらが、無関係な 2 つの関心事を持つ単一の複合体にまとめられることはありません。この慣例により、個々の Features は組み合わせ可能で、独立してバージョン管理でき、独立してアタッチできる状態に保たれます。

コアの Go コンパイラはこの慣例を強制しません。複数の関心事が混在する Feature 定義も構文上は正当であり、問題なくコンパイルされます。強制はオプトインです。

  • 社内カタログを作成する企業は、CI/CD で Feature 定義を検査し、単一の Feature の appliesTo ラベルが無関係な機能ドメインにまたがる場合に警告するカスタムの linter プラグインを作成できます。
  • 2 つの Features が重複することを interoperability.conflictsWith に記録した Feature の作成者は、ビルド時チェックにオプトインします。この 2 つが 1 つのコンポーネントに到達する箇所では、コンパイラは停止します。コンパイラは宣言された名前を比較するだけであり、それ以上のことは行いません。したがって、強制されるのは作成者が記述した宣言であり、純粋性の慣例そのものではありません。

オープンソースの標準ライブラリの Features は、作成上の規律によって純粋性の慣例に従っています。企業のカタログは、密結合の複合体がデプロイメントモデルに本当に適合する場合には、自由にこれから外れることができます。

何が Feature に値するか、そして製品固有のダイヤルはどこに属するか

Feature はアタッチメントです。開発者またはオペレーターが意図的にアタッチするもの(リソース、パイプラインのステップ、配線)をもたらし、標準ライブラリの慣例では、少なくとも 2 つの独立した製品によって尊重できるものであることとされています。この後半部分こそ、Feature を作成する前に適用すべきテストです。アタッチメントという言葉が約束するのは移植性だからです。アタッチメントは、その機能が持ち運べることを意味します。あるコンポーネントにアタッチし、別のコンポーネントにもアタッチすると、各製品の実現がそれぞれのやり方でそれを尊重します。

**現場で 1 つの製品だけが持つ機能は、Feature ではなくその製品固有のダイヤルです。**それはその製品自身のサーフェス上で作成される値として属し、それを決める作成者が自身のピラーで設定し、同じ製品を設定する他のすべてのものと並べて読みます。代わりにそれを Feature として公開すると、他のどの製品も提供できない移植性を謳うことになります。そのアタッチメントは構造上 1 つの製品を指すため、次に手に取った製品にそれをアタッチした作成者は、型を名指しして停止するビルドに直面し、Feature は持っていなかった機能を教えたことになります。

このテストが数えるのは、このカタログ内のコンポーネントではなく現場の製品であり、それぞれをその製品自身の現行の設定リファレンスから読み取ります。2 つの独立した製品がある機能を実装していれば、ここでいくつ提供されているかにかかわらずその機能は移植可能です。そのため、カタログ内の何もそれを実現していないうちから Feature を宣言できます(その場合、アタッチすると型を名指ししてビルドが停止します)。提供される各実現は 1 つの製品向けの FeatureRecipe であり、その製品が設定する方法でアタッチメントを尊重します。

**アップストリーム証明書のピン留めが実例です。**ピンは、アップストリームがどの鍵を提示してよいかを制御するものです。公開鍵が Release の提供する鍵と一致する証明書のみを受け入れます。これは、アップストリームの証明書が Release の提供するトラストアンカーへチェーンすることを要求するのとは異なる主張であり、証明書のサブジェクトが何を述べているかを主張するのともさらに異なります。後者の 2 つはいずれも証明書が何を述べるべきかを示すのに対し、ピンは証明書がどの鍵であるべきかを示します。ここにある複数のゲートウェイはアンカーに対する検証ができ、それが dataplane.aggrega.ai/upstream-tls: trust-anchor がセレクターで一致させられる値である理由です。ピン留めは別の機能であり、少なくとも 2 つの独立した製品が、アップストリームへ開く接続に対してこれを実装しています。Tyk はアップストリームの公開鍵を PEM 形式で受け取り、Envoy はそのハッシュを受け取ります。したがってこれは Feature core/upstream-key-pinning であり、そのセレクターは dataplane.aggrega.ai/upstream-pinning: public-key を指定します。このカタログが何を実現するかは製品ごとに決まります。core/gateway/tyk はこの値と、各ターゲット向けの FeatureRecipe を持ちます。一方、ここにある Envoy を組み込んだゲートウェイは、そのピン設定をクライアントが提示する証明書に対してのみ公開するか、まったく公開しないため、値を持たず、それらへのアタッチメントはセレクターで停止します。ピンはアップストリームが提示してよいものを絞り込みます。これは制御であり、接続がその他の点で健全であることの保証ではありません。

このテストには 2 つの限界があり、2 つ目は最も見落とされやすい部分です。

  • **これは作成上の規律であり、コンパイラのチェックではありません。**どの製品も実装していないオプションを宣言する Feature も、スキーマ検証、公開用リンター、レンダリングのいずれも通過します。コンパイラは Feature が何を約束するかを解釈しません。判断はカタログの作成者に委ねられます。
  • **1 つの製品がオプションを尊重できないことは、そのオプションを削除する根拠にはなりません。**2 つ以上の製品が、まとめられる名前のもとで機能を提供している場合、その機能は移植可能であり、Feature はそれを保持します。尊重できない製品はそれを辞退します。すべての製品がサポートするものだけに縮められた Feature には、述べることがほとんど残りません。

Feature のスコープとオーサリングの形

Feature の spec.schema は Feature 自身の values: と infra: の形を定義します。これは、Developer が Aggregate 内の Feature のアタッチメントごとに設定する認知的な意図(values)であり、Operator が環境ごとに決める容量の数値(infra)とは区別されます。Feature のピラーはそれぞれ独自の名前空間に置かれ、ホストの Component のピラーとは独立して検証されます。Developer が Aggregate 内で autoscaler Feature を web-server Component にアタッチすると、Aggregate は Component の values:(ホストの形)に加えて Feature の values:(スケーリング意図の形、つまりどのメトリクスがスケーリングを駆動するか)を保持します。オペレーター向けの容量の数値(min_replicas / max_replicas)は、Feature のアタッチメントにある Release の infra: ブロックを通じて流れます。

# Aggregate fragment — Feature attachment with its own values:
components:
web-server:
type: core/web-server
values:
log_level: "info" # the Component's own values
tls_enabled: true
features:
autoscaler:
type: core/autoscaler
values:
metric_target: "cpu" # the Feature's own values (dev intent: scale on CPU)
# Release fragment — Feature attachment's infra block (operator-side capacity):
boundaries:
prod:
components:
web-server:
features:
autoscaler:
infra:
min_replicas: 2
max_replicas: 10

Feature の schema: は、Feature のアタッチメント自身の values: ブロックと infra: ブロックを検証します。Component の schema: は Component 自身のものを検証します。この 2 つは静的解析の段階で独立して評価されます。Feature の schema: に一致しないアタッチメントのピラーは、ホストの Component ではなく Feature のアタッチメント箇所にスコープされたエラーでビルドを停止させます。検証されるのはアタッチメントの実効設定、つまりそれを設定したすべてのスコープを合成した結果です。そのため、あるスコープで適合させた値を、より狭いスコープで不正な値に上書きした場合も検出されます。

宣言されたデフォルトは、アタッチメントのレンダリングされたピラーに具体化されます。 検証に加えて、Feature の values または infra のフィールドに宣言された default: は、何もオーサリングされていないすべてのキーについて、ビルド時にそのアタッチメントのレンダリングされたピラーへ埋め込まれます。そのため、{{ .infra.tier }} を読む FeatureRecipe のテンプレートは、空の値ではなくスキーマで宣言された値を受け取ります。作成者が指定した値が常に優先され、デフォルトはそれが省略したキーだけを埋めます。Feature のスキーマのキーを 1 つだけオーサリングしたアタッチメントも、そのスキーマの他のキーについては宣言されたデフォルトを受け取り、部分的にオーサリングされたネストしたオブジェクトは、書かれた内容を保持したまま、書かれていない兄弟要素を得ます。

オーサリングの際には、この埋め込みの 3 つの性質を知っておくと役立ちます。

  • デフォルトは、いずれかのスコープが指定した値を置き換えることはありません。 Feature が複数のスコープ(たとえば Release の境界とそのコンポーネントの 1 つ)でアタッチされている場合、より狭いスコープの値が維持され、デフォルトはどのスコープもまったく書いていない部分だけを埋めます。
  • デフォルトはアタッチメントを埋めるものであり、アタッチメントを作成することはありません。 何もアタッチしていない Feature にデフォルトを宣言しても出力には何も寄与しないため、Feature のスキーマが、どの作成者も求めていない設定を追加することはできません。
  • 単一のコンポーネントではなく Release の境界で宣言されたアタッチメントは infra だけを埋めます。その面には埋めるべき values: ブロックがないためです。

具体化は検証と同じスキーマ解決を使うため、親の Feature に宣言されたデフォルトは extends: の子のアタッチメントにも届き、ドキュメントをまたぐ $ref: を通じて SchemaLibrary から届いたデフォルトも具体化されます。ドキュメント内のローカルな #/$defs/ 参照の中、または allOf / oneOf / anyOf の分岐の下にのみ宣言されたデフォルトは具体化されません。

検証だけでは明らかにならないため、1 つの帰結をはっきり述べておきます。default: も持つ required: フィールドはそのデフォルトによって満たされるため、省略しても正当です。そして、チェックが受け入れた値が、レンダリングされた出力に含まれる値です。

コンパイラのテンプレートコンテキストは、.features.<alias> フィールド (アタッチメントごとに .type、.resolved_version、.labels、.values、.infra、.provides を含む) を通じて、Feature のインスタンス状態をバインドされた FeatureRecipe に公開します。FeatureRecipe 内のテンプレートは、FeatureRecipe 自身のテンプレートスコープで .values.<field> を介して Feature 自身の values: を読みます。ホストの Component の values: は、Feature がホストの Component への uses: ソケットを明示的に宣言しない限り、FeatureRecipe のテンプレートから直接は見えません。

このスコープの分離により、Features は合成可能になります。autoscaler Feature は、どの Component にアタッチされるかに依存せず、その schema: はホストに関係なくオートスケーリングの意図を記述します。ホストの Component の values: はホストの関心事であり、Feature の values: は Feature の関心事です。2 つのピラーは、境界を越えてフィールド名を漏らすことなく合成されます。

アノテーションバインディングのターゲット

Feature 自体はアノテーションバインディングを宣言しません。バインディングは Manifest の mappings.features.annotations マップが保持します。Feature はルーティングのターゲットとして、間接的にバインディングの関係に参加します。各バインディングは feature: フィールドで Feature の型を指定し、バインディングの maps.infra リストと maps.values リストは、指定された Feature の spec.schema.infra.<path> プロパティと spec.schema.values.<path> プロパティへのドット区切りのパスを宣言します。

カタログのロード時に、コンパイラはバインディングの maps リストにあるすべてのドット区切りのパスが、ターゲットの Feature の spec.schema が指定されたピラーで実際に宣言しているプロパティに対応していることを検証します。Feature のスキーマが宣言していないパスへルーティングするバインディングは、明確な OPS_ERROR でカタログのロードを停止させ、そのバインディング、ターゲットの Feature、およびルーティングに使われたピラーとパスを示します。バインディングは Manifest に記述されており、Manifest はオペレーターのドキュメントだからです。したがってスキーマの作成者は、spec.schema.values.<path> または spec.schema.infra.<path> の下に宣言したプロパティはすべてバインディングのターゲットとして到達可能であることを把握できます。逆に、Manifest のバインディングがルーティングに使うプロパティは、すべてターゲットの Feature のスキーマに存在する必要があります。

Aggregate 側または Release 側のアノテーションがバインディングに一致すると、コンパイラは Feature のアタッチメントを合成し、そのピラーのペイロードがアノテーションの値を指定されたパスへルーティングします。合成されたアタッチメントは、同じ箇所で作成者が明示的に宣言した Feature のアタッチメントと構造上区別できません。下流のレンダリング、検証、および FeatureRecipe のテンプレートコンテキストは、どちらの形も同じように扱います。バインディングの形、サイドとピラーの区分、および明示的なアタッチメントを優先する規律については、entities/manifest.md の §“Annotation-Driven Feature Bindings” を参照してください。Aggregate 側のカスケードのルールと記述例については、providers/well-known-annotations.md の §“Aggregate-side annotation cascade” を参照してください。

assertions: ブロック

Feature.spec.assertions: は、Feature コントラクトのアーキテクチャ上の不変条件を表す名前付きルールの省略可能なマップです。これは、Feature の values: と、アタッチ先 Component の解決済み状態にまたがるフィールド横断のルールです。各キーは失敗メッセージに表示されるルール識別子であり、各値は Go テンプレートの本体です。コンパイラはこれらをスキーマ検証の後、バインドされた FeatureRecipe のレンダリングの前に、記述された順序で評価します。最初に失敗したルールが、そのルール固有のエラーメッセージとともにビルドを停止させます。

spec:
appliesTo: "component.aggrega.ai/type=server"
assertions:
active-active-needs-two-replicas: |
{{- if and (eq .values.mode "active-active") (lt .values.replicas 2) -}}
{{- fail "mode=active-active requires replicas >= 2" -}}
{{- end -}}

Component のアサーションと同様に、Feature のアサーションはコントラクトレベルの不変条件を表します。これは、どの FeatureRecipe がレンダリングを実装するかにかかわらず、Feature のアタッチメントが満たさなければならない性質です。特定の実装に依存するフィールド横断のルール(Wasm プラグインの要件、チャート固有の癖など)には、代わりに FeatureRecipe の assertions: フィールドを使用します。完全な記述文法、テンプレートコンテキスト、および Feature と FeatureRecipe のアサーション間の責任分担については、templates/assertions-block.md を参照してください。