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

Recipe の入力構成 — 3 つの入力種別、Workload、Artifacts

Recipe は、対象のプロバイダー向けにマニフェストファイルを生成します。この章では、Recipes が sourced、synthesized、artifacts という互いに直交する 3 つの入力種別から出力をどのように構成するか、各入力種別がどのように構造化されているか、そしてどのプロバイダーがどの出力を生成するかを説明します。Recipe エンティティの概念上の役割(Developer Intent を単一の物理プロバイダーにマッピングする、Ops が作成する変換テンプレート)については 04-entity-taxonomy.md を、キーワードレベルでの Recipe の記述方法については ../language-reference/entities/recipe.md を参照してください。

根拠

各プロバイダーのネイティブなレンダリングツール(Helm、Docker Compose)は、プロバイダーネイティブなマニフェストのレンダリング方法をすでに備えています。Recipe の役割は、それらのマニフェストが何を記述すべきかを宣言することです。つまり、どのコンテナイメージ、どのポート、どの環境変数、どのボリューム、どのサービス、どのリソース制限を使うかです。

Recipe は、Deployment と Service にマッピングされる固定のキーセット(例:image、environment、ports、replicas)が表せる以上のものを表現する必要があります。その中には次のものがあります。

  • resources(CPU/メモリの requests/limits)
  • Liveness、readiness、startup の各プローブ
  • volumeMounts / volumes
  • nodeSelector / affinity / tolerations
  • serviceAccount / securityContext
  • マルチコンテナ Pod、サイドカー
  • ConfigMap / Secret / PVC / CRD リソース
  • ClusterIP 以外の Service(LoadBalancer、NodePort、Headless)

抽象化レイヤーは、固定のキーセットではなく、ワークロードの形状全体を記述する必要があります。以下で説明する 3 つの入力種別がその抽象化です。Recipe は、外部から読み込まれるチャートまたはモジュール(source:)、プロバイダーがプロバイダーネイティブなマニフェストへ合成する抽象的な Workload 仕様(workload:)、そして Recipe が直接出力するテンプレート化されたプロバイダーネイティブなマニフェスト(artifacts:)から、出力を加算的に構成します。

3 つの入力種別

加算による合成

Recipe からプロバイダーネイティブのマニフェストファイルを生成する方法は 3 つあり、それらは相互排他ではなく加算によって合成されます。

  1. source: — プロバイダーがネイティブにレンダリングする外部ロードのアーティファクト(Helm チャート、compose ファイル)で、valuesMapping: がオーバーレイ値を供給します。
  2. workload: — プロバイダーがプロバイダーネイティブのマニフェストへ合成する抽象的な Workload 仕様(プラットフォーム所有の kind)です。このフィールドはインラインの YAML ブロックスカラー、または単一のローカルファイルやライブラリエントリへの $import: を受け付けます。ディスパッチは内容の形状によって決まります。
  3. artifacts: — インラインまたは $import: でロードされたプロバイダーネイティブのマニフェストのマップで、ピラーコンテキスト全体に対して Go テンプレートで処理されます。各エントリはインライン(エントリの値がブロックスカラー)で記述するか、単一のファイルまたはライブラリコンテンツへの $import: で記述できます。

3 つはいずれも、コンパイラが境界の出力ディレクトリに出力するファイルを生成します。下記の検証ルールに従う限り、3 つすべてを 1 つの Recipe 内に共存させることができます。マージのセマンティクスはトップレベルのみです。各入力種別は完全なファイルを生成し、ファイルは並べて出力され、出力ファイル名の衝突は致命的エラーになります。

記述的なモード名

3 つの「モード」は、ドキュメントと診断のための記述的な用語です。Recipe の作成者はモードを宣言せず、必要なキーワードを記述します。Recipe はその主要な入力によって特徴付けられます。

主要なキーワード記述的なモード名
source: + valuesMapping:(workload: なし、artifacts なし)sourced
workload:(source: なし、artifacts なし)synthesized
artifacts:(source: なし、workload: なし)artifacts-only(非公式には「inline」)
2 つ以上の任意の組み合わせ明示的に記述(例:「sourced with artifacts」、「synthesized with artifacts」)

mode: という名前のキーワードも列挙型もありません。モードは、どの入力が存在するかによって生じる性質です。

Recipe の形状の概要

apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: ...
version: 1.0.0
spec:
capability: helm | compose | helm-chart | ...
implements: core/...:1.0.0
locals: { ... }
provides: { ... }
# ─── Sourced input (optional, paired) ───
source: ...
valuesMapping: |
# Go template → YAML/JSON overlay values
# OR:
valuesMapping:
$import: ./mappings/api-server.tmpl # local file path
# OR:
valuesMapping:
$import: <Lib>#/mappings/<entry> # MappingLibrary entry
# ─── Synthesized input (optional) ───
workload: |
# Go template → YAML → parsed Workload
# OR (single-source $import for whole-content load from a file or library):
workload:
$import: ./workload.yaml
# ─── Artifacts input (optional, multiple entries permitted) ───
artifacts:
"filename.yaml": |
# Inline Go template → manifest YAML
"other.yaml":
$import: ./artifacts/other.yaml # per-entry $import: for file or library content

上記のすべてのフィールドは Recipe スキーマで受け付けられ、コンパイラは 3 つの入力種別すべて、つまり sourced レンダリング、Workload 合成、artifacts の出力を処理します。異なるのはプロバイダーごとのサポート、つまりどのプロバイダーがどの入力種別をレンダリングするかであり、これは本章末尾の Provider Capability Matrix にまとめています。

ロード時の検証ルール

Recipe スキーマとロード時の検証は、次の合成ルールを適用します。

  1. valuesMapping: には source: が必要です。 オーバーレイ先の source: がなければ、マッピングされた値を受け取るものがありません。valuesMapping: があり source: がない Recipe はロード時エラーになります。(valuesMapping: のない source: は許可されます。チャートやモジュールは独自のデフォルトでレンダリングされます。)
  2. workload: は 1 つのソースを受け付けます。インラインか $import: のどちらかで、両方は不可です。 Recipe は Workload をインラインのブロックスカラー、または単一ファイルへの $import: のいずれかで指定します。$import: 形式は統一されたファイルインポートの用語に従い単一ソースです。workload: では複数ソースのマージはサポートされません。不正な形式のディスパッチはロード時エラーになります。
  3. workload: には合成可能なプロバイダーが必要です。 合成のサポートはプロバイダー自体の性質であり、宣言されたフィールドの性質ではありません。合成できないプロバイダーにバインドされた workload: Recipe は、ノードのレンダリング時に、プロバイダー機能ゲート(Provider Capability Matrix を参照)によって明確な診断とともに拒否されます。標準ライブラリのカタログは、文書化された変換契約として、慣例により合成可能なプロバイダーに workloadSchema を宣言しますが、ゲートはそのフィールドの有無ではなく、プロバイダー自身が報告する機能に基づいて判定します。
  4. 少なくとも 1 つの入力種別が必要です。 source:+valuesMapping:、workload:、artifacts: のいずれも持たない Recipe は出力を生成せず、ロード時エラーになります。
  5. インラインと $import: の artifact エントリは共存できます。 Recipe は一部の artifacts: エントリをインラインで、他をエントリごとの $import: ディレクティブで宣言できます。各エントリのキーがそれ自身の出力に名前を付けるため、2 つの形式のエントリが互いに衝突することはありません(各出力ファイルの名前を決めるものを参照)。
  6. 入力種別をまたぐファイル名の衝突はレンダリング時エラーです。 Recipe の 2 つの入力種別(source によるレンダリング出力、workload による合成出力、artifact による出力)が同じ名前のファイルを生成した場合、コンパイラはすべての寄与元を特定する致命的エラーを出力します。このチェックは Workload の変換後に実行されるため、ロード時ではなくレンダリング時になります。

