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

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

parameters: ピラーは、Release によって充足され、コントラクトで検証されたパラメータ値を保持します。そのアクセス可能性は、2 つの並行するメンタルモデルによって決まります。

  • 値テンプレートのサーフェス(Aggregate 内の component / feature / sub-aggregate の values: 文字列、および Recipe の valuesMapping、FeatureRecipe の injectMapping と provides、Workload の本体)は、パラメータ値を補間済みのリテラルとして消費します。解決処理内の補間パスは Aggregate のテキスト全体をテンプレートとして評価し、すべての {{ .parameters.<slot> }} 参照を解決済みの値で置き換えます。下流の値テンプレートのサーフェスが、そのテンプレートコンテキストで .parameters を直接参照することはありません。
  • パステンプレートのサーフェス(Release の境界でオペレーターが記述する directory: および subDirectory: テンプレート)は、レンダリング中のパステンプレート評価時に .parameters.<slot> を直接読み取ります。マージされたパラメータマップはレンダリングの終了まで読み取り可能なままであるため、パステンプレートは閉じた許可リストに照らして .parameters を読めます。

この非対称な許可(パステンプレートは .parameters を直接読み取り、値テンプレートは読み取らない)により、各層は必要なものを自ら所有できます。開発者側の values: は、解決済みの環境固有データを値テンプレートへ引き渡します。オペレーター側のパステンプレートは、Aggregate の values スキーマを経由することなく、リージョン / 環境 / アカウント ID のパラメータを参照します。

このページでは、補間パス、スロットごとの値の形、Aggregate の YAML 文字列内でのアクセスパターン、パステンプレートの例外、およびマージされたマップがどの期間読み取り可能であるかを説明します。Recipe / FeatureRecipe のテンプレートコンテキスト全体の形(.values、.infra、.uses など)については、template-context-contract.md を参照してください。コンパイルパイプライン全体におけるテンプレート箇所ごとの利用可否については、expansion-matrix.md を参照してください。Aggregate における型付きパラメータコントラクトの宣言の形については、entities/aggregate.md の §「Typed parameter contracts」を参照してください。境界の directory: / subDirectory: の評価時に .parameters.<slot> を含むパステンプレート変数の許可リストについては、path-template-variables.md を参照してください。

パラメーターのライフサイクル

