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

`assertions:` ブロック

Component、Feature、Recipe、FeatureRecipe は、省略可能な spec.assertions: フィールドを持ちます。これは名前付きルールのマップで、コンパイラはスキーマ検証の後、レンダリングの前にこれを評価します。各キーは失敗メッセージに表示されるルール識別子で、各値は Go テンプレートの本体です。assertions: の直下に単一のテンプレート本体を書く形はこのフィールドの形ではなく、エンティティの読み込み時に拒否されます。そのため、すべてのルールはそれぞれ固有の名前の下に記述します。このブロックは、JSON Schema では簡潔に表現できないフィールド横断ルールを表します。つまり、複数のフィールドが関わり、どれか単一のフィールドが「検証対象」とはならない不変条件です。このページでは、記述の文法、評価フェーズ、テンプレートコンテキスト、そして Component / Feature のアサーション(契約のアーキテクチャ上の不変条件)と Recipe / FeatureRecipe のアサーション(特定の provider の実装上の不変条件)の責任分担について説明します。

フィールド単位の制約(範囲、パターン、列挙、フォーマット)には、schema: 内で JSON Schema のネイティブキーワードを使用します。フィールド単位のカスタム述語には、コンパクト形式の validate: フィールドを使用します。条件付きの形には when: を使用します。assertions: フィールドはこれらを補完するもので、真のフィールド横断ルールを置く場所です。

フィールドが現れる場所

assertions: を持つことができる 4 つのエンティティ:

  • Component — Component コントラクトのアーキテクチャ上の不変条件。
  • Feature — Feature コントラクトのアーキテクチャ上の不変条件。
  • Recipe — Recipe の基盤となるチャートまたはモジュールの実装上の不変条件。
  • FeatureRecipe — FeatureRecipe の基盤となる仕組みの実装上の不変条件。

このフィールドはいずれのエンティティでも省略可能です。フィールド間にまたがるルールを持たないエンティティでは、このフィールド自体を省略します。

アサーションが実行されるタイミング

アサーションの評価フェーズは、コンパイルパイプラインにおいてスキーマ検証とレンダリングの間に位置します。

  1. 解決:パラメータの検証と補間、続いて schema: / usesSchema: / featuresSchema: に対するスキーマ検証。
  2. トポロジーの構築とグラフの確定:グラフが組み立てられます。
  3. 静的解析:各 uses: ソケットのセレクターを、その接続が到達するコンポーネントのラベルに照らしてチェックします。
  4. Component / Feature のアサーションを各インスタンスに対して評価します。
  5. Recipe のバインド。
  6. Recipe / FeatureRecipe のアサーションをバインドされたインスタンスに対して評価します。
  7. レンダリング: マッピングテンプレートを評価し、出力を生成します。

2 つのアサーションフェーズは、あらゆるレンダリングより前に実行されます。チャートはレンダリングされず、Compose ファイルも生成されません。Recipe のアサーションが実行される前にプロバイダに問い合わせられる唯一の事項は、バインドされた各ノードのリソースに付ける名前であり、これは Recipe の provides から読み取れます。アサーションが失敗すると、そのアサーション固有のエラーメッセージとともにビルドは直ちに停止し、後続のステップは実行されません。

2 つのフェーズの分割は責任の分割を反映しています。Component レベルのルールはどの Recipe がバインドされるかに関係なく適用されるため、バインドの前に発火します。Recipe レベルのルールは特定の Recipe の選択を前提として適用されるため、バインドの後に発火します。

テンプレートコンテキスト