Workload 種別

所有権と配置

Workload は apiVersion: aggrega.ai/v1beta1 に属するプラットフォーム所有の種別です。その JSON Schema 2020-12 宣言はビルド時にコンパイラバイナリに埋め込まれます。カタログ作成者は Workload スキーマを編集せず、単独の Workload YAML ファイルをカタログエンティティとして作成することもありません。Workload の文法は Recipe または FeatureRecipe の workload: フィールド内(インライン、または単一ファイルや WorkloadLibrary エントリへの $import:)でのみ使用され、それ以外の場所では使用されません。

Workload はプラットフォーム種別でありコンパイラの概念であって、エンティティ分類における独立したエンティティではありません。Recipe が作成対象のエンティティであり、Workload は Recipe の合成入力がとる形です。

Recipe ごとに 1 つの Workload

Recipe は最大 1 つの workload: を宣言します。Workload は、この Recipe が実装する Component に関連付けられた単一の計算単位を表します。FeatureRecipe も同様に、自身の workload: を最大 1 つ宣言します。これは同じ Workload 種別を通じて合成される、Feature が所有する計算単位です。FeatureRecipe を参照してください。追加のサイドワークロードを必要とするユースケースは、次の方法で表現します:

  • artifacts: — 同じ Recipe 内で、ワークロードと並べて置く追加のマニフェスト(インライン、またはエントリごとの $import:)。
  • リソース生成を伴う Features — 横断的なサイドワークロード(例: データベースにアタッチされるバックアップ用サイドカー)を独立したカタログエンティティとして宣言し、FeatureRecipe が自身の workload: を合成します(または source: / artifacts: でレンダリングします)。FeatureRecipe のリソース生成については 14-extensibility.md を参照してください。

これにより、作成者ごとに 1 つの計算単位というモデルが保たれます。Recipe は Component のワークロードを合成し、FeatureRecipe は自身のワークロードを合成します。

全体のサーフェス

Workload のフィールドセットは大きく、今後も増えていきます。ここで再掲すると、その写しは何の通知もないまま契約から遅れてしまうため、本章ではその全体を記載している次の 2 つのサーフェスを示します:

  • 生成された Workload スキーマリファレンス — すべてのフィールド、その型、デフォルト値、制約を記載します。公開された JSON Schema から生成され、ビルドのたびに照合されるため、コンパイラが受け付けない形を記述することはありません。
  • Workload 作成ページ — フィールド単位の作成ガイド: 各フィールドの意味、各プロバイダーがそれを何にレンダリングするか、そしてビルドがどの組み合わせを拒否するかを記載します。

Workload の JSON Schema 2020-12 宣言が正であり、コンパイラバイナリに埋め込まれて提供されます。helm と compose のプロバイダーは、インラインまたは $import: で読み込まれた Recipe の workload: を合成します。プロバイダーごとの対応については Provider Capability Matrix を参照してください。

featuresSchema とのシークレット統合

Workload の containers.<name>.attachments ブロックは、Component の featuresSchema で宣言されたスロットを参照します。新しいスロットを宣言することはありません。featuresSchema の作成サーフェスについては ../language-reference/entities/component.md を参照してください。

検証の契約:

  • すべての attachments.<KEY>.from の値は、Component の featuresSchema で宣言されたスロット名と一致する必要があります。connection: <alias> で接続を指定するエントリの場合は、その接続のソケットが usesSchema.<socket>.featuresSchema で宣言するスロットと一致する必要があります。このようなエントリは、以下のいずれの規則が実行されるよりも前に、その接続のアタッチメントがコンポーネント上でとる名前(<alias>.<slot>)に書き換えられます。そのため、以下のすべての規則は、Component 自身のスロットを指定するエントリと同じようにこれを読み取ります。
  • as: の配信方式(env または file)は、そのスロットの inject: 配列で許可されている必要があります。
  • Component の featuresSchema で inject: [](ブラックボックス)とされたスロットは、Workload の attachments: ブロックに記述できません。これらのスロットは、Workload での公開ではなく、Recipe 内部の仕組み(例: Helm の existingSecret)によって配信されます。

例:

# In the Component
spec:
featuresSchema:
db_password:
required: true
inject: [env, file] # transparent: Workload may dictate delivery
root_password:
required: true
inject: [] # blackbox: Recipe handles internally
# In the Recipe
workload: |
containers:
main:
attachments:
DB_PASSWORD: # OK — db_password slot allows env inject
from: db_password
as: env
# ROOT_PASSWORD: ... # rejected — root_password is blackbox

ヘルスプローブ: 仕組みではなく意図

Kubernetes のプローブと Docker Compose のヘルスチェックは形が異なります。単一の抽象的な意図の形が、その両方にきれいに変換されます:

health:
ready:
http: /healthz # intent: HTTP GET probe
timeoutSeconds: 5
live:
tcp: 8080 # intent: TCP socket check
timeoutSeconds: 5
startup:
exec: ["check-ready.sh"] # intent: command exec
timeoutSeconds: 30
periodSeconds: 10

Providers は各意図をそれぞれのネイティブな形に変換します:

意図Helm (K8s)Compose
http: /pathhttpGet.path: /path, httpGet.port: <alphabetically-first port name>CMD-SHELL "curl -f http://localhost:<port>/path"
tcp: <port>tcpSocket.port: <port>CMD-SHELL "nc -z localhost <port>"
exec: [cmd]exec.command: [cmd]CMD [cmd]

明示的なポートのない http: のポート解決では、両方のターゲットで、コンテナが containers.<name>.ports の下で宣言するポート名のうちアルファベット順で最初のものを使用します。名前付きポートを宣言していないコンテナは HTTP プローブを持てず、ビルドはそのプローブを示して停止します。

