データピラー
DSL の 5 つの構造キーワード(parameters、values、uses、infra、inject)の概念的な枠組みは architecture/06-data-taxonomy-and-composition.md にあります。このページでは、正規のデータピラー一覧、ピラーごとのオーサリングのセマンティクス、ピラー間のメカニズム、そして作成者が複数のピラーにわたって出会うデフォルト値の語彙を扱います。補完的なトポロジーの三つ組(provides、inject、uses。グラフのエッジを結線するキーワード)は topology-triad.md に記載されています。データピラーとは別のメタデータ語彙(ラベル、アノテーション、公開サーフェスのフィールド)は labels-and-annotations.md と publishing-surface.md にあります。
正規のピラー一覧
Aggrega のエンティティは 7 つの名前付きデータピラーを持ちます。5 つはレンダリングを通じて有効な状態として IR のデータフローに参加し、2 つは一時的またはプライベートで、特定のコンパイル段階にのみ存在します。
| ピラー | 配置先 | ライフサイクル | 役割 |
|---|---|---|---|
values | Aggregate のコンポーネント / アタッチメントインスタンス | レンダリングを通じて有効 | Developer が記述する認知的ペイロード |
infra | Release のコンポーネント、アタッチメント、接続のエントリ | レンダリングを通じて有効 | Operator が記述する物理的サイジング |
provides | Recipe の provides: ブロック | レンダリングを通じて有効(派生ピラー — 後述) | Recipe が計算し、トポロジーパイプが消費する公開出力文字列 |
uses | Aggregate のコンポーネント / フィーチャーインスタンス | レンダリングを通じて有効 | 他のコンポーネント / フィーチャーへのトポロジー上のエッジ |
features | Aggregate + Release のコンポーネントインスタンス。スロットはカタログエンティティの featuresSchema で宣言されます — 後述の「Features ピラー」を参照 | レンダリングを通じて有効 | アタッチメントピラー — すべてのアタッチメントファミリーに共通の 1 つの形 |
parameters | Aggregate + Release のルート | パイプラインの終端まで、すべてのレンダーフェーズが完了するまで読み取り可能です。レンダリング中は非対称な許可によりパステンプレートからアクセスできます。値テンプレートのコンテキストは .parameters を直接ではなく、補間後のリテラルを消費します | Release が満たす環境ごとのスロット |
locals | Recipe の locals: ブロック | Recipe プライベート — その Recipe 自身のテンプレート内でのみ参照可能 | Recipes が locals プリアンブルで導出する計算済みの文字列状態 |
values / infra / provides / uses / features は 5 つの有効なピラーであり、ランタイムのテンプレートコンテキストがそれぞれ .values、.infra、.provides、.context.uses、.features を通じて公開します。parameters と locals は有効なピラーの一覧に含まれません。parameters は解決後に残らないため、locals は Recipe プライベートでエンティティの境界を越えないためです。
ピラーは壁ではなく道標です。テンプレートエンジンは、自己完結性のルールで明示的に禁止されている場合(Recipe の provides: および Recipe の source: ブロックが .context.inject / .context.uses を読む場合。templates/expansion-matrix.md に記載)を除き、すべての箇所でピラーをまたぐ読み取りを許可します。ピラーの境界は記述上の規律であり、言語による強制ではありません。
ピラーの境界とオーサリングの規律
Recipe テンプレートからのピラーをまたぐ読み取りは、完全なテンプレートコンテキストを許可するすべてのサイトで制限されません。オーサリングの規律として、作成者には次のことが期待されます。
- 認知的ペイロード(Developer が作成した意図)には
.valuesを読み取ります。 - 物理的なサイジング(Operator が作成したサイジング)には
.infraを読み取ります。 - コンポーネント間のポインタ文字列(トポロジートライアドのデータフロー)には
.context.uses[].provides.<key>を読み取ります。 - ハイドレーション後の配信パイプ(
component.inject、uses[].inject、および FeatureRecipe のinjectMappingによるインターセプトにわたる inject ソースから組み立てられます)には.context.injectを読み取ります。
この規律は壁ではなく道標です。.infra.replicas を読み取って values: フィールドを駆動する Recipe テンプレートは動作し、テンプレートエンジンはその読み取りを制限しません。アーキテクチャの考え方では、ピラーの境界はランタイムの制限ではなく、オーサリングの意図(誰がデータを所有するか)を表します。慣例は 4 ドメインの分割に対応しています。Developer が作成した値は .values から、Operator が作成したサイジングは .infra から、コンポーネント間の座標はトポロジーパイプから取得します。
意図的にピラーをまたぐブリッジが必要な場合(たとえば、vocabulary/inheritance-and-interface.md に従い、Component の schema: が開発者向けのダイアルを公開し、Recipe の valuesMapping: テンプレートがそれを Ops 側の infra: 形式の出力へパイプする場合)、アーキテクチャはそのブリッジを道標付きの例外として扱います。後述の「ピラーをまたぐメカニズム」を参照してください。
Values
values: ピラーは、Developer が記述する認知的ペイロード、つまり Developer がコンポーネントインスタンスごとに指定するアプリケーション形状のパラメータを保持します。Component の schema: が values の形状を宣言し、Developer の Aggregate がインスタンスごとに具体的な値を設定します。これは Developer の領域です。
記述場所:
- Aggregate
components.<id>.values:— コンポーネントインスタンスごとの認知的ペイロード。 - Aggregate
subsystems.<name>.components.<id>.values:— 同上。サブシステムでグループ化されたコンポーネント内のもの。 - Aggregate
components.<id>.features.<name>.values:およびサブシステムのfeatures.<name>.values:— アタッチメントの values ペイロード。アタッチされた Feature がどのファミリーに属するかを問いません(認証情報アタッチメントの vault クエリパラメータも、他と同様にここに記述します)。
禁止される場所:
- Release エンティティ(Release のスキーマは、どのネストレベルでも
values:ブロックを禁止しています。環境ごとの差異をサポートする方法は Parameter Hoisting です。後述の Parameters を参照してください)。
検証元: Component schema の values: ブロック(Feature アタッチメントの場合は Feature schema の values: ブロック)。vocabulary/validation-surface.md の Layer 2 に従い、Component / Feature の読み込み時に JSON Schema 2020-12 に解決されます。
消費元: .values を介した Recipe の valuesMapping: テンプレート。完全なテンプレートコンテキストは、すべてのベースレンダリングテンプレートの箇所で、解決済みの values 辞書を公開します。
Infra
infra: ピラーは、Operator が記述する物理的なサイジング(レプリカ数、リソース要求、IOPS 制限、リージョンの固定、マシンクラス)を保持します。これは どこで、どの規模で を表し、values の 何を、どのように振る舞うか を補完します。これは Operator の領域です。
4 つの記述画面
作成者は infra: に 4 つの異なる画面で出会います。それぞれ適用範囲とカスケードの動作が異なります。
| # | 画面 | 適用範囲 | マージの優先順位 |
|---|---|---|---|
| 1 | Release 境界の components.<id>.infra:(境界を持たない Release では spec.components.<id>.infra:) | 1 つのコンポーネントインスタンス | そのコンポーネント自身のサイジング。他のサーフェスはこれを書き込みません |
| 2 | Release 境界の features.<name>.infra: | 境界全体のアタッチメント。境界内のすべてのコンポーネントに適用されます | そのアタッチメントについて最も低い — サーフェス 3 がフィールドごとに上書きします |
| 3 | Release 境界の components.<id>.features.<name>.infra: | 1 つのコンポーネント上の 1 つのアタッチメント | そのアタッチメントについて、サーフェス 2 をフィールドごとに上書きします |
| 4 | Release の components.<id>.uses.<socket>.<alias>.infra: | 1 つの接続 | ソケットの infraSchema に対して検証されます。利用側コンポーネントのレンダリングにのみ届きます |
サーフェス 1 は最もよく記述されます。Operator は Release が配置する各コンポーネントのサイジングを行います。境界自体は infra: を持たない(Release スキーマが拒否します)ため、複数のコンポーネントで共有するサイジングは各コンポーネントに記述するか、extends: を通じて親の Release から継承します(後述)。サーフェス 2 と 3 は Feature アタッチメントのサイジングを扱います。Features は独自の infra ペイロードを持ち、FeatureRecipe はサイドカーや Feature ごとのリソースを合成する際にそれを使用します。境界全体のアタッチメントは一度だけサイジングされ、1 つのコンポーネントがその単一のフィールドを調整します。
「Infra は主にローカライズされる」— 例外のあるルール
infra: のアーキテクチャ上の目標はコンポーネントローカルであることです。コンポーネントのサイジングはそのコンポーネントインスタンスに適用され、他のコンポーネントには波及しません。この仕組みにより、Ops は API サーバーの CPU 要求に影響を与えずにデータベースの IOPS を増やせます。
ルール: infra: は、それを記述したサーフェスに 主にローカライズ されます。設計上、カスケードの例外があります。
- 境界アノテーションのカスケード。 境界の
annotations:は、ネストされた境界を通じて内側のコンポーネントへカスケードします(labels-and-annotations.md のアノテーションマトリクスの画面 5)。Recipes がルーティング入力として使用するアノテーションは、間接的なinfraの到達経路になります。境界レベルのアノテーションは.context.annotations.releaseを通じてノードごとの Recipe のレンダリング出力へ流れ込みます。 extends:による Release の継承。 親 Release をextends:する Release は、子がキー単位で上書きしない限り、infra宣言を持つすべての画面で親の宣言を継承します。子の値はキーごとに優先され、最初の分割できない値(スカラー、リスト、テンプレート)まで下ると、その値は丸ごと置き換えられます。子がnullと書いたキーは、空に設定されるのではなく削除されます。この継承は意図的に Release ごとの境界を越えます。畳み込みルール全体と、一緒に引き継がれるその他のものについてはentities/release.mdを参照してください。- スキーマブリッジによるピラー横断のパイプ。 Component の
schema:は開発者向けのvalues:ダイヤルを公開でき、Recipe のvaluesMapping:テンプレートがそれをプロバイダーのinfra:形の出力へパイプします(後述の「ピラー横断の仕組み — スキーマブリッジによるピラー横断のパイプ」を参照)。厳密には、値はvalues:から生じてレンダリング出力へ流れ込みます。このカスケードはインスタンス内ですが、ピラーを横断します。
ローカライズは設計意図であり、エンジンが強制する壁ではありません。上記のカスケードは意図的な例外であり、それぞれがそれを持つサーフェスで文書化されています。
アノテーション駆動の Feature 展開におけるサイドとピラーの区分。 「記述画面としての Aggregate」という不変条件は、アノテーション駆動の Feature 展開経路にも引き継がれます。Aggregate 側のアノテーション(サブシステムおよびコンポーネントインスタンスのスコープ)は maps.values のサブキーのみを発火でき、Release 側のアノテーション(境界およびコンポーネントインスタンスのスコープ)は maps.infra のサブキーのみを発火できます。Manifest のバインディングは両方のピラーのパスを宣言できます。各サイドは互換性のあるサブセットのみを発火し、サイド横断の合成は IR 構築時にフィールドごとに寄与をマージします。この区分により、アノテーション画面でも values を担う開発者と infra を担うオペレーターの記述上の分離が保たれます。これは、明示的アタッチメントの画面で values: と infra: が強制するのと同じ分離です。サブキーごとの解説とサイド横断の合成パターンについては providers/well-known-annotations.md §「Side-vs-pillar partition per subkey」を参照してください。
Provides
provides: ピラーは派生的です。Recipe がこれを宣言しますが、values / infra とは異なり、開発者が直接記述するものではありません。Recipes は、トポロジーパイプが消費する公開出力文字列を計算します。
Recipe の provides: ブロックは、<key>: <template> のペアからなるマップです。各テンプレートは、provides の評価中に、Recipe 自身の自己完結したサーフェス(.values、.infra、.context.instance_id、ノードのプロバイダーが報告する場合は .context.rendered_name、およびノードの解決済み .locals)に対して評価されます。結果の文字列は .provides を通じて公開され、呼び出し側の uses[].inject ブロックが from: "<key>" 参照によって消費します。.locals が利用できるのは、ノードの locals がそのステージのプリアンブルで provides より先に解決されるためです(後述の Locals を参照)。locals ブロックが宣言していないキーを指定すると停止します。
自己完結の不変条件。 Recipe の provides: テンプレートは .context.inject や .context.uses を参照してはなりません。provides の評価はこれらのテンプレートを任意の順序で実行します。テンプレートはノード自身のデータのみを閉包するため、順序は問題になりません。ノード間の参照があると、その評価がトポロジー的な反復順序に結び付いてしまいますが、設計上これは意図的に避けられています。規則とその理由については templates/expansion-matrix.md の 6 行目を参照してください。
provides: がピラーである理由。 出力文字列はすべての Recipe の正規の公開サーフェスです。下流の消費者(呼び出し側の uses[].inject、.context.uses を通じてターゲットの解決済み provides を読む FeatureRecipe の injectMapping ブロック)は、この辞書を型付きの契約として扱います。provides: をピラーと呼ぶことで、values / infra / uses / features と並ぶ第一級の地位を認めることになります。これを「単なる Recipe の内部」として扱うと、トポロジーパイプの主要なデータソースとしての役割を過小評価することになります。
Uses
uses: ピラーは、トポロジーのエッジを宣言するものです。コンポーネントインスタンスの uses: ブロックは、そのコンポーネントが参加するエッジ、つまりターゲットを消費する際に経由するソケットを指定します。完全な文法は topology-triad.md に記載されています。このセクションでは、網羅性のために uses: をピラーとして挙げています。
uses: は Aggregate のコンポーネントインスタンスとフィーチャーアタッチメントに置かれます。ランタイムのテンプレートコンテキストは、外向きの接続ごとに 1 つのエントリを、そのエイリアスをキーとして .context.uses で公開します。この射影は各エッジの解決済みターゲットメタデータ(ターゲットの provides、ラベル、アノテーション)を保持するため、呼び出し側の Recipes はベースレンダリングのテンプレート評価時にコンポーネント間のポインタ文字列を読み取ることができ、さらにその接続に記述されたアタッチメントを .context.uses.<alias>.features.<slot> で読み取ることができます。
Features ピラー
features: はアタッチメントのピラーです。1 つのキーワード、1 つの形で、すべてのアタッチメントを扱います。運用 Feature、認証情報 Feature、アイデンティティ Feature はいずれも、作成者が選んだインスタンス名のもとでここに宣言されます。ランタイムのテンプレートコンテキストは、ノードのアタッチメントを .features.<name> として公開し、それぞれが type、values、infra、およびアタッチメントの解決済み provides を持ちます。コンポーネントの接続の 1 つに記述されたアタッチメントは、代わりにその接続のもとで同じ形で .context.uses.<alias>.features.<slot> に公開され、.features のもとには決して現れません。そのため、.features を range する Recipe が出会うのはコンポーネント自身のアタッチメントだけです(テンプレートコンテキストの契約を参照)。
インスタンス名がエンティティの featuresSchema で宣言されたスロットと一致するアタッチメントは、そのスロットを埋めます。それ以外のインスタンス名はフリーアタッチメントです。スロットを埋めることで、スロットベースの認証情報がたどる 4 つの画面が結び付けられます。
| 画面 | 記述場所 | 役割 |
|---|---|---|
Component / Feature featuresSchema: | カタログエンティティ | エンティティが想定するスロットを宣言します。スロットごとに、配信の許可リスト(env / file / blackbox)と、任意で埋める側が満たすべきラベルセレクタを制限します |
Aggregate components.<id>.features.<slot>: | Aggregate のコンポーネントインスタンス | スロットをアタッチメントで埋めます。アタッチメント自身の values: と、透過スロットの場合はその inject: マッピングを与えます |
Workload containers.<name>.attachments.<KEY>.from/as: | Recipe の Workload 本体 | 宣言されたスロット、または connection: <alias> と並べた場合はその接続のソケットが宣言するスロットを参照し、それを埋めたもののコンテナごとの配信を指定します |
FeatureRecipe(source / workload / artifacts / valuesMapping、injectMapping、pipeline:) | バインドされた FeatureRecipe | アタッチメントの出力を生成します。出力されるリソース、配信の書き換え、またはその両方です |
スロット名は 4 つすべてにわたって要となる識別子です。画面 1 がそれを宣言し、画面 2~4 がそれを参照し、データの流れは一方向です(宣言 → 埋める → 参照 → 生成)。
作成時のチェックリストについては、examples/04-secrets.md の「The secret-delivery checklist」を参照してください。
Locals
locals: ピラーは Recipe のプライベートな状態です。ブロック全体はそのノードの provides: より前に、locals プリアンブルで解決されます。解決された文字列は、その Recipe 自身の後続のすべてのテンプレート(provides:、source:、valuesMapping:、workload:、artifacts:、assertions:、pipeline[].with)から参照できます。ブロックが宣言していないキーを指定する provides: テンプレートは停止します。
記述場所: Recipe の spec.locals: ブロック。<key>: <template> のペアからなるマップで、自己完結したノードローカルなサーフェス(.context.instance_id、.values、.infra、および同じブロック内で既に解決済みのエントリ)に対して評価されます。それ以外はこのサーフェスに含まれません。.provides、.metadata、その他の .context.* は含まれず、それらへの参照は停止します。
順序が重要です。 エントリは記述順に解決され、エントリはそれより上で定義された兄弟エントリを読み取り、その解決済みの値を受け取れます。連鎖は下方向にのみ進みます。あるエントリが別のエントリを読み取る場合、その定義を読み取り側より下に移動すると拒否され、コンパイラは参照を解決させるためにブロックを並べ替えることはありません。後のエントリへの参照は順序の誤りを示して停止し、宣言されていないキーへの参照はそのキーを示して停止します。source: が構造化ブロックである Recipe では、それが指すアーティファクトのピン留め時にも両方の誤りが拒否されるため、aggrega pull はビルドが出力をレンダリングする前にそれらを報告します。このチェックはキー入力そのものではなく、参照が解決される先のパスを読み取るため、直接の形式、with .locals ブロック、.locals に束縛された変数、そして括弧で囲んだブロック((.locals).<key> または ($.locals).<key>)のいずれにも同様に及びます。対象外となる書き方が 1 つあります。index .locals や (default dict .locals).<key> のように関数を通じて到達するキーです。この方法で存在しないキーに到達しても停止せず、何も出力しないのではなくリテラルテキスト <no value> をレンダリングします。ただし index 自体は例外で、読み取るマップにキーが存在しない場合、どのテンプレートサーフェスでもそのキーを示して停止します。
可視性: Recipe プライベートです。.context.uses[].locals フィールドは存在せず、呼び出し側はエッジを通じてターゲットの locals を読み取れません。呼び出し側が読み取れるのはターゲットの provides: です。
ユースケース:
- Recipe 内部のポインタ文字列(例:
secret_target_admin_password: "redis-auth"、Secret の名前のサフィックス)を計算し、Recipe のvaluesMapping:とprovides:の両方で使用するとともに、同じコンポーネントにアタッチされた認証情報の FeatureRecipe が.locals.secret_target_admin_passwordとして読み取るようにします。アタッチメントのテンプレートには、ホスト Recipe の解決済み locals とアタッチメント自身の locals をマージしたものが見えます。helmターゲットでは、それぞれが完全な名前を{{ .context.rendered_name }}-{{ .locals.secret_target_admin_password }}として記述します。レンダリング名は Kubernetes の名前で使用できる文字で表記したコンポーネント名であり、local はそれを読み取れないため、local がサフィックスを保持し、各読み取り側が両者を結合します。 - 1 つの Recipe 内で繰り返される計算値の重複排除(一度計算したホスト名を複数の
valuesMapping:フィールドから参照するなど)。 - インラインで書くと読みにくくなる複雑なテンプレートロジックの中間値。
provides: と locals: — 公開面とプライベート面
Recipe 側の 2 つのピラーには意図的な可視性の区分があり、作成者はこれを念頭に置く必要があります。
provides:は公開面です。 すべてのキーは正規のトポロジーパイプのサーフェスであり、下流の呼び出し側のuses[].injectブロックがfrom: "<key>"参照を通じてそれらを使用します。provides:ディクショナリは呼び出し側が依存する型付きの契約であり、キーの名前変更や削除は、それを参照するuses[].inject宣言を持つすべての Recipe に対する破壊的変更となります。locals:はプライベート面です。 すべてのキーは、Recipe 自身の後続テンプレート内でのみ参照できる Recipe 内部の状態です。Recipe の locals を読み取れる呼び出し側は存在せず、locals:内の名前はいかなる公開インターフェースにも含まれないため、名前の変更は下流に影響しない Recipe 内部のリファクタリングです。
両者には順序もあります。locals: が先に解決されるため、provides: は .locals を読み取れますが、locals: は .provides を読み取れません。したがって、local の値を provides: を通じて公開するには、その local を読み取る provides エントリを追加します。式は 1 か所に保たれます。
この区分は、Recipe の内部(プライベート)と Recipe のインターフェース(公開)を分離するアーキテクチャ上の方針に基づく意図的なものです。provides: と locals: を 1 つの名前空間として扱う作成者は可視性の区別を失い、トポロジーパイプを通じて内部状態を公開してしまうおそれがあります。provides: で宣言したすべてのキーは、作成者の意図にかかわらず Recipe の契約サーフェスの一部になります。目指すべき方針は、まずキーを locals: で宣言し、下流の呼び出し側が実際に必要とする場合にのみ provides: へ昇格させることです。
可視性はキーを宣言したピラーで決まります。キーごとの可視性マーカーはないため、非公開でありかつ公開もされる値は、locals: エントリと、それを読み取る provides: エントリの組になります。
Parameters
Aggregate と Release のスキーマはいずれも、ルートに parameters ディクショナリを持ちます。開発者は Aggregate が期待するキーを宣言し、運用担当者は環境固有の Release ファイルから値を埋めます。この分離が GitOps プロモーションの仕組みです。単一のイミュータブルな Aggregate.yaml が Dev、Staging、Production の各環境を移動し、各環境の Release がそれぞれのパラメータ値を提供します。
spec: parameters: corp_db_name: type: string required: true env_workers: type: integer required: true region: type: string required: true enable_debug: type: boolean required: true components: my-backend: type: core/python-worker:1.0.0 values: workers: {{ .parameters.env_workers }} region: "{{ .parameters.region }}"# release-prod.yaml — inline parameter valuesspec: aggregate: my-app manifest: prod-manifest parameters: corp_db_name: "enterprise_data" env_workers: 10 region: "eu-west-1" enable_debug: falseパラメータ値を別ファイルに保持する CI/CD フロー(例: Release と並べてチェックインされた環境ごとの .yaml)では、Release は $import: 形式を使用します: parameters: { $import: ./prod-values.yaml }。ファイルの内容が Release サーフェスのインラインマップを置き換えます。パスはコマンドの実行場所にかかわらず Release を含むディレクトリから解決され、ワークスペース内のファイル(ワークスペース外で指定された Release の場合は、それを含むディレクトリ内のファイル)を指す必要があります。複数ファイルの階層化(ベースファイルと環境固有のオーバーレイの組み合わせ)は Release の extends: チェーンで表現します。親 Release がベースのパラメータを提供し、子 Release がそれを拡張してキー単位で上書きします。
パラメータのライフサイクル。 コンパイラはパラメータを 3 つのフェーズで解決します。(1) デフォルトの補完: default: が定義され Release の値がないスロットにデフォルト値が入ります。(2) パラメータ契約の検証: 型付きの parameters: 契約が、各値を宣言された type / enum / min / max / pattern 制約に照らして検証します。補完されたデフォルトも対象となるため、自身の契約に違反するデフォルトはビルドを停止させます。(3) 補間: コンパイラは Aggregate のテキスト全体をテンプレートとして評価し、すべての {{ .parameters.<slot> }} 参照を解決済みの値で置き換えます。マージされたマップはその後もレンダリングを通じて読み取り可能なままであり、パステンプレート(Release 境界の directory: / subDirectory:)は ../path-template-variables.md に記載された閉じた許可リストに従って .parameters.<slot> を直接読み取れます。値テンプレートのサーフェス(Recipe の valuesMapping、FeatureRecipe の injectMapping / provides / pipeline.with、Workload の本体)はテンプレートコンテキストで .parameters を受け取りません。これらはフェーズ 3 の補間によって周囲の values: 文字列に書き込まれた解決済みの値を使用します。
パラメータ巻き上げのチェックリスト
環境をまたぐすべての値は、4 つの記述箇所を順に通過します。作成者が持つべきメンタルモデルは次のとおりです。Dev / Staging / Production 間で変化する値については、Aggregate(宣言)、values テンプレート(参照)、Release(充足)、Recipe テンプレート(使用)に手を入れることを想定します。
| ステップ | 画面 | アクション |
|---|---|---|
| 1 | Aggregate の spec.parameters.<name> | Aggregate の型付き記述契約の一部としてパラメータを宣言します。各パラメータスロットは、宣言された type(string、integer、number、boolean、array、object)、任意の description、任意の default、任意の値空間制約(enum、min、max、pattern、minLength、maxLength)、およびオブジェクト型スロットの場合は任意のネスト構造を持ちます。契約は、Release から提供された各値を補間の前に検証します。 |
| 2 | 同じ Aggregate 内の Component の values: テンプレート | パラメータを使用する任意のコンポーネント(または feature、サブアグリゲート)の values: ブロック内から、{{ .parameters.<name> }} でパラメータを参照します。この参照は Go テンプレート式であり、コンパイラは解決の補間フェーズでこれを評価します。 |
| 3 | Release の spec.parameters.<name>(インラインまたは parameters: { $import: ./path.yaml }) | Release サーフェスで環境固有の値によりパラメータを充足します。環境ごとの Release ファイルは、Aggregate を変更せずに同じパラメータキーに異なる値を提供します。 |
| 4 | Recipe の valuesMapping: テンプレート | {{ .values.<key> }} で解決済みの値を使用します。Recipe は値テンプレートのサーフェスであり、そのテンプレートコンテキストは .parameters を直接持ちません。環境ごとの差異は、上記の補間フェーズが書き込む補間後の values: ディクショナリを通じて Recipe に届きます。(Release 境界のパステンプレートは例外で、非対称な許可に従い、レンダリング中に .parameters.<slot> を直接読み取ります。) |
4 つの記述箇所は順序どおりであり、いずれも欠かせません。Aggregate での宣言を省くと Release が充足すべきスロットがなくなり、values での参照を省くと Recipe が使用する値がなくなり、Release での充足を省くとパラメータが空になります。コンパイラは解決中にこの連鎖を検証します(型付きの parameters: 宣言に対するパラメータ契約の検証、次に周囲の values: 文字列への補間、次に得られた values: ディクショナリの Component または Feature の schema: に対する JSON Schema 検証)。不一致は、パラメータ契約違反(型付きの parameters: 宣言に対して検出)、未充足テンプレートエラー(補間時に検出)、または values: スキーマに対する JSON Schema 制約違反(スキーマ検証時に検出)のいずれかとして表面化します。
このパターンは GitOps プロモーションの正規の仕組みです。単一のイミュータブルな Aggregate が環境間を移動し、各環境の Release がそれぞれのパラメータ値を提供します。作成者が環境ごとに変えたい値はすべて、Aggregate に直接埋め込むのではなく、パラメータの連鎖に置くべきです。
ピラーごとの extends: マージセマンティクス
カタログエンティティが extends: を宣言し、コンパイラが継承チェーンをたどるとき、各ピラーの内容はピラー固有の規則に従ってマージされます。セマンティクスはピラーごとに異なります。以下の表がピラーごとの正規のリファレンスです。
| ピラー | extends: チェーンにおけるマージの動作 |
|---|---|
values(JSON Schema 2020-12) | Feature のチェーンでは、スキーマは JSON Schema 2020-12 の合成によって合成されます。拡張する Component はピラーの内容を記述せず、チェーンのどの深さでも、ベースが記述したとおりのブロックをそのまま受け取ります。 |
infra(JSON Schema 2020-12 フラグメント) | values と同じです。Feature のチェーンでは合成され、拡張する Component にはそのまま継承されます。 |
provides(Recipe テンプレートマップ) | トップレベルの浅い置換です。同じ名前については子のキーが親のキーを完全に置き換え、兄弟キーは親から保持されます。テンプレートは合成されず、子のテンプレートがそのスロットを完全に所有します。 |
uses (usesSchema) | ソケット名によるソケットごとのエントリ全体のオーバーレイです。子はベースが宣言していないソケットを追加でき、既存の名前で再宣言したソケットはそのエントリを丸ごと置き換えます。値と infra のスキーマ、および selector がまとめて置き換わります。ソケットのエントリは合成されず、再宣言された selector がベースのものと比較されることもありません。 |
features(featuresSchema のスロットごとのスキーマ) | スロット名によるスロットごとのエントリ全体のオーバーレイで、usesSchema と同じ条件です。子はスロットを自由に追加でき、再宣言したスロットはベースのエントリと合成されるのではなく、それを丸ごと置き換えます。 |
locals(Recipe テンプレートマップ) | トップレベルの浅い置換です。provides と同じです。 |
parameters(Aggregate ルートマップ) | Aggregate には extends: フィールドがないため、パラメータをマージする Aggregate のチェーンは存在しません。Release の extends: チェーンでは、マップ値のパラメータは子のキーが優先される形でディープマージされ、スカラー値のパラメータは子によって置き換えられ、子が null と記述したキーは削除されます。 |
全体的なパターンは、種類とサーフェスによって決まります。Feature のスキーマ検証されるピラーは JSON Schema 2020-12 のもとで合成されます。拡張する Component のピラーはそのまま継承されます。Component は何も記述しないため、その契約はベースのものと完全に同一であり、したがってベースの制約を緩めることは構造上できません。固定形状のサーフェスである usesSchema と featuresSchema は、どちらの種類でも名前によってオーバーレイされます。子はエントリを追加でき、再宣言したエントリはベースのものを丸ごと置き換えます。テンプレートで記述されるピラーはキーごとの浅い置換を使用し、子は宣言したテンプレートスロットを完全に所有します。
拡張する Component は、ピラーではなく assertions: によって制約を厳しくします。これは Component が追加する述語で、継承した述語とともに評価されます。この仕組みについては inheritance-and-interface.md を参照してください。
継承の仕組みそのものについては、カタログの種類を扱う inheritance-and-interface.md の「Inheritance via extends」を参照してください。Release はカタログエンティティではなく、独自の規則によって畳み込まれます。その規則は entities/release.md の「Composite Release and extends: inheritance」にあります。
ピラー横断のメカニズム
道標としての枠組みでは、文書化された自己完結のサーフェスを除き、あらゆる場所でピラー横断の読み取りが許可されます。以下のパターンはよく使われるピラー横断のメカニズムを形式化しており、作成者がトレードオフを認識できるよう、記述上の好ましくない兆候を 1 つ文書化しています。
スキーマブリッジによるピラー横断のパイプ処理 — 壁ではなく道標
ピラーの境界は作成上の規律です。アーキテクチャは何をどこに置くかを道標として示し(開発者の認知的な意図には values:、Ops の物理的なサイジングには infra:、Recipe が出力する文字列には provides: など)、カタログのレビュアーがその慣例を守らせます。テンプレートエンジン自体は、文書化された自己完結のルールが禁止しない限り、ピラー横断の読み取りを許可します(Recipe の provides: は .context.inject を参照できず、FeatureRecipe の境界スコープの provides: はコンシューマごとのフィールドを参照できません)。ピラーの壁は道標であり、強制ではありません。
道標として示された代表的な例外として、Component の schema: では開発者向けの values: ダイヤルを宣言でき、Recipe の valuesMapping: テンプレートがそれをレンダリングされた infra: 形の出力へパイプします。開発者は型付きの values: フィールドで意図を指示し、Recipe のテンプレートは、開発者がインフラストラクチャのコードを書くことなく、その結果の値を provider のインフラストラクチャ層へパイプします。実例を示します。
# Component schema declares a developer-facing dial in valuesspec: schema: values: required_iops: { type: integer, min: 100 }# Recipe valuesMapping pipes the developer's intent into the provider's infra-side knobvaluesMapping: iops_limit: "{{ .values.required_iops }}"このブリッジは inheritance-and-interface.md に実例付きで文書化されています。アーキテクチャ上の意図(Recipe がパイプする、宣言されたピラー横断のダイヤル)は一方向のみ、すなわち開発者側の values: から Ops 側のレンダリング出力への流れであり、Component のスキーマ自体ではなく Recipe のマッピングテンプレートに置かれます。ピラーの境界は道標のままです。開発者は values: を参照し、Recipe は values: と infra: の両方を参照し、レンダリング出力はそれらを組み合わせます。
ピラー横断の inject アキュムレータ
.context.inject パイプは、ピラーにまたがる 3 つのソースの合流点です。
- Component レベルの自己 inject(
component.inject)— component 自身のvaluesと自身のprovidesから文字列を取得します。 - Uses-inject(
uses[].inject)— ターゲットのprovidesから文字列を取得します。 - FeatureRecipe の
injectMapping:による介入 — 上記のいずれかに加え、FeatureRecipe 自身のinfra:ペイロードから文字列を取得します。
ベースレンダリングが実行される時点で、.context.inject.<mechanism>.<key> には 3 つすべてのソースからのエントリが蓄積されています。このアキュムレータは構造上ピラー横断です。values、provides、infra に由来するエントリはすべて同じ .context.inject マップに流れ込みます。.context.inject を利用する Recipes は、どのピラーがどのエントリを提供したかを知る必要なく、マージ後の状態を参照します。
inject の文法と衝突ルールについては、topology-triad.md を参照してください。
ピラー横断の制約の重複
検証層の異なる 2 つのピラーに存在するフィールドは、重複した制約を持つことがあります。代表的な例は、Component の usesSchema で宣言されたポート番号(JSON Schema で検証、範囲 min: 1, max: 65535)と、Workload の services.<name>.ports.<port> フィールドで利用される同じポート番号です。後者については、provider レンダリング plugin の spec.provider.workloadSchema が非特権ポート用に min: 1024 ルールを追加する場合があります。provider レンダリング Plugin の spec.provider.workloadSchema は、provider が Workload をどのように変換するかを記述し、その provider が Workload を合成できることを示すものであり、何も検証しません。すべての Workload 本体は、provider にかかわらずプラットフォームの Workload スキーマに対して検証されるため、workloadSchema にだけ書かれた制約(たとえば min: 1024 のポートルール)は強制されません。そのような値を拒否するには、制約を Component のスキーマかアサーションに記述してください。
Feature のアタッチメントと Component のピラーの分離
Feature のアタッチメントは親 Component のピラーに書き込みません。アタッチされた各 Feature は独自のピラーペイロード(独自の values: ブロックと独自の infra: ブロック)を持ちます。Feature のリソースを合成する FeatureRecipe は、Component のものとは独立に自身のピラーペイロードを読み取ります。分離されるのは入力です。書き込んだものがどうなるかにかかわらず、アタッチメントが読み取るのは自身のものです。ターゲットの provider が個別のドキュメントを書き出す場合、アタッチメントのレンダリング出力は独自のディレクトリの下に Component のものと並んで置かれます。provider が境界のコントリビューターを 1 つのドキュメントにまとめる場合、アタッチメントは Component と同様にそのドキュメントに寄与し、各リソースはアタッチメント自身の識別情報を保持するため、何がどこから来たかを読み取れる状態が保たれます。
作成者にとっての 2 つの帰結:
- Feature のアタッチメントの
values:設定は、Component のvaluesMapping:テンプレートの.valuesには現れません。Component は自身の値のみを参照します。 - Feature の
infra:ペイロードは Component のinfra:には流れ込みません。アタッチされた各 Feature は、その Feature のリソースにスコープされた独自の物理的なサイジングを持ちます。
この分離は、アーキテクチャの関心の分離に従って明示的に行われています。Features は、5-Tier Onion Model によって Components の上に重ねられる独立したコントリビューターです。アタッチメントのサーフェスと順序については、labels-and-annotations.md の「Feature attachment — five surfaces」を参照してください。
両方のピラーで同じプロパティ名
spec.schema.values: と spec.schema.infra: が同じプロパティ名を宣言している Component または Feature は、ルート、任意のネスト深さ、またはその両方において、よく見られる作成上の問題の兆候です。2 つのピラーは設計上別々の名前空間であるため(コンパイラは重複を受け入れます)、スキーマは検証を通過し、レンダリング出力も正しい形式になります。問題は認知的なものです。読者やテンプレート作成者は、スキーマを読むたび、あるいはそれに対してテンプレートを書くたびに、「今読んでいる foo はどちらのピラーのものか」という引っかかりに直面します。
# Smell — both pillars declare `mode`. A reader of the schema or a# template against the Feature has to disambiguate every reference.spec: schema: values: mode: { type: string } infra: mode: { type: string }意図的に重複させている作成者には、両方を保持する正当な理由があります。たとえば、values では「アプリケーションの運用モード」("debug" / "production")、infra では「デプロイのトポロジーモード」("standalone" / "clustered")を意味する mode は、異なるセマンティクスを持ち、名前がたまたま一致しているだけです。偶然重複させている作成者(より一般的なケース)は、一方のエントリの名前を変更します。
2 つ目の意図的な形は、どちらの作成者も提供できる 1 つのデータです。呼び出し元のロケーターを持つ標準ライブラリの認証情報 Features(core/referenced-secret、core/referenced-secret-set、core/secret-value、core/secret-provided)は、それを両方のピラーで同じ名前と同じ形で宣言します。これにより開発者は values に、オペレーターは infra に書くことができ、各 Feature 自身のアサーションが、両方に書いた、またはどちらにも書いていないアタッチメントを拒否します。以下のアドバイザリは、これら 4 つに到達するすべてのロードでそれらを名指しします。これらについては、誤りではなく契約を報告しています。
カタログのロードでは、重複が少なくとも一方の側で末端のリーフに解決される同名プロパティごとに、notice: LINT: <kind> "<name>" at <path> declares property "<property>" in both values: and infra: pillars (path: <dotted-path>) アドバイザリが出力されます。共有の整理用名前空間として存在する同名プロパティ(両方のピラーが互いに重ならないサブプロパティを持つ ingress という名前のオブジェクトを持つ場合)は警告されず、リーフの重複のみが報告されます。この警告はアドバイザリであり、ビルドは続行されます。
ピラーの検証ティア
ピラーは 3 つのティアにわたって検証を行います。各ティアはそれぞれ異なる関心事を扱い、同じフィールドが複数のティアで検証されることがあります(前述の「ピラー横断の制約の重複」を参照)。
| ティア | 検証する内容 | 実行される場所 |
|---|---|---|
| 1 — JSON Schema エンベロープ | 構造的な形状(どのキーが存在するか、型がフィールド宣言と一致するか) | 解決時、ファイルの読み込みごと |
2 — ピラーごとのスキーマ(schema / featuresSchema / usesSchema) | JSON Schema 2020-12 として検証される、ピラーごとの型付きコンテンツ | 解決時、エンベロープの検証通過後 |
| 3 — provider の機能ゲート | バインドされた provider の synthesized モード機能によってゲートされる Workload コンテンツ。provider レンダリングプラグインの spec.provider.workloadSchema で文書化されます | ベースレンダリング時、valuesMapping の解決後 |
4 層のエラー形状の表とレイヤーごとのエラープレフィックスについては、validation-surface.md を参照してください。
デフォルト値のメカニズム
デフォルト値は、コーパス全体で複数の異なるメカニズムを通じて現れます。作成者は「default」という語に 5 つ以上の文脈で出会います。以下の表は、作成者がフィールドを空のままにしたときにどのメカニズムが値を生成するかについての正規のリファレンスです。
| # | メカニズム | 記述場所 | トリガー |
|---|---|---|---|
| 1 | JSON Schema default:(コンパクト形式 { default: <value> }) | Component / Feature schema:、Aggregate parameters: | 開発者がキーを省略した場合、フィールドはデフォルト値で検証されます。Aggregate のパラメータでは、コントラクト検証の実行前にパラメータのマージが宣言されたデフォルト値を埋めます(templates/parameters-context.md を参照)。 |
| 2 | Go テンプレート optional .X `Y` <fallback> | Recipe valuesMapping:、Workload 本体、FeatureRecipe テンプレート、アサーション評価器 | 存在を考慮したフォールバックです。キーがマップに存在しない場合にのみ <fallback> を返し、キーに記述されたゼロ / 空 / false はその記述値を返します。Aggrega 側における、フィールド不在時フォールバックの正規の形です。templates/sprig-functions.md を参照してください。 |
| 3 | Go テンプレート | default <expr> | Recipe valuesMapping:、Workload 本体、FeatureRecipe テンプレート | 「空」(Sprig の空判定。ゼロ、空文字列、false、nil)で発動するインラインパイプラインです。マップに存在しないことと、存在するがゼロ / 空 / false であることを混同します。この混同が許容される、呼び出し箇所ごとのオーバーライドのセマンティクス(バインディングのフォールバックがフィールドのスキーマレベルのデフォルトと異なる場合)に適しています。記述されたゼロ / 空 / false が正当な意図であるフィールド不在時フォールバックには適していません。その場合は optional(メカニズム 2)を使用してください。 |
| 4 | Sprig の default 関数({{ default <expr> .field }}) | 3 と同じ | メカニズム 3 の関数形式で、同じ空判定の混同を伴います。 |
| 5 | Recipe locals: フォールバック | Recipe locals: テンプレート | locals のエントリが、Recipe の残りの部分で使用されるデフォルトを含む文字列を計算します |
推奨される配置ガイダンス。 デフォルト値が本当に型コントラクトの一部である場合(例:「開発者がオーバーライドしない限り、このポートはデフォルトで 5432」)、JSON Schema default:(メカニズム 1)が正規の方法です。IDE の自動補完がデフォルト値を表示し、検証ツールがそれを尊重し、コントラクトは Component / Feature カタログエンティティ、または Aggregate のパラメータ宣言とともに運ばれます。Recipe テンプレートで省略可能なマップキーのフォールバックが必要な場合は、optional ヘルパー(メカニズム 2)がフィールド不在時フォールバックの正規の形です。これは記述されたゼロ / 空 / false と不在を区別します。Go テンプレートの | default(メカニズム 3)は、不在の値と偽値の混同が許容される、呼び出し箇所ごとのオーバーライドの場合のためのものです。オーバーライドのセマンティクスが明示的な意図である場合にのみ使用してください。
相互参照
inheritance-and-interface.md—extends:の仕組み、implements:による Interface Binding、schema-bridge によるピラー間のパイプ処理。topology-triad.md—provides、inject、usesのトポロジー上の仕組み。labels-and-annotations.md— データピラーとは別の、コンテンツ側のメタデータ語彙(上記のピラーの正規リストには labels / annotations / 公開用フィールドは含まれません。これらはメタデータ語彙です)。publishing-surface.md— データピラーとは別の、公開側のメタデータ語彙。validation-surface.md— 上記の 3 つのピラー検証ティアを含む、4 つのスキーマ検証レイヤー。templates/expansion-matrix.md— ピラー間の読み取りについてのテンプレート箇所ごとの利用可否、および Recipe のprovides:とsource:における自己完結ルール。examples/04-secrets.md— 6 つの接点からなるシークレット配信チェックリスト。architecture/06-data-taxonomy-and-composition.md— 5 つの DSL 構造キーワードについての正規の概念的な枠組み。