Component および Feature の assertions: では、テンプレートコンテキストは解決済みのインスタンス状態を公開します。

  • .values — 開発者の values の内容。
  • .infra — Ops の infra の内容(Aggregate または Release から)。
  • .uses — 解決済みの uses: 接続で、それぞれソケットのセレクターに照らしてチェック済みであり、作成者が記述した形をとります。ソケット名をキーとし、各ソケットの下ではそのソケット上の各接続のエイリアスをキーとします。エイリアスとは、作成者がソケットの下で接続に付けた名前、またはリスト要素として記述された接続の場合はそのターゲットです。各接続のエントリは接続そのものを記述し、ターゲットが公開したものは何も持ちません。target は解決済みターゲットのインスタンス ID、alias はキーとなっている名前の繰り返しであり、origin_feature は Feature のアタッチメントがその接続を作成した場合に存在します。これらと並んで、Recipe テンプレートが同じ接続の .context.uses.<alias> エントリで読むのと同じ名前で 3 つの事実が置かれ、それぞれの内容は template-context-contract.md に記載されています。labels はターゲットのラベルであり、アサーションが実行される component のラベルでは決してありません。values は接続上に記述された値、features は接続上に記述されたアタッチメントで、それぞれが埋めるスロットをキーとします。3 つはいずれもすべての接続に存在し、接続が何も持たない場合は空です。また features の下のアタッチメントは、後述の .features が示すのと同じ形をとります。したがって .uses.<socket>.<alias>.target は 1 つの接続の解決済みターゲットを、.uses.<socket>.<alias>.labels はそのターゲットのラベルを読みます。複数の接続を持つソケットはそれぞれのエントリを持ちます。そして、このマップを通じてターゲットが公開した値を参照しようとすると、エントリにそのようなフィールドがないため停止します。
  • .features — 解決済みのアタッチメントで、作成者が各アタッチメントに付けたインスタンス名をキーとします。各エントリは type(アタッチされた Feature のカタログ URI)、resolved_version(このビルドでバインドされたバージョン)、values(アタッチメント自身の開発者意図の内容)を持ちます。component の接続のいずれかに記述されたアタッチメントは、Recipe テンプレートの .features に含まれないのとまったく同様に、ここにも含まれません。それは接続の下、.uses.<socket>.<alias>.features.<slot> で、同じ形で読みます。
  • .metadata — 評価対象のインスタンスです。その instance_id、その component 型と resolved_version、その boundary_path、そしてビルドの aggregate_name、aggregate_version、release_version です。

Recipe および FeatureRecipe の assertions: では、コンテキストに Recipe 固有のフィールドが追加されます。

  • .provides — 評価対象の component の解決済み provides: 値で、アサーションの実行時点で計算済みです。ターゲットの公開値はこのサーフェスにはなく、代わりにレンダーコンテキストで呼び出し側に届きます。
  • .locals — Recipe のローカル変数。
  • .recipe.metadata — Recipe の name と version、およびその capability。
  • .recipe.source — Recipe のソースポインター。

フィールドアクセスには標準の Go テンプレート構文(.values.architecture、.uses.databases.primary.target)を使います。停止させる構文は Loud Guardrails 契約に従う {{ fail "message" }} です。失敗したアサーションは、違反した不変条件を明示する、明確で具体的なビルド時エラーを生成します。

このサーフェスは missingkey=error で評価されます。 コンテキストが持たないキーへの参照は、何もない値としてレンダリングされるのではなく、エンティティ、インスタンス、アサーション、欠けているキーを示してビルドを停止します。この厳格さこそがアサーションを信頼できるものにしています。参照が空にレンダリングされる述語は何もない値と比較して合格してしまうため、たった 1 つのタイプミスで、アサーションが強制するために書かれたルールが黙って無効になってしまいます。また、素の参照はフォールバックが実行される前に解決されるため、任意フィールドには存在を考慮した形式が必要です。サーフェスごとの欠落キーのポリシーとその下で機能する形式は errors/fatal-halts.md に記載されています。

ソケット上の接続を読む。 ソケットのエントリは、何を保持していても同じ形をとります。接続ごとに 1 つのエントリが、そのエイリアスの下に置かれます。アサーションは 1 つの接続をそのエイリアスで読み、ソケットを数えるか range で走査してその上のすべての接続を確認し、ソケット自身のキーを調べて配線されているかどうかを確かめます。Aggregate のエントリが次のように記述する component があるとき、

uses:
models:
local: { target: llama }
fast: { target: turbo }

以下のアサーションはそれぞれの方法で読みます。