コンパイラは、順序付けられた 4 つのフェーズでパラメーターを解決します。

  1. コントラクトの読み取り — Aggregate の spec.parameters: ブロックは、Release の値を参照する前にそれ自体として検査されます。そのため、何も制約できないスロットは、それを供給する Release がない場合でもビルドを停止させます。パラメーター自身の宣言にある負の minLength または maxLength は、Aggregate の読み込み時に、パラメーターとキーを示して拒否されます。すべての pattern(スロット自体のもの、および items、properties、valuesType の下にあるネストされたコントラクト内のもの)は正規表現としてコンパイルされ、コンパイルできないものは、パラメーター、パターン、理由を示して拒否されます。ネストされたコントラクト内の長さの境界には、この下限は適用されません。entities/aggregate.md を参照してください。
  2. デフォルトの補完 — default: が定義され、Release が値を供給していないスロットには、そのデフォルトが入ります。この時点で .parameters マップはスコープ内にあります。
  3. パラメーターコントラクトの検証 — マージされたマップ内の各値は、Release が供給したものか default: が補完したものかにかかわらず、Aggregate の spec.parameters.<slot> で宣言された type / enum / min / max / pattern / ネスト構造の制約に対して検証されます。pattern は、コントラクトの読み取り時にコンパイルされた式と照合されます。.parameters マップは、検査対象の構造化ペイロードとして、バリデーターのメモリ上のコンテキストに存在します。
  4. 補間 — コンパイラは、Aggregate のテキスト全体を YAML として読み取る前にテンプレートとして評価し、すべての {{ .parameters.<slot> }} 参照を解決済みの値に置き換えます。テキスト内のそれ以外の {{ もテンプレート構文として読み取られるため、独自の二重波括弧を含む値では、各 {{ を {{"{{"}} と記述します(独自の二重波括弧を含むテキストを参照)。補間は値テンプレートのサーフェスに対する置換の経路です。このパスの後、値テンプレートのコンテキストは .parameters を持たず、周囲の values: 文字列に書き込まれた解決済みの値を使用します。マージされたマップは、パステンプレートの評価をサポートするために、補間後もレンダリング全体を通じて読み取り可能なままです。その読み取り可能な期間はビルドの期間に限られます。コンパイラは解決済みのビューを呼び出し元に返すのではなく、それを使用するコンパイルに渡すため、そのビルドの外部からはマップに到達できません。パステンプレートのサーフェス(Release の directory: / subDirectory:)は、レンダリング中に、path-template-variables.md に記載された閉じた許可リストに対して .parameters.<slot> を読み取ります。

Aggregate YAML 文字列内のテンプレート(コンポーネントの values:、フィーチャーの values:、サブアグリゲートの parameters: パススルー式)は、補間パス中に標準の Go テンプレート構文で .parameters マップを読み取ります。Recipe および FeatureRecipe ファイル内のテンプレートは、テンプレートコンテキストで .parameters を受け取りません(サーフェスごとのコントラクトについては、後述の「下流のテンプレートコンテキストとの境界」を参照してください)。

独自の二重波括弧を含むテキスト

テキスト全体がテンプレートであるため、テンプレートではなく値に属する二重波括弧もテンプレートアクションとして読み取られます。よくあるのは、component の values: に保持されるフロープラットフォームの定義です。n8n はノードのパラメータ内の各式を ={{ $json.body.message }} のように二重波括弧で囲みます。Flowise のプロンプトは変数を {{question}} と記述し、Flowise の chatflow は 2 つのノード間の接続ごとに {{chatOpenAI_0.data.instance}} と書きます。また Langflow のエクスポートはそのコンポーネントのソースコードを保持しており、そこにも波括弧が現れることがあります。これらをそのまま Aggregate に書くと、ビルドは Aggregate の時点で E0158 により停止します。これは Fatal halts の「A {{ .parameters.* }} reference cannot be interpolated(parameters への参照を補間できない)」で説明されています。その理由には、行と、テンプレートエンジンが読み取れなかった最初のトークンが示されます。n8n の式であれば undefined variable "$json" です。YAML のコメントもテンプレートテキストであるため、コメント内に書いた {{ も同様に停止を引き起こします。

このような値の中の各 {{ は {{"{{"}} と書きます。これは結果が文字列 {{ になるテンプレートアクションであり、補間によって 2 つの波括弧が元に戻ります。閉じる }} はアクションの外ではプレーンテキストであるため、何もする必要はありません。補間は Aggregate のテキストに対して 1 回だけ実行され、Recipe テンプレートは .values から読み取ったものをデータとして書き出すため、復元された波括弧はエクスポートされたときのままレンダリング結果に届きます。

# Aggregate fragment — an n8n workflow definition carried as exported
spec:
components:
automation:
type: core/ai-agent/n8n
values:
workflow_id: support-reply
flow_definition: |
{
"name": "Support reply",
"nodes": [
{
"name": "Set reply",
"type": "n8n-nodes-base.set",
"parameters": {
"value": "={{"{{"}} $json.body.message }} for {{"{{"}} $env.SUPPORT_TEAM }}"
}
}
],
"connections": {}
}

プラットフォームは "value": "={{ $json.body.message }} for {{ $env.SUPPORT_TEAM }}" を受け取ります。

このような定義は、上の例のようにブロックスカラー(|)に入れてください。ブロックスカラーの中では、エスケープの引用符は通常の文字です。Aggregate のテキストは補間される前に YAML としても読み取られ、二重引用符で囲まれた YAML 文字列の中ではエスケープの " が文字列を閉じてしまうため、ファイルはパースできなくなり、ビルドは YAML エラーで停止します。

.parameters.<slot> アクセスパターン

宣言された各パラメータスロットには、.parameters マップのフィールドとしてアクセスできます。型に沿ったアクセスは、宣言された type に一致します。

# Aggregate fragment — parameter declarations
spec:
parameters:
region: { type: string, enum: [us-east-1, us-west-2] }
cache_ttl_seconds: { type: integer, min: 1, max: 86400, default: 60 }
enable_debug: { type: boolean, default: false }
components:
web:
type: core/web-server:1.0.0
values:
region: "{{ .parameters.region }}" # string
cache_ttl_seconds: {{ .parameters.cache_ttl_seconds }} # integer
debug: {{ .parameters.enable_debug }} # boolean

補間パスは、.parameters マップに対する Go テンプレートの評価を行い、その結果がドキュメント内のテンプレート式をその場で置き換えます。その後、Component / Feature の values: スキーマが、解決の補間後スキーマ検証フェーズで結果の値を検証します。

クォートの有無が引き上げられる型を決める

**文字列のリーフを対象とする参照はクォートし、それ以外の宣言型では裸のまま書きます。**この規則は YAML 自身のものであり、Aggrega が上乗せするものではありません。補間は充足された値をドキュメントのバイト列に代入するだけで、それ以外は何も行わないため、続くパースは結果を他のスカラーとまったく同じように読みます。裸の {{ .parameters.cache_ttl_seconds }} は充足された値自身の型を持ち、これによって整数パラメータは整数のリーフに、真偽値パラメータは真偽値のリーフに届きます。クォートされた "{{ .parameters.cache_ttl_seconds }}" は文字列を持ち、integer または boolean と宣言されたリーフはそれを拒否します。記述された値は Component または Feature の values: スキーマの型チェックで失敗し、診断は、その文字列が同様に満たさなかったであろう値空間の制約ではなく、型の不一致を示します。

他のテキストとスカラーを共有する参照は、どちらの書き方をしても文字列になります。代入後のドキュメントには読むべきスカラーが 1 つしかないためです。image: app:{{ .parameters.tag }} は app:1.4.0 になります。文字列以外のパラメータを文字列のリーフに入れる必要がある場合は、この形式を使います。

オブジェクト型と配列型のスロットへのアクセス

オブジェクト型のパラメータスロットは、宣言されたプロパティを .parameters.<slot> マップ上のネストしたフィールドとして公開します。配列型のスロットは Go テンプレートのスライスのセマンティクス(range、index、len)を公開します。

# Aggregate fragment — object-typed parameter
spec:
parameters:
database_config:
type: object
properties:
host: { type: string, required: true }
port: { type: integer, min: 1, max: 65535, default: 5432 }
ssl_mode: { type: string, enum: [disable, require, verify-full] }
components:
api:
type: core/compute/api:1.0.0
values:
db_host: "{{ .parameters.database_config.host }}"
db_port: {{ .parameters.database_config.port }}
db_ssl: "{{ .parameters.database_config.ssl_mode }}"

配列型のパラメータスロットは range による反復をサポートします。

# Aggregate fragment — array-typed parameter
spec:
parameters:
allowed_hosts:
type: array
items: { type: string, format: hostname }
min: 1
components:
ingress:
type: core/ingress:1.0.0
values:
# Compose a comma-separated list from the parameter array
hosts: "{{ range $i, $h := .parameters.allowed_hosts }}{{ if $i }},{{ end }}{{ $h }}{{ end }}"

Release が指定する各要素は補間の前に items の契約に照らしてチェックされるため、ホスト名ではない値(たとえば *)はビルドを停止させ、そのパラメータ、要素、フォーマットを示します。format が受け付ける名前と、それぞれがチェックする内容は vocabulary/compact-form-authoring.md に一覧があります。

補間中は Sprig テンプレートライブラリが利用でき、配列から文字列への簡潔な変換を行う join などのヘルパーを提供します。

hosts: "{{ join `,` .parameters.allowed_hosts }}"

デフォルト値の補完のセマンティクス

default: 宣言を持つパラメータスロットは、Release がそのスロットを省略した場合にデフォルト値を受け取ります。デフォルト値はコントラクト検証パスの実行前に適用されるため、検証は解決済みの値(Release が指定した値またはデフォルト値)を対象とします。

# Aggregate
spec:
parameters:
timeout_seconds:
type: integer
min: 1
max: 300
default: 30
components:
api:
type: core/compute/api:1.0.0
values:
timeout: {{ .parameters.timeout_seconds }}
# Release omits timeout_seconds — interpolation uses default: 30
# Release supplies timeout_seconds: 60 — interpolation uses 60
# Release supplies timeout_seconds: 0 — validation rejects (below min: 1)
# Release supplies timeout_seconds: 500 — validation rejects (above max: 300)
# Release supplies timeout_seconds: "thirty" — validation rejects (type mismatch)

required: true が付けられ default: のないスロットは、Release がそれを省略するとビルド時エラーを発生させます(E0165)。このエラーは、作成者が修正できるよう、スロットとコントラクト内でのその場所を示します。required: true も default: も持たないスロットは省略可能です。省略された場合、それへの各参照は空として補間され、その結果は Component の values: スキーマによって判定されます。

ネストしたオブジェクトのパラメータ

パラメータが type: object を宣言し、その properties: の子自体が default: 値を持つ場合、3 つの記述ケースがそれぞれ異なる結果を生みます。この違いを理解することは、パラメータ宣言が単一のスカラーではなく、データベース設定、フィーチャーフラグのまとまり、タイムアウトとリトライのポリシーといった構造化オブジェクトである場合に重要です。

ケース 1 — Release が親スロットを省略する。 コントラクトの子のデフォルト値が補完されます。ネストしたデフォルト値を宣言した Aggregate の作成者は、意図したとおりの動作を得られます。運用側がスロットを指定しない場合、設定はドキュメント化されたデフォルト値を使用します。

# Aggregate
spec:
parameters:
database:
type: object
properties:
host: { type: string, default: "localhost" }
port: { type: integer, default: 5432 }
# Release (parent omitted)
spec:
parameters: {}
# Resolved at template-interpolation time
parameters:
database:
host: "localhost"
port: 5432

ケース 2 — Release が親を明示的な空のマップとして記述する。 明示的な空は意図的なオプトアウトとして尊重されます。子のデフォルト値は補完されず、スロットは空のままです。運用側が上書き値を指定せずにコントラクトのネストしたデフォルト値を抑制したい場合、たとえば下流のコンシューマーがスロットの存在を期待しつつ中身は空であることを想定している場合に、この形式を使用します。

# Release (parent explicit empty)
spec:
parameters:
database: {}
# Resolved at template-interpolation time
parameters:
database: {}

ケース 1 との違いは意図的なものです。運用側は「デフォルト値を使う」(スロットを省略する)と「デフォルト値を抑制する」(スロットを {} として記述する)の両方を表現できます。これは Aggrega がアノテーションにおける明示的な null を扱う方法と同じです。aggrega.ai/<key>: null として記述されたアノテーションは、アノテーションを完全に省略することとは異なる意図的なオプトアウトです。

ケース 3 — Release が親を部分的に記述する。 Release が指定した子は記述された値を取り、Release が指定しなかった子はデフォルト値で補完されます。

# Release (partial)
spec:
parameters:
database:
host: "db.prod.example.com"
# Resolved at template-interpolation time
parameters:
database:
host: "db.prod.example.com" # Release-supplied
port: 5432 # filled from default

これは、選択したフィールドを上書きし、残りをコントラクトのデフォルト値のままにしたい Release 作成者にとっての一般的なケースです。

各形式の使い分け

  • コントラクトのデフォルト値を適用したい場合は、スロットを省略します。
  • スロットを存在させつつ意図的に空にしたい場合、つまりコントラクトのデフォルト値が環境に合わず、上書き値もない場合は、{} を記述します。
  • 一部を上書きし、残りにはコントラクトのデフォルト値を使いたい場合は、部分的に記述します。

「デフォルト値をください」のつもりで database: {} と書いた Release 作成者は驚くことになります。解決済みの値は補完されたデフォルト値ではなく、空になります。デフォルト値を得るには、スロットを完全に省略してください。

3 つのケースの振り分けは、あらゆるネストの深さで兄弟要素ごとに行われます。{ connection: {}, other_field: "x" } として記述された親は、connection が空(深さ 1 でのケース 2)で、other_field が Release の指定した値(深さ 0 でのケース 3)となる解決済みツリーを生成します。ケースはサブツリー全体に対する単一の判断としてではなく、兄弟要素ごとに独立して振り分けられます。

下流のテンプレートコンテキストとの境界

非対称な付与、すなわちパステンプレートは .parameters を直接読み取り、値テンプレートは読み取らないという点が、この境界における重要な区別です。サーフェスごとの境界のセマンティクスは次のとおりです。

  • {{ .parameters.X }} を記述する Aggregate の component-values: テンプレートは、補間時に正しく解決されます。解決されたリテラルは、その場で YAML 文字列に書き込まれます。
  • {{ .parameters.X }} を記述する Recipe の valuesMapping: テンプレートは値テンプレートのサーフェスであり、テンプレートコンテキストは .parameters を持ちません。valuesMapping: で環境ごとの差異が必要な作成者は、解決済みの .values.<key> を消費する経路を通じてそれを表現します。つまり、Aggregate がパラメータを公開し、Component の values: からそれを参照し、Release がそれを充足し、補間後の値が Recipe へと流れます。
  • FeatureRecipe の injectMapping:、provides:、または pipeline.with: テンプレートは値テンプレートのサーフェスであり、Recipe の valuesMapping: と同様です。.parameters はテンプレートコンテキストに含まれません。
  • Workload 本体テンプレート(Recipe 内の workload: の内容)は値テンプレートのサーフェスであり、同様です。
  • パステンプレート(Release の境界の directory: / subDirectory:)は例外です。パステンプレートのコンテキストは、閉じた許可リストに照らして .parameters.<slot> を含み、参照はレンダリングが各境界の出力を配置する際に解決されます。パステンプレート変数の全体の対応表については path-template-variables.md を参照してください。

4 つのドメインの所有境界は、パイプラインの特定の段階でパラメータマップがメモリ上に存在するかどうかではなく、どのサーフェスがパラメータを受け取るかによって保たれます。パステンプレートはオペレーターが作成し、オペレーターが所有するものです。そこに直接のパラメータアクセスを与えることで、オペレーターの関心事(環境ごとの成果物レイアウト)がオペレーターのサーフェス内に収まります。値テンプレートはカタログが作成するものです。そこに直接のパラメータアクセスを与えないことで、カタログ側の記述は Aggregate を唯一の信頼できる情報源とする契約と疎結合に保たれます。

マージされたパラメータマップは、すべてのレンダーフェーズが完了するまで読み取り可能であり、それ以降は読み取れません。このマップは解決の対象となったコンパイルからのみ到達可能であるため、その存続期間はビルドの存続期間に制限されます。

ピラー間のブリッジ

パラメータは、解決時に周囲の values 文字列へ補間されます。補間された値は、Aggregate が自身のスコープで記述する任意のピラーに入ることができます。component の values: 文字列、feature の values: 文字列、サブ aggregate の parameters: パススルー宣言(親 Aggregate のパラメータ値が解決された後、子 Aggregate のパラメータスロットへ伝播します)、および metadata の name: / labels: 文字列です。

このブリッジは一方向です。パラメータ値は、Release が供給した(またはデフォルト値が適用された).parameters.<slot> から、参照箇所の YAML 文字列へ流れます。パラメータが逆方向に流れることはありません。パラメータは values: フィールド、provides: フィールド、その他のピラーの内容を読み取ることはできません。この方向性は、パラメータ契約のコンパイル時限定という保証の一部です。

相互参照

  • Aggregate 上の型付きパラメータ契約の宣言形式については、entities/aggregate.md の §「Typed parameter contracts」を参照してください。
  • Recipes がベースレンダリング時に使用する、より広範なテンプレートコンテキスト(.values、.infra、.uses、.context.* など)については、template-context-contract.md を参照してください。
  • コンパイルパイプライン全体におけるテンプレートサイトごとの利用可能性(どのフィールドがどの評価サイトに存在するか)については、expansion-matrix.md を参照してください。
  • パラメータホイスティングのチェックリスト(Aggregate の宣言、values での参照、Release での充足、Recipe での使用という、順に行う 4 つのオーサリング上のタッチポイント)については、vocabulary/data-pillars.md の §「The parameter-hoisting checklist」を参照してください。
  • より広範なデータピラーのセット(values:、infra:、provides:、uses:、features:、locals:、parameters:)については、vocabulary/data-pillars.md を参照してください。