Recipe
Recipe エンティティの概念的な役割(Developer Intent を物理的な形式へマッピングする、Ops が作成する変換テンプレート)については architecture/04-entity-taxonomy.md で説明しています。このページでは Recipe の記述面、すなわちポインタ(source)、マッパー(valuesMapping:)、ネイティブ IaC サポート、および実例を扱います。
Recipe のアーキテクチャ: ポインタとマッパー
Recipe が果たす機能は、ちょうど 2 つです。
- ポインタ(
source): インフラストラクチャコードがどこにあるかをコンパイラに正確に伝えます。 - マッパー(
valuesMapping): Aggrega の抽象的なコンテキストを、基盤となるコードが期待する特定の変数に注入します。このフィールドは単一の Go テンプレートの記述面で、インラインのブロックスカラー、ファイルの$import:、ライブラリの$import:という 3 つの記述モードを持ち、内容の形によって振り分けられます。下記のvaluesMappingフィールド — 3 つの記述モード を参照してください。
Recipe はレンダリング機能と厳密に 1:1 で対応するため、その機能(spec.capability)はルートレベルで明示的に宣言されます。これにより、Go コンパイラは呼び出すべき下流の Wasm レンダリングプラグインを正確に把握できます。
spec.implements は、その Recipe が実装できるカタログのコンポーネント型を宣言します。コンパイラはこれを使って Manifest のマッピングを検証し(マッピングされた Recipe の implements は、マッピング先の型と一致しなければなりません)、候補を提示します。候補とは、マッピングがないことを示す診断に列挙され、エディタの補完で上位に並ぶ Recipe です。これがビルドを解決することはありません。Manifest のマッピングはユーザーによる明示的なデプロイの選択であり、ロックファイルに固定されます。implements がバージョンなし、完全一致、またはメジャー互換の範囲である Recipe も、ある型に対して自らを提示するだけで、選択を固定するのはユーザーです。FeatureRecipe.spec.implements は、フィーチャー型に対して同じ役割を担います。
A. Wasm 駆動のソーススキーマ
実装上の偏りをコンパイラに持ち込まないよう、source ブロックはインフラストラクチャのフィールドの固定セットではありません。source フィールドは 2 つの形式をサポートします。
- 汎用文字列(高速かつ簡潔): ローカルパス、OCI アーティファクト、Git リポジトリに最適です。コンパイラは文字列のプレフィックスとサフィックス(
./src、https://github.com/example/module.git、oci://...)から取得方法を推定します。.gitで終わる URL、またはgit://やssh://で書かれた URL は、デフォルトブランチで取得される Git リポジトリです。リポジトリも.tgzチャートも.yamlフラグメントも指さないhttps://URL は、曖昧であるとして拒否されます。 - オープンな構造化オブジェクト: キーをプロバイダーが定義するオープンな辞書(
additionalProperties: true)で、Recipe のテンプレートには.source.*(たとえば.source.chart)として公開されます。設計上の意図は、各プロバイダーの WebAssembly ソケットが自身のソースの形を定義し検証することです(例: Helm の場合はregistry/chart/appVersion)。
コアが解決するもの。 独自のソースキーを検証するプロバイダーはありません。フェッチされるソースは組み込みの識別子によって解決され、その kind がリゾルバーを選択します。リゾルバーは helm-oci-chart、helm-https-chart、compose-https-fragment、git-repository です。フェッチを意図したソースは kind と url を持つ必要があり、どの追加の座標がコンテンツを選択するかは kind によって異なります。チャートとフラグメントの kind は version を取り、記述されたとおりに固定します。git-repository は ref(タグ、ブランチ、またはコミット)を取り、オプションでリポジトリ内のアーティファクトとなるディレクトリを指定する module_subdir を取ります。付け替えられないコンテンツを指すのはコミットだけであるため、参照はロック時に解決され、lockfile には記述された参照と、それが解決されたコミットの両方が記録されます。記述されたとおりの状態でリポジトリより上の階層に出る module_subdir(バックスラッシュも区切り文字として扱われます)は、何かがフェッチされる前に拒否されます。リポジトリはそれ自身のチェックアウトからアーカイブされます。リポジトリがコミットしているシンボリックリンクは、リンク先がリポジトリ内にある場合はリンク先のファイルまたはディレクトリとしてアーカイブされ、リポジトリの外を指すリンクはプルを停止させ、そのリンクをリポジトリ内の位置で示します。url: がファイルシステムのパスを指す構造化ソースはフェッチされません。単なるパス文字列と同じ条件でディスクから読み込まれ、相対的な url: はそれを宣言するエンティティファイルを含むディレクトリを基準とします。kind/url を省略した構造化ソースもフェッチされず、フェッチが意図されていた場合、何も解決しないまま黙って進むのではなく、ロック時のソース走査でビルドが明示的に停止します。コンテンツは常に事前に固定され、コンパイラが実行時の状態をライブでフェッチすることはありません。
Recipe の横に固定されるもの。 kind、url、chart、module_subdir、version、ref がすべてテンプレートではなく直接記述された取得ソースについて、aggrega pin は取得したもののダイジェストを entity.lock に記録します。これは Recipe 自身のディレクトリにあるファイルで、Recipe と一緒にコミットします。固定は Recipe の作成者が行う手順で、Release を必要としません。ロックに固定が記録されていない Recipe に対するプルは、停止してそれを示します。ただし、プルに同じ手順を実行するよう求めた場合を除きます。ビルドはそのダイジェストを、Release のロックファイルが同じソースについて記録しているダイジェストと比較し、両者が一致しない場合は停止します。ただし、git の ref: で記述されたソースは例外で、その行は ref が解決されたコミットで記録され、比較されません。座標がテンプレートから埋められる取得ソースは、代わりに Release ごとに、各 Release のロックファイルに固定されます。Recipe の横にあるディレクトリやファイルを指すソースは取得されません。aggrega pin は、そのソースが Recipe の公開物に含めるファイルごとに 1 つのダイジェストを記録します(テンプレートとして記述されたソースの場合は Recipe のディレクトリ内のすべてのファイル)。ロックにそれらが記録されると、ビルドはプロバイダーがソースを読む前にそれらと比較し、固定以降にファイルが追加、変更、削除されていれば停止します。このとき E0305 で停止しますが、変更前に書かれた Release のロックファイルが Recipe をその内容によって記録している場合は、先に E0130 で停止します。このようなソースについて固定を記録していないロックでは、ビルドは比較するものがなく、固定を行わないプルや公開はそれを拒否します。Recipe ファイル自体に書き込まれることはありません。aggrega pull で、このファイルと各停止への対処方法を説明しています。
spec.capability には、implements と同じ形式でバージョン固定を付けることができます。完全一致(helm:<version>)またはキャレット範囲(helm:^<version>)で、どのバージョンのプロバイダープラグインが Recipe をレンダリングするかを選択します。利用可能などのバージョンも満たさない固定はビルドを停止します。固定がない場合(spec.capability: "helm")は、利用可能な最上位のバージョンがレンダリングします。利用可能なバージョンは aggrega plugin list が示すものです。aggrega に組み込まれたプロバイダーはコンパイラ自身のバージョンを持ちます。固定は Recipe の名前の一部ではありません。Manifest は capability: "compose:1.2.3" を宣言する Recipe を、固定のないものとまったく同じく compose/<name>:<version> としてマッピングし、固定を変えても名前が変わることはありません。固定を名前に書き込んだマッピング値(compose:1.2.3/<name>:<version>)は、何かが検索される前に不正な recipe 参照として拒否されます(E0095)。
メンタルモデル: spec.capability は必要な出力形式(例: helm、terraform、compose)を指定し、コンパイラはそれを、その形式をレンダリングする Wasm プラグイン(例: provider/helm)に解決します。形式を宣言するのは利用者で、ツールを結び付けるのは Aggrega です。
B. コンテキスト注入: セマンティックマッピング層
複数の環境にまたがる危険で非決定的なディープマージをコンパイラが行わないよう、Recipe はマッピング層について単一の信頼できる情報源のみを許可します。
Ops エンジニアは、Wasm レンダリングプラグインが実行される前に抽象コンテキストを変換するマッピング内容を記述します。マッピング言語は Go テンプレート(text/template + Sprig)です。Sprig ライブラリは事前登録されており、標準の define と template アクションはサポートされますが、include は登録されていません。
| フィールド名 | スコープと実行フェーズ | 最適なユースケース |
|---|---|---|
injectMapping (FeatureRecipe のみ) | レンダリング前のインターセプト。 ベース Recipe の前に Go のメモリ内で評価されます。出力辞書を、呼び出し元の .context.inject パイプの上にネイティブに厳密にディープマージします。ベースの Recipe スキーマには意図的に含まれていません。アーキテクチャ上の根拠は entities/featurerecipe を参照してください。 | Wasm JSONPatch を必要とせずに、注入された env 変数を外科的に書き換えたり、呼び出し元向けに FQDN を整形したりします。 |
valuesMapping | ベースレンダリング(Go テンプレート)。 変数を基盤となる source のインフラストラクチャ chart/module にマッピングするために評価されます。単一のフィールドで、3 つの記述モード(インライン、ファイル $import:、ライブラリ $import:)があります。ディスパッチの仕組みは下のサブセクションを参照してください。 | 標準的な変数(レプリカ数やイメージタグなど)を Recipe YAML 内で直接 Helm chart にマッピングする、または Recipe 間で再利用するために $import: で共有テンプレートを参照します。 |
注: injectMapping は FeatureRecipes 専用であり、変数のインターセプトを valuesMapping から分離します。ベース Recipe の valuesMapping は、FeatureRecipe の injectMapping ブロックが生成した書き換え済みの .context.inject 文字列を、それと知らずに消費するため、両者は分離されたままです。
valuesMapping が null と書いたキーは null として provider に届き、そこでどう扱われるかは provider が決めるため、各 provider のページに記載されています。helm はそのキーに対する chart のデフォルトを削除し、helm-chart はアンブレラの values に書き込み、compose は compose ファイルに書き込み、terraform は null のモジュール引数として書き込み、cloudformation は拒否します。
valuesMapping フィールド — 3 つの記述モード
Recipe の valuesMapping: は、3 つのディスパッチモードを受け付ける単一の Go テンプレートの面です。コンパイラはフィールドの内容の形に基づいてディスパッチするため、$mode: アノテーションは不要です。
モード 1: インライン Go テンプレート(YAML ブロックスカラー)。 フィールドの値は、YAML ブロックスカラーの | 形式で書かれた文字列です:
spec: valuesMapping: | {{- with .values -}} image: tag: {{ optional .image `tag` "11.4.4-debian-12-r0" }} pullPolicy: {{ optional .image `pullPolicy` "IfNotPresent" }} architecture: {{ optional . `architecture` "standalone" }} primary: replicaCount: {{ optional .primary `replicaCount` 1 }} {{- end }}インラインモードは、マッピング内容が小〜中規模(約 50 行未満)の Recipes で典型的な記述形式です。テンプレート本体は Recipe の他の部分とインラインで並び、Recipe の内容は自己完結します。
モード 2: ファイル $import:。 フィールドの値は、ローカルファイルパスを持つ $import: のみを含むマップです:
spec: valuesMapping: $import: ./mappings/api-server.tmplコンパイラはファイルの内容(Go テンプレート)を読み込み、標準の Recipe テンプレートコンテキストに対してレンダリングし、その結果をマッピング出力として扱います。パスの解決は Recipe のディレクトリからの相対です。相対パスは、それを宣言する recipe.yaml を含むディレクトリを基点とし、ビルドを起動したディレクトリではありません。また、Recipe のコンテンツパスは Recipe 自身のディレクトリ内にとどまるで説明するとおり、パスはそのディレクトリ内にとどまる必要があります。ファイルモードは、中〜大規模のマッピング内容(約 50 行以上)や、マッピングの変更を独立したファイルの差分として確認するレビュー形態に適しています。
モード 3: ライブラリ $import:。 フィールドの値は、MappingLibrary のエントリへの bare-name の識別参照を持つ $import: のみを含むマップです:
spec: valuesMapping: $import: DatastoreHelpers#/mappings/MariaDBCoreコンパイラは、解決済みの MappingLibrary の集合(ローカルカタログと、lockfile で固定されたライブラリ)に対して参照を解決し、エントリの内容を読み込んで、マッピング出力として扱います。本体自体がフィールドルートの $import: であるエントリは再帰的に解決されます。参照にはレジストリホストは含まれません。ライブラリ名は識別によって解決され、バージョンは Release ごとの lockfile から得られます。任意で :<version> の最小バージョン下限を指定できます(<Library>:<version>#/mappings/<entry>)。ライブラリの内容は標準の Recipe テンプレートコンテキストを共有します。ライブラリモードは Recipe 間の再利用、つまり多くの Recipes で繰り返し現れるマッピングパターン(データストアのヘルパーロジックを共有する複数のデータストア Recipes、pod テンプレートのパターンを共有する複数の Helm provider の Recipes)に適しています。MappingLibrary エンティティは、バージョニング、lockfile による固定、ハブ UI での表示を提供します。
ディスパッチ規則。 コンパイラは YAML ノードをたどり、内容の形に基づいてディスパッチします:
- ノードが文字列スカラーであれば、インラインモード(モード 1)としてディスパッチします。
- それ以外の場合、ノードはマップです。
$import:キーを確認します。 $import:の値が bare-name のライブラリ参照(<Library>#/mappings/<Entry>、任意で:<version>の下限付き)であれば、ライブラリモード(モード 3)としてディスパッチします。- それ以外(ローカルファイルパス)の場合は、ファイルモード(モード 2)としてディスパッチします。
- それ以外の形(
$import:を持たないマップ、$import:以外に追加のキーを持つマップなど)は、ビルド時エラーになります。
単一ソースの $import: のみ。 $import: は単一のソースを受け付けます。valuesMapping: では複数ソースのマージはサポートされません。複数のマッピング断片を組み合わせる必要がある Recipe は、内部で Go テンプレートの define / template による合成を行う MappingLibrary エントリ、兄弟ファイルを呼び出す Go テンプレートの template ディレクティブを持つローカルファイル、または短い内容であればインラインでの合成を使います。ライブラリエンティティについては entities/mappinglibrary、より広い $ref: / $import: の区別については vocabulary/cross-document-ref を参照してください。
出所。 テンプレートのレンダリング失敗によるエラーメッセージは、モードごとに適切な出所を示します。インラインテンプレートはブロックスカラーが始まる Recipe の file:line を示し、ファイルインポートはインポートされたファイルの内容を示し、ライブラリインポートは MappingLibrary エントリのソース位置を示します。その際、ホストを含まないライブラリ識別(<Library>#/mappings/<entry>)が安定した参照のための正規のポインタとなります。参照にレジストリホストが含まれると拒否されるため、物理的な場所がポインタに入ることはありません。
C. ネイティブ IaC サポート
独自の Infrastructure as Code を持ち込む Ops チームは、それを Recipe 自身のディレクトリ(source: で指定する ./src のようなモジュールまたはテンプレートのディレクトリ)に置くか、構造化された source: で取得するか(kind: git-repository を使って git リポジトリから取得する Terraform モジュールなど)、artifacts: の下にテンプレート化された本体として記述します。マッピング層(valuesMapping:。インライン、ファイルインポート、ライブラリインポートのいずれか)がそのコードに抽象的なコンテキストを提供し、プロバイダーはターゲット自身の形式で結果を出力します。ある構成言語が別の構成言語に変換されることはありません。
- Terraform: モジュールはファイル単位でそのままベンダリングされ、作成された本体は記述どおりに出力されます。ネイティブ HCL(
main.tf)でも Terraform JSON(.tf.json)でも同様で、terraformCLI はその両方を読み取ります。バウンダリのルート構成aggrega.modules.tfは、各コンポーネントのディレクトリをmoduleブロックとして呼び出し、ソースから取得したモジュールのvaluesMapping:の出力がそのブロックの引数になります。terraform プロバイダー を参照してください。 - CloudFormation: ソースから取得したテンプレート(YAML または JSON)と、Recipe が作成するリソースフラグメントは、ロングフォームの JSON に正規化され、バウンダリごとに 1 つのスタックテンプレートにマージされます。
valuesMapping:の出力は、ソースのテンプレートが宣言するパラメーターを埋めます。cloudformation プロバイダー を参照してください。
インフラストラクチャが適用されて初めて存在する値は、ターゲットが解決するポインター(Terraform の ${ ... } 補間、CloudFormation の Ref や Fn::GetAtt)のままであり、ビルド時に評価されることはありません。
例 A: リモート Helm chart(インラインマッピングと locals の契約)
apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: mariadb-chart version: 1.0.0spec: capability: helm implements: core/datastore/mariadb:1.0.0 source: # The shipped fetch form: { kind, url, version }. 'kind' selects a built-in # resolver (helm-oci-chart, helm-https-chart, compose-https-fragment). kind: helm-oci-chart url: oci://registry-1.docker.io/bitnamicharts/mariadb # Default chart version. Override via infra.source_version. version: "{{ optional .infra `source_version` \"25.0.8\" }}"
locals: primary_compute: mariadb listen_port: "3306" volumes_path: "/spec/template/spec/volumes" root_path: "/-" # The Base Recipe EXPLICITLY dictates the physical secret name to the Wasm # pipeline: the suffix it follows the rendered name with. A local cannot read # .context.rendered_name, so each template writing the full name joins the two. secret_target_db_password: "mariadb-auth"
provides: # The chart's primary Service, named by the fullnameOverride pinned below host: "{{ .context.rendered_name }}" port: "3306" # Every key the Component's provides contract declares is published user: "{{ .values.user }}" database: "{{ .values.database }}" protocol: "mariadb"
valuesMapping: | fullnameOverride: "{{ .context.rendered_name }}" auth: # Reads the suffix from the local rather than restating it, so the secret # name is authored once and every reader follows that one definition existingSecret: "{{ .context.rendered_name }}-{{ .locals.secret_target_db_password }}" primary: persistence: size: "{{ .infra.storage.size }}"例 B: ローカルの Terraform モジュール(ファイルマッピング)
apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: aws-s3-tf version: 1.0.0spec: capability: terraform implements: aws/s3-bucket:1.0.0 source: "./src"
locals: primary_compute: bucket_instance resource_path: "/resource/aws_s3_bucket/main" root_path: "/data"
# Guaranteeing global uniqueness across multiple AWS environments valuesMapping: | bucket_name: "{{ .metadata.release_name }}-{{ .context.instance_id }}-data" region: "{{ .infra.aws_region }}"例 C: 具体的な Component Recipe(インフラストラクチャをバインド)
Ops が汎用インターフェースを物理的な実体にマッピングします。(L4 ネットワークの詳細がバインドされるのはここです。ハードコードされるか、下記のプロキシポートのように、Release が埋める infra ブロックから取得されます。)
apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: kong-gateway version: 1.0.0spec: capability: helm implements: core/gateway/kong:1.0.0 source: # A chart repository root paired with the chart's name. kind: helm-https-chart url: https://charts.konghq.com chart: kong version: "{{ optional .infra `source_version` \"3.4.1\" }}"
provides: # The chart's proxy Service: it suffixes the name pinned below with "-proxy" host: "{{ .context.rendered_name }}-proxy" port: "{{ .infra.proxy_port }}" protocol: "http" # The contract's other keys: empty while nothing is wired to the models # socket, and while metrics are off endpoint: '{{ with optional .values "model" "" }}http://{{ $.context.rendered_name }}-proxy:{{ $.infra.proxy_port }}/{{ . }}/v1{{ end }}' model: '{{ optional .values "model" "" }}' metrics_endpoint: '{{ if .values.metrics_enabled }}http://{{ .context.rendered_name }}-status:8100/metrics{{ end }}'
valuesMapping: | fullnameOverride: "{{ .context.rendered_name }}"クラウドリソースの命名規律。
クラウドリソース名(S3 バケット名、RDS データベース識別子、IAM ロール名、CloudFormation スタック名、およびクラウドプロバイダーのグローバル名前空間を占める値を持つその他のフィールド)を出力する Recipes は、同じ Recipe が複数の Releases や component インスタンスにわたって実行されたときの衝突を避けるため、レンダリングされる名前に {{ .metadata.release_name }} と {{ .context.instance_id }} の一方または両方を連結する必要があります。例 B の bucket_name: "{{ .metadata.release_name }}-{{ .context.instance_id }}-data" が標準的なパターンです。
この規律は、単一のグローバル名前空間が名前を制約するあらゆる場所に適用されます。AWS S3 のバケット名は、リージョン内のすべてのアカウントで 1 つのグローバル名前空間を共有します。同じ Aggregate の 2 つの Releases(prod-billing と staging-billing)が、どちらも customer-data という名前のバケットをデプロイすることはできません。2 つ目のデプロイは実行時に AWS 側で拒否されて失敗します。release_name を連結すると Release ごとに区別され、context.instance_id を連結すると component インスタンスごとに区別され、両方を連結すると Release ごと・component ごとに区別されます。
コンパイラがチェックすることとしないこと。 コンパイラは、これらの補間を含まないクラウドリソース名フィールドについて valuesMapping: の出力を検査しません。この規律は、Recipe の作成者(対象プロバイダーでどのフィールドがグローバルに一意なリソースを命名するかを知っています)とレビュアー(PR レビューで未命名リソースのパターンを見つけます)によって守られます。linter プラグインであれば、valuesMapping: の出力が release_name / instance_id の補間なしにクラウドリソース名フィールドを参照する Recipes を検出できます。linter ソケットは提供されており aggrega lint を通じて実行されますが(plugins/plugin-contract.md の「Placement criterion: the linter socket vs the governance verdict roles」を参照)、公開用 linter のルールにこれをチェックするものはありません。
この規律は、慣例によって守られるいくつかの社会契約の 1 つであり、作成者がコンパイラによる強制ではなくドキュメントから学ぶ作成規律です。慣例の完全な一覧と、各契約の分類に関するアーキテクチャ上の根拠については、vocabulary/social-contracts.md を参照してください。
source フィールドのテンプレート化。
Recipe の source フィールド自体もテンプレート化の対象です。source のどちらの形も Go テンプレートを受け付けます。汎用文字列形式
source: "{{ optional .infra `module_path` \"./src\" }}"と構造化オブジェクト形式(文字列値の各サブフィールドはテンプレート評価され、文字列以外のサブフィールドはそのまま渡されます)です。source テンプレートが読み取れるものは、その source がリモートのアーティファクトを指すかどうかによって異なります。 リモート source の座標、つまりレジストリ、チャートリポジトリ、または git リポジトリを指す構造化ブロックの version、chart、ref、module_subdir は、aggrega pull がアーティファクトを解決してピン留めするときに評価されます。評価対象は .values、.infra、.locals のみで、使えるのは Aggrega 独自のヘルパー(optional、capitalizedWords、index)だけであり、Sprig の関数は使えません。.context はこの対象に含まれないため、component にどのアーティファクトがピン留めされるかは、与えられた values と infra によって決まり、インスタンス名によって決まることはありません。そこで評価される locals: のエントリは、それらのフィールドが読み取るエントリと、そのエントリがさらに読み取るエントリです。どの source フィールドも読み取らないエントリは source の解決中には評価されないため、レンダリングだけが必要とする local(Sprig 関数を呼ぶもの、または .context.instance_id を読み取るもの)はピン留めに影響せず、ノードのレンダリング時に評価されます。{{ index .locals "version" }} のように特定のエントリを名指ししない形で .locals を読み取るフィールドがあると、すべてのエントリが評価されます。上記のようにワークスペース内のパスを指す source は、ピン留めのために解決されません。そのテンプレートはノードのレンダリング時に、Recipe の locals と同じ自己完結したコンテキスト(.context.instance_id、.values、.infra、そしてノードの解決済みブロック全体である .locals)に対して評価されます。そのため、locals: エントリと同じ参照ルートを許可・拒否しますが、有利な違いが 1 つあります。上にあるエントリだけでなく、ブロックが宣言する任意のエントリを読み取れます。リモートの座標も同様に、ブロックが宣言する任意のエントリを読み取れます。.provides はどちらのコンテキストにも含まれず、source テンプレートが自身のノードの provides を参照しようとするとビルドが停止し、問題の参照が示されます。これは後の作業を待つ欠落ではなく、この対象の固定的な性質です。provides: が .locals を読み取れるように、ノードの locals はその provides より先に解決され、source テンプレートは provides を先読みする代わりに、同じ解決済みの locals を読み取ります。.context.inject と .context.uses への参照も、同じ自己完結性の理由から禁止されています。source URI は、トポロジーのパイプが構築される前、かつ URI が指すチャート、モジュール、またはアーティファクト本体を下流が読み込む前に解決されなければなりません。完全な利用可否のルールと禁止参照の根拠は Template Expansion Matrix の行 #5 にあります。標準的な用途は、Component が公開する infra.source_version のオーバーライドを source の version フィールドに渡すことです(entities/component の「The infra Pillar」を参照)。これにより、カタログは互換性のある上流バージョンが上がるたびに Recipe を再公開する必要がなくなります。
source フィールドのスキーム一覧。 source: フィールドは、スキーマ上いくつかの形のバリエーションを受け付けます。各バリエーションの実行時サポートはプロバイダーによって異なります。下の表は、それぞれの形が何をするかを示します。
| 形 | 例 | ステータス |
|---|---|---|
| 単純な相対ファイルシステムパス | source: "./charts/postgres" | available — 提供中のすべてのプロバイダー(helm、helm-chart、compose、terraform、cloudformation)が、単純なファイルシステムパス文字列を受け付けます。 |
| 単純な絶対ファイルシステムパス | source: "/abs/path/to/chart" | accepted but blocked — スキーマはこれを受け付けますが、Recipe を読み取るすべてのコマンドが拒否します。絶対パスは Recipe 自身のディレクトリ内のコンテンツではなく、それが書かれたマシン上の場所を指すため、Recipe と一緒に持ち運べません。チャートを Recipe のディレクトリに移動し、そこからの相対パスで指定してください。コンテンツパスは Recipe 自身のディレクトリ内にとどまる を参照してください。 |
| 空文字列 | source: "" | accepted but blocked — スキーマは空文字列を受け付けますが、Recipe を読み込むすべてのコマンドは、Recipe の読み取り時にそれを拒否します。空文字列はどちらのモードも指定しないためです。この拒否は、曖昧さと、そこから抜け出す 2 つの方法を示します。sourceless モードにするにはフィールドを省略し、sourced モードにするには実際のパスまたは URI を指定します。aggrega validate <recipe-file> は Recipe に対してこれを報告し、aggrega pull、aggrega build、aggrega validate --release はその Recipe に到達する Release に対してこれを報告します。errors/fatal-halts.md の「Recipe source: is an empty string(Recipe の source が空文字列です)」を参照してください。 |
url: がトランスポートスキームを持つ構造化オブジェクト | source: { url: "oci://…/mariadb", version: "25.0.8" } | available — 組み込みの source-resolver は {kind, url, version, chart, ref, module_subdir} 形式を読み取り(url: のスキームが種類を選びます。oci:// → OCI チャート、https://….tgz → チャートアーカイブ、chart: と組み合わせた https:// リポジトリルート → リポジトリチャート。あるいは kind: で指定します)、aggrega pull でアーティファクトを取得してピン留めし、ビルドはキャッシュからそれを展開します。代替としてチャートをローカルにベンダリングすることもサポートされていますが、必須ではありません。スキーマは開いた構造化オブジェクトを受け付けます。providers/helm.md の「source: keyset」を参照してください。 |
url: がファイルシステムパスを指す構造化オブジェクト | source: { kind: helm-oci-chart, url: "./charts/postgres", version: "1.0.0" } | available — トランスポートスキームを持たない url: はパスを指すため、何も取得されず、何もピン留めされません。ビルドはディスクから内容を読み取ります。相対的な url: はそれを宣言する recipe.yaml を含むディレクトリを基準とし、そのディレクトリの外に出るもの(絶対パスを含む)は拒否されます。これは上の 2 つの素のパスの行と同じ解釈であり、記述した形によって変わることはありません。内容の読み取り元を決めるのは url: だけです。その他のフィールドは取得されるはずのものを選択し、引き続き .source.* として Recipe のテンプレートに渡されます。 |
OCI URI(oci://...) | source: "oci://hub.aggrega.ai/recipe/helm/postgres:1.0.0" | planned — カタログ配布のための設計目標です。現在の 3 層リゾルバ(Release がパスで指定するファイル、ワークスペースカタログ、リモート OCI レジストリ)は architecture/13-catalog-and-registry.md に記載されています。エンティティレベルのリゾルバはそのカスケードを通じて OCI URI を扱いますが、Recipe ごとの source: フィールドの OCI 形式は現在 provider に接続されていません。 |
その他の URL スキーム(https://、git+https:// など) | (例示) | planned — アーキテクチャのプラガブルソースのロードマップに設計意図として記載されています。現在 provider のサポートはありません。 |
source: パスの基準の決まり方。
基準付けはファイルシステムパスにのみ適用され、パスを持つのが 2 つの形のどちらであっても適用されます。相対パスはそれを宣言する recipe.yaml を含むディレクトリを基準とし、そのディレクトリの外に出るパス(絶対パスを含む)は、コンテンツパスは Recipe 自身のディレクトリ内に留まるで説明するとおり拒否されます。トランスポートスキームを持つ参照(oci://、https://、http://、git://、ssh://、git+ssh://、または .git で終わる参照)はパスではなく取得対象を指すため、記述したとおりにそのまま引き渡され、ディレクトリと結合されることはありません。
構造化形式ではパスは url: フィールドであり、同じように解釈されます。相対的な url: は recipe.yaml を含むディレクトリを基準とし、そのディレクトリの外に出るものは拒否され、トランスポートスキームを持つものは取得されます。構造化された source: のその他のフィールドは、provider 定義のものも含め、変更されずにそのまま引き渡されます。
テンプレートとして記述された source: は、テンプレート自体のテキストではなく、テンプレートが生成する値に対して基準付けされます。テンプレートは評価されるまで何も指さないため、上記の解釈はその結果に適用されます。結果が相対パスであれば recipe.yaml を含むディレクトリを基準とし、そのディレクトリの外に出るもの(絶対パスを含む)はビルドを停止させ、トランスポートスキームを持つものは引き渡されて取得されます。したがってテンプレートは上記一覧のどの形でも生成でき、それぞれは同じ値をリテラルで記述した場合とまったく同じに扱われます。違いはパスを判定できる時点だけで、テンプレートの場合は Recipe が読み込まれる時点ではなく、ビルドが評価する時点です。
何も生成しないテンプレート(空の結果)は Recipe を source なしの状態にし、これは sourceless モードです。これは自分で source: "" と記述することとは異なります。後者はどちらのモードも指さず、拒否されます。上の一覧の行を参照してください。
この一覧は、作成者が source: に何を書けるかについての正規のリファレンスです。そのラベルは 10-status.md が定義するものです。
コンテンツのパスは Recipe 自身のディレクトリ内にとどまる
Recipe のコンテンツは Recipe 自身のディレクトリに置かれます。Recipe の公開物が運ぶファイルはすべてそこから取得されるためです。Recipe が運ぶコンテンツのために記述するすべてのパス(source: は素のパスでも構造化形式の url: でも同様、また valuesMapping:、workload:、artifacts: の各エントリが $import: でインポートする各ファイル)は、recipe.yaml を含むディレクトリを基準に読み取られ、そのディレクトリ内にとどまる必要があります。これらのパスは公開物が運ぶものでもあります。パスが指すファイルは Recipe とともに移動し、ディレクトリ内のそれ以外のものは移動しません(aggrega push を参照)。ディレクトリの外に出るパスは Recipe とともに移動しないファイルを指すため、利用する側にはそのファイルが存在せず、そのファイルに対して記録されたピンは、利用者が入手できないバイト列を保証することになります。
ディレクトリの外に出る形は 2 つあり、どちらも拒否されます。
../shared/charts/appのように、ディレクトリより上へ上るパス。/opt/charts/appのような絶対パス。これは記述されたマシン上の場所を指します。
上ってから内側に戻るパスは、ディレクトリ内の通常のパスです。./charts/../values.tmpl は Recipe の隣にある values.tmpl を指します。判定されるのはパスの到達先であり、Recipe のディレクトリから外に出ずに測られます。そのため、1.0.0 というディレクトリ内で記述された ../1.0.0/values.tmpl のように、外に出て戻る途中でディレクトリ名を再び指定するパスも拒否されます。ディレクトリ自身の名前は移動しません。公開された Recipe は利用者のキャッシュが名付けたディレクトリから読み取られ、そこではその名前は何も指しません。
拒否される場所。 Recipe を読み取るすべてのコマンドは、何かが取得、レンダリング、公開される前に、読み取りの時点でそのようなパスを拒否します。対象は aggrega validate(カタログに対しても Recipe 自身のファイルに対しても)、aggrega pull、aggrega build、aggrega pin、aggrega push です。テンプレートとして記述された source: はビルドが評価するまで何も指さないため、ディレクトリ外のパスを生成するテンプレートは、値が存在した時点でビルドによって拒否されます。この停止は A path names content outside the entity’s own directory(パスがエンティティ自身のディレクトリ外のコンテンツを指しています) であり、記述したパスを表示します。
代わりにどうするか。 ファイルを Recipe のディレクトリ、またはその配下のディレクトリに置き、Recipe からの相対パスで指定します: ./charts/app、./extras/netpol.yaml。複数の Recipes が使う chart は、各 Recipe が個別に公開されるため、各 Recipe のディレクトリにコピーします。複数の Recipes が共有する mapping、workload、artifact の本体は MappingLibrary、WorkloadLibrary、ArtifactLibrary に置き、各 Recipe はそれを ID で参照します。
Release が異なる理由。 Release は他のエンティティ(その Aggregate、その Manifest、拡張元の Release)を指し、公開されることはないため、読み取るものはどこにも移動しません。それらの参照と、parameters: がインポートするファイルは記述どおりに読み取られます。これにより、1 つの Aggregate をサブディレクトリ内の Release バリアント間で共有できます。entities/release.md を参照してください。
同じ制限は FeatureRecipe にも、Component または Feature がインポートするすべてのスキーマにも適用されます。
workload: フィールド — 合成される入力種別
Recipe.spec.workload: は、コンパイラがプロバイダーネイティブなリソースへと合成する Workload 本体を宣言します。これは、source:(ソースからのレンダリング)および artifacts:(補助マニフェスト)と並んで Recipe が宣言できる 3 つの入力種別の 1 つです。どのプロバイダーでも 3 つのうち少なくとも 1 つが必要です。ビルドがプロビジョニングしないサービスは、form: reference の workload: を宣言します。
このフィールドは 3 つの記述モードを受け付けます。インラインのブロックスカラー、ファイルの $import:、ライブラリの $import: です。コンパイラはフィールドの内容の形状に基づいて振り分けるため、$mode: アノテーションは不要です。
モード 1:インライン(Go テンプレートの文字列スカラー)。 値は YAML のブロックスカラーで、その出力は aggrega.ai/v1beta1 Workload としてパースされます:
spec: capability: helm implements: core/web-server:1.0.0 workload: | apiVersion: aggrega.ai/v1beta1 kind: Workload replicas: {{ optional .infra "replicas" 1 }} containers: app: image: "{{ .values.image }}" ports: http: 8080Workload のフィールドはドキュメントのルートに置かれ、spec: のラッパーはありません。また containers: と各コンテナの ports: はシーケンスではなく名前をキーとするマップで、記述した順序が保持されます。プロバイダーはこの形状を自身のネイティブな形式に変換するため、コンテナのマップエントリは helm のレンダリング出力では、そのキーを名前とする containers[] 要素として現れます。記述する形状はマップであり、レンダリングされたリストではありません。
モード 2:ファイルの $import:。 値は、ローカルの Go テンプレートファイルを指す単一の $import: キーを持つマップです。
spec: workload: $import: ./workload/web-server.yaml.tmplパスの解決は valuesMapping: と同じです。相対パスは、ビルドを起動したディレクトリではなく、それを宣言する recipe.yaml を含むディレクトリを基点とし、そのディレクトリの内側に留まる必要があります。インポートされた本体は、インラインの本体とまったく同じように、Recipe のレンダリングコンテキストで評価される Go テンプレートです。
モード 3:ライブラリの $import:。 値は、WorkloadLibrary のエントリへのベア名によるアイデンティティ参照を持つ単一の $import: キーからなるマップです。
spec: workload: $import: BaseWorkloads#/workloads/StatelessServiceWorkload エントリを選択するのは #/workloads/ フラグメントであり、このフラグメントによって、この参照は valuesMapping: が使う #/mappings/ 形式と区別されます。後者は MappingLibrary のエントリを指し、Workload 本体を指定しません。参照はレジストリホストを含まず、解決されるバージョンは Release ごとのロックファイルから得られます。オプションの :<version> による最小バージョンの下限を <Library>:<version>#/workloads/<Entry> として指定でき、本体自体がフィールドルートの $import: であるエントリは再帰的に解決されます。インポートされた本体は、利用する側の Recipe のレンダリングコンテキストで評価される Go テンプレートであるため、.values、.infra、.features はインラインの本体とまったく同じように流れ込みます。ライブラリエンティティと参照の完全な文法については entities/workloadlibrary を参照してください。
対象のプロバイダーは合成をサポートしている必要があります(標準ライブラリのカタログは、慣例としてそのようなプロバイダーに workloadSchema を宣言します)。合成できないプロバイダーを対象にすると、ノードのレンダリング時にプロバイダー機能の診断で拒否されます。この判定は workloadSchema の有無ではなく、プロバイダーの機能に基づきます。Workload の完全な文法、K8s 形状のパススルーフィールド、プロバイダーごとの変換動作については entities/workload.md を参照してください。3 つの入力種別からなるより広いモデルと、合成をソースからレンダリングされた出力および成果物とマージするアセンブラについては architecture/16-recipe-input-composition.md を参照してください。
コンポーネント自身の値を開発者自身のイメージに渡す。開発者がビルドするイメージを実行する Recipe は、標準ライブラリカタログの慣例により、開発者の inject: ブロックが解決したものをすべて .context.inject から渡すことが想定されており、さらにコンポーネント自身の値を独自の名前で渡すこともできます。Component が spec.inject を宣言している場合は、開発者自身のブロックが名前を選び、.context.self_inject が、各エントリのテンプレートが読み取る自身の値 1 つを Recipe に伝えます。自身の値をちょうど 1 つだけ読み取り、それ以外は何も読み取らないエントリでは、それは values.<key> です。標準ライブラリカタログの慣例では、Recipe がこれらの値に付ける名前を、開発者のコードが読み取らなければならない契約ではなくデフォルトとして扱い、どのエントリもその値にマッピングされていない場合にのみ、その値をデフォルト名で渡します。エンタープライズカタログは別の選択をしてもかまいません。テンプレートコンテキストの契約 に、このマップの正確なルールと完全なテンプレート例があります。
artifacts: フィールド — 補助マニフェスト
Recipe.spec.artifacts: は、エントリ名 → アーティファクト本体の記述からなるマップであり、そのエントリは Recipe のソース由来または合成されたプライマリ出力と並んで追加のマニフェストファイルを出力します。これは 3 つの入力種別(ソース由来/合成/アーティファクト)の 1 つです。Recipe は artifacts: を単独で宣言することも、workload: や source: と併せて宣言することもできます。
各エントリの値は、workload: と同様に内容の形でディスパッチされる 3 つのモード(インラインの内容、ファイルの $import:、ライブラリの $import:)のいずれかを持ちます。コンパイラは値の内容の形でディスパッチするため、$mode: アノテーションは不要です。マップのキーは、3 つのモードすべてでエントリが出力するものを指定します。単一ファイルの 2 つのモードでは出力ファイル名であり、バンドルモードではバンドルのファイルが配置されるディレクトリです。キーが出力を指定するため、キーは単一のファイル名として取りうるものに制限されます。先頭は英字または数字で、その後に英字、数字、ドット、ハイフン、アンダースコアが続きます。ドットにより、キーが慣例として持つ拡張子(main.tf、template.yaml、serviceaccount.yaml)を保持できます。一方、この文字集合は / を許可しません。これを許すとキーがファイルではなくパスを指定することになるためです。また先頭の . も許可しないため、キーが親ディレクトリのセグメントになることはありません。この文字集合に含まれないキーは、ワークスペースの読み込み時、aggrega validate の実行時、およびエディタの診断において、エンベロープの検証に失敗します。
spec: capability: helm implements: core/web-server:1.0.0 artifacts: extra-configmap.yaml: | apiVersion: v1 kind: ConfigMap metadata: name: "{{ .context.instance_id }}-extras" data: threshold: "{{ .values.threshold }}" network-policy.yaml: $import: ./artifacts/network-policy.tmpl operator-support: $import: PlatformArtifacts#/artifacts/OperatorSupportモード 1:インライン(Go テンプレートの文字列スカラー)。 値はブロックスカラーであり、マップのキーが記述どおりに出力ファイル名として使われます。上の最初のエントリは extra-configmap.yaml を出力します。
Mode 2: File $import:. 値は、ローカルの Go テンプレートファイルを指す単一の $import: キーを持つマップで、マップキーはモード 1 とまったく同じく出力ファイル名です。インポートされたファイルが提供するのは内容であり、名前ではありません。上の 2 番目のエントリはキーが network-policy.yaml で、インポートするファイルの名前が network-policy.tmpl であっても network-policy.yaml を出力します。したがって、特定の出力ファイル名を使いたい作成者はそれをキーとして書きます。また、たまたま同じ名前を持つ異なるファイル(./extras/shared.yaml と ./overrides/shared.yaml)をインポートする 2 つのエントリは、2 つの別個の出力になります。パスの解決は valuesMapping: および workload: と同じです。相対パスは、ビルドを起動したディレクトリではなく、それを宣言する recipe.yaml を含むディレクトリを基準とし、そのディレクトリの内側にとどまる必要があります。
モード 3:ライブラリの $import:。 値は、ArtifactLibrary のバンドルへの素の名前によるアイデンティティ参照 <Library>#/artifacts/<name> を持つ単一の $import: キーからなるマップです。バンドルは 1 つの単位としてインポートされるファイルの集合であるため、1 つのエントリはバンドル内のファイルごとに 1 つの出力に展開され、それぞれがマップのキーの下に <key>/<filename> として配置されます。キーは利用箇所を指定し、いずれか 1 つのファイルの名前ではなく、それらのファイルが置かれるディレクトリになります。上の 3 番目のエントリはキーが operator-support です。PlatformArtifacts#/artifacts/OperatorSupport が crd.yaml と rbac.yaml を宣言している場合、この単一のエントリは operator-support/crd.yaml と operator-support/rbac.yaml を出力します。参照はレジストリホストを持ちません(ホストを含む oci://… 形式は拒否されます)。解決されるバージョンは Release ごとのロックファイルから取得され、任意の :<version> による最小バージョンの下限を <Library>:<version>#/artifacts/<name> として指定できます。ライブラリエンティティと参照の完全な文法については entities/artifactlibrary を参照してください。
ファイルの $import: は Recipe のそばでピン留めされます。 aggrega pin は、インポートされた各ファイルのバイト列のダイジェストを、エントリのマップキーをキーとして Recipe のディレクトリにある entity.lock に記録します。aggrega build はファイルのダイジェストを再計算し、一致しなくなった場合は [CATALOG_ERROR E0026] で停止します(編集前に書かれた Release のロックファイルが Recipe をその内容によって記録している場合は、先に E0130 で停止します)。そのため、ピン留め後に編集されたファイルが未検証のままレンダリングされることはありません。変更が意図したものであれば、Recipe に対して aggrega pin を実行して新しいダイジェストを記録します。そうでなければファイルを元に戻します。インラインのエントリは Recipe ファイルの一部であり、ライブラリのエントリはロックファイルが記録するライブラリのバージョンによってピン留めされるため、どちらも独自のピンを持ちません。このファイルについては aggrega pull で説明しています。
各アーティファクトエントリのテンプレートは、どのモードが本体を提供したかにかかわらず、valuesMapping: と同じテンプレートコンテキストで評価されます。同じファイル名を持つ 2 つの出力は、ノードのレンダリング時にビルドを停止させます。1 つの artifacts: マップの 2 つのエントリが 1 つの出力を指定することはできません。マップのキーは 1 つのドキュメント内で一意であり、単一のファイル名を表すため、単一ファイルのエントリの出力はそのキーであり、バンドルのエントリのファイルはそのキーの名前のディレクトリの下に置かれます。エントリが出力するすべてのパスの最初のセグメントはそれを生成したキーであるため、インポートされたファイルの名前にかかわらず、異なるキーは異なる出力名のままです。停止の対象となるのは、2 つの異なる入力種別が提供する 1 つのファイル名(チャートのテンプレートとアーティファクトエントリの両方が servicemonitor.yaml を生成する場合など)であり、その Recipe に対して、提供元をすべて挙げる診断とともに報告されます。
ユースケース。 artifacts: は、プライマリのチャートやモジュールが生成しない補助リソースの置き場所です。たとえば、ワークロードに付随する NetworkPolicy、Deployment と組になる HPA、instance_id に基づくサイドカーの ConfigMap などです。多数のコンポーネントにまたがって適用される横断的な補助リソース(たとえば、すべてのデータストアに付加されるバックアップ用サイドカー)は、Recipe ごとの artifacts: ではなく FeatureRecipe の Resource Generation に置きます。FeatureRecipe の拡張面については entities/featurerecipe.md を参照してください。
boundary: ブロック — boundary の共有出力のためのファイル
ほとんどの Recipes ではこれは必要ありません。Recipe が書き出すそれ以外のものはすべて、その Recipe 自身のコンポーネントに属します。provider はそれを boundary の出力内のそのコンポーネント自身の位置に配置します。一方、一部のファイルは boundary 全体に属します。これは、boundary がデプロイするすべてのものに対してターゲットが一度だけ読み込むファイルです。典型的な例は Terraform の provider 設定です。Terraform のドキュメントでは、別の設定から呼び出されるモジュールに provider ブロックを含めないこととしており、独自の provider ブロックを持つモジュールは depends_on、count、for_each を使って呼び出すことができません。spec.boundary.artifacts は、Recipe がそのようなファイルを書き出す場所です。
spec: capability: terraform implements: core/api-gateway/azure-api-management:1.0.0 artifacts: main.tf: $import: ./module/main.tf boundary: artifacts: # Terraform reads this beside the root configuration; one copy serves every # component of the boundary that declares it. provider-azurerm.tf: | provider "azurerm" { features {} }このブロックは、もう一つのスコープにおける artifacts: です。 artifacts が唯一のメンバーであり、Recipe 自身の artifacts: とまったく同じ形をとります。同じ 3 つのモード(インラインコンテンツ、ファイルの $import:、ファイルがエントリのキーの下に <key>/<filename> として配置されるライブラリの $import:)、同じキーからファイル名への規則とキーに使える同じ文字集合、そして同じテンプレートコンテキストを持つため、エントリは artifacts: エントリとまったく同様に .values、.infra、.locals などを読み取ります。少なくとも 1 つのエントリが必要で、boundary: の下にあるその他のメンバーは Recipe の読み込み時に拒否されます。FeatureRecipe にはこのようなブロックはありません。
ファイルが書き出される場所。 boundary の組み立て済み出力を保持するディレクトリに一度だけ、provider 自身の組み立て処理がそこに書き出すファイルと並べて書き出されます。terraform の場合は、コンポーネントのモジュール内ではなく、aggrega.modules.tf ルート設定の隣です。これらのファイルは provider には一切渡されません。コンパイラがそれらを評価して自ら書き出し、どのコンポーネントに由来するかを示す情報は何も書き込みません。そのファイルは、それを宣言したすべてのコンポーネントに属するためです。テンプレートが何もレンダリングしないエントリは、ファイルを書き出しません。
複数の寄与元が出会う場合。 すべてのエントリは、Recipe が boundary 内でレンダリングする各コンポーネントごとに評価され、boundary へのすべての寄与元が宣言したファイルは名前によってマージされます。同じ名前が同じバイト列に評価された場合(1 つの Recipe にバインドされた 2 つのコンポーネントによる場合や、1 つの provider を同一に設定する 2 つの Recipes による場合)、それは 1 つのファイルになります。同じ名前が異なるバイト列に評価された場合は、すべての寄与元が書いた内容を表す単一のファイルが存在しないため、ファイルとすべての寄与元を示してビルドが停止します。aggrega.modules.tf のように provider 自身の組み立て処理が書き出す名前の場合も同様です。どちらも組み立て済み出力の衝突です。1 つの provider を 2 つの異なるファイル名で設定する 2 つの Recipes はマージされず、それぞれのファイルが書き出されます。その場合、重複した設定を報告するのはターゲットです。そのため、provider 設定を共有することを意図した Recipes はそのファイル名を共有し、慣例として、設定する provider にちなんだ名前を付けます。
どの providers がこれを受け付けるか。 boundary の組み立て済み出力の隣に置かれたファイルが何らかの意味を持つかどうかは provider のターゲットの性質であるため、provider 自身の宣言の一部となります。provider がこのブロックを受け付けない Recipe がブロックを宣言した場合、エントリが何をレンダリングするかにかかわらず、何かがレンダリングされる前に拒否されます。The provider does not support boundary artifacts(provider は boundary artifacts をサポートしていません)を参照してください。機能一覧表には、各 provider の対応状況が記載されています。
| Provider | boundary.artifacts: |
|---|---|
terraform | 受け付けます。各ファイルは boundary のルート設定の隣に書き出され、Terraform はそのディレクトリ内の他のすべての設定ファイルとあわせてそれを読み込みます。 |
helm, compose, helm-chart, cloudformation | 何かがレンダリングされる前に拒否されます。 |
ここでのファイルの $import: は、artifacts: エントリがインポートするファイルと同様にピン留めされます。 entity lock は、そのダイジェストを同じ artifactDigests リストに、キー単体ではなく boundary/<key> の下に記録するため、1 つのキーの下に書かれた各ブロックのエントリは別々にピン留めされます。pin ステップがそれを記録し、pin を行わない pull はピンが欠けているか一致しなくなった場合に停止し、build はピン留め後に編集されたファイルを artifacts: のファイルとまったく同様に拒否します。
outputLabels: フィールド — レンダリング出力に作成者が宣言するラベル
Recipe.spec.outputLabels: は、ラベルのキー → 値のマップで、Recipe のレンダリング出力が生成するすべてのオブジェクトに provider が付与します。これは実現特性、つまり component が何であるかではなく、特定の Recipe がその component をどのように実現するかという性質を置くための本来の場所です。実現が永続化に使うストレージを例に取り、以下では例示用のキー example.io/storage-backing として記述します。PersistentVolumeClaim をマウントする Helm の Recipe と、名前付きボリュームをマウントする Compose の Recipe は、同じ component を異なる仕組みで実現するため、異なる outputLabels を持ちます。これにより、下流のツール(コスト配分、ポリシー、インベントリ)は出力されたリソース上でそれらを区別できます。このキーは例示です。example.io/ は例としての名前空間であり、どのキーを使うかはカタログが自身のツールが読むものに合わせて選びます。
spec: capability: helm implements: core/datastore/postgres:1.0.0 outputLabels: example.io/storage-backing: persistent-volume example.io/team: platform出力ラベルは、固定のビルド来歴ラベルと同じ経路をたどります。出力を生成するすべての箇所が付与するラベル集合にマージされるため、来歴が付く場所にはどこでも付きます。異なるのは所有者です。来歴のキーはコンパイラが所有し、outputLabels は Recipe の作成者が所有します。
component 自体の識別ラベルはここには記述しません。これはカタログの慣例であり、コンパイラが強制する規則ではありません。 ある Recipe がどう実現するかではなく、component が何であるかを表すキー、すなわち認知カテゴリ、運用タイプ、ロールごとの機能ラベル、基盤リソースの運用者、ラップする対象のライセンス区分などは、Component の metadata.labels で宣言します。軸については entities/component の「The Semantic Label Taxonomy」を参照してください。Recipe がそれらのいずれかをレンダリング出力に付けるには、ここでキーと値を記述するのではなく、後述の outputComponentLabels: でキーを指定します。理由は、リテラルのエントリが component がすでに持つ値の2 つ目のコピーになり、2 つ目のコピーは 1 つ目と食い違う可能性があるためです。Recipe の作成者は、Component が別の姿勢を宣言しているノードに異なる姿勢を記述でき、グラフが示していない内容を下流の読み手に伝えてしまいます。昇格されたエントリは参照によってコピーされるため、ずれる 2 つ目のコピーが存在しません。コアは、後述の予約名前空間の規則を除き、どちらを記述しても受け入れます。この慣例はカタログの作成者によって守られます。
予約名前空間。 aggrega.ai/ と app.kubernetes.io/ の名前空間は、プラットフォームネイティブの来歴のために予約されています。いずれかのプレフィックスの下に outputLabels のキーを宣言した Recipe は、読み込み時に、問題のキーを示す明確なカタログエラーで拒否されます。それ以外のキーはすべて受け入れられます。コアはそれ以外にキーや値を検査しません。ターゲットエンジンのラベルとして有効でないキーや値は作成者の責任であり、下流のランタイムが拒否します。コンパイラは予約名前空間の規則以外には関与しません。
provider ごとの反映。 各 provider は、ラベルを自身の出力に変換します。
- helm、ワークロード合成 — オブジェクトの
metadata.labelsと Pod テンプレートのmetadata.labelsの両方に付与します。合成が来歴を配置する場所と一致します。 - helm、ソースレンダリングと artifacts — オブジェクトの
metadata.labelsに付与します。 - compose — 各サービスの
labels:マップに付与します。 - terraform — 構造的にアドレス可能な
.tf.jsonの artifact 本体に、リソースごとのタグとしてベストエフォートで付与します。すでにtags(AWS/azurerm)またはlabels(Google)マップを宣言しているリソースブロックはそこに出力ラベルを受け取り、作成者が宣言したキーは上書きされず、そのような属性を持たないリソースは変更されません(属性が新たに作られることはありません)。ネイティブ HCL の本体(main.tf、*.tf)とベンダリングされたモジュールはそのまま出力され、タグは注入されません。Terraform の来歴は引き続き付随するコメントファイルで運ばれ、タグの経路とは別です。
出力ラベルはラベルのみであり、出力用のアノテーションを付ける別の仕組みはありません。outputLabels は Aggregate ではなく Recipe の作成者(運用担当が記述する実現レイヤー)が宣言します。これは実現を記述するものであり、開発者の抽象グラフ上の識別を記述するものではありません。
outputComponentLabels: フィールド — コンポーネント自身のラベルの昇格
Recipe.spec.outputComponentLabels: はラベルのキーのリストであり、キーと値のペアのリストではありません。プロバイダは、指定された各キーについて、レンダリング対象のコンポーネントインスタンス上でそのキーが持つ値を使って、そのキーをレンダリング出力に付与します。outputLabels が値を記述するのに対し、outputComponentLabels は値の読み取り元を指定します。
spec: capability: helm implements: core/datastore/postgres:1.0.0 outputLabels: example.io/team: platform outputComponentLabels: - component.aggrega.ai/hostingmetadata.labels で component.aggrega.ai/hosting: managed を宣言している Component がある場合、この Recipe がそのコンポーネントのためにレンダリングするすべてのオブジェクトは component.aggrega.ai/hosting: managed を持ちます。同じ Recipe を self-hosted を宣言するコンポーネントにバインドすると、そのコンポーネントのオブジェクトは代わりに self-hosted を持ちます。1 つの Recipe、1 つの指定キー、コンポーネントごとの値です。
昇格は参照によって行われ、それこそが要点です。 値は出力がレンダリングされるたびにコンポーネントから読み取られるため、元のアイデンティティから乖離することはありません。コンポーネントのラベルが変わったときに同期を保つべき 2 つ目のコピーは存在しません。コンポーネントのラベルを再記述するリテラルの outputLabels エントリは、まさにその 2 つ目のコピーであり、どちらかが変わった瞬間に両者は食い違います。したがって、値がこの Recipe によるコンポーネントの実現方法の性質である場合は outputLabels を、値がすでにコンポーネント上に存在し、レンダリング出力にもそれを持たせるべき場合は outputComponentLabels を使います。
昇格されたキーは、リテラルのキーとまったく同じ出力面に配置されます。前述のプロバイダごとの出力方法はそのまま適用され、昇格されたキーとその場で記述されたキーを区別するプロバイダはありません。
予約済み名前空間。 aggrega.ai/ と app.kubernetes.io/ の名前空間はプラットフォームネイティブの来歴情報のために予約されており、いずれかのプレフィックスの下にある昇格キーは、ロード時にそのキーと出現したフィールドを示すカタログエラーで拒否されます。判定はプレフィックスそのもので行われます。component.aggrega.ai/hosting のようなキーは予約済みのルートの下ではなく独自の名前空間に属するため、昇格できます。
キーはどちらか一方のブロックに属します。 同じキーを outputLabels と outputComponentLabels の両方で宣言するとロード時に拒否されるため、付与されるすべてのキーは単一の出所を持ちます。Recipe に記述されたリテラル値か、コンポーネント自身のラベルのいずれかであり、両方になることはありません。
コンポーネントが宣言していない昇格キーは何も付与しません。 ビルドは続行され、ノード、Recipe、欠落しているキーを示す警告が出力されます。これは意図的なものです。ラベルセットが異なるコンポーネントにバインドされた Recipe もレンダリングされ、不一致は停止ではなく表面化されます。
単一の態勢を持つコンポーネント — 規則ではなく慣例。 昇格はコンポーネントが宣言する値をそのまま運び、コンパイラはその値を解釈しません。そのため、アイデンティティラベルに「さまざま」を表すプレースホルダーを持つコンポーネントは、そのプレースホルダーを自身のためにレンダリングされるすべてのオブジェクトに昇格させます。コンポーネントが本当に複数の態勢を持つ場合、標準ライブラリのカタログの慣例では、各 Recipe が自身の実現の態勢を、Recipe が所有する outputLabels キーで記述します。コンポーネントのアイデンティティキーは使いません(同じ慣例により、こちらは代わりに outputComponentLabels: を通します)。あるいは何も付与しません。2 つのキーは異なる問いに答え、どちらも他方を置き換えません。アイデンティティキーはあらゆる実現にわたってコンポーネントが何であるかを示し、Recipe が所有するキーはこの 1 つの実現が何をするかを示します。これはカタログの作成者が支える慣例であり、コンパイラが強制する制約ではありません。
locals: ブロック
Recipe.spec.locals: は Private Ops State です。名前付きの Go テンプレート文字列のマップで、そのレンダリング結果は .locals.* マップとして Recipe の後続のテンプレートに公開されます。物理的な実体(ターゲットコンテナ、JSON パス、派生ホスト名)を一度だけ計算し、provides:、source:、valuesMapping:、workload:、artifacts:、assertions:、pipeline[].with のペイロード全体で再計算なしに再利用するための作業領域です。各エントリのレンダリング結果は、先頭と末尾の空白を取り除いて格納されます。
spec: capability: helm implements: core/postgres-db:1.0.0 source: ./charts/postgresql locals: primary_compute: postgresql listen_port: "5432" secret_target_db_password: "postgres-auth" volumes_path: "/spec/template/spec/volumes" valuesMapping: | primary: auth: existingSecret: "{{ .context.rendered_name }}-{{ .locals.secret_target_db_password }}"locals: が呼び出し元に公開されることはありません。uses: を介してこの Recipe を利用する下流のコンポーネントからは provides: しか見えません。Recipe 自身の provides:、source:、valuesMapping:、workload:、artifacts:、assertions:、pipeline[].with のテンプレートは、いずれも解決済みの .locals.* マップを参照できます。各キーの値はプレーンな文字列でも Go テンプレートでも構いません。コンパイラはブロック全体を locals プリアンブルで、そのノードの provides: より先に解決するため、後続のすべてのテンプレートは安定した解決済みの値を参照します。
各エントリは、自己完結したノードローカルなコンテキスト、すなわち .context.instance_id、.values、.infra、および同じブロック内ですでに解決済みのエントリに対して評価されます。local は .provides を読めません。この柱はこのサーフェスにはなく、これを参照しようとするエントリは停止します。また .context.rendered_name(helm などの provider がノードに対してレンダリングするリソースに付ける名前)も読めません。そのため、それらのリソースの名前を表す local は、上の secret_target_db_password のようにその名前以降の部分だけを持ち、完全な名前を書き出すテンプレートが両者を連結します。
記述順序には意味がある
エントリは記述された順に解決され、エントリはその上で定義された兄弟エントリを読むことができ、その兄弟の解決済みの値を受け取ります。
spec: locals: db_identifier: "{{ .context.instance_id }}-postgres" # defined first secret_target: "{{ .locals.db_identifier }}-auth" # reads the entry above連鎖は下方向にのみ働きます。あるエントリが別のエントリを読む場合、エントリの順序がビルドの成否を決めます。db_identifier を secret_target の下に移動するとビルドは停止します。コンパイラは参照を解決するためにブロックをソートしたり並べ替えたりすることはないため、記述順序が契約です。locals: ブロックの並べ替えは見た目だけの変更ではなく、動作の変更です。
作成者が犯しうる 2 つの誤りは修正方法が異なるため、2 種類の停止で区別されます。
- ブロックが後で定義するエントリへの参照は、順序の誤りを示して停止します。修正方法は、定義をそれを読む箇所より上に移動することです。
- ブロックがまったく宣言していないキーへの参照は、そのキーを示して停止します。修正方法は、綴りを直すことです。
チェックはブロックの別名もたどります。 with .locals の本体が再束縛するドット、または .locals に束縛された変数を通じて参照されるキーは、直接の書き方とまったく同じ条件でチェックされます。{{ with .locals }}{{ .nope }}{{ end }} と {{ $l := .locals }}{{ $l.nope }} は、{{ .locals.nope }} と同様に、どちらも .locals.nope を示して停止します。{{ (.locals).nope }} と {{ ($.locals).nope }} も同様です。括弧が返すのはブロックそのものであり、それ以上のものではないためです。チェックを逃れる書き方は 1 つだけです。テンプレートのテキストからは結果を特定できない呼び出しを通じて参照されるキー({{ index .locals "nope" }} や {{ (default dict .locals).nope }})です。このような呼び出しが返すものは、書かれた内容ではなくテンプレートの実行時に決まるためです。このような呼び出しの結果からフィールドとして読む存在しないキーは停止せず、何も出力しないのではなく、リテラルのテキスト <no value> をレンダリングします。index を通じて参照される存在しないキーは、そのキーを示して停止します。index は、読み取るマップに要求されたキーがない場合、すべてのテンプレートサーフェスで停止するためです。これはこのチェックとは別の報告で、errors/fatal-halts.md の「A template indexes a map with a key the map does not hold(テンプレートがマップに存在しないキーでマップをインデックス参照している)」に記載されています。したがって index は、{{ index .locals (printf "secret_target_%s" .values.slot) }} のように名前自体が計算されるキーを参照する方法として引き続き使えます。ブロックが宣言していない計算された名前は、引き続きそのキーで報告されます。
ノードの locals はその provides より先に解決されるため、provides: は .locals を読み、解決済みの値を受け取ります。locals ブロックが宣言していないキーを指定する provides: テンプレートは停止します。つまり、provides: のエントリとアーティファクトの両方が必要とする値は、locals: に一度だけ記述し、両方の箇所から読み取ります。
公開 API 側の対応については、後述の provides: ブロック を参照してください。FeatureRecipe のサーフェスも同じ規則に従います。entities/featurerecipe.md の「locals: ブロック」を参照してください。
provides: ブロック
Recipe.spec.provides: は Public Developer API(公開開発者 API)です。名前 → Go テンプレート文字列のマップであり、この Recipe が下流の呼び出し元の .context.inject パイプおよび .context.uses パイプに提供する値を宣言します。コンパイラは provides: テンプレートを provides 評価(自己完結、順序不問)の段階で評価し、呼び出し元の inject キーは inject ハイドレーションの段階でこれらの値に対して解決されます。
spec: capability: helm implements: core/postgres-db:1.0.0 source: ./charts/postgresql provides: # The Service this chart names after its release name, suffixed "-postgresql" host: "{{ .context.rendered_name }}-postgresql" port: "5432" database: "{{ .values.db_name }}"各エントリのテンプレートは、自己完結した provides 評価のサーフェスに対して評価されます。このサーフェスにあるのは、.context.instance_id、ノードの provider が報告する場合の .context.rendered_name、.values、.infra、ノードの解決済み .locals、および静的テキストです。ノードが配置される namespace はこのサーフェスにないため、公開されるホストには namespace が含まれません。別の namespace にいるコンシューマは、自身の側でそれを修飾します。.locals がサーフェスにあるのは、ノードの locals が同じステージのプリアンブルで、その provides より先に解決されるためです。locals ブロックが宣言していないキーを指定する provides テンプレートは停止します。provides 評価と inject ハイドレーションを分離することには意味があります。provides 評価の実行時には呼び出し元がまだ解決されていないため、Recipe の provides: はどの呼び出し元の状態も参照できません。アーキテクチャ上の不変条件により、provides: は自己完結しています。その後、呼び出し元は自身のテンプレートで .context.uses.<alias>.provides.<provided-name> を介してこれらの値を読み取ります。提供される名前は、エッジの他のフィールドと並んで、エッジ上の provides の下にネストされます。エッジ上で inject: 許可リストを宣言する呼び出し元は、代わりに自身の .context.inject パイプを通じて同じ値に到達します。
provides: のキーは Recipe のコントラクトサーフェスの一部です。キーの名前変更や削除は、古い名前に依存するすべての呼び出し元にとって破壊的変更となります。implements: のインターフェースバージョンは、コントラクトの変化を反映するべきです。カスケード解決のセマンティクス、inject パイプのコントラクト、およびクロス namespace とクロスリージョンのルーティングを扱う実例については、architecture/06-data-taxonomy-and-composition.md §3 と templates/expansion-matrix.md を参照してください。
アタッチメントが公開する値の読み取り
Recipe は、自身のコンポーネントにアタッチされた Features を .features.<instance-name> で、認証情報の Features を .features.<slot> で読み取ります。どちらも同じアタッチメントの形(.type、.values、.infra、.provides)を持つため、アタッチメントはどちらのマップに含まれていても同じ方法で読み取られます。両者の違いは、アタッチメントが何を生成するかにあります。
.provides はアタッチメントが公開する出力であり、そのアタッチメントにバインドされた FeatureRecipe から解決されます。これは上記の provides: ブロックを利用側から見た対応物です。Recipe が呼び出し元に対して公開するのと同様に、アタッチメントはホストとなるコンポーネントに対して公開します。
workload: | # The identity attachment emits a ServiceAccount and publishes its name; # the pod binds to that published name rather than restating it. serviceAccount: "{{ .features.identity.provides.name }}" containers: main: env: DB_SECRET: "{{ .features.app_credentials.provides.name }}"同じ values/infra 入力から値を再計算するのではなく公開された値を読み取ることは、名前を一度だけ記述するか、食い違う可能性のある二つの記述を持つかの違いになります。利用可能性の規則を含むフィールドごとの完全な形は、templates/template-context-contract.md を参照してください。
コンポーネントの接続の一つに記述されたアタッチメント(コンポーネントが一つのターゲットに提示する認証情報)は、その接続の下で同じ形のまま .context.uses.<alias>.features.<slot> で読み取られ、.features に含まれることはありません。複数のターゲットに到達する Recipe は、各ターゲットの認証情報をそのターゲットのエイリアスの下で読み取ります。また、.features をループしてタイプでアタッチメントを選び出す処理が出会うのは、コンポーネント自身のアタッチメントだけです。
artifacts: routes.yaml: | {{- range $alias, $edge := .context.uses }} - name: {{ $alias }} {{- with $edge.features }}{{ with .credential }} api_key_secret: {{ .provides.name }} {{- end }}{{ end }} {{- end }}形と、テンプレートが接続を走査する順序については、接続のアタッチメント を参照してください。
pipeline: フィールド
Recipe.spec.pipeline: は、レンダリング後にレンダリング済みドキュメントセットに対して実行される Wasm パイプラインステップの順次配列で、各ステップは RFC 6902 パッチと副作用を返します。各エントリは id(ステップごとの識別子。英字、数字、アンダースコア)、plugin(ステップが実行する Plugin エンティティ。プラグインタイプでスコープされ、pipeline-step/<name> と書き、バージョンを付けることもできます。裸の .wasm やアーティファクト参照は拒否されます)、function(呼び出すプラグインのエクスポート)、プラグインのペイロードを供給する省略可能な with: Go テンプレート本体、およびステップを実行するかどうかを制御する省略可能な when: Go テンプレートを宣言します。偽値と評価される結果はそのステップをパススルーとしてスキップし、ドキュメントセットは変更されません。when: ゲート、その optional: からの独立性、および真偽判定の規則については、entities/featurerecipe.md の「Conditional steps — when:」で詳しく説明しています。
spec: capability: helm implements: core/web-server:1.0.0 source: { kind: helm-oci-chart, url: "oci://…", version: "…" } pipeline: - id: inject_sidecar plugin: pipeline-step/envoy-sidecar:1.0.0 function: Inject with: | target_container: "{{ .locals.primary_compute }}" envoy_version: "{{ .values.envoy_version | default "1.30.0" }}"コンパイラは、ベース Recipe の pipeline: ステップを、FeatureRecipe の pipeline: を実行するのと同じ方法で、宣言された順序で実行します。各ステップで指定された Wasm プラグインをレンダリング済みの出力に対してディスパッチし、返された JSON Patch 操作を対象のドキュメントに適用し、そのステップの副作用を出力します。FeatureRecipe の pipeline: フィールドは同じスキーマの形と同じ実行方式を共有します。各サーフェスの実行状況については、entities/featurerecipe.md の「Authoring Contract」および Status of the Language を参照してください。
このフィールドの仕組みは FeatureRecipe のセマンティクスと同じです。宣言された順序での逐次評価、レンダリング済みドキュメントへの JSON Patch 操作の適用、それと並行した副作用の出力、そして問題のあるステップを指す来歴付きのエラー報告です。when: ゲートが偽値としてレンダリングされたステップはパススルーとしてスキップされ、ドキュメントセットは変更されないまま次のステップに渡されます。
assertions: ブロック
Recipe.spec.assertions: は、Recipe の実装上の不変条件を表す名前付きルールのオプションのマップです。これは、Recipe がソースとする特定のチャートやモジュールを前提として成り立つ、フィールド横断のルールです。各キーは失敗メッセージに表示されるルール識別子で、各値は Go テンプレート本体です。Component のアサーション(どの Recipe がバインドされるかに関係なく、契約レベルの不変条件を表すもの)とは異なり、Recipe のアサーションは選択された特定の実装の性質です。
spec: implements: core/datastore/mariadb:^1.0.0 source: kind: helm-oci-chart url: oci://registry-1.docker.io/bitnamicharts/mariadb version: "20.0.0" 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 -}}上記のルールは Bitnami チャート 20.x に固有のものであり、別の MariaDB Recipe がバインドされる場合には適用されません。契約の Component レベルのルールも並行して引き続き適用され、より前のパイプラインフェーズで評価されます。
Recipe のアサーションは、Recipe のバインド後かつレンダリング前、すべてのノードの locals と provides が解決された時点で評価されます。テンプレートコンテキストには、エンティティインスタンスのフィールド(.values、.infra、.uses、.features)に加えて、Recipe の .provides、.locals、.recipe.source が含まれます。ここでの .uses と .features は、Recipe テンプレートのものではなく、アサーション用のより狭い形です。接続のエントリには、そのターゲットとエイリアス、ターゲットの labels、接続自身の values、および features の下でその接続に記述されたアタッチメントが含まれますが、ターゲットが公開するものは含まれません。また、アタッチメントのエントリ(コンポーネント自身のものでも接続のものでも)には、その type、resolved_version、values が含まれますが、infra も provides も含まれません。アサーションの実行時点では、アタッチメントの FeatureRecipe はまだその provides を解決していないためです。したがって、.features.<name>.provides への参照は停止を引き起こし、存在を考慮した読み取りはそのフォールバックを返します。完全な記述文法、契約レベルと実装レベルのルールの責任分担、および実例については、templates/assertions-block.md を参照してください。
omits: フィールド — レンダリングされたドキュメントをソースから除外する
ほとんどの Recipes では、これは必要ありません。これは、そのまま使うソース(多くの場合、レジストリから取得したチャート)が、Release に含めてはならないドキュメントをレンダリングする場合のためのものです。たとえば、チャートがレンダリングのたびに新たに生成する Secret は、2 回のビルドの結果を異ならせ、適用されるとオペレーターが用意した Secret を上書きしてしまいます。取得したチャートは編集せず、ignore ルールもその中には及ばないため、omits: は Recipe がそのようなドキュメントをビルドから除外する手段です。取得した compose ファイルも同じケースです。Release が持ってはならない service、volume、config が同梱されていることがあり、valuesMapping: のオーバーレイはそれを変更できても削除はできません。取得した CloudFormation テンプレートも同様で、Release が作成してはならないリソースを宣言していることがあります。valuesMapping: はテンプレートが宣言するパラメータを埋めることはできても、そのリソースを削除することはできません。
spec: capability: helm implements: core/gateway/kong:1.0.0 source: kind: helm-oci-chart url: oci://registry.example.com/charts/gateway version: "2.4.0" omits: # The chart generates this key on every render; the operator supplies it. - kind: Secret name: "{{ .context.rendered_name }}-session-key" # Left out only where the Release asks for it. - when: "{{ .infra.without_dashboards }}" kind: ConfigMap name: "{{ .context.rendered_name }}-dashboards" namespace: monitoring対象範囲。 source: がレンダリングするものだけです。workload: と artifacts: のエントリはフィルタリングされません。これらは Recipe 内に記述するものなので、不要なドキュメントは記述しなければよいのです。このキーには source: が必要です。このルールに反するドキュメントは読み込み時に拒否され、そのルールが示されます。
エントリ。 各エントリは 3 つのフィールドで除外対象を指定し、4 つ目のフィールドで適用するかどうかを決めます。最初の 3 つが指定するものは、provider がそのソースのレンダリング結果について持つ独自の語彙であり、provider ごとに下の表に示します。
kind— ソースがレンダリングするものの種類です。チャートの場合はレンダリングされたドキュメントの kind(Secret、ConfigMap、Deployment)、compose ファイルの場合はservice、volume、configのいずれか、CloudFormation テンプレートの場合はリソースのType(AWS::S3::Bucket)です。構造化されたsource:が持つkind:とは無関係で、そちらはソースの取得方法を示します。name— その名前です。ドキュメントの場合はmetadata.name、compose のユニットの場合はservices:、volumes:、configs:の下のキー、CloudFormation リソースの場合は論理 ID、つまりResourcesの下のキーです。namespace(省略可) — 出力に名前空間を持つ provider の場合に、ドキュメントが属する名前空間です。指定しない場合、エントリは任意の名前空間にあるその kind と名前を指定します。空にレンダリングされるnamespaceは指定なしとして扱われます。when(省略可) — エントリをこのビルドに適用するかどうかです。最初に評価され、パイプラインステップのwhen:と同じルールで解釈されます。結果が false の場合はエントリが除かれ、他のフィールドは評価されず、provider に渡されることもチェックされることもありません。when:がない、または空の場合はエントリが維持されます。
kind と name は必須であり、それ以外のフィールドを持つエントリは Recipe の読み込み時に拒否されます。
すべての値はテンプレートであり、valuesMapping: と同じコンテキストに対して評価されます。このコンテキストには .context.rendered_name が含まれます。これは provider がノードのリソースに付ける名前で、チャートが通常リソースの命名に用いるものでもあるため、エントリはチャートが付けるとおりの名前でドキュメントを指定できます。レンダリングに失敗したテンプレートは、valuesMapping: のテンプレートが失敗した場合と同様にビルドを停止します。
適用されるエントリはすべて、何かを除外しなければなりません。 provider は各エントリが除外したユニットの数を報告し、何も除外しなかったエントリはそのエントリを示してビルドを停止します。An omits entry left out nothing the source rendered(omits エントリがソースのレンダリング結果から何も除外しませんでした) を参照してください。通常の原因は、ドキュメントの名前を変更または削除するソースのアップグレードであり、この停止によって、名前が変わったドキュメントが気付かれないまま出力に入ることを防ぎます。ドキュメントを特定の場合にのみ除外するには、ドキュメントが存在しないことに頼るのではなく、when: でそれを指定してください。
ソースは引き続き完全にレンダリングされます。 フィルタリングされるのは出力だけです。チャートのすべてのテンプレートは引き続き実行されるため、失敗するテンプレートはやはりビルドを失敗させ、除外されるドキュメントはレンダリングされてから破棄されます。破棄されたドキュメントは、その後のビルド処理には一切届きません。出力ファイルにも含まれず、他のコンポーネントの名前と比較されることもなく、Feature がレンダリングについて読み取る情報にもならず、パイプラインステップに渡されることもありません。
Release は infra と parameters を通じてこのキーに関与します。 このキーは Recipe に属するため、Release が記述することはできません。それでも、エントリの動作を決めることはできます。エントリのテンプレートは Release が設定する infra を読み取り、Release が渡す parameters は、Aggregate がそこへルーティングする箇所で Recipe の .values に届きます。したがって Release は、上の 2 つ目のエントリのように when: でエントリを有効・無効にしたり、エントリが指定する名前を決めたりできます。
何を除外するかの責任は利用者にあります。 ビルド内の何も、ドキュメントが何のためにあるかを知りません。チャートの他の部分が実行時に依存するもの(Deployment がマウントする Secret、Pod が実行に使う ServiceAccount など)を除外すると、横に適用される別のものがそのドキュメントを提供しない限り、ビルドは問題なく通っても適用時に失敗する出力が生成されます。compose ファイルと CloudFormation テンプレートについては、それぞれが自身の参照を記述しているため、ビルドがチェックを行います。残ったものが除外されたユニットを依然として参照している場合(除外されたサービスを参照するサービス、除外されたリソースを参照するリソースや出力)、下の表で説明するとおりビルドが停止します。
このキーに対応する provider。 ドキュメントの除外は provider にしかできません。ソースが何をレンダリングするかを知っているのは provider だけだからです。そのため、provider がこのキーに対応するかどうかは provider 自身の宣言の一部です。omits: を宣言する Recipe の provider がこれに対応していない場合、エントリの when: が何にレンダリングされるかにかかわらず、何もレンダリングされる前に拒否されます。The provider does not support omits(provider が omits をサポートしていません) を参照してください。
| Provider | omits: |
|---|---|
helm | 対応。エントリは、チャートがレンダリングするドキュメント(テンプレート由来または crds/ ディレクトリ由来)を、そのドキュメント自身の kind、metadata.name、およびエントリが指定する場合はドキュメントが属する名前空間で指定します。helm → Sourced mode を参照してください。 |
compose | 対応。エントリは、ソースとなる compose ファイルの service、volume、config を services:、volumes:、configs: の下のキーで指定し、valuesMapping: がファイルにマージされた後に照合されます。名前空間は指定しません。他の種類や名前空間を指定するエントリは、コンポーネントのレンダリング時にビルドを停止します。残ったものが除外されたユニットを依然として参照しているファイル(depends_on、links、volumes_from、service: のネットワークモードまたは名前空間モード、extends、ビルドコンテキスト、volumes: または configs: のエントリによる参照)は、各参照を示してビルドを停止します。compose → Sourced mode を参照してください。 |
cloudformation | 対応。エントリは、ソースとなるテンプレートのリソースを Type と論理 ID で指定し、ディレクトリソースの場合はそのすべてのテンプレートが対象になります。名前空間は指定しません。名前空間を持つエントリは、コンポーネントのレンダリング時にビルドを停止します。残ったものが除外されたリソースを依然として参照しているテンプレート(Ref、Fn::GetAtt、DependsOn、Fn::Sub の変数による参照)は、各参照を示してビルドを停止します。cloudformation → Leaving resources out of a sourced template を参照してください。 |
helm-chart, terraform | 拒否。この provider はソースをデプロイ時にレンダリングされるよう引き渡すため、ビルド時には除外すべきドキュメントが存在しません。ローカルのチャートやモジュールの場合は、代わりに Recipe の横にある .aggregaignore に 1 行記述することで、そのファイルを除外できます。 |
同じキーは FeatureRecipe でも記述できます。entities/featurerecipe.md を参照してください。
実例(取得したチャートが生成する Secret の除外、エントリがない場合に同じチャートで発生する決定性による停止、何にも一致しないエントリによる停止。いずれも実際のビルドによるもの)については、ai-gateway-own-webhook-certificate を参照してください。