assertions:
# The socket's presence: the socket key alone, however many connections it holds.
models-wired: |
{{- if not (hasKey .uses "models") -}}
{{- fail "wire at least one model to the models socket" -}}
{{- end -}}
# Every connection on the socket: a range visits each one.
every-model-distinct: |
{{- $seen := list -}}
{{- range $alias, $connection := (optional .uses "models" dict) -}}
{{- if has $connection.target $seen -}}
{{- fail (printf "connection %s points at %s, which another models connection already points at" $alias $connection.target) -}}
{{- end -}}
{{- $seen = append $seen $connection.target -}}
{{- end -}}
# One connection, by the alias it was written under; guarded, because the
# connection is optional.
fast-is-not-local: |
{{- with (optional .uses "models" dict) -}}
{{- if and (hasKey . "fast") (hasKey . "local") (eq .fast.target .local.target) -}}
{{- fail (printf "the fast and local connections both point at %s" .local.target) -}}
{{- end -}}
{{- end -}}

range はソケットの接続をエイリアスのアルファベット順に巡回します。ここでは fast が local より先で、Aggregate が記述した順ではありません。接続を 1 つだけ持つソケットも同じ方法で読みます。.uses.models.local.target は、fast が隣に配線されているかどうかにかかわらず llama を読み、.uses.models.target はどの接続も指さないため停止します。

component が持つすべての接続は、ここにそれぞれ独自のエントリを持ちます。1 つの component の 2 つの接続がエイリアスを共有することはないためです。これは、同じソケット上でも 2 つのソケットにまたがっても、各接続をどのドキュメントやアタッチメントが作成したかにかかわらず成り立ちます。ビルドはそのような組を、両方の接続とそれぞれの記述箇所を示して、アサーションの実行前に拒否します。同じターゲットを 2 回挙げるリストはそのような組です。リスト要素のエイリアスはそのターゲットだからです。同じ component 上で、component 自身の local 接続とアタッチメントの local 接続が並ぶ場合も同様です。

接続が持つものを読む。 接続に関するルールは、ターゲットが何か、開発者が接続に何を記述したか、接続に何がアタッチされているかを読めるため、どの Recipe がバインドしても成り立ちます。models ソケットで unauthenticated 値と credential スロットを宣言する Component は、カタログがホスト型サービスとラベル付けしたターゲットへの接続が、認証情報もオプトアウトも持たない場合にその接続を拒否できます。

assertions:
hosted-model-needs-a-credential: |
{{- range $alias, $connection := (optional .uses "models" dict) -}}
{{- $hosted := eq (optional $connection.labels "component.aggrega.ai/hosting" "") "managed" -}}
{{- $optedOut := optional $connection.values "unauthenticated" false -}}
{{- if and $hosted (not (hasKey $connection.features "credential")) (not $optedOut) -}}
{{- fail (printf "the models connection %s reaches a hosted model with no credential: attach one under credential, or set unauthenticated: true on the connection" $alias) -}}
{{- end -}}
{{- end -}}

ラベルは labels から読みます。これはターゲット、つまりモデルのものであり、component 自身のものでは決してありません。オプトアウトは接続の values から読み、認証情報は接続の features の下のスロットです。ターゲットがそのようなラベルを持たない場合や、接続がそのような値を持たない場合があるため、いずれも optional または hasKey で読みます。ラベルが何を意味するかはカタログの慣例です。ビルドは文字列を運び、その意味はアサーションが決めます。

アサーションの .uses は Recipe テンプレートの .context.uses とは異なり、一方のために書いた参照はもう一方には通用しません。 レンダーコンテキストは同じエッジのより豊かな投影を持ちます。キーはエイリアスのみで、ソケット名はエントリ上のフィールドとなり、各ターゲットの公開値は provides の下にネストされます。そのため、アサーションが .uses.<socket>.<alias>.target を読むところで、Recipe テンプレートは .context.uses.<alias>.provides.<name> を読みます。両方のビューが持つ事実は名前を共有しますが、パスは共有しません。.context.uses.<alias>.labels と .uses.<socket>.<alias>.labels は同じターゲットのラベルであり、values と features も同様にどちらでも同じ接続を読みます。両方のアサーションフェーズはレンダリングの前に評価されます。そのため、アサーションから見たエッジはターゲットが公開したものを何も持たず、その上のアタッチメントも provides を持ちません。

テンプレートコンテキストのより広い形とフィールドごとの利用可否のセマンティクスについては、template-context-contract.md を参照してください。

このサーフェスでの数値

