appliesTo とセレクタ
モディファイアシステムは、Feature がどのノードにアタッチされるかを制御します。Feature
はラベルセレクタを宣言し、コンパイラのネイティブなラベルマッチングエンジンが、
静的解析ステージで各ターゲット Component の metadata.labels に対してそれらを評価します。
同じエンジン(および同じセレクタ文法)は、ノード間の型安全性のための usesSchema
ソケットセレクタも評価するため、言語内のあらゆるセレクタ面で 1 つの語彙が使われます。
2 つのエンベロープ
Feature の spec は最大 2 つのセレクタフィールドを持ちます。
appliesTo:AND 合成の面です。Kubernetes 形式の単一のラベルセレクタ文字列で、アタッチが有効となるには、 カンマ区切りのすべての要件が満たされる必要があります。appliesToAnyOf:OR 合成の面です。セレクタ項目のリストで、 いずれか 1 つの項目が一致すればアタッチが成立します。各項目は、 文字列形式のセレクタ(appliesToと同じ文法で、文字列内の要件は AND で結合されます)、 または等価性のみで照合されるフラットなキーと値のマップのいずれかです。
Feature が両方を宣言した場合、結果はエンベロープ間で AND されます。つまり
appliesTo 文字列が満たされ、かつ少なくとも 1 つの appliesToAnyOf 項目が
一致する必要があります。省略された、または空のセレクタは制約を宣言せず、
あらゆるラベルセットに一致します。どちらのフィールドも持たない Feature は、
開発者が配置したどこにでもアタッチされます。
spec: appliesTo: "compliance.aggrega.ai/scope in (pci), tier notin (dev, staging)" appliesToAnyOf: - { component.aggrega.ai/type: stateful-server } - "datastore.aggrega.ai/engine in (relational, document, vector)"文字列の文法
セレクタ文字列は、kubectl get -l
が受け付けるラベルセレクタ構文に従います。カンマ区切りの要件を AND で合成し、
各要件は次の 6 つの形式のいずれかです。
| 形式 | 意味 |
|---|---|
key=value | ラベルが存在し、値がちょうどこの値である |
key!=value | ラベルが存在しない、または異なる値で存在する |
key in (v1, v2) | ラベルの値がセットのいずれかである |
key notin (v1, v2) | ラベルが存在しない、またはその値がセットの外にある |
key | ラベルが存在する(値は任意) |
!key | ラベルが存在しない |
キーには DNS 形式のプレフィックスを付けられます(team.aggrega.ai/owner)。
演算子の語彙は 6 つからなる閉じた集合であり、エンジンは正規表現、部分文字列、
数値比較をサポートしません。
appliesTo: "component.aggrega.ai/type in (server, worker), !legacy.aggrega.ai/exempt"6 つの形式に当てはまらない要件は、推測されることなく拒否されます。
- 空の要件:先頭、末尾、または二重のカンマ、あるいは
区切り文字だけの文字列です。
"tier=frontend,"と" , , "は、 より少ない要件や要件なしとして読まれるのではなく、拒否されます。 - 空白または文法自体の文字を含むキー:
=、!、(、)、およびカンマで、これらは形式を互いに区別する文字です。!はラベルキーのみを指すため、!tier=frontendは拒否されます。 frontend を除外するために書かれたこの記述は、そうでなければ 「tier=frontendという名前のラベルが存在しない」と読まれ、すべての コンポーネントがそれを満たしてしまいます。値を除外するにはtier!=frontendと書きます。 同様にtier in frontendも拒否され(セットはtier in (frontend)と書きます)、tier: frontendも拒否されます。 - 閉じていないセット:
)のないin (またはnotin (です。
値はいかなる文字集合にも制限されません。値は演算子の後のテキストから
前後の空白を除いたもので、ラベルの値と書かれたとおりに比較されます。
したがって tier==frontend は値が =frontend のラベルを求めます。== は
等価性の別表記ではありません。上記のキーの規則以外では、キーも値も判定されません。
ラベルは、エンジンが比較する不透明な文字列です。
検証が行われる場所
セレクタは 2 つの層で検査され、それぞれの厳密さは意図的に異なります。
- JSON Schema の
patternは緩い外側のゲートです。 Feature スキーマはappliesTo(および文字列形式のappliesToAnyOf項目)を、 明らかに不正な形のみを拒否する境界パターンを持つ文字列として宣言します。 これは意図的に寛容であり、スキーマはエンジンが評価するセレクタを拒否することはありません。 - パーサーがバリデータです。 コンパイラのセレクタパーサーが文法を担います。パーサーが拒否するセレクタ(上記のいずれかの形)は、セレクタ、それを宣言する Feature、ソケットまたはスロット、および読み取れなかった要件を示す診断とともにビルドを停止します。パースの失敗は明示的かつ具体的に報告され、黙ってスキップされることはありません。ビルドでは、パーサーはセレクタが評価される場所、すなわち Feature の各アタッチ、ソケットを通じて配線される各エッジ、スロットの各充填で実行されます。
aggrega validateは、カタログ全体に対しても、1 つの Component または Feature に対しても、エンティティのドキュメントが宣言するすべてのソケットとスロットのセレクタも読み取ります。そのため、何も使用しないソケットまたはスロット上の不正なセレクタはそこで、ビルドと同じコードと文言で拒否されます。何もアタッチしない Feature 上の不正なappliesToは、何かがそれをアタッチするまで報告されません。
パースできても一致しないセレクタは、それ自体はエラーではなく、 満たされない制約です。静的解析では、ターゲットのラベルが Feature のセレクタを 満たさないすべての Feature アタッチが、フィーチャーインスタンス、ターゲットノード、 そのラベル、および制約を示す違反診断を生成します。アナライザーは停止する前に すべての違反を収集するため、1 回のコンパイルですべてが表示されます。
コンパイラが行わないこと
コンパイラはラベルのセマンティクスに依存しません。見つけたラベル文字列をそのまま評価します。component.aggrega.ai/type を特別なものとして認識せず、カテゴリ値が標準カタログの閉じた集合に属するかを検証せず、キー名から意味を推論しません。ラベルの語彙自体(運用上の型の契約、認知カテゴリの軸、ロールごとのケイパビリティラベル)は、コンパイラではなく、カタログ作成者と公開用リンターによって維持される標準ライブラリの慣例です。独自のカタログを作成する企業は、独自のラベル語彙を自由に定義でき、セレクタエンジンはそれを同じように評価します。標準カタログが使用する 3 軸のラベルスキームについては architecture/13-catalog-and-registry.md を、ラベルごとの説明については architecture/09-ai-features.md §1.2 を参照してください。
言語全体でのセレクタの共通性
usesSchema ソケットセレクタ(selector: "component.aggrega.ai/type=stateful-server")
と、それらから合成される x-aggrega-selector: アノテーションは、
Feature の appliesTo と同じ文法、同じエンジンを使用します。作成の知識は
そのまま 1 対 1 で通用します。ソケットセレクタとして機能する文字列は、
アタッチセレクタとしても機能します。ソケット側の説明については、
topology-triad.md と
entities/component.md を参照してください。
Feature 側の作成面(spec フィールド、アタッチの実例、および extends
継承との相互作用)については、
entities/feature.md §Label-Based Attachment を参照してください。