Compose は HTTP/TCP プローブを healthcheck のシェルコマンドに縮退させ、compose のサービスは healthcheck を 1 つしか持てません。複数のプローブが宣言されている場合は 1 つだけが変換され、警告が破棄されたプローブを示します。

ボリュームの種類

ボリュームの種類は 5 つで、複合型はありません:

種類セマンティクスK8s (helm)Compose
ephemeralTmpfs / emptyDir。Pod とともに消滅emptyDir: { sizeLimit }tmpfs: マウント、サイズは持たない(記述された sizeLimit は警告で報告されます)
configmap読み取り専用の設定ファイルConfigMap ボリューム参照Recipe の artifacts: が宣言するトップレベルの config へのサービスレベルの configs: 参照
secret読み取り専用のシークレットファイルSecret ボリューム参照読み取り専用でバインドマウントされたシークレットファイル
persistent単一の PVC。Pod の再起動後も存続PVC リソース + volume.persistentVolumeClaim名前付きボリューム
persistentTemplateレプリカごとの PVC。form: stateful と組み合わせて使用StatefulSet.volumeClaimTemplates名前付きボリューム(縮退。警告を出力)

Compose はレプリカごとのテンプレートを表現できません。persistentTemplate を compose に変換すると、すべてのレプリカで共有される単一の名前付きボリュームに縮退し、警告がその縮退を報告します。persistentTemplate ボリュームには form: stateful が必要で、それ以外の form で宣言するとビルドが停止します。

複数サービスの公開

各サービスは独立した公開です。よくあるパターン: ポート 8080 の HTTP サービス(ClusterIP、内部)+ ポート 9090 のメトリクスサービス(ClusterIP)+ ポート 9901 の管理エンドポイント(LoadBalancer):

services:
http:
type: ClusterIP
ports:
web: 8080
metrics:
type: ClusterIP
ports:
prom: 9090
admin:
type: LoadBalancer
ports:
admin: 9901

helm プロバイダーでレンダリングすると、それぞれが個別の Kubernetes Service オブジェクトになります。helm プロバイダーは Loopback エントリに対しては停止します。compose では、NodePort と LoadBalancer のサービスは compose サービスのすべてのホストインターフェースでポートを公開し、Loopback のサービスはホストのループバックアドレスでのみ公開し、ClusterIP と Headless のサービスは何も公開しません。

K8s の出力では、一意性のためにサービス名の先頭にコンポーネントの instance_id が付きます。ポート名は containers.<name>.ports で宣言されたコンテナのポート名と一致する必要があります。

Provider 側の変換契約: workloadSchema

プロバイダーレンダリングを行う Plugin(pluginType: provider)は spec.provider.workloadSchema を宣言します。これは、Workload のフィールドがそのプロバイダーのネイティブ出力にどう変換されるかを記述する JSON Schema 2020-12 宣言です。これが自己記述的な変換契約です。spec.provider ブロックを含む Plugin の作成サーフェスについては ../language-reference/entities/plugin.md を参照してください。

apiVersion: aggrega.ai/v1beta1
kind: Plugin
metadata:
name: helm-renderer
version: 1.0.0
pluginType: provider
spec:
abiVersion: v1beta1
provider:
workloadSchema: | # how Workload translates to K8s manifests
// Each Workload produces: 1 controller object chosen by workload.form
// (stateless -> Deployment, stateful -> StatefulSet, daemon -> DaemonSet, task -> Job)
// + 1..N Services (one per workload.services entry)
// + 1..N PVCs (one per workload.volumes.*.persistent entry)
// + 1..N ConfigMap volume refs (from workload.volumes.*.configmap.source)
// ...

workloadSchema フィールドは、カタログ作成者と IDE ツールに変換の意図を伝えます。これは文書化された変換契約であり、合成を行うプロバイダーで慣例として宣言されます。ただし、合成への対応はこのフィールドの有無ではなく、プロバイダー自身によって決まります。合成できないプロバイダーを workload: でターゲットとする Recipe は、プロバイダーが workloadSchema を宣言しているかどうかにかかわらず、ノードのレンダリング時にプロバイダー能力ゲートによって明確なエラーとともに拒否されます。

Plugin スキーマは spec.provider.workloadSchema を宣言しており(その本体は Plugin の読み込み時に JSON Schema 2020-12 にコンパイルされます)、Recipe 側の workload: の使用も提供されています。合成への対応は、バインドされたプロバイダーが報告する能力に基づき、レンダリング時にプロバイダー能力ゲートによって強制されます。workloadSchema は標準ライブラリカタログがその能力と同期させている文書化された契約であり、それ自体はゲートの入力ではありません。さらに、カタログ全体に対して実行される aggrega validate は、合成を行わないプロバイダーにバインドされた workload: Recipe を、カタログがそのプロバイダーの Plugin エンティティを持っている場合に、ビルド前の早い段階で検出します。

補助リソースは Workload の外側に置く

Workload の spec には additionalResources フィールドも extras もなく、ConfigMap/Secret/CRD のインライン宣言もありません。Workload がモデル化するのはワークロードの形状だけです。コンテナ、ボリューム、サービス、レプリカ、スケジューリング、セキュリティコンテキスト、サービスアカウントなど、単一の計算単位がどのように実行されるかを記述するものすべてです。

補助リソースには、Workload の外側に正当な置き場所が 2 つあります。

  1. Features + FeatureRecipes — 横断的な関心事のための仕組みです。「メトリクスを公開しているあらゆるサーバー」にアタッチされる ServiceMonitor は、Feature としての core/prometheus-exporter です。サーバーをホスト名で公開するルーティングリソースも Feature であり、どれになるかはルーティングの形式で決まります。ターゲットが Ingress を調整する場合は core/public-ingress、Gateway API を実行する場合は core/http-route で、いずれも Manifest が Release ごとに選択する FeatureRecipe によって実現されます。すべての本番ワークロードに適用される NetworkPolicy は、本番の Release が境界全体にアタッチする Feature です。Features は直交的に合成でき、Recipes をまたいで再利用できます。FeatureRecipe のリソース生成については 14-extensibility.md を参照してください。
  2. Recipe レベルの artifacts: — この特定の Recipe の実装に属し、Feature を作成するほどではないリソースのためのものです。Recipe が必要とする一回限りの CRD 登録。この Recipe が使われる場合にのみ適用される、Recipe 固有の PodDisruptionBudget。Recipe の Workload が参照する ConfigMap。各エントリはインラインか $import: による読み込みです。後述の Artifacts Mechanism のセクションを参照してください。

Feature と artifact の境界は社会的な慣例です。補助リソースが横断的である(多くの Recipes に適用される、またはセレクターを介して条件付きでアタッチされる)なら、それは Feature です。この 1 つの Recipe に固有である(そのリソースを出力しなければ Recipe が役割を果たせない)なら、それは artifact です。作成者は再利用性とアタッチのセマンティクスに基づいて選択し、コンパイラはその選択を取り締まりません。