アサーションは、記述された数値を値テンプレートとまったく同じように読みます。値テンプレートでの数値を参照してください。

  • 比較。 6 つの比較は、それぞれをどの種類が保持しているかにかかわらず、2 つの数値を値で読みます。lt .values.replicas 1.5 と eq .values.replicas 3.0 はここでも値テンプレートと同じ結果を返し、記述された 0.1 はアサーション内に書かれた 0.1 と eq であり、数値と引用符付きのテキストを比較すると同じ文言で停止します。
  • 空であること。 記述された 0 は空です。if と with に対しては偽、empty に対しては真であり、default によって置き換えられます。作成者が値を書いたかどうか(0 を含む)を問うルールは、存在を判定するヘルパーで問います。記述された 0 に対して、hasKey .values "replicas" は真であり、optional .values "replicas" 1 は 0 を返します。値がゼロかどうかを問うルールは比較します:eq .values.replicas 0。存在と空であることでは、この 2 つの問いを並べて示しています。
  • 出力。 fail メッセージが出力する数値は、値テンプレートの出力と同じように読めます。整数は整数のまま出力されるため、printf "%d" はその桁を出力し、それ以外の数値は最短の正確な 10 進表記で出力されるため、記述された 0.0000001 は 0.0000001 と読めます。

Component / Feature のアサーション — アーキテクチャ上の不変条件

これらは、どの Recipe が Component をバインドするかにかかわらず成り立つルールを表現します。ルールは実装ではなく、コントラクトの性質です。

apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/datastore/mariadb
version: 1.0.0
labels:
component.aggrega.ai/type: stateful-server
component.aggrega.ai/category: datastore
spec:
schema:
values:
architecture: { type: string, enum: [standalone, replication], default: standalone }
primary:
replicaCount: { type: integer, min: 1, max: 9, default: 1 }
secondary:
replicaCount: { type: integer, min: 0, max: 9, default: 0 }
assertions:
# Replication mode requires at least 2 secondary replicas.
replication-needs-two-secondaries: |
{{- if eq .values.architecture "replication" -}}
{{- if lt .values.secondary.replicaCount 2 -}}
{{- fail "architecture=replication requires secondary.replicaCount >= 2" -}}
{{- end -}}
{{- end -}}
# Total node count limit for safe replication coordination.
total-node-count-within-cap: |
{{- $total := add .values.primary.replicaCount .values.secondary.replicaCount -}}
{{- if gt $total 9 -}}
{{- fail (printf "total node count must not exceed 9; got %d" $total) -}}
{{- end -}}

どちらのルールも MariaDB コントラクトの性質を表現しています。Bitnami チャートであれ、独自に作成した代替実装であれ、どの Recipe がバインドされてもルールは適用されます。

{{- ... -}} による空白制御は重要です。assertions テンプレートは出力を生成せず、{{ fail }} による副作用のみを持ちます。空白のトリムにより、成功時にはレンダリングされたテンプレート本体が空に保たれます。

Recipe / FeatureRecipe のアサーション — 実装の不変条件

これらは、Recipe が取り込む特定のチャートまたはモジュールについて成り立つルールを表します。このルールは契約ではなく、実装の性質です。

apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: bitnami/datastore/mariadb/k8s
version: 1.0.0
spec:
capability: helm
implements: core/datastore/mariadb:^1.0.0
source:
# Keys this provider defines for itself; a source the build fetches is written as { kind, url, version } instead.
chart: oci://registry-1.docker.io/bitnamicharts/mariadb
version: "20.0.0"
valuesMapping:
$import: BitnamiHelpers#/mappings/MariaDBBitnamiCore
assertions:
# Bitnami chart 20.x requires an explicit ServiceMonitor namespace when
# replication and metrics scraping are both enabled.
service-monitor-namespace-required: |
{{- if and (eq .values.architecture "replication") .values.metrics.serviceMonitor.enabled -}}
{{- if not .values.metrics.serviceMonitor.namespace -}}
{{- fail "Bitnami MariaDB 20.x requires metrics.serviceMonitor.namespace when architecture=replication and metrics.serviceMonitor.enabled=true" -}}
{{- end -}}
{{- end -}}
# ARM-node incompatibility.
arm-rejects-hard-anti-affinity: |
{{- if and (eq .values.primary.podAntiAffinityPreset "hard") (eq .infra.cpu_arch "arm64") -}}
{{- fail "Bitnami MariaDB 20.x is incompatible with ARM nodes when podAntiAffinityPreset=hard; use 'soft' or omit" -}}
{{- end -}}

各ルールは Bitnami チャート 20.x の実装に固有のものです。別の MariaDB Recipe がバインドされる場合(自作のチャートや代替の実装など)、これらのルールは適用されません。Component レベルのルール(replication-needs-two-secondaries、total-node-count-within-cap)は契約の性質であるため、引き続き適用されます。

Component と Recipe のアサーションが分かれている理由

2 つの役割は似て見えます(どちらもフィールド横断のルールに対して {{ fail }} による停止を実行します)が、責任の分担は構造上欠かせないものです。

  • Component のアサーションは契約の一部です。 開発者が architecture: replication を secondary.replicaCount: 1 とともに記述した場合、どの Recipe がバインドされるかにかかわらずビルドは拒否されます。将来の代替 Recipe があってもそれは変わりません。
  • Recipe のアサーションは実装の一部です。 アーキテクトが Recipe として Bitnami chart 20.x を選択した場合、その chart には固有の癖(serviceMonitor.namespace の要件、ARM ノードのバグ)があります。これらは別の chart には当てはまりません。

両方の種類のルールを Component に同居させると、契約とその実装が絡み合ってしまいます。Component は、どの実装ルールを適用するかを知るためにバインドされた Recipe を参照する必要が生じ、Component と Recipe の分離が崩れます。ルールを本来の場所に分けることで、責任モデルが明快に保たれます。分割による実行時のコストは無視できる程度です。どちらのフェーズもレンダリング前に実行され、エンティティ、インスタンス、ルールを示す同じ Loud Guardrails 診断 E0033 で停止します。

fail メッセージの慣例

{{ fail "..." }} の引数は、ユーザーに表示されるビルド時のエラーです。慣例は次のとおりです。

  • 制約を明示する — 「architecture=replication requires secondary.replicaCount >= 2」。
  • 関係する場合は値を明示する — 「total node count must not exceed 9; got 12」。
  • 可能な場合は修正方法を提示する — 「use ‘soft’ or omit the field」。
  • 専門用語を避ける — 読み手はアサーションを書いたアーキテクトではなく、Aggregate を記述した開発者です。

長いメッセージや値を含むメッセージには printf を使用します。

{{- fail (printf "field %s exceeds limit: got %d, max is %d" .field .value .max) -}}

コンパイラは、エンティティ名、アサーションのソース位置、失敗メッセージとともに、Loud Guardrails のエラー形式でメッセージを提示します。この診断は、開発者が根本原因を特定して修正できる程度に具体的です。

作成者が sensitive: true と宣言した値は、そのメッセージが引用する箇所ではどこでも <redacted> と表示されます。そのため、宣言されたフィールドの値をメッセージで明示しても安全です。診断は引き続きルールとフィールドを明示し、値だけが伏せられます。結果がそのような値の内容に依存するアサーション(リテラルとの比較、接頭辞のテストなど)は、メッセージの代わりに、失敗テキストが伏せられていることを報告します。ルール全体については vocabulary/compact-form-authoring.md の「What a refusal says about a declared value」を参照してください。

assertions: が置き換えないもの

assertions: は、複数フィールドにまたがるルールを置く場所です。次のものは置き換えません。

  • schema: 内の JSON Schema 制約 — フィールド単位のルール(範囲、パターン、列挙、形式、型)は、JSON Schema のネイティブキーワードで記述します。
  • コンパクト形式の validate: フィールド — 単一フィールドをスコープとする、フィールド単位のカスタム述語です。ルールが特定のフィールドに適用される場合は validate: を使用し、ルールが複数のフィールドに関わり、どのフィールドも単独では「検証対象のフィールド」とならない場合は assertions: を使用します。
  • コンパクト形式の when: フィールド — 条件付きの形状(サブツリーの制約が適用されるかどうか)です。形状の変化には when: を使用し、値の組み合わせが無効であり、それが自由形式の述語としてより適切に表現できる場合は assertions: を使用します。
  • ランタイムチェック — assertions: はコンパイル時にのみ実行されます。ランタイムのクラスター状態(稼働中の IP、vault の内容、ランタイムの pod ステータス)に依存するものはすべて、決定的なポインター文字列として表現する必要があります(AOT 純粋性の契約を参照)。