Features と Recipe の artifacts を合わせることで、Recipe が必要とする補助リソースをカバーします。

Artifacts の仕組み

インラインの artifact とファイルから読み込む artifact

artifacts 入力種別は、テンプレート化されたプロバイダーネイティブのマニフェストファイルを、source からレンダリングされた出力や workload から合成された出力と並べて、境界の出力に直接出力します。作成者は次の 2 つの形式で宣言します。

spec:
artifacts:
"servicemonitor.yaml": |
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
name: {{ .context.instance_id }}-monitor
spec:
endpoints:
- port: {{ .workload.services.metrics.ports.prom }}
"networkpolicy.yaml":
$import: ./artifacts/networkpolicy.yaml
"crd-registration.yaml":
$import: ./artifacts/crd-registration.yaml

$import: のパスは Recipe ディレクトリからの相対パスで、そのディレクトリ内に収まっている必要があります。Recipe の公開物に含まれるファイルはすべてそのディレクトリから取得されるため(インポートが指定する各ファイルも一緒に運ばれます)、ディレクトリ外のファイルは含まれないからです。一般的な慣例ではこれらを ./artifacts/ サブディレクトリに置きますが、コンパイラはこれを強制しません。マップのキーは出力される各ファイルの名前を決めます。3 つの形式それぞれでそれが何を意味するかは次のセクションで説明します。

各エントリ(インラインまたは $import: で読み込んだもの)は、出力ディレクトリに出力される前に、テンプレートコンテキスト全体に対して Go テンプレートとして評価されます。

各出力ファイルの名前を決めるもの

マップはエントリ名をキーとし、どの作成形式でもキーがそのエントリの出力の名前を決めます。インラインエントリでは、キーが出力ファイル名となり、書かれたとおりに使われます。

artifacts:
"configmap-config.yaml": |
...
"pdb.yaml": |
...

configmap-config.yaml と pdb.yaml を生成します。キーはファイル名を決めますが、ファイルの配置先はターゲットが決めます。これについては後述のプロバイダーごとの出力のセクションで説明します。

ファイルの $import: エントリでも、キーが出力ファイル名になります。インポートされたファイルは内容を提供しますが、名前は提供しません。そのため、特定の出力ファイル名にしたい作成者はその名前をキーとして書きます。

artifacts:
"monitor.yaml":
$import: ./artifacts/monitor.yaml
"netpol.yaml":
$import: ./artifacts/subdir/some-other-name.yaml

.../monitor.yaml と .../netpol.yaml を生成します。2 番目のエントリがインポートするファイルの名前は some-other-name.yaml ですが、その名前は出力には反映されず、キーが反映されます。したがって、たまたま同じ名前を持つ別々のファイル ./extras/shared.yaml と ./overrides/shared.yaml をインポートする 2 つのエントリは、それぞれ自身のキーで名前が付けられた 2 つの別個の出力になります。

ファイル群を 1 つの単位として取り込むライブラリの $import: エントリでは、エントリはバンドル内のファイルごとに 1 つの出力に展開され、それぞれ <key>/<filename> としてキーの下に入れ子になります。1 つのキーが多数のファイルを指すため、キーだけではそれらに名前を付けられません。キーはいずれか 1 つのファイルの名前ではなく、バンドルのファイルが配置されるディレクトリになります。

どの形式もキーから出力の名前を決めるため、キーは作成時点で単一のファイル名として有効なものに制限されます。先頭は英字または数字で、その後に英字、数字、ドット、ハイフン、アンダースコアが続きます。ドットは利用側が期待する拡張子を表し、これによりキーをそのままファイル名として使えます。また、この文字集合には / も先頭の . も含まれないため、1 つのキーが複数のパスセグメントを表すことも、親ディレクトリのセグメントになることもありません。文字集合に含まれないキーは、ワークスペースの読み込み時、aggrega validate 実行時、およびエディタの診断で、エンベロープの検証に失敗します。

同じファイル名を持つ 2 つの artifacts: 出力は、どの形式から生成されたかにかかわらず、ノードのレンダリング時にビルドを停止させます。1 つの artifacts: マップ内の 2 つのエントリが同じ出力を指すことはありません。キーは 1 つのドキュメント内で一意で、単一のファイル名であるため、単一ファイルのエントリの出力名はそのキーであり、バンドルエントリの出力はすべてそのキーで名付けられたディレクトリの下に置かれます。したがって、出力されるすべてのパスの最初のセグメントはそれを生成したキーであり、異なるキーは異なる出力名のままです。この停止が対象とするのは入力種別をまたぐケース、つまり 2 つの入力種別が同じファイル名を提供する場合(チャートのテンプレートと artifact エントリの両方が servicemonitor.yaml を生成する場合など)で、診断には提供元がすべて示されます。

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

artifact テンプレートはピラーコンテキスト全体にアクセスできます。

  • .values、.infra、.context.*、.locals、.provides、.features、.metadata:06-data-taxonomy-and-composition.md で説明されている Aggrega の標準ピラーです。
  • .workload:この Recipe のパース済み Workload spec です(存在する場合)。artifact が Workload の値を重複なく参照できます。例:.workload.services.metrics.ports.prom を参照する ServiceMonitor。
  • .source:解決済みの source: フィールドの内容です(存在する場合)。

Artifacts は Workload のパース後に評価されるため、存在する場合は .workload を利用できます。workload: を持たない Recipes では .workload は nil で、これを参照しようとするテンプレートは明確なエラーで失敗します。source: を持たない Recipes では .source が nil となり、同様に失敗します。

自己完結性の不変条件

Artifacts は自己完結している必要があります。参照できるのは Recipe が宣言した入力、つまりピラーコンテキスト、Recipe 自身の Workload(存在する場合)、Recipe 自身の source: の値のみです。次のものは参照できません。

  • 同じ境界内の他の Recipes の出力。
  • Recipe が宣言していない、環境に存在する Kubernetes リソース。
  • 外部に存在すると想定される Secret、ConfigMap、その他のリソース(宣言されたピラー経由で参照される場合を除く)。

Workload の volumes.*.configmap.source から参照される ConfigMap の artifact は、この Recipe 自身(その ConfigMap を生成する artifacts: 経由)か、このノードにアタッチされた Feature によって出力される必要があります。境界内での Recipe をまたぐ依存関係はサポートされていません。

この不変条件により Recipe の再利用性が保たれます。Recipe は、そのピラー契約を満たす任意の Aggregate と Release の組み合わせに、隠れた依存関係なしに組み込めます。

来歴ラベル