実例

最小構成 — 単一のアーキテクチャルール

spec:
assertions:
replication-needs-two-secondaries: |
{{- if and (eq .values.architecture "replication") (lt .values.secondary.replicaCount 2) -}}
{{- fail "replication requires secondary.replicaCount >= 2" -}}
{{- end -}}

中規模 — 複数ルールの Component コントラクト

spec:
assertions:
# Replication minimum.
replication-needs-two-secondaries: |
{{- if eq .values.architecture "replication" -}}
{{- if lt .values.secondary.replicaCount 2 -}}
{{- fail "architecture=replication requires secondary.replicaCount >= 2" -}}
{{- end -}}
{{- end -}}
# Total node limit.
total-node-count-within-cap: |
{{- $total := add .values.primary.replicaCount .values.secondary.replicaCount -}}
{{- if gt $total 9 -}}
{{- fail (printf "total node count exceeds 9: got %d (primary=%d, secondary=%d)"
$total .values.primary.replicaCount .values.secondary.replicaCount) -}}
{{- end -}}
# A ServiceMonitor scrapes the metrics exporter, so it needs one.
service-monitor-needs-metrics: |
{{- if and .values.metrics.serviceMonitor.enabled (not .values.metrics.enabled) -}}
{{- fail "metrics.serviceMonitor.enabled=true requires metrics.enabled=true" -}}
{{- end -}}

本番 — 実装ルールを持つ Recipe

spec:
assertions:
# Bitnami 20.x: serviceMonitor namespace requirement.
service-monitor-namespace-required: |
{{- if and (eq .values.architecture "replication") .values.metrics.serviceMonitor.enabled -}}
{{- if not .values.metrics.serviceMonitor.namespace -}}
{{- fail "Bitnami MariaDB 20.x requires metrics.serviceMonitor.namespace when architecture=replication and metrics.serviceMonitor.enabled=true" -}}
{{- end -}}
{{- end -}}
# TLS certificate consistency.
tls-needs-both-certificate-files: |
{{- if .values.tls.enabled -}}
{{- if not (and .values.tls.certFilename .values.tls.certKeyFilename) -}}
{{- fail "tls.enabled=true requires both tls.certFilename and tls.certKeyFilename" -}}
{{- end -}}
{{- end -}}
# Replication-mode storage class consistency.
replication-needs-one-storage-class: |
{{- if eq .values.architecture "replication" -}}
{{- $primaryClass := .values.primary.persistence.storageClass -}}
{{- $secondaryClass := .values.secondary.persistence.storageClass -}}
{{- if and $primaryClass $secondaryClass (ne $primaryClass $secondaryClass) -}}
{{- fail "replication mode requires primary and secondary to use the same storageClass" -}}
{{- end -}}
{{- end -}}

ツールとの統合

  • aggrega build はスキーマ検証とレンダリングの間でアサーションを評価します。失敗したアサーションは、そのアサーションの {{ fail }} メッセージとともにビルドを停止します。
  • aggrega validate は、アーティファクトを書き出さずに、レンダリングに先立って同じ正しさの検査を適用します。ソースが取得されない Recipe については、合成された最小限の Aggregate、Manifest、Release を用いて実際のコンパイルパイプラインを実行するため、不正な形式のアサーションテンプレートや、未知のフィールドを参照するアサーションは正しさのエラーとして検出されます。ソースが取得される Recipe のアサーションは、ビルドによって評価されます。そこで fail を呼び出すアサーションは、そのメッセージを含む警告として報告され、検査は成功します。合成された Release は、実際の Release が設定する値ではなくプレースホルダーとデフォルト値を保持しているため、アサーションの判定はビルドに委ねられます。詳しくは失敗したアサーションは警告になるを参照してください。(aggrega lint が扱うのは公開に関する慣例であり、アサーションの正しさではありません。)
  • Sprig テンプレートに対応した IDE では .values.X 参照がハイライトされます。IDE 統合が設定されている場合、ホバー時のドキュメントはスキーマ定義に解決されます。