変換後、出力されるすべてのファイルは、そのメタデータに aggrega.ai/* の来歴情報を持ちます。これは、ソースからレンダリングされたもの、Workload から合成されたもの、artifact テンプレートから出力されたもののいずれであっても同じです。出力を行うすべての箇所が共通の 1 組のビルダーから来歴を付与するため、どの入力種別が生成したかにかかわらず、同じファイルは常に同じ来歴を持ちます。この組は、値が Kubernetes のラベル値の文字セットを満たすかどうかで分かれます。ラベルとして安全なキーは ラベル(クエリ可能)となり、文字セット上安全でないキー、すなわち recipe-uri(: を含む)、boundary-path(ネストしたパスは / を含む)、sync-wave(負のウェーブの先頭の -)は アノテーション となり、その値には制約がありません。ビルドがラベルの規則に従わせない識別値(集約名、環境、プロバイダー名、コンパイラとプロバイダーのバージョン)は、ラベルが許容する形式で書かれたラベルとなり、その形式が値と異なる場合は、元の値がそのまま同じキーのアノテーションにもなります(imported/flow という名前の Aggregate には、ラベル imported-flow とアノテーション imported/flow が付きます)。同じ Recipe の出力を持つすべてのファイルは同じ来歴を共有します。

metadata:
labels:
aggrega.ai/component-id: api
# ... plus the recommended app.kubernetes.io/name label
annotations:
aggrega.ai/recipe-uri: api-server-helm:1.0.0
aggrega.ai/boundary-path: production

この分割は 3 つの入力種別すべてで共通です。(Compose プロバイダーにはアノテーションの概念がなく、そのラベル値には制約がないため、組全体をサービスラベルとして出力します。)コンパイル時の来歴付与については 11-governance-and-compliance.md を参照してください。

プロバイダーは自身の出力形式が来歴を保持できる場所に来歴を付与するため、あるファイルについてそのような場所を形式が提供しないプロバイダーは、そのファイルを変更せずに出力し、その旨を通知します。知っておくべきケースは Compose です。Compose の来歴の付与先はサービスの labels: ブロックであるため、トップレベルの volumes:、configs:、models: のみを提供する compose の artifact フラグメントは来歴を持たず、ビルドはその artifact を名指しする「skipped provenance label injection(来歴ラベルの注入をスキップしました)」警告を出力します。この警告はその形のフラグメントでは想定どおりのものであり、問題の兆候ではありません。同じ component が出力するサービスは完全な組を持ち、出力されるバイト列は何も変わりません。これが排除するのは 3 つ目の可能性、つまりファイルが名指しされないまま来歴なしでビルドから出ていくことです。

もう 1 つ知っておくべきケースは CloudFormation で、来歴が付与されるかどうかではなく、どこに 付与されるかが異なります。CloudFormation テンプレートには、リソースとともに移動するドキュメントレベルのメタデータブロックがないため、来歴は各リソース自身の Metadata 属性に、組全体を保持する 1 つの aggrega.ai/provenance キーの下に置かれます。

"StoreBucket": {
"Type": "AWS::S3::Bucket",
"Metadata": {
"aggrega.ai/provenance": {
"aggrega.ai/component-id": "store",
"aggrega.ai/recipe-uri": "store-recipe:1.0.0",
"aggrega.ai/boundary-path": "stack"
}
}
}

この付与先から 3 つの性質が導かれます。Metadata 属性は種類を問わずすべてのリソースで利用できるため、組み立てられたスタックが持つすべてのリソースに来歴が付与されます。これには、タグをまったく受け付けない多くのリソース種別も含まれ、タグベースの付与ではそれらに置き場所がありませんでした。付与は作成者が書いた Metadata を置き換えるのではなく、そこに 追加 されるため、作成者自身のエントリはそのまま並存します。そして、テンプレート単位ではなくリソース単位であるため、複数の component が組み立てられるスタックでは、各リソースがそれ自身を提供した ID、つまりその component、その Recipe、その boundary を持ちます。これはテンプレート全体に 1 つのエントリでは表現できないものです。

組全体がそのキーの下にまとめて置かれます。Metadata の値は制約のない JSON であるため、文字セットによる分割は不要です。Kubernetes ランタイムのみが読み取る 2 つのキー、すなわち標準の推奨ラベル名と、GitOps コントローラーが利用するデプロイ順序のアノテーションは、どちらもスタック内の何も指さないため除外されます。プレーンな aggrega.ai/sync-wave 来歴エントリは残ります。これはコントローラーに指示するものではなく、component が宣言したウェーブを記録するものだからです。

ここで付与先を持たない形は、リソースを宣言しないテンプレートまたはフラグメント、つまり Parameters、Mappings、Conditions、Rules のみを提供するものです。これは来歴を持たず、自身の内容をそのまま保って組み立てられたスタックに到達し、ビルドはそれを名指しする「skipped provenance injection(来歴の注入をスキップしました)」警告を出力します。compose の場合と同様に、この警告はその形の提供物では想定どおりのものです。同じ component が他の場所で提供するリソースは完全な組を持ち、出力されるバイト列は何かが監視しているかどうかにかかわらず同じです。

Provider ごとの Artifact セマンティクス

以下のプロバイダーごとのセマンティクスは、各プロバイダーがアーティファクトをネイティブ出力にどのように統合するかを説明します。

helm プロバイダー: アーティファクトは Kubernetes YAML ドキュメントであり、チャートからレンダリングされたマニフェストと Workload から合成されたマニフェストを格納する出力ディレクトリ内の、それらを宣言したコンポーネントにちなんで名付けられたディレクトリの下に書き出されます。理由は命名にあります。レンダリングまたは合成されたマニフェストは、所属するコンポーネントからプロバイダーが名前を付けますが、アーティファクトは作成者が書いたキーで名前が付けられ、そのキーはどのコンポーネントのものかを何も示しません。そのため、1 つの Recipe にバインドされた 2 つのコンポーネントは、どちらの作成者も区別できないまま 1 つのパスに書き込むことになります。ディレクトリはコンポーネント自身の名前であるため、作成者が出力で読み返すファイルは、1 階層下にある、自分が書いた名前のファイルです。

別のレイアウトを望むオペレーターには境界の subDirectory: テンプレートがあり、これはアーティファクトだけでなく、コントリビューターが出力するすべてのファイルを移動します。../language-reference/path-template-variables.md を参照してください。

compose プロバイダー: アーティファクトは compose フラグメントです。トップレベルのキー(services:、volumes:、configs:、models:)は、境界の合成ステップで境界ごとに結合された docker-compose.yaml にマージされます。

helm-chart プロバイダー(特殊ケース): アーティファクトはスタンドアロンファイルとして出力ディレクトリに書き出されません。レンダリングパイプラインは Helm が所有しているためです。代わりに、helm-chart プロバイダーは各 artifacts: エントリをチャート自体の中に配置し、エントリの記述形式によって配置先が決まります。すべてのエントリは、配置の前にまず Aggrega のピラーコンテキストで Go テンプレート処理されます。そこから 2 つの形式が分かれます。$import: で読み込まれたエントリは Helm 前処理のテンプレートファイルです。Helm のレンダリングの前にチャートの templates/ ディレクトリに注入されるため、Helm はソースとなるチャート自身のテンプレートと並べてそれをレンダリングします。インラインのブロックスカラーはルーズなチャートファイルです。記述されたキーでチャートのルートに配置され、templates/ プレフィックスもマージされた来歴ラベルも持たないため、チャート自身のテンプレートは Helm の .Files.Get / .Files.Glob を通じてそれを読み取れます。これはファイルから ConfigMap を作成するパターンです。これにより、helm-chart プロバイダーは、通常の helm プロバイダーに対して artifacts: が提供するものと同等の拡張メカニズムを、Helm のチャートモデルを尊重しつつ得られます。

注入されたファイルは boundaries/<bp>/charts/<nodeID>/templates/<authored-key> に配置されます(バンドルのファイルはそのキーの下にネストされます)。そのため、ソースとなるチャートのテンプレートと並び、Helm は後続のレンダリングパスでそれを取り込みます。インラインのブロックスカラーは boundaries/<bp>/charts/<nodeID>/<authored-key>、つまり templates/ の 1 階層上のチャートルートに配置されます。.Files を通じて読み取られるファイルはチャートが探す場所に置かれている必要があり、templates/ の下に置かれたファイルは代わりにマニフェストとしてレンダリングされるためです。どちらの形式も記述されたキーで名前が付けられます。両者で異なるのは、プロバイダーが配置するディレクトリです。

helm-chart のデリミタの慣例。 helm-chart のアーティファクトエントリ($import: で読み込まれたものもインラインのものも同様)に対する Aggrega の事前テンプレートパスは、デフォルトの {{ }} ではなく [[ ]] デリミタを使用します。これにより、ファイル内の Helm 自身の {{ ... }} 構文は手を加えられずに Helm のレンダリングパスまで残ります。作成者は Aggrega 側の置換を [[ .context.instance_id ]]、[[ .values.name ]] などと書き、Helm 側の置換は {{ .Values.x }}、{{ .Release.Name }}、{{- include "common.labels" . }} などのままにします。1 つのファイル内で 2 種類のデリミタを混在させることが、サポートされている記述形式です。

来歴と helm-chart アーティファクト。 来歴は、Helm トークンを保持したまま YAML を往復できる $import: で読み込まれたファイル、つまり [[ ]] の Aggrega コンテキストのみを使用するファイル、または Helm の {{ }} を引用符付きスカラーの位置にのみ持つファイルについて、metadata.labels と metadata.annotations に(前述の文字セットによる分割に従って)マージされます。構造的な Helm テンプレートアクション(スカラーの葉ではなく YAML 構造を出力する位置にある {{- include ... }}、{{- if ... }}、{{- range ... }}、{{- with ... }})を持つファイル、または値の位置に引用符なしの {{ ... }} を持つファイルは、Aggrega の YAML 往復に耐えられません。ビルドはアーティファクトを名指しした「skipped provenance label injection(来歴ラベルの注入をスキップしました)」警告を出し、ファイルを変更せずにそのまま渡します。**この警告は、構造的な Helm テンプレートアクションまたは引用符なしの Helm 値置換を使用する、helm-chart の $import: で読み込まれたあらゆるアーティファクトファイルで想定されるものです。**これは本番の Helm 記述では例外的なケースではなく一般的なケースです。そのようなファイルに来歴ラベルを必要とする作成者は、Aggrega の事前テンプレート注入ではなく、チャート自身の _helpers.tpl に自分で書く名前付きテンプレート(たとえば aggrega.commonLabels という名前のもの)または同等の Helm 側の仕組みを使って注入します。

チャートルートのファイル名の衝突。 記述されたキーがチャートルートのファイル名(Chart.yaml、values.yaml、.helmignore など)と衝突する $import: で読み込まれたアーティファクトは、Aggrega のファイル名衝突チェックでは検出されません。アーティファクトは templates/<authored-key> に配置され、チャートルートのファイルはチャートルートに配置されるため、パスのプレフィックスによって Aggrega から見ると両者は別物になります。作成者はこれらのキー名を避けます。使用した場合、Helm は両方のファイル(チャートルートに 1 つ、templates/ 内に 1 つ)を認識し、templates 側のコピーを予期せずレンダリングする可能性があります。

terraform プロバイダー: アーティファクトは Terraform 設定ファイルであり、境界の modules/ ツリーの下にあるコンポーネント自身のディレクトリにそのまま出力されます。HCL(main.tf)が使いやすいデフォルトであり、Terraform JSON(.tf.json)も同等に受け付けられます。どちらもトランスパイルや再フォーマットはされません。境界のルート設定は、そのコンポーネントを source がそのディレクトリを指す module ブロックとして宣言するため、境界全体が 1 つの依存関係グラフのままとなります。これはベンダリングされたモジュールのファイルが置かれるのと同じディレクトリであるため、source: と artifacts: の両方を宣言する Recipe はそれらを並べて書き出します。来歴は先頭の Terraform コメントブロックとして付与されます。コンポーネントがコメント構文を持たない JSON 本体を提供する場合、すべての本体は変更されずに出力され、来歴はその横に置かれるコメントのみのコンパニオン .tf ファイルで伝えられるため、スタンプが両者で重複することはありません。terraform プロバイダーのページを参照してください。

cloudformation provider: artifacts はスタックフラグメントです。つまり、テンプレート全体ではなく、1 つの component が提供するリソースです。provider は各フラグメントを純粋な JSON の長形式組み込み関数に正規化し、その出力ディレクトリ用に組み立てられる単一のスタックにマージします。そこでリソースは 1 つの Resources マップに統合され、component の provides は公開元の component にスコープされた名前でスタックの Outputs として現れます。フラグメントのその他のトップレベルセクションのうちどれが組み立て後に残るかは、マージされたドキュメントが artifacts: から引き継ぐもので説明しています。cloudformation provider のページを参照してください。

境界スコープ:境界の共有出力のためのファイル

artifacts の仕組みには 2 つ目のスコープがあります。ここまでの内容はすべて、境界の出力内にある component 自身の位置に書き込まれます。Recipe の spec.boundary.artifacts は同じマップ(同じ 3 つの形式、同じキーからファイル名への規則、同じテンプレートコンテキスト)ですが、代わりに境界全体に対して一度だけ書き込まれます。これは、境界がデプロイするすべてのものに対してターゲットが一度だけ読み込むファイルのために存在し、そのようなファイルはどの component 自身の位置にも置けません。Terraform のドキュメントによれば、呼び出されることを意図したモジュールは provider ブロックを含んではならず、含むモジュールは depends_on、count、for_each を使って呼び出すことができません。そのため、provider の設定は component のモジュール内ではなく、境界のルート設定に置くべきものです。

配置先。 ディスパッチグループの組み立て済み出力を保持するディレクトリ内で、provider 自身の組み立てがそこに書き込むファイルの隣に置かれます。terraform の場合はルート設定の隣です。コンパイラは、Recipe がレンダリングする component ごとに、その component のコンテキストに対して各エントリを一度評価し、ファイルを自ら書き込みます。provider にはこれらのファイルは一切渡されず、どの component に由来するかを示す情報もファイルに刻印されません。そのファイルは、それを宣言したすべてのコントリビューターに属するためです。

コントリビューター同士の合流。 1 つのディスパッチグループに対する全コントリビューターが宣言したファイルは、名前によってマージされます。同一のバイト列で宣言された 1 つの名前は 1 つのファイルになります。異なるバイト列で宣言された 1 つの名前、または provider の組み立て自体が書き込む名前は、そのファイルとすべてのコントリビューターを示してビルドを停止させます。これは、2 つのコントリビューターが 1 つの出力パスに書き込む場合と同じ拒否です。したがって、2 つの Recipes が必要とする provider 設定は両者が同じ名前で書き込み、ビルドがその一致を確認します。

受け入れる側。 境界の組み立て済み出力の隣に置かれたファイルが意味を持つかどうかは provider のターゲットの性質であるため、それは provider 自身の主張であり、入力種別と同様に provider 自身の宣言から読み取られます。それを主張しない provider に対してこのブロックを宣言した Recipe は、何もレンダリングされる前に拒否されます。下の表ではこの主張を最後の列に示しています。コンパイラとともに配布される provider のうち、terraform がこれを主張しています。

Artifacts ではないもの

構造上の 3 つの区別:

単一の Recipe 内でのクロス provider ではありません。 Recipe は spec の先頭で capability: をちょうど 1 つ宣言します。Recipe が生成するもの(source からレンダリングされた出力、workload から合成された出力、artifact の出力)はすべて、その provider のネイティブ形式です。helm の Recipe の artifacts には Kubernetes YAML が含まれます。compose の Recipe の artifacts には compose フラグメントが含まれます。Recipe は 1 つの provider を対象とし、すべての出力はその provider のネイティブ形式です。

複数 provider の合成は Release のレベルで行われます。境界は異なる provider の component を混在して保持でき、境界の評価済みパスにおける各 provider のコントリビューターは、(パス, provider) ごとに独立してディスパッチされ組み立てられます。helm、helm-chart、compose をそれぞれ対象とする component を持つ Release は、3 つすべてを 1 つの境界に配置できます。ディスパッチのグループ化によりそれらは provider ごとに分割され、各 provider のコントリビューターは境界のパス下にある各自の組み立て済み出力に配置されます。そして運用者は、自ら選んだ境界構造を通じて provider 間の調整を記述します。provider 間の調整は Release の作成者の責任です。

Recipe 内の Recipe ではありません。 Artifacts は他の Recipes を読み込んだり合成したりしません。これらはインラインのマニフェスト(またはインラインマニフェストへのファイルパス)であり、この Recipe のピラーでテンプレート処理され、この Recipe の出力に出力されます。Recipe の再利用は 3 つの仕組みで行われます。Component の extends:(ベースの Component に対して書かれた Recipe は、それを拡張するすべての Component に使われます。継承されるのはメタデータとスキーマであり、出力ファイルではありません。Recipe 自体は extends: を宣言しません)、Manifest のフラット URI マッピング(同じ Component がカタログごとに異なる Recipes に解決され得ます。../language-reference/entities/manifest.md を参照)、そして Features + FeatureRecipes(直交的に付加される横断的関心事)です。

Recipe 間をつなぐ接着層ではありません。 Artifacts は、Recipe 自身が宣言していない名前、リソース、状態を参照できません。Recipe の Workload が参照する ConfigMap の artifact は、この Recipe が出力しなければなりません。外部でプロビジョニングされた Secret を想定する artifact は、その存在を前提とするのではなく、.features ピラーを介して、つまりそれを出力するアタッチメントの解決済み provides から、その Secret の名前を取得しなければなりません。これは前述の自己完結性の不変条件を artifact 作成の観点から述べたものです。各 Recipe は、1 つの形式のファイルを、1 つのツールで適用されるように、1 つの境界の出力ディレクトリに出力します。

Provider 機能マトリクス

各 provider は、自身がレンダリングする入力種別を宣言します。中央の入力種別ゲートは、サポートされる組み合わせを受け入れ、それ以外をノードのレンダリング時に統一された診断で拒否します。機能は Recipe ではなく provider の性質であり、provider は 3 つの種別のうちの一部をレンダリングします。artifacts: 列は、ソース由来または合成されたプライマリに付随する artifacts と、単独の artifacts のみの Recipe(source: も workload: もないもの)を区別します。最後の 2 列は、provider が omits: を尊重するという主張と、Recipe が boundary.artifacts: のもとで boundary の共有出力に提供するファイルを受け入れるという主張です(前述)。どちらも入力種別ではありません。

各列は個別に読んでください。 行は、provider がどの種別をそれぞれ単独でレンダリングするかを示します。チェックの付いた 2 つの種別を一緒に宣言できるとは示していません。種別は加算によって合成されるため、宣言された各種別は個別にディスパッチされ出力されます。そのため、ある組み合わせがどちらの列にも表れない理由で拒否されることがあります。最も多いのは、両方の種別が同じ出力名でファイルを生成する場合です。各 provider が実際に受け入れる組み合わせは、What each provider accepts, in full に文章で記載しています。

Providersource: + valuesMapping:workload:artifacts:(付随)artifacts のみ(単独)omits:boundary.artifacts:
helm✅✅✅✅✅❌
compose✅✅✅✅✅❌
helm-chart✅❌✅ [[ ]] 区切り文字でテンプレート化❌❌❌
terraform✅❌✅✅❌✅
cloudformation✅❌✅✅✅❌

この表は、コンパイラとともに配布される provider を対象としています。別途提供される provider も、受け入れる入力種別、omits: を尊重するかどうか、boundary.artifacts: を受け入れるかどうかを同じ方法で宣言し、コンパイラはその宣言を同じ経路で読み取ります。ここに記載されていないのは、公開されたページが見たことのない provider を列挙できないためです。

✅ のセルはレンダリングされます。❌ はゲートによって表面化される provider 機能による拒否です。ノードごとの compose フラグメントは組み立てパスごとにマージされるため、directory: を共有する boundary は 1 つのファイルを共有します。

各 provider が受け入れるものの全容

helm — すべての組み合わせ。 source: + valuesMapping:、workload:、artifacts:、そのうちの任意の 2 つ、または 3 つすべてです。コンパイラとともに配布される provider のうち、どの組み合わせも拒否しない唯一のものであり、その理由は出力の命名方法にあります。出力される各ファイルはその中のリソースにちなんで命名されるため、チャートのレンダリング済みマニフェストと合成された Workload のマニフェストが同じ名前になることはありません。3 つすべてを宣言する Recipe は、チャートのファイル、Workload のファイル、artifact ファイルを boundary の出力ディレクトリに並べて出力します。

compose — source: と workload: が一緒に現れる 2 つを除くすべての組み合わせ。 各種別は単独でビルドでき、artifacts: はどちらにも付随できます。source: と workload: の組み合わせはビルドできず、3 つすべての組み合わせも同様です。その理由は Why compose cannot combine a source with a workload で説明しており、これは機能による拒否ではありません。

helm-chart — source: + valuesMapping:、単独または artifacts: を付随させたもの。それ以外はありません。 workload: は合成せず、artifacts のみの形式もありません。唯一の入力種別が artifacts: である Recipe は停止します。理由は、この provider が artifact を置く場所、つまり component 自身のチャートの中にあります。そのため source: のない Recipe には、artifact を置くチャートがありません。

terraform — 3 つの形: source: + valuesMapping: の単独、artifacts: の単独、またはその 2 つの組み合わせです。workload: は合成しません。

cloudformation — terraform と同じ 3 つの形で、同じ 1 つの除外があります。 source: + valuesMapping: の単独、artifacts: の単独、またはその 2 つの組み合わせです。workload: はありません。

拒否された入力種別の表示

バインドされた provider がレンダリングしない入力種別を宣言する Recipe は、ノードのレンダリング時にビルドを停止します。その種別に付随して Recipe が他に何を宣言していても停止します。provider がレンダリングできる source: と workload: を組み合わせても、workload は通りません。停止メッセージは、provider、レンダリングできない種別、レンダリングできる種別を示します:

[CATALOG_ERROR E0265] instance unit
provider does not support the node's input kind (node "unit"). provider "terraform" does not support synthesized recipes (this provider supports: sourced, artifacts-only); declare one of the supported input kinds, or target a provider that supports synthesized

artifacts のみの拒否も同じように読め、その形式を示します: provider "helm-chart" does not support artifacts-only recipes (this provider supports: sourced)。この停止を継続的インテグレーションのゲート、issue、ランブックなどで永続的に名指しする必要がある場合は、E0265 を記録する識別子として使用します。すべての条件の表で解決できます。

compose が source と workload を組み合わせられない理由

compose provider は component ごとに 1 つのフラグメントを生成し、そのフラグメントに component にちなんだ名前を付けます。ソース由来のレンダリングと Workload の合成は、それぞれその component のフラグメントを同じ 1 つの名前で生成するため、両方を宣言する Recipe は同じ名前のファイルを 2 つ生成し、ビルドはその衝突で停止します:

[CATALOG_ERROR E0211] instance unit
rendering node "unit"
caused by: [CATALOG_ERROR] aggregate.yaml at .spec.components.unit
filename collision across input kinds: two input-kind blocks produced a file under one output name (output name "unit.compose-fragment.yaml", produced by "source, workload")

フラグメントの名前は component 自身の識別子から決まり、それを記述する手段はないため、Recipe 自身の内容をどう変更しても衝突は避けられません。この停止はどちらかの種別ではなく組み合わせの性質です。compose は source をレンダリングし、compose は Workload を合成するので、表が両方にチェックを付けているのは正しいことです。compose で 1 つの component に両方の形を使うには、2 つの component に分割するか、source の内容を Workload に取り込んでください。

マージされたドキュメントが artifacts: から引き継ぐもの

2 つのプロバイダーは、アセンブリパスごとにコントリビューターを単一のドキュメントにマージします。compose は 1 つの docker-compose.yaml に、cloudformation は 1 つのスタックテンプレートにマージします。マージされたドキュメントが引き継げるのは、そのアセンブラーがモデル化しているセクションだけです。そのため artifacts: のチェックは、フラグメントの内容が配置される場所を示すものであり、フラグメント内のすべてのキーが残ることを示すものではありません。

compose はアーティファクトフラグメントから services:、volumes:、configs:、models: を、x- プレフィックス付きの拡張キーとともに引き継ぎます。 フラグメントがトップレベルでそれ以外のものを宣言すると、ビルドはそのキーを示して停止します。networks: は、ネットワークがコントリビューターから蓄積されるのではなくバウンダリーごとに導出されるため停止の対象となり、secrets: ブロックやトップレベルの name: も同様です。キーごとのマージ規則とネットワークをまたぐルーティングの代替手段は、compose プロバイダーのページにあります。

cloudformation は Resources、Outputs、Parameters、Mappings、Conditions、Metadata、Rules を引き継ぎ、Transform はすべてのコントリビューターのものから構築します。 トランスフォームは CloudFormation がドキュメント化している順序で結合され、SAM の Globals はそれを読み取るトランスフォームとともに扱われます。また、別のコントリビューターの内容のデプロイ方法を変えてしまうトランスフォームは、名前を示してビルドを停止させます。Description は引き継がれませんが、ビルドはそのことを通知します。セクションとコンポーネントを示す unsupported-field 警告を出し、スタックが引き継がないその他のトップレベルキーについても同様に警告するため、何も黙って破棄されることはありません。この警告は助言的なものです。出力されるテンプレートは警告がない場合とバイト単位で同一であり、--no-unsupported-field-warnings でこの種類の警告を抑止できます。Outputs は、プロバイダーがコントリビュートするコンポーネントにスコープを限定した名前で引き継がれるため、2 つのコンポーネントが同じ名前の出力を 1 つのスタックにコントリビュートしても、両者は区別されます。組み立てられたスタックのトップレベルセクションで、すべてのセクションを 1 つずつ説明しています。

他の 3 つのプロバイダーはマージを行わないため、アセンブラーによってアーティファクトのキーが破棄されるおそれはありません。helm は何も組み立てません。各コンポーネントのマニフェストは、そのままバウンダリーの出力ディレクトリに置かれます。terraform と helm-chart は入れ子にします。各コンポーネントのファイルはそれぞれ専用のディレクトリ(Terraform のモジュールディレクトリまたはサブチャート)に置かれ、バウンダリーのルートドキュメントがそれらを参照します。そのため、アーティファクトのエントリは共有ドキュメントに読み込まれるのではなく、ファイル全体として配置されます。helm-chart のアーティファクトエントリがどこに置かれるか、またそのデリミターの組がなぜ異なるかは、Per-Provider Artifact Semantics にあります。