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

Compose Provider

compose プロバイダは、Aggrega の Recipes を Docker Compose ファイルにレンダリングします。このプロバイダは (path, provider) ごとにアセンブルを行います。各境界の compose コントリビュータは、その境界の評価済み directory: にコンポーネントごとの subDirectory: を連結したものをキーとするアセンブラにルーティングされ、そのアセンブラは、そのパスにあるすべてのコントリビュータを含む docker-compose.yaml を 1 つ出力します。同じパスに評価される 2 つの兄弟境界は、マージされた 1 つの compose ファイルにまとめられます。典型的な例は、親境界と、directory: "{{ .parent_boundary.directory }}" を持つ 2 つの子境界の組み合わせです(compose-bridge パターン)。

サポートされる入力の種類

compose provider は、Recipe の 3 種類の入力をすべて受け付けます。

  • Sourced モード。 既存の compose ファイルを指す source: と、オーバーレイドキュメントを生成する valuesMapping: を持つ Recipe です。ベースとなる compose ファイルが読み込まれ、オーバーレイが評価され、両者が docker-compose ネイティブのオーバーレイのセマンティクスに従ってディープマージされます。
  • Workload モード。 workload:(インライン、または $import: で読み込んだもの)を持つ Recipe は、Workload ドキュメントを宣言します。provider は Workload の spec から 1 つ以上の compose サービスを合成します。
  • Artifacts モード。 Recipe の artifacts: エントリは compose フラグメントとして評価され、Artifacts が出力する compose フラグメントの規則に従って組み立てられたファイルにマージされます。artifacts は source や Workload と併用でき、Recipe の出力全体を artifacts だけで構成することもできます。artifacts: を宣言し、source: も workload: も宣言しない Recipe はここでレンダリングされ、フラグメントが宣言する内容をそのまま提供します。これにより、リソースだけで構成される component(共有ネットワークとボリュームのセット、初期値を投入した設定など)は、持たないコンピュートの代わりにプレースホルダーの Workload を置くことなく、compose のデプロイメントに含められます。

3 つの種類は加算的に組み合わさり、いずれも宣言しない Recipe は読み込み時に拒否されます。source: を伴わない valuesMapping: も、どの provider を指定していても、Recipe の読み込み時に拒否されます。オーバーレイを適用する対象が存在しないためで、診断メッセージは source: ポインタを宣言するか valuesMapping: を削除するよう求めます。

Workload の feature マッピング

Recipe が workload: を宣言すると、provider はプラットフォームが所有する Workload の形を compose のプリミティブに変換します。このマッピングは意図的に狭くしてあります。Compose の表面は Kubernetes よりも形が乏しく、いくつかの Workload の機能は、文書化された損失を伴って最も近い compose の同等物に劣化します。

コンテナのフィールド

Workload のフィールドCompose のフィールド
imageimage
imagePullPolicy: Always / IfNotPresent / Neverpull_policy: always / if_not_present / never
commandentrypoint(リスト形式)— イメージのエントリポイントを上書きします。それを行う compose のキーがこれです
argscommand(リスト形式)— エントリポイントが受け取る引数を与えます。compose の command が上書きするのはこれです
variablesenvironment(マップ形式)
attachments[as: env]値が空の environment エントリと、そのエントリを名指しする警告(compose provider が提供しないものを参照)
attachments[as: file]volumes のロング形式のバインドマウント(読み取り専用)
volumeMounts参照先の Volume のバリアントが対応する compose のプリミティブ — volumes のロング形式エントリ、サービスレベルの tmpfs: エントリ、またはサービスレベルの configs: 参照(Volumesを参照)
ports暗黙(compose のコンテナはイメージがリッスンするポートを公開します)
restartPolicy: Alwaysrestart: unless-stopped
restartPolicy: OnFailurerestart: on-failure
restartPolicy: Neverrestart: "no"

variables と attachments[as: env] は 1 つの environment マップに入ります。attachment のエントリが先、variables がその後で、それぞれ記述された順序に従います。これは helm provider が書き出す順序と同じであり、1 つの Workload はどのターゲットでも 1 つの環境変数の並びをレンダリングします。Compose はサービスの環境変数エントリ間で $(NAME) 参照を展開しないため、compose ではこの順序に実行時の意味はありません。マップは各名前を 1 回しか保持しないため、1 つの名前を variables エントリとしても、as: env で渡される attachments エントリとしても与えるコンテナは、2 つの値のどちらかを残すのではなくビルドを停止させます(A container gives one environment variable two values(コンテナが 1 つの環境変数に 2 つの値を与えています)を参照)。

コンテナのリソース

コンテナの resources は compose の deploy.resources ブロックに渡され、docker compose は非 swarm モードでこれを尊重します。Kubernetes の requests は保証された最小値を表すため compose の reservations になり、limits は厳格な上限を表すため limits のままです。

Workload のフィールドCompose のフィールド変換
resources.requests.cpudeploy.resources.reservations.cpus10 進数のコア数。裸の数値(2、0.5)で書かれたコア数はそのまま出力され、それ以外の形式は値から変換されます(500m → 0.5、1500m → 1.5、5n → 0.000000005、1e1 → 10)
resources.limits.cpudeploy.resources.limits.cpus同じ変換
resources.requests.memorydeploy.resources.reservations.memory正確なバイト数。どの形式で書かれていても値から変換されます — 8Gi は 8589934592、1.5Gi は 1610612736、1e3 は 1000 になります
resources.limits.memorydeploy.resources.limits.memory同じ変換
resources.limits、resources.requests、またはその両方の下の nvidia.com/gpudeploy.resources.reservations.devicesコンテナのサービス上の 1 つの NVIDIA デバイスエントリ — driver: nvidia、count: に GPU 数、capabilities: [gpu]。数は、limit が書かれていれば limit の値(Kubernetes が拡張リソースに対してスケジュールする数)、そうでなければ request の値です。0 の数は GPU を要求せず、エントリを書き出しません
その他の拡張リソースキー — amd.com/gpu およびその他すべての <domain>/<name>—単一ホストの compose に相当するものはありません。キーは削除され、ビルドはそのキーを名指しする unsupported-field 警告を出します。requests と limits のいくつにそのキーがあっても、警告は異なるキーごとに 1 つです。値は出力されないため、検査もされません

各 cpu、memory、nvidia.com/gpu の値は、Recipe のテンプレートが評価した後の Workload 上で、Workload → Resource quantities に定める形式の数量として読み取られます。次の 2 つはビルドを TRANSLATION_ERROR で停止させ、エラーはそのどちらに該当したかを示し、コンテナのパス、値が request か limit か、リソース、値を名指しします:

  • 数量ではない値 — lots、1.5 cores、または空のテンプレートが "{{ .infra.cpu }}m" に残す m;
  • compose が正確に表現できない数量 — 負の量、バイトの整数ではない(1500m、4u)または 9223372036854775807 バイトより大きい(8Ei)メモリ量、コアの小数点以下 9 桁(Kubernetes の数量自体が保持する最も細かい精度)より細かい、または 9223372036.854775807 コアより大きい cpu 量、デバイスの整数ではない GPU 数(0.5、500m)。

nvidia.com/gpu の request と limit が異なる数を要求するコンテナも同様に停止し、両方のパスを名指しします。compose はサービスに 1 つの数しか予約しないため、そうしなければ変換がどちらかを選ばなければならなくなるからです。両方に同じ数を書くか、limit だけを書いてください。

丸めは一切行われず、別の意味を持つ値が出力されることもありません。

GPU の request は NVIDIA GPU を予約します。 nvidia.com/gpu: "1" を要求する Workload のコンテナは、request が予約する cpus と memory に加えて、次の予約を持つサービスをレンダリングします:

deploy:
resources:
reservations:
devices:
- driver: nvidia
count: 1
capabilities:
- gpu

Docker Compose は、Docker ホストにその数の NVIDIA GPU があり、コンテナに渡すよう設定されている場合に、予約された GPU をコンテナに渡します。ビルドからはホストが見えないため、GPU を予約するファイルはどこで実行されるかにかかわらず同じように組み立てられます。Compose は数のないデバイスエントリをホスト上のすべての GPU と解釈するため、エントリは常に数を明記します。変換されるのは NVIDIA のキーだけです。amd.com/gpu およびその他のベンダーのキーは、削除されるキーの行の警告のままです。Pod-level fields の runtimeClassName の行は変わりません。compose には runtime class に相当するものがないため、GPU 対応のランタイムを名指しする Workload にはランタイムが省略されたことが伝えられ、GPU 数は予約されます。

プローブ

Workload の 3 つのプローブスロット(live、ready、startup)は、サービスごとに 1 つの compose の healthcheck にまとめられ、優先順位は live > ready > startup です(最も正統な liveness のシグナルが優先されます)。このまとめによって作成者が宣言したスロットが捨てられる場合、ビルドは変換されたスロットと削除されたスロットを名指しする unsupported-field 警告を出し、出力のどこにも届かない意図が失われずに報告されるようにします。1 つのスロットを宣言する health ブロックは損失なく変換され、何も出しません。ただし、そのスロットが successThreshold を設定している場合は別です。compose の healthcheck にはそのためのフィールドがないため、作成者が書いた値は 1 も含めて省略され、それを名指しする unsupported-field 警告(containers.<name>.health.<slot>.successThreshold)が出されます。スロットの残りの部分は下の表のとおりに変換されます。

Workload のプローブの形Compose の healthcheck.test
http: /path["CMD-SHELL", "curl -f http://localhost:<port>/path || exit 1"]
tcp: <port>["CMD-SHELL", "nc -z localhost <port>"]
exec: [cmd, ...]["CMD", cmd, ...]

HTTP 形式では、コンテナが名前付きポートを少なくとも 1 つ宣言している必要があります。シンセサイザーはアルファベット順で最初のポート名を選び、その番号を使って curl の URL を組み立てます。ポートを宣言していないコンテナは HTTP プローブを使えず、コンパイラは問題のプローブを名指しする TRANSLATION_ERROR で停止します。

プローブのタイムアウトのフィールドは compose 形式の期間文字列に対応します:

Workload のフィールドCompose の healthcheck フィールド
periodSecondsinterval: <n>s
timeoutSecondstimeout: <n>s
failureThresholdretries: <n>
initialDelaySecondsstart_period: <n>s

ボリューム

Compose には独自の config プリミティブがあり、configmap ボリュームはこれに変換されます。Secret やレプリカごとのボリュームテンプレートに相当する Kubernetes 同等のものはないため、これらのバリアントは最も近い compose プリミティブに縮退します。

Workload ボリュームバリアントCompose での変換失われるものについての注記
ephemeralサービスレベルの tmpfs: リストエントリsizeLimit は保持されません(compose の tmpfs 短縮形にはサイズがありません)。記述された sizeLimit は、コンテナがそのボリュームをマウントしているかどうかにかかわらず、記述された座標(volumes.<name>.ephemeral.sizeLimit)でそれを示す unsupported-field 警告を発生させます。このフィールドを省略した場合は何も発生しません
configmapconfigmap を名前で指すサービスレベルの configs: 参照。ボリュームマウントのパスにマウントされます🔴 マウントパスはディレクトリではなく単一ファイルのパスです。 Compose は config の内容をちょうどそのターゲットパスに書き込みますが、Kubernetes ターゲットで ConfigMap をパスにマウントすると、キーごとに 1 つのファイルを持つディレクトリが生成されます。そのため、同じ記述の path: がここではファイルを、あちらではディレクトリを表します。configmap ボリュームのマウントは、それを含むディレクトリではなく、コンテナが読むべきファイル名(/seed/config.json)に向けてください。両方のターゲット向けに記述された Recipe は、ターゲットごとに異なるパスを持ちます。もう一方のターゲットの形に合わせて書かれたパスをビルドで検出する手段はありません。パスはコンパイラがそのまま通す不透明な文字列であり、出力はどちらの場合も有効だからです。参照は、Kubernetes ターゲットが ConfigMap リソースを参照するのとまったく同じく 名前 によるもので、config の内容を読むものは何もありません。対応するトップレベルの configs: エントリは Recipe の artifacts: 入力から来ており、その compose フラグメントがインラインの content: で宣言します。そのようなエントリのない参照はビルドを停止させます(Artifacts が出力する compose フラグメントを参照)。configs: 参照は config 名とマウントパスのみを持つため、マウントの readOnly には個別の表現がありません
secretvolumes のロング形式のバインドマウント(読み取り専用)secret ボリュームは意図的に configmap の変換に従いません。インラインの configs: エントリでは secret の値が出力される compose ファイルに平文で書き込まれてしまいますが、コンパイラは secret を平文に解決することはなく、secret はビルドのすべての段階を通じてポインタのままです。バインドソースは secret の source 名であり、オペレーターがビルドとは独立に compose ホスト上で到達可能にするパスとして解決されます
persistent名前付きボリューム + トップレベルの volumes: { <volume-name>: {} } 宣言。名前はボリューム名の導出方法に従って付けられますストレージクラス、アクセスモード、サイズは保持されません(compose には同等の形がありません)。記述された class または accessModes は、記述された座標(volumes.<name>.persistent.class、volumes.<name>.persistent.accessModes)でそれを示す unsupported-field 警告を発生させます。どちらも省略した場合は何も発生しません。必須の size は警告を発生させません — 下記を参照
persistentTemplate名前付きボリューム + トップレベル宣言。名前は同じ方法で付けられます(persistent と同じ)form: stateful の付随要素です。compose にはレプリカごとのボリュームテンプレートのプリミティブがないため、レプリカごとの動作は失われ、ボリュームがすべてのレプリカで共有される 1 つのボリュームになったことを unsupported-field 警告が伝えます。ストレージクラス、アクセスモード、サイズは、persistent の場合とまったく同じく保持されません。記述された class または accessModes は volumes.<name>.persistentTemplate.class または volumes.<name>.persistentTemplate.accessModes で unsupported-field 警告を発生させ、必須の size は警告を発生させません

マウントの subPath は、compose に対応する形式がある場合にボリュームの一部をマウントします。 persistent または persistentTemplate ボリュームを指定し subPath を持つ volumeMounts エントリは、volume.subpath を持つ長形式の volumes エントリになります。そのため、マウントにはボリュームのルートではなく、ボリューム内の指定されたディレクトリまたはファイルが見え、1 つのボリュームを 2 つの異なる subPath 値でマウントする 2 つのマウントには、ボリュームの異なる 2 つの部分が見えます:

volumes:
- type: volume
source: store--data
target: /var/lib/app/db
volume:
subpath: db
- type: volume
source: store--data
target: /var/lib/app/uploads
volume:
subpath: uploads

subPath なしで書かれたマウントは volume: ブロックを持ちません。ephemeral、configmap、secret ボリュームのマウントに subPath を指定すると、ビルドは TRANSLATION_ERROR で停止し、コンポーネント、コンテナ、マウントの記述されたパス(containers.<name>.volumeMounts[<i>])、ボリューム、subPath を示します。これらのバリアントは compose ではそれぞれ tmpfs エントリ、configs: 参照、バインドマウントになり、いずれも提供する内容の一部だけをマウントすることはないため、停止しなければマウントにはボリューム全体が見えてしまいます。そのようなマウントから subPath を削除するか、persistent ボリュームをマウントしてください。Docker Compose はリリース 2.26.0 以降、Docker Engine 26.0 以降で volume.subpath を読み取ります。ビルドはファイルを実行するホストを確認できないため、これを含むファイルは実行場所にかかわらず同じように組み立てられます。

ボリュームが示すのは自身がどのバリアントかということだけです。 secret ボリュームの変換はちょうど 1 つ(上記の読み取り専用バインドマウント)であり、ボリュームには別の変換を選ぶ as: フィールドはありません。スロットが公開したものを環境変数として渡すのは、ボリュームではなくコンテナの attachments エントリ(as: env)です。compose がそれをどう扱うかはcompose provider が提供しないものにあります。

ストレージサイズを持つバリアントは 3 つありますが、サイズが破棄されたことを警告するのはそのうち 1 つだけです。 違いは選択の余地があったかどうかです。ephemeral ボリュームの sizeLimit は任意なので、それを書いたのは意図的な判断であり、警告はその値がこのターゲットでは何にも影響せず削除できることを伝えます。この警告は参考情報で帯域外のものであり、出力ファイルは警告がない場合とバイト単位で同一で、--no-unsupported-field-warnings でこのクラスの他の警告とともに抑制できます。persistent または persistentTemplate ボリュームの size は必須なので、それを省略した文書は存在しません。そこでビルドごとに警告を出すと、変更できるものを何も示さないままあらゆるステートフルなワークロードで発生してしまうため、その違いはビルドごとに報告する代わりにここで説明しています。compose をターゲットにする場合、永続ボリュームの size、class、accessModes は出力ファイルに何も影響しません。得られるのは、compose ホストのボリュームドライバーがデフォルトで行うとおりのサイズとバックエンドを持つ、単なる名前付きボリュームです。class と accessModes は任意なので、記述したものはそれぞれ ephemeral の sizeLimit と同じように報告されます。フィールドごとに 1 つの unsupported-field 警告が出され、参考情報で帯域外のものであり、同じフラグで抑制されます。基盤となるストレージのサイズはホスト上で設定するか、これらのフィールドが出力に反映される Kubernetes ターゲットで設定してください。

どのコンテナもマウントしていないボリュームは、記述された座標(volumes.<name>)でそれを示す unsupported-field 警告を発生させます。その場合、出力ファイルに反映されるものがバリアントによって大きく異なるためです。persistent と persistentTemplate はそれでもトップレベル宣言を生成するため、ボリュームは作成されますが何も使用しません。ephemeral、configmap、secret はマウント自体以外に表現を持ちません。それぞれマウントパスに書かれるもの、つまり tmpfs エントリ、configs 参照、バインドマウントに変換されるため、何もマウントしていなければ、宣言したボリュームは出力にまったく痕跡を残しません。この 2 番目のケースこそが警告が存在する理由です。警告がなければ、マウントを忘れた configmap ボリュームは単に存在せず、出力ファイルにはそれに気づく手がかりが何もありません。ワークロードのすべてのコンテナがマウント元として数えられ、init コンテナも含まれるため、init コンテナだけがマウントしているボリュームは接続済みとなり、何も発生させません。この警告は参考情報で帯域外のものであり、出力ファイルは警告がない場合とバイト単位で同一です。--no-unsupported-field-warnings でこのクラスを抑制できます。

ボリューム名の導出方法

persistent または persistentTemplate のボリュームは compose の名前付きボリュームになります。トップレベルの volumes: エントリが 1 つ作られ、それをマウントするすべてのコンテナがそれを参照します。compose のボリュームは共有ストレージであり、トップレベルの volumes: ブロックはエントリを名前で統合します。そのため、2 つの記述されたボリュームが同じ名前になると、両方のコンテナが書き込む 1 つのボリュームになり、出力ファイルには 2 つが意図されていたことを示すものが何も残りません。そこで名前は、どのボリュームであるかを合わせて示す 2 つの識別子から構築されます。ボリュームが属する <component> と、Workload が volumes: の下でボリュームに付けた名前です。

compose のボリューム名が受け付ける文字の集合は、どちらの識別子が持ちうる文字よりも狭く、英字、数字、ドット、アンダースコア、ハイフンです。導出では、compose が受け付けない文字を別の文字で置き換えるのではなく書き出します。そのため、少しでも異なる 2 つのボリュームは 2 つの異なる名前になり、組み立てられた名前から元の 2 つの識別子を読み戻すことができます。

  • 英字、数字、ドット、アンダースコアは記述どおりにそのまま引き継がれます。
  • ハイフンは、その次の文字がそのまま引き継がれる文字で、かつ小文字の z でない場合に限り、記述どおりに保持されます。ハイフンの後に小文字の z が続くとエスケープの開始になるため、その位置に記述されたハイフン自体が書き出されます。api-zone は api-zhzone になり、これによってどの名前も推測なしに読み戻せます。後ろに何も続かないハイフンも同じ理由で書き出されるため、db- は db-zh になります。
  • それ以外の文字はすべて、-z の後にその文字を示す英字を続けて書き出されます。パス区切り文字には s、上記の規則で保持されないハイフンには h を使います。その他の文字(スペースや非 ASCII の文字を含む)は、x とその文字の 6 桁の 16 進コードポイントで書き出されます。どの文字の先頭にもならないバイトは b とそのバイト自身の 2 桁の値で書き出されるため、有効なテキストでない名前も潰されることなく区別して書き出されます。
  • 空の値は -ze と書き出され、空でない値がこれを生成することはありません。
  • 2 つの識別子は -- で連結されます。エンコードされた単一の識別子にはこの組が決して含まれないため、連結された名前は一方の識別子がどこで終わり、もう一方がどこで始まるかを曖昧さなく示します。

したがって、コンポーネント store と、Workload が data と呼ぶボリュームからはボリューム名 store--data が得られ、db-server と data からは db-server--data が得られます。同一の入力からは常に同一の名前が生成されます。

二重の連結子によって組が曖昧さなく示されます。1 文字の連結子ではそうはなりません。 どちらの識別子もそれ自体にハイフンを含みうるため、ハイフン 1 つで連結すると、複数の位置で分割できる名前が残ります。data-cache というボリュームを持つ db と、cache というボリュームを持つ db-data はどちらも db-data-cache となり、トップレベルのブロックは名前で統合するため、2 つのコンポーネントは 1 つのボリュームを共有し、出力ファイルにはそれを示すものが何も残りません。エンコードされた識別子にはハイフンの組が決して含まれないため、二重の連結子では別の読み方ができません。2 つはそれぞれ db--data-cache と db-data--cache になります。

どちらかの識別子を変更すると compose のボリューム名が変わり、compose はボリュームをその場で名前変更しません。 新しい名前でボリュームが新規に作成され、古いボリュームはデータを保持したまま残ります。そのため、コンテナは空のストレージで起動し、内容は何もマウントしないボリュームに残ったままになります。どちらの識別子の名前変更も、展開する変更としてではなく、計画すべき置き換え(バックアップ、コピー、またはスケジュール)としてのみ行ってください。

コントローラーの形態

Workload の form は抽象的なコントローラーの形態を選択します(entities/workload.md を参照)。compose は stateless と stateful(および stateless として扱われる空のデフォルト)を長時間稼働するサービスとしてレンダリングします。stateful 形態は、persistentTemplate のコンパニオン用に名前付きボリュームを追加します。daemon、scheduled、task の形態には単一ホストの compose で明確に対応するものがないため、compose バウンダリを対象としてこれらのいずれかを宣言した Workload は、その形態とサポートされる形態の集合を示す TRANSLATION_ERROR で停止します。compose は、サポートされない形態を意図を誤って表す単純なサービスに格下げしません。reference 形態の Workload は外部エンドポイントを宣言し、コンテナを持たないため、compose はそれに対してサービスを出力しません。

reference Workload にはサービスが出力されないため、それが実現するコンポーネントの配信パイプを読むものはありません。そのコンポーネントにアタッチされた認証情報(dotenv-secret によって、またはアタッチメント自身の inject: ブロックによってパイプ上で配信されるもの)は、出力されるどのファイルにも届きません。そのため、この方法で外部サービスを実現し、その Component が認証情報スロットを宣言している標準ライブラリの Compose Recipe はすべて、そのスロットを埋める認証情報を拒否します。ビルドは、認証情報が欠けたまま成功するのではなく、スロットとコンポーネントを示して停止します。compose では、外部サービスの認証情報は、それを呼び出すコンポーネントに、そのコンポーネントが読む環境変数のもとでアタッチします。この拒否は各 Recipe 自身のアサーションであり、このプロバイダが何かをレンダリングする前に実行されます。このプロバイダは、Recipe がどのカタログから来たかにかかわらず、ノード自体でも拒否します。reference ノード上のアタッチメントのうち、その素材が機密と宣言されているもの(その Feature がフィールドを sensitive: true と宣言しているか、それが埋めるスロットがそう宣言しているもの)は、ビルドを TRANSLATION_ERROR(E0288)で停止させ、ノードとそのようなアタッチメントをすべて示します。これは、アタッチ時の名前をいずれかのスロットが宣言しているかどうかにかかわりません。機密と宣言されたものを何も持たないアタッチメントは、ここでは拒否されません。これらの Components は認証情報スロットを任意として宣言しているため、compose では空のままのスロットによって停止することはありません。Kubernetes での実現に認証情報が必要な場合(twilio、vonage、telnyx、bland、letta、retell、vapi の helm Recipes)は、その Recipe が代わりにスロットを必須とし、空の場合はスロットを示してビルドを停止します。

サービスの公開

Workload の services エントリの type フィールドは、compose がポートを公開するかどうか、およびどのホストアドレスで公開するかを決定します。

Workload のサービスタイプcompose の動作
ClusterIPports: による公開なし — サービスには compose ネットワーク上からのみ到達できます
NodePortすべてのホストインターフェースでの ports: [<host>:<container>] による公開
LoadBalancerすべてのホストインターフェースでの ports: [<host>:<container>] による公開(compose にはマネージドロードバランサーに相当するものがなく、ホストポートの公開が最も近い類似物です)
Loopbackports: [127.0.0.1:<host>:<container>] による公開 — ホスト自身からのみ到達でき、それ以外からは到達できません
Headlessports: による公開なし

どちらの番号がどちら側になるか。 サービスエントリはコンテナポートを指定し、それに番号を与えます。これは Kubernetes の Service が port を targetPort に対応付けるのと同じです。エントリの番号は公開されるペアの <host> 側で、名前が解決されるコンテナポートの番号が <container> 側です。したがって、http: 8080 を宣言するコンテナと、http: 8081 と書く NodePort エントリは 8081:8080 を公開します。ホストのポート 8081 が、コンテナがサービスを提供するポートに到達します。コンテナポート自身の番号を持つエントリは、その番号を両側に公開し、8080:8080 となります。compose ネットワーク上のピアは、公開されたポートではなく、コンテナのポートでサービス名によってサービスに到達します。公開されたポートはホストに属するためです。そのため、独自に選んだポートを公開する Recipe も、利用者に渡すのはコンテナのポートです。

Loopback エントリは IPv4 のループバックアドレスのみにバインドします。IPv6 のループバックアドレス ::1 にはバインドしません。compose のポート構文はエントリごとに 1 つのホストアドレスしか持てず、ループバックインターフェースに IPv6 アドレスがないホストではバインドできないため、そこではサービスが起動しなくなるからです。ホスト上のクライアントは 127.0.0.1 でポートに到達します。

1 つの Workload 上の複数のサービスが同じコンテナポートを同じ番号で公開する場合、ポートは 1 回だけ公開され、最も広い到達範囲が優先されます。NodePort または LoadBalancer からの参照が 1 つでもあれば、Loopback エントリが同じポートを指定している場合でも、またどのエントリが先に宣言されているかにかかわらず、すべてのホストインターフェースで公開されます。Loopback エントリのみが指定するポートは 127.0.0.1 で公開されます。2 つの番号で公開される 1 つのコンテナポートは、それぞれの番号で 1 回ずつ、計 2 回公開されます。公開されるポートはコンテナポートの順に列挙され、1 つのコンテナポート内では公開ポートの順に列挙されます。

ポートのトランスポート。 公開エントリは、指定するコンテナポートで宣言されたトランスポートを compose の /protocol サフィックスとして持ちます。53:53/udp、または Loopback エントリの場合は 127.0.0.1:53:53/udp です。トランスポートを宣言していないポートはサフィックスなしの <host>:<container> として公開され、compose 自身のデフォルトが適用されます。compose は公開ポートのトランスポートを tcp または udp と表記します。SCTP を宣言したポートには compose での表記がないため、異なるトランスポートを持つポートを公開するのではなく TRANSLATION_ERROR で停止します。どのサービスも公開しないコンテナポートは compose ファイルのどこにも反映されないため、そのようなポートで宣言されたトランスポートには表記先がなく、停止しません。

マルチコンテナの Workloads

複数のコンテナを持つ Workload は、1 つのメインサービスと、メイン以外のコンテナごとに 1 つのサイドカーサービスになります。メインコンテナは、main という名前のコンテナ(存在する場合)、または宣言順で最初のコンテナです。サイドカーは network_mode: "service:<main>" によってメインサービスのネットワーク名前空間を共有します。これは Kubernetes の Pod の共有ネットワークモデルに最も近い compose のプリミティブです。

サイドカーまたは init サービスの命名方法

メインサービスは <component> の名前をそのまま使います。Workload が生成するそれ以外のすべてのサービス — サイドカーごとに 1 つ、init コンテナごとに 1 つ — は、2 つの識別子を組み合わせて命名されます。<component> と、コンテナの名前です。コンテナの名前は、サイドカーでは containers: の下のキー、init コンテナでは name、または名前のない init エントリが取る位置ベースの init-<index> です。組み立てられた services: ブロックは名前ごとに 1 つのサービスを保持するため、名前は、どちらかの識別子が異なる 2 つのコンテナが必ず 2 つの名前になるように構築されます。

それぞれの識別子は、ボリューム名の 2 つの部分とまったく同じように書き出されます — 英字、数字、ドット、アンダースコアは記述どおり、ハイフンはそこでの規則が残す箇所で残され、それ以外のすべての文字は書き換えられます — そして 2 つは、書き換えられたどの識別子にも含まれない -- で結合されます。そのため、サイドカー logger を持つコンポーネント api はそれを api--logger として実行し、platform の init コンテナ import-seed は platform--import-seed として、api の名前のない最初の init エントリは api--init-0 として実行されます。サービス名が受け付けない文字を含むコンテナ名は、記述どおりに出力されるのではなく書き換えられます。api の warm cache/x という名前の init コンテナは api--warm-zx000020cache-zsx として実行されます。

二重の結合によって、2 つのコンポーネントのコンテナが区別されます。 コンテナ warm-cache を持つ api と、コンテナ cache を持つ api-warm は、api--warm-cache と api-warm--cache という 2 つのサービスとして実行されます。ハイフン 1 つの結合では、どちらも api-warm-cache になってしまいます。

サイドカーと init コンテナはこの 1 つの命名を共有します。そのため、同じ名前を持つ containers エントリと initContainers エントリは同じサービス名になり、一方のコンテナを他方の代わりに実行するのではなく、ビルドはその組で停止します(Init コンテナを参照)。

コンポーネント自身のサービスは、これらの名前のいずれも取りません。 メインサービスはコンポーネントにちなんで命名され、コンポーネント名に書かれた二重ハイフンはそこで書き換えられます — api--prep という名前のコンポーネントは api-zh-prep として実行されます — そのため、-- の結合を含むことはありません。それでも 2 つの異なるコンポーネントのサービスが 1 つの compose ファイル内で同じ名前になる場合 — たとえば、アーティファクトが自ら名付けるサービスを通じて — ビルドは両方を示して停止します。(path, provider) ごとの出力で説明しているとおりです。

コンポーネント名またはコンテナ名を変更すると、サービスの名前が変わります。 Compose は新しい名前のサービスを新しいサービスとして扱うため、そのコンテナは新しい名前で新たに作成されます。

Pod レベルのフィールド

Pod レベルの Workload フィールドはメインサービスにのみ適用されます。サイドカーはメインサービスのネットワーク名前空間を共有し、init サービスも同じ規則に従います。唯一の例外は Pod のユーザーです。Pod はすべてのコンテナを podSecurityContext.runAsUser と runAsGroup で実行するため、これらはサイドカーと init サービスを含め、Workload が生成するすべてのサービスに届きます。

いくつかは compose のサービスフィールドに対応します。

Workload のフィールドCompose のフィールド
podSecurityContext.runAsUser / runAsGroupWorkload のすべてのサービス上の user("1000"、またはグループ付きの場合は 1000:3000)。独自の securityContext.runAsUser を設定したコンテナは、代わりに自身のサービス上でそのユーザーとして実行され、独自の runAsGroup を設定している場合はそのグループも使われます
terminationGracePeriodSecondsstop_grace_period: <n>s
dnsConfig.nameservers / dnsConfig.searchesdns / dns_search
hostAliasesホスト名ごとに 1 つの extra_hosts エントリ(記述順)
hostNetwork: truenetwork_mode: host

ノードのネットワーク上での実行。 hostNetwork: true を宣言したワークロードは、自身のサービスに network_mode: host が設定され、そのサービスはバウンダリのネットワークに接続されず、そこから外されます。compose は networks: と network_mode: の両方を宣言したサービスを拒否するため、この 2 つは追加ではなく択一の関係です。実際の帰結はホストネットワーキングが常に伴うものと同じです。ピアはそのネットワーク経由で compose のサービス名によってサービスに到達できなくなります。サービスがもうそのネットワーク上にないためです。ピアはホスト自身のアドレスでサービスに到達し、これが宣言の求めたことです。バウンダリ上のほかのサービスは影響を受けません。

これと組み合わさる形が 2 つあります。サイドカーはメインサービスを指定し続ける(network_mode: "service:<main>")ため、自身では何も宣言せずにメインサービスに従ってホストのネットワークに移ります。Kubernetes の Pod のコンテナが 1 つの名前空間を共有するのと同じです。init サービスはそうなりません。init サービスは独自にバウンダリのネットワークに参加します。メインサービスの名前空間を共有すると、メインサービスによる init サービスの待機が循環してしまうためです。したがって、hostNetwork と initContainers の両方を持つワークロードは、自身のサービスをホストのネットワーク上で実行し、init サービスはバウンダリのネットワーク上に残ります。これはモデル化する Pod の形よりも限定的です。この違いは実行時に発見されるままにせず、unsupported-field 警告で示されます。

残りには単一ホストで相当するものがありません。どれも黙って破棄されることはありません。 記述された各フィールドについて、そのフィールドを示す unsupported-field 警告が出されるため、作成者は対象が反映できなかった設定を、稼働中のスタックから発見するのではなく事前に知ることができます。

Workload のフィールドcompose が反映できない理由
scheduling配置(nodeSelector、affinity、tolerations、topologySpreadConstraints)は、ノードの中から選択するスケジューラーを前提とします。compose は 1 つのホスト上で実行されます
replicascompose 自身のレプリカ数は deploy: の下にあり、swarm モードの機能です
runtimeClassName代替のコンテナランタイム(たとえば GPU 対応のもの)の選択には compose での表現がありません
priorityClassNameプリエンプションの順序はスケジューラーを前提とします
serviceAccountWorkload identity はクラスタの概念です
imagePullSecretscompose ホスト上のレジストリ認証情報はホスト自身のログイン状態であり、ファイルのフィールドではありません
dnsPolicy, dnsConfig.optionscompose が公開するのは dns と dns_search だけで、それより細かい設定はありません
podSecurityContext.fsGroup, podSecurityContext.supplementalGroupsuser が運ぶのは 1 つのユーザーと 1 つのグループです。Pod のボリュームを所有するグループや、そのプロセスの追加のグループは変換されません
Pod が runAsUser を設定していない場合、またはコンテナ(メイン、サイドカー、init のいずれか)が独自の runAsUser を設定し runAsGroup を設定していない場合の podSecurityContext.runAsGroupuser はユーザーと並べてのみグループを指定でき、コンテナ独自のユーザーは Pod のユーザーに取って代わるため、そのように書かれたサービスには Pod のグループが届きません

コンテナレベルの securityContext は部分的に変換されます。readOnlyRootFilesystem → read_only、capabilities.add / drop → cap_add / cap_drop、runAsUser / runAsGroup → user です。runAsNonRoot と allowPrivilegeEscalation には compose での表現がなく、同じ unsupported-field 警告が出されます。横に runAsUser なしで書かれたコンテナの runAsGroup も同様です。この場合、Pod がユーザーを設定していればサービスは Pod のユーザーとして、そのグループなしで実行されます。

このセクションの警告はすべて助言的で帯域外のものです。ビルドは成功し、出力ファイルは警告がない場合とバイト単位で同一です。--no-unsupported-field-warnings でこの種類の警告を抑制できます。

Init コンテナ

Workload の initContainers のエントリは、compose の実行完了型のイディオムを用いて、それぞれ独立したサービスになります。各エントリはサービスを 1 つ追加し、その名前はサイドカーと同じ命名によって <component> とエントリの name から付けられます。通常の名前では <component>--<container-name> です。name を省略したエントリには、Workload リファレンスに記載されている位置に基づく init-<index> という名前が付き、その名前から命名されます。

オーサリング契約が約束する順序、すなわち init コンテナは記述された順に実行完了まで動作し、他のすべてのコンテナはそれらがすべて終了した後にのみ起動するという順序は、depends_on の長い形式で表現されます。

  • 最初のもの以降の各 init サービスは、condition: service_completed_successfully で直前のサービスを待機します。
  • メインサービスとすべてのサイドカーサービスは、同じ条件で最後の init サービスを待機します。init サービスはチェーンを形成するため、最後のものを待機すれば十分です。
  • 各 init サービスには restart: "no" が付きます。init サービスは一度だけ実行されます。再起動したサービスは、依存するサービスが待機している完了状態に到達しないため、init コンテナに記述された restartPolicy によってもこれは変わりません。
services:
platform:
image: platform:1.0
depends_on:
platform--verify-seed:
condition: service_completed_successfully
platform--import-seed:
image: platform:1.0
restart: "no"
platform--verify-seed:
image: platform:1.0
depends_on:
platform--import-seed:
condition: service_completed_successfully
restart: "no"

init コンテナは他のコンテナとまったく同じように変換されます。image(aggrega.ai/image-registry アノテーションが適用するレジストリの書き換えを含む)、command、args、variables、attachments、volumeMounts、securityContext はすべて init サービスに反映されます。これにより、init コンテナが持つ設定(多くの場合、マウントしたファイルをメインコンテナもマウントするボリュームに書き込むもの)が、コンテナとともに失われることなく compose ターゲットに引き継がれます。compose で表現できない形は、通常のコンテナと同じように init コンテナでも失敗します。宣言された lifecycle または envFrom は、その由来となった init コンテナを示す TRANSLATION_ERROR で停止します。

init サービスがメイン以外のサービスであることから、メインサービスとの違いが 2 つ生じます。

  • Pod レベルの Workload フィールドは適用されません。これはサイドカーと同じ規則です。ただし Pod のユーザーは例外で、Pod レベルのフィールドで説明するとおり、すべてのサービスに届きます。
  • init サービスは、サイドカーのようにメインサービスのネットワーク名前空間を共有するのではなく、境界のネットワークに直接参加します。そうせざるを得ません。メインサービスは init サービスを待機しますが、名前空間の共有はそれ自体がメインサービスへの依存であり、待機が循環となって compose が起動を拒否するためです。したがって、init コンテナは境界ネットワーク上の他のサービスにサービス名で到達できますが、メインサービスの localhost は共有しません。

init サービスとサイドカーサービスは、同一の命名方法によって両方に名前が付けられるため 1 つの名前空間を共有します。そのため、initContainers のエントリと containers のエントリに同じ名前を付けることはできません。同じ名前の場合、コンパイラは一方のサービスが他方を黙って置き換えることを許さず、ノード、コンテナ名、および両者が求めたサービス名を示す TRANSLATION_ERROR で停止します。

完了条件の出力によって、必要な Compose の最小バージョンが上がることはありません。condition とその値は基本の Compose Specification に属します。これは、同じ長い形式のブロック内で並ぶ restart および required フィールドとは異なります。これらは仕様によって特定の Compose リリースに結び付けられています。compose プロバイダーの出力が要求する各最小バージョンは、それを必要とする構成要素とともに現れます。インラインの configs.content には ≥ 2.23.1、マウントの subPath には ≥ 2.26.0(ボリュームを参照)、モデルには 2.38 です。1 つ目は、インラインの content: を持つ config を含むすべての compose 出力に及びます。configmap ボリュームの背後にあるファイルも、ブリッジされたクロスネットワークのエッジの背後にある config も、この方法で届けられるため、特定のオーサリング経路に限りません。

サービスが参加するネットワーク

すべてのサービスは Docker ネットワークに参加します。サイドカーは、メインサービスへの network_mode 参照を通じてそれを継承します。ノードがどのネットワークに配置されるかは、そのノードの aggrega.ai/namespace アノテーションから読み取られ、ノードにそのアノテーションがない場合は compose ファイルのパスにフォールバックします。これはビルドの出力ディレクトリの下でファイルが書き込まれるディレクトリで、たとえば directory: が bridge である境界では bridge/compose です。したがって、1 つの compose ファイル内でアノテーションを持たないすべてのノードは、どの境界にあるかにかかわらず、ファイルのパスにちなんで名付けられた 1 つのネットワークに参加します。compose ファイルを共有するアノテーションなしの境界はそのネットワークを共有し、それらを分けるのが aggrega.ai/namespace です。異なるアノテーションを持つノードは、異なるアノテーションごとに 1 つのネットワークに配置されます。ネットワーク名の導出方法は、その識別子から生成される名前です。

ネットワーク名の導出方法

compose ネットワークは共有された L3 接続であり、トップレベルの networks: ブロックはエントリを名前で統合します。そのため、1 つの名前に行き着いた 2 つの識別子は、両方のサービス群が属する 1 つのネットワークになり、互いにサービス名で到達できるようになります。出力されたファイルには、2 つのネットワークが意図されていたことを示すものは何も残りません。そこで名前は、それがどのネットワークかを示す識別子、すなわちノードの aggrega.ai/namespace アノテーション、またはノードにそれがない場合は compose ファイルのパスから構築されます。

compose のネットワーク名が受け付ける文字は、どちらの識別子が含みうる文字よりも狭い範囲で、英字、数字、ドット、アンダースコア、ハイフンです。導出処理は、compose が受け付けない文字を別の文字に置き換えるのではなく書き出します。そのため、少しでも異なる 2 つの識別子は 2 つのネットワークになり、名前から構築元の識別子を読み戻すこともできます。

  • 英字、数字、ドット、アンダースコアは、記述どおり、記述された大文字・小文字のまま引き継がれます。したがって、prod と Prod は 1 つではなく 2 つのネットワークです。
  • ハイフンは、その次の文字がそのまま引き継がれる文字で、かつ小文字の z でない場合に限り、記述どおりに保持されます。ハイフンの後に小文字の z が続くとエスケープの開始になるため、その位置に記述されたハイフン自体が書き出されます。api-zone は api-zhzone になり、これによってどの名前も推測なしに読み戻せます。後ろに何も続かないハイフンも同じ理由で書き出されるため、db- は db-zh になります。
  • それ以外の文字はすべて、-z の後にその文字を表す英字を続けて書かれます。パス区切り文字には s、上記の規則で保持されないハイフンには h です。その他のもの(スペースや非 ASCII の文字を含む)は、x とその文字の 6 桁の 16 進コードポイントとして書かれ、どの文字の先頭にもならないバイトは b とそのバイト自身の 2 桁の値として書かれます。そのため、有効なテキストでない識別子も、まとめられることなく区別して書き出されます。
  • 識別子がまったく存在しない場合(パスを持たない compose ファイル内にある、aggrega.ai/namespace アノテーションを持たないノード)は -ze と書かれます。これは作成者が記述したどの識別子からも生成されません。したがって、識別子を持たないネットワークが、特定の綴りの識別子を持つネットワークと接続を共有することはありません。

したがって、namespace が prod であればネットワークは prod に、core-net であれば core-net になり、dist/app/compose にある compose ファイルは dist-zsapp-zscompose になります。同一の入力からは常に同一の名前が生成されます。

namespace と compose ファイルのパスは同じ空間に書き込まれます。 これらは同じもの(ノードがどのネットワークにあるか)を名付ける 2 つの方法です。そのため、namespace が app/compose のノードと、app/compose にある compose ファイル内の namespace を持たないノードは、同じ aggrega.ai/namespace アノテーションを持つ 2 つの境界と同様に、意図的に 1 つのネットワークに配置されます。2 つのノードを分けたい場合は、異なる識別子を与えてください。

ノードの識別子を変更すると compose ネットワークの名前が変わり、compose はネットワークをその場で名前変更しません。 ネットワークは新しい名前で新たに作成され、そこに属するすべてのサービスはそれに接続するために再作成されます。古いネットワークは、何かが削除するまで残ります。ネットワークはデータを持たないため失われるものはありませんが、そこにあるコンテナは再起動し、変更をまたいで接続を保持しているものはその切断を経験します。namespace アノテーションや compose ファイルの書き込み先ディレクトリの変更は、その場で調整する値としてではなく、計画すべき再デプロイとして扱ってください。

2 つの境界が 1 つのアセンブリパスにまとめられる場合(directory: の共有)、aggrega.ai/namespace アノテーションを持たないそれらのノードはファイルの 1 つのネットワークを共有します。各境界に独自の aggrega.ai/namespace アノテーションを与えると、マージされた docker-compose.yaml はアノテーションごとに 1 つのトップレベル networks: エントリを宣言します。同じ compose ファイル内の異なる境界のサービスは、compose 自身のネットワーク間到達性の規則に従い、compose のデフォルトの DNS 解決の範囲でサービス名によって通信できます。単一の compose ファイル内でのネットワーク間 L4 ルーティングを可能にするのは標準ライブラリの compose-bridge Feature であり、これはカタログのコンテンツで、このプロバイダはそのロジックを一切持ちません。共通祖先の境界にアタッチすると、その FeatureRecipe は、両端がその境界自身の compose ファイルにアセンブルされ、そのファイルの異なるネットワークに属する境界の uses エッジからゲートウェイを導出します。これは、nginx の stream 設定で各ブリッジ対象エッジをプロキシする aggrega-gw サービスです(エッジごとに 1 つの server ブロック、ターゲットのポートを使用し、衝突時は portBase にフォールバック)。そして FeatureRecipe 自身の injectMapping が、各コンシューマーのホスト環境変数を aggrega-gw:<port> に書き換えます。同じ接続がホストとポートの両方を提供する場合は、aggrega-gw に書き換え、ポート変数をリッスンポートに書き換えます。この書き換えは、コンシューマー自身の接続が提供した値を置き換えます。コンシューマーにアタッチされた別の Feature が同じ変数を提供していた場合、ビルドは置き換えずに両方を示して停止します。FeatureRecipe の valuesMapping はその設定をマウントされた compose config として書き出します。これはインラインの content: を持つトップレベルの configs: エントリで、ゲートウェイから参照され /etc/nginx/nginx.conf にマウントされます。オペレーターがマウントする事項ではありません。また、ブリッジ対象のすべてのエンドポイントをゲートウェイの x-aggrega-networks-of の下に指定し、このプロバイダはそれをそれらのエンドポイントが配置されたネットワークに解決します(後述)。両端が 2 つの compose ファイルにアセンブルされるエッジはブリッジされず、ターゲット自身の名前を保ちます。ブリッジするものがない境界にもアイドル状態のゲートウェイが置かれ、設定はなく、自身のもの以外のネットワークもありません。そして、compose ファイルにコンポーネントを 1 つも含まない境界にアタッチされたブリッジは、ゲートウェイをどこにも書かないのではなく、ビルドを停止させます。stream 設定は resolver ディレクティブを持ち、エッジごとの変数(set $uN <host>; proxy_pass $uN)を介してプロキシするため、各アップストリームは起動時に一度ではなく接続時に解決されます。そうしないと、まだ実行されていないターゲットへの素の proxy_pass によって、ゲートウェイが起動時に失敗してしまいます。(これらの変数内の $ は configs.content 内で $$ にエスケープされるため、Docker Compose 自身の $ 補間によって nginx にはリテラルの $ が残ります。)インラインの configs.content には Docker Compose ≥ 2.23.1 が必要です。compose-bridge パターンを参照してください。

他のコンポーネントのネットワークへの参加 — x-aggrega-networks-of

フラグメントが書くサービス(オーバーレイがマージされた後のソースの compose ファイル、または artifacts: の本体)は、拡張キー x-aggrega-networks-of の下に他のコンポーネントを指定することで、同じ compose ファイルにアセンブルされたそれらのコンポーネントのネットワークに参加できます。このキーはコンポーネント ID のリストで、Aggregate がそのコンポーネントに与える ID です。バウンダリスコープの FeatureRecipe は、これを .boundary.components のキーとして、また .boundary のエッジリストの source と target として読み取ります。プロバイダは、すべてのノードが受けるのと同じ配置によって、各 ID をそのコンポーネントがこのファイル内で配置されているネットワークに解決し、それらのネットワークを、それぞれ一度だけ名前順でサービスに追加します。これらはサービス自身のネットワークより前に置かれ、サービスは引き続き自身のネットワークにも参加します。キー自体はアセンブルされたファイルから除かれます。プロバイダは ID を解決すべき参照として読むだけで、サービスが何をするかについては何も読まないため、どの Recipe や FeatureRecipe でもこのキーを使用できます。compose bridge のゲートウェイは、この方法で中継先のエンドポイントのネットワークに参加します。

# written by a FeatureRecipe attached at the boundary `bridge`, whose file holds adminer (namespace frontend) and db (namespace backend)
services:
probe-svc:
image: busybox
x-aggrega-networks-of: ["adminer", "db"]
# dist/bridge/compose/docker-compose.yaml (abridged)
services:
probe-svc:
image: busybox
networks:
- backend
- frontend
- bridge-zscompose

ファイルのアセンブル時に、次の 3 つの場合はビルドが TRANSLATION_ERROR で停止し、それぞれサービスを示します。

  • このファイルにアセンブルされたどのコンポーネントも持たない ID。たとえば、別の compose ファイルにアセンブルされたコンポーネントの ID です。ネットワークは 1 つのファイルに属するため、メッセージは ID とサービスが属するファイルを示します。同じファイルにアセンブルされたコンポーネントだけを指定するか、ID を削除してください。
  • 文字列のリストではない値。 このキーは、ID が 1 つだけの場合でも、コンポーネント ID のリストを取ります。
  • network_mode を書いたサービス上のこのキー。 Compose では、network_mode を持つサービスがネットワークに参加することはできません。どちらか一方を削除してください。

depends_on の推論

compose プロバイダーは、IR の uses エッジから depends_on を自動的に導出します。ソースとターゲットの両方がマージ後の compose ファイルにサービスを提供するエッジごとに、プロバイダーはソースサービスに depends_on: [<target>] を追加します。

依存関係はソースコンポーネント自身のサービスに付与され、そのコンポーネントが提供する他のサービスには付与されません。 init コンテナも宣言するコンポーネントは、エントリごとに完了まで実行されるサービスを 1 つ提供しますが、そのいずれもエッジから導出された依存関係を受け取りません。エッジが指すのはコンポーネントであり、init サービスは独自の名前を持つためです。そのため、コンポーネントが uses するデータベースに対するスキーマ移行など、エッジのターゲットに到達する必要がある init コンテナは、そのターゲットに対する順序付けを持たず、ターゲットに到達可能になる前に実行される場合があります。一方、コンポーネント自身のサービスは、init チェーンの完了とターゲットの起動の両方を待ちます。

エッジから導出されたエントリはゲートなしで出力されます。ターゲットがヘルスチェックを宣言しているかどうかにかかわらず、service_started のセマンティクスを持ちます。ターゲットのヘルスでゲートすること、つまりターゲットのヘルスチェックが healthy を報告するまで compose ランタイムに起動をブロックさせることは表現可能ですが、uses エッジはそれを求めません。同じペアを指すウェーブだけが、エッジから導出されたエントリの条件を変更します。これはエッジではなくウェーブがそれを求めるためです。

エッジから導出されたエントリは、出力の安定性のためにターゲットのアルファベット順で出力されます。ソースまたはターゲットが別のプロバイダー(helm または helm-chart)によって提供されるエッジはスキップされます。depends_on は Release のうち compose が提供するサブセット内でのみ適用されます。

サービスの depends_on は、compose の 2 つの形式のいずれか一方で出力され、混在することはありません。compose は長い形式のすべてのエントリに条件を要求するためです。

  • 短い形式のリスト(depends_on: [<service-name>])は、そのサービスのどのエントリも条件を持たない場合に使われます。依存関係がすべて uses エッジに由来するサービスはすべてこれに該当します。
  • 長い形式のマッピングは、いずれかのエントリが条件を持つ場合に使われます。これは、サービスが init コンテナも待つ場合や、デプロイメントウェーブによって順序付けられる場合に発生します。その際、エッジから導出されたエントリは明示的な condition: service_started を出力します。Compose Specification はこれを短い形式と同等と定義しているため、意味は変わりません。

サービス内では、各ソースは独自の順序を保ち、交互に混ざることはありません。作成者がリストを記述した順序に従う init チェーンの待機が最初に出力され、次にアルファベット順のエッジ由来のエントリ、続いてアルファベット順のウェーブ由来のエントリが出力されます。

デプロイウェーブの順序付け

Release の境界の syncWave: の値は、その境界がレンダリングされる compose ファイルのサービスを順序付けます。境界内のすべての component は境界のウェーブを継承します。複数の境界が 1 つの directory: を共有し、それらの寄与が単一の docker-compose.yaml にまとめられる場合、マージされたファイルは複数のウェーブを保持し、provider はそれらの間の順序を depends_on として表現します。

各サービスは、サービスを持つ直前のウェーブのすべてのサービスを待機し、それより前のウェーブは待機しません。 残りは Compose が推移的に解決します。ウェーブ 2 のサービスはウェーブ 1 を待機し、そのウェーブはさらにウェーブ 0 を待機するため、各サービス自身のリストはファイル全体ではなくひとつのウェーブ分の大きさに収まりつつ、シーケンス全体が順序付けられます。ウェーブは連続している必要はなく、負の値もごく普通に使えます。-1 は、他のすべてより先に実行するマイグレーションによく選ばれる値です。

条件は、ターゲットが満たせるものによって決まります。 ウェーブは、後のグループが起動する前に前のグループが稼働していることを意味し、これはプロセスの起動ではなくレディネスです。そのため、次のようになります。

  • ターゲットサービスが healthcheck を宣言している場合、待機は condition: service_healthy です。
  • 宣言していない場合、待機は condition: service_started です。healthcheck を持たないサービスは healthy を報告できず、それに対するヘルスゲート付きの待機は決して満たされない、つまりファイルが決して起動しないためです。

弱い方の条件は出力されたファイル内で強い方の条件と並んで確認でき、さらにビルドはそのような各サービスを警告で示します。そのため、レディネスによる順序付けを期待していた作成者は、宣言したウェーブのどの部分が起動順序のみとして届くかを知ることができます。この警告は助言的なものです。ビルドは成功し、レンダリングされるバイト列は警告がない場合とまったく同じです。待機を引き上げるには、そのコンテナに health: ブロックを追加します。--no-unsupported-field-warnings でこの種の警告を抑制できます。

ウェーブは引き続きラベルとして記録されます。 順序付けは aggrega.ai/sync-wave ラベルを置き換えるのではなく、その横に追加されます。出力されたファイルを調べる読者は、depends_on のエントリには記載されない、サービスがどのウェーブに由来するかをこのラベルで確認できます。

ウェーブと uses エッジが同じペアを指す場合、1 つのエントリが両方を担います。 Compose は依存関係ごとに 1 つのエントリしか受け付けないため、ターゲットを uses し、かつそのターゲットより後のウェーブに位置するサービスは、ウェーブの条件でゲートされた単一のエントリを出力します。ウェーブの要件の方が 2 つのうち強く、それが表現されます。

すべての component が 1 つのウェーブに属する境界は、これにより何も出力しません。 syncWave をまったく宣言しない Release も同様です。すべての寄与元はこのフィールドのデフォルト値 0 を持ち、マージされたファイルは単一のウェーブを保持し、出力は provider がウェーブの順序付けを一切表現しなかった場合とまったく同じになります。

2 つの compose ファイルにまたがる順序付けは表現できず、近似もされません。 depends_on は同じファイル内のサービスを指し、異なるアセンブリパスに評価される境界は別々の docker-compose.yaml ファイルを生成し、compose ランタイムはそれらを独立したプロジェクトとして扱います。したがって、ウェーブはレンダリング先のファイル内のすべてのサービスを順序付け、その外側は何も順序付けません。2 つの compose プロジェクトの順序付けは、ファイル間のルーティングと同様にオペレーターの関心事です。共有の directory: を宣言すると 2 つの境界が 1 つのファイルにまとまりますが、これは順序付けを得るためではなく、それ自体の理由で行う出力形状の判断です。

後のウェーブを指す uses エッジは記述どおりに出力され、報告されます。 出力される depends_on は、宣言された内容、つまり uses エッジとウェーブの両方を反映します。消費側が、それが使用するターゲットよりも前のウェーブにあるエッジは、ウェーブが示すものと逆のことを示します。エッジは消費側にターゲットを待たせる一方、ウェーブはその間にあるすべてのウェーブを通じて、ターゲットに消費側を待たせます。マージされたファイルは両方を表現し、それは Docker Compose が起動を拒否する循環依存の集合になります。ビルドはそのようなエッジをそれぞれ警告で示し、両方のサービスと両方のウェーブを明記するため、循環は docker compose up の時点ではなくビルド時に明らかになります。この警告は参考情報です。ビルドは成功し、レンダリングされるバイトは警告がない場合とまったく同じです。また、何も破棄されていないため、--no-unsupported-field-warnings ではこの警告は抑制されません。2 つの宣言はそれぞれ表現されており、合わせると起動できないのです。この警告が扱うのは直接のペアだけです。循環全体をたどるのではなく、1 つのエッジが接続する 2 つのサービスを示します。uses エッジとウェーブの組み合わせで構成される循環は、少なくとも 1 つのそのようなエッジを通るため、常に報告されます。一方、ウェーブが関与せず uses エッジだけで形成される循環や、Recipe が提供する compose ファイルに書かれた depends_on エントリによって閉じる循環は、記述どおりに出力され、報告されません。エッジの方向とウェーブの順序を一貫させてください。消費側をターゲットのウェーブかそれより後のウェーブに置くか、ターゲットを消費側のウェーブかそれより前のウェーブに置きます。

# release.yaml fragment — three boundaries collapsing onto one compose file
boundaries:
data:
directory: ./dist/cluster
syncWave: -1
components:
migrator: {} # no health: block
core:
directory: ./dist/cluster
syncWave: 0
components:
store: {} # declares health:
edge:
directory: ./dist/cluster
syncWave: 1
components:
frontend: {} # uses: store
# dist/cluster/compose/docker-compose.yaml (abridged)
services:
frontend:
labels:
aggrega.ai/sync-wave: "1"
depends_on:
store:
condition: service_healthy # store declares a healthcheck
migrator:
labels:
aggrega.ai/sync-wave: "-1" # lowest wave: waits on nothing
store:
depends_on:
migrator:
condition: service_started # migrator declares no healthcheck
healthcheck:
test: [CMD-SHELL, "nc -z localhost 5432"]

frontend は migrator を指しません。順序付けは直前のウェーブまでで、残りは compose が store を通じて連鎖させます。

ソースモード

compose プロバイダの source: は、プロバイダが読み込んで解析できる docker-compose YAML ファイルを指定します。source: フィールドが取る 2 つの形のどちらも受け付けます。素のファイルシステムパス文字列と、url: に場所を持つ構造化オブジェクトです。その場所がファイルシステムパスである場合は常に、ビルドを起動したディレクトリではなく、それを宣言する recipe.yaml を含むディレクトリを基準とし、そのディレクトリの内側にとどまる必要があります。外へ出るパスや絶対パスは拒否されます。Recipe の公開物に含まれるすべてのファイルはそのディレクトリから取られるためです。entities/recipe.md の「Content paths stay inside the Recipe’s own directory」を参照してください。このように指定されたファイルは Recipe とともに公開されますが、Recipe の横にあっても、その宣言のどれからも指定されていないファイルは公開されません。

spec:
capability: compose
source: ./docker-compose.base.yaml # filesystem path to the base compose file
valuesMapping: |
services:
api:
image: "{{ .values.image }}"

構造化された形では、url: の内容によって何かを取得するかどうかが決まります。https:// で公開されたフラグメントは取得され、kind: compose-https-fragment で固定されます。aggrega pull がそれを取得し、ビルドはキャッシュから読み込みます。ファイルシステムパスを指定する url: は取得されません。ディスクから読み込まれ、上記の素の文字列形式とまったく同じ基準で解決されます。また aggrega pin が、指定されたファイルのダイジェストを Recipe の横の entity.lock に記録し、ビルドはフラグメントを読み込む前にそれを比較します。リモートのフラグメントをローカルにベンダリングし、source: をそのコピーに向けることは取得の代替としてサポートされていますが、必須ではありません。スキーマは開いた構造化オブジェクトを受け付けます。

source: <path-to-compose-file> と valuesMapping: を持つ Recipe は、次のパイプラインを実行します。

  1. <path> にあるベースの compose ファイルが読み込まれ、YAML として解析されます。
  2. valuesMapping テンプレートが Recipe のテンプレートコンテキストに対して評価されます。その出力は compose オーバーレイドキュメント、つまりベースのフィールドを補強または上書きする部分的な compose ファイルとして扱われます。
  3. ベースとオーバーレイは、docker-compose ネイティブのオーバーレイセマンティクスでディープマージされます。

ディープマージの規則は次のとおりです。

  • スカラー: オーバーレイが優先。 ベースとオーバーレイの両方が同じスカラーフィールドを設定している場合、オーバーレイの値がベースの値を置き換えます。
  • マップ: 再帰的にマージ。 ベースとオーバーレイの両方が同じマップフィールドを設定している場合、マージはマップの中へ再帰します。両方にあるキーは同じ規則に従い、一方にしかないキーはそのまま保持されます。
  • リスト: 置換。 ベースとオーバーレイの両方が同じリストフィールドを設定している場合、オーバーレイのリストがベースのリストを完全に置き換えます(要素ごとのマージや追加は行いません)。これは docker compose -f base.yaml -f overlay.yaml config の動作と一致します。
  • null: 置き換え、残る。 オーバーレイがサービス上で null に設定したキー(user、command、healthcheck などのサービス自身のキー、environment エントリ、ラベル、または healthcheck や deploy の直下のキー)は、他のスカラーと同様にベースの値を置き換え、compose ファイルに key: null として書き出されます。キーは削除されません。プロバイダがそのキーに独自の値を書き込む場合、ファイルには代わりにプロバイダの値が入ります。labels: null ではプロバイダが付与する来歴ラベルが残り、networks: null ではプロバイダがアタッチするネットワークが残ります。オーバーレイのそれ以外の場所に書かれた null はこの規則の対象外です。その null が何を意味するかは、その属性に対する Compose の解釈によります。たとえば値のない environment エントリは、docker compose を実行する環境から値を取ります。

サービスの作成者が書いたラベルはすべて残ります。 ベースファイルまたはオーバーレイ内のサービスの labels: は、マップとしても、Compose の key=value エントリのリストとしても書くことができ、各ラベルはプロバイダが付与する来歴ラベルと並んで compose ファイルに届きます。リストのエントリは Compose と同じように読まれます。最初の = より前のテキストがラベル名、後のテキストが値であり、= のないエントリは値が空のラベルです。数値や true/false の値はそのテキストとして書かれるため、replicas-hint: 2 はファイルに replicas-hint: "2" として届き、null と書かれたラベルは null のままです。作成者が書いたラベルと来歴ラベルが同じキーを持つ場合、ファイルには来歴の値が入ります。マップでもリストでもない labels: の値と、テキストでないリストエントリは、ソースファイルとサービスを示してビルドを停止させます。artifacts: 本体のサービスラベルはマップ形式をとります。そこでリストを使うと、アーティファクトとサービスを示してビルドが停止します。

マージされたドキュメントは、その後、合成モードの寄与とともに Release レベルのマージに流れ込み、同じ境界ごとのネットワーキングと depends_on の推論が適用されます。

サービス、ボリューム、設定を除外する。 オーバーレイはベースファイルから何も削除できません。オーバーレイの値は置き換えるだけで、削除はしません。そのため、Release で実行してはならないサービスを同梱した取得ファイルには、Recipe または FeatureRecipe の omits: エントリを使います。このプロバイダはこのモードでのみそれを尊重し、他のモードでは尊重しません。合成された Workload と artifacts: 本体はそれらなしでレンダリングされます。エントリは、ファイルのトップレベルの単位 1 つを、その kind(service、volume、config のいずれか)と name(services:、volumes:、configs: の下にあるその単位のキー、完全一致で比較)で指定します。compose ファイルには名前空間がないため、namespace を持つエントリは、他の種類を指定するエントリと同様に、コンポーネントのレンダリング時にビルドを停止させ、そのエントリとこのプロバイダが受け付ける種類を示します。何かを除外する前に、すべてのエントリが検査されます。エントリは、上記のオーバーレイがマージされた後、かつプロバイダが独自のものを追加する前のファイルに対して照合されます。したがって、オーバーレイが追加した単位もベースが宣言した単位とまったく同様に除外され、エントリがプロバイダ独自のものを指定することはありません。エントリが指定した単位は削除され、すべての単位が除外されたセクションもあわせて削除されます。その他の単位は、エントリがない場合とまったく同じに書き出されます。エントリが及ぶのは、それを宣言した Recipe または FeatureRecipe のファイルだけです。別のコンポーネントや付与された Feature が同じ docker-compose.yaml に寄与するものは、同じキーを持つ単位も含めて影響を受けません。プロバイダは各エントリが除外した単位の数を報告し、何も除外しなかったエントリはビルドを停止させます。An omits entry left out nothing the source rendered(omits エントリがソースのレンダリング結果から何も除外しなかった) を参照してください。

除外された単位は、残ったものから参照されたままであってはなりません。compose は、宣言していないサービス、ボリューム、設定を参照するファイルを拒否するためです。単位が削除された後、ファイルがなおそれらのいずれかを参照していれば、その参照ごとにビルドが停止し、メッセージは参照元の各サービスまたはジョブ、参照先の単位、参照があるフィールドを示します。参照とは、Compose Specification が、ファイルのあるエントリが別のエントリを指定するものとして定義しているものです。

  • サービス: いずれかの形式の depends_on、links(SERVICE または SERVICE:ALIAS)、volumes_from(SERVICE または SERVICE:MODE)、service:<name> に設定された network_mode、ipc、pid、uts、同じファイルのサービスを指定する extends、または build.additional_contexts の値 service:<name> によって指定されるもの。
  • ボリューム: volumes: エントリのソースとして指定されるもの。ソースがパスではなく名前である短縮形式 SOURCE:TARGET と、type: volume の長形式です。
  • 設定: いずれかの形式の configs: エントリによって指定されるもの。

サービスの pre_start フックと、トップレベルの各 jobs: エントリも、仕様がそれぞれに許す参照について読み込まれます。参照のように見えても参照としては読まれない値もあります。container: で始まる volumes_from や network_mode のエントリはコンテナを指定し、external_links はこのファイルが宣言していないコンテナを指定し、file: を持つ extends は別ファイルのサービスを指定し、credential_spec.config はファイルではなくプラットフォームが保持する設定を指定する場合があります。すべての値は書かれたとおりに比較されるため、${VARIABLE} を通して記述された参照はこの検査では検出されず、ファイルが一度も宣言していない単位への参照はそのまま残されます。

この検査は、宣言した Recipe または FeatureRecipe 自身のファイルだけを読みます。そのため、同じアセンブリパスの別の寄与者が同名のサービスを宣言していても、除外されたサービスへの参照はビルドを停止させます。参照を残すには、その単位を残します。参照をなくすには、valuesMapping: で参照元のエントリを変更するか(そこでのリストはベースファイルのリストを置き換えるため、depends_on: [] で消去できます)、参照元のサービスも除外します。

(path, provider) ごとの出力

compose の各アセンブリパスは、1 つの docker-compose.yaml を生成します。評価結果が異なるパスになる境界は、それぞれ別の compose ファイルを生成します。評価結果が同じパスを共有する境界は、そのパスにあるすべてのコントリビューターを含む 1 つのマージ済み compose ファイルを生成します。パスは、境界の directory: にコンポーネントごとの subDirectory: を結合したものです(デフォルトは {{ .capability }} であり、compose のコントリビューターはデフォルトで compose/ サブフォルダの下に配置されます)。

単一のアセンブリパス内でサービス名が衝突すると、ビルドは停止します。2 つの異なるノードが同じ (path, provider) タプルで同じインスタンス ID のサービスを提供する場合、コンパイラは停止し、診断は提供元のすべての (boundary, node) タプルをアルファベット順に示します。作成者は、コントリビューターの 1 つの名前を変更する(通常は、シンセサイザーが異なるサービス名を生成するようにノードの識別子を調整する)か、異なる directory: 宣言によってコントリビューターを別々のパスに振り分けることで衝突を解決します。

トップレベルのボリュームはアセンブリパス内で和集合を取り、2 つのコントリビューターは内容が一致する限り同じ名前を宣言できます。コントリビューターはフラグメントであるため、1 つのコンポーネントの 2 つのフラグメント(自身の compose ファイルと artifacts: エントリ、または 2 つの artifacts: エントリ)は、2 つのコンポーネントとまったく同様に 2 つのコントリビューターです。名前付きボリュームは 1 つの物理ボリュームであるため、同一の 2 つの宣言はどちらも、アセンブルされたファイルに最終的に入るエントリを正確に記述しており、その名前の下には 1 つのエントリだけが残ります。プロバイダーが導出したボリュームは本体を持たないため、それら 2 つは自明に一致し、いずれにせよ両者が出会うことはありません(How a volume name is derived を参照)。

注意すべきなのは作成者が書いた volumes: エントリです。これは独自の本体(driver、driver_opts、labels)を持つことがあるためです。2 つのコントリビューターが同じ名前を異なる本体で宣言した場合、ビルドは TRANSLATION_ERROR で停止し、ボリュームと提供元のすべての (boundary, node, fragment) タプルを示します。1 つのボリュームについて 2 人の作成者の意見が食い違う場合、アセンブラが選べる答えはありません。どちらかの本体を残すと、本来は成功するはずのビルドから、もう一方の作成者が書いたものが失われます。両方の作成者が同じボリュームを意図していた場合は 2 つの宣言を同一にし、2 つのボリュームを意図していた場合はどちらかの名前を変更して解決します。トップレベルのネットワークは、異なる aggrega.ai/namespace アノテーションごとに 1 つと、アノテーションを持たないノードのために compose ファイルのパスにちなんで名付けられた 1 つで、How a network name is derived に従って命名されます。同じ aggrega.ai/namespace アノテーションを持つ 2 つの提供元バウンダリは、両者が共有する 1 つのネットワークにマージされます。ファイルを共有するアノテーションなしの 2 つのバウンダリも同様です。

フラグメントが書くすべてのキーは運ばれるか拒否される

フラグメント(オーバーレイがマージされた後のソースの compose ファイル、または compose YAML に評価される artifacts: 本体)は、プロバイダが運ぶキーを通じてのみアセンブルされた docker-compose.yaml に届き、そのキーの集合は固定されています。フラグメントが書く各キーは、書かれたとおりにアセンブルされたファイルに運ばれるか、名指しで拒否されるかのどちらかであり、黙って除外されるものはありません。フラグメントは 1 つの compose ファイルなので、1 つの YAML ドキュメントです。

  • 運ばれるもの。 トップレベルでは services、volumes、configs、models。サービス上では image、pull_policy、command、entrypoint、environment、env_file、ports、labels、volumes、tmpfs、networks、network_mode、depends_on、healthcheck、restart、user、working_dir、privileged、read_only、cap_add、cap_drop、configs、models、deploy、stop_grace_period、dns、dns_search、extra_hosts、profiles。プロバイダが記述するブロックの中では、deploy.resources とその limits(cpus、memory)および reservations(cpus、memory、devices、各デバイスエントリの driver、count、device_ids、capabilities、options)、healthcheck の test、interval、timeout、retries、start_period、長形式の volumes: エントリの type、source、target、read_only、volume.subpath、長形式の configs: エントリの source と target、長形式の depends_on: エントリの condition、トップレベルのボリュームの driver、driver_opts、labels、トップレベルの config の content です。モデルの本体とサービスの長形式の models: エントリは、モデルで説明するとおり、すべてのメンバーを運びます。拡張メンバー(x- で始まるキー)は、拡張メンバーで説明するとおり、トップレベルとサービス上で運ばれます。
  • 拒否されるもの。 それ以外のキー(サービス上の stdin_open、トップレベルの secrets: や name:、deploy.replicas、長形式の depends_on: エントリ内の restart: や required:、トップレベルのボリュームの本体や healthcheck 内の x- キー)は、ビルドを TRANSLATION_ERROR で停止させ、そのようなキーすべてを、フラグメント内のパス(services.migrate.stdin_open)、フラグメント、コンポーネントとともに示します。また、そのようなキーがどこから来るかの 2 か所を示します。1 つはフラグメント自体で、修正方法はそこからキーを削除することです。もう 1 つは valuesMapping: を宣言していないソースの Recipe です。この場合、ノードの値がそのまま compose ファイルに重ねられるため、各値のキーがフラグメントのトップレベルのキーとして届きます。修正方法は、各値をプロバイダが運ぶキーの下に置く valuesMapping: を宣言することです。YAML のマージキー(<<: *anchor)がブロックに持ち込むキーは、そこに書かれたものとして、配置された場所で判定されます。ソースからレンダリングされたフラグメントの名前は <component>.compose-fragment.yaml で、artifacts: のフラグメントは Recipe が付けた名前で示されます。
  • 全体として拒否されるもの: フラグメント独自のネットワーク。 フラグメントのトップレベルの networks: の下にあるエントリは、本体の内容(空のエントリ、driver、その他何でも)にかかわらず、ビルドを TRANSLATION_ERROR で停止させ、エントリ(networks.back)、フラグメント、コンポーネントを示します。アセンブルされたファイルには、プロバイダが導出するネットワークだけが含まれるためです(サービスが参加するネットワークを参照)。エントリを削除してください。サービスは何も宣言しなくても自身のコンポーネントのネットワークに参加し、コンポーネントがどのネットワークに参加するかは aggrega.ai/namespace アノテーションが選び、サービスは追加で参加するネットワークのコンポーネントを x-aggrega-networks-of の下に指定し、異なるネットワーク上のサービス間のルーティングは compose-bridge Feature が行います。空の networks: {} は何も宣言しないため拒否されず、サービス自身の networks: リストは上記のとおり運ばれます。
  • 全体として拒否されるもの: 複数のドキュメントからなるフラグメント。 --- で区切られた 2 つ以上の YAML ドキュメントを含む artifacts: 本体は、ビルドを TRANSLATION_ERROR で停止させ、フラグメント、コンポーネント、含まれるドキュメントの数を示します。マージはフラグメントを 1 つの compose ファイルとして読むため、そうしなければ最初のドキュメント以降のすべてのドキュメントがアセンブルされたファイルから欠落してしまうからです。フラグメントを 1 つのドキュメントとして書くか、各ドキュメントに独自の artifacts: エントリを与えてください。何も含まないドキュメント(末尾の --- が開始する空のドキュメント)は数えられません。複数のドキュメントからなるソースの compose ファイルがこのようなフラグメントになることはありません。ファイルの読み込み時に拒否されます。

プロバイダはキーの意味を読みません。キーが運ばれるのは上記の集合に含まれるからであり、拒否されるのは含まれないからです。

拡張メンバーは記述どおりに運ばれる

Compose Specification は、x- で始まるキーを拡張用に予約しています。これは、ファイルを読むツールが使用でき、Compose 自体は無視するデータです。フラグメントのトップレベルおよびサービス上の拡張メンバーは、プロバイダーがそのレベルでモデル化するすべてのキーの後に、フラグメントが保持する順序で、記述どおりにアセンブルされたファイルに届きます。プロバイダーはその中身を一切読みませんが、サービスの x-aggrega-networks-of だけは例外で、サービスが参加するネットワークに解決し、アセンブルされたファイルからは除外します(他のコンポーネントのネットワークへの参加を参照)。artifacts: の本体は、記述した順序でそれらを保持します。ソース指定の compose ファイルのキーは、オーバーレイがマージされた後に名前順でフラグメントに届くため、その拡張メンバーは名前順で書き出されます。

# an artifacts: body
x-owner: team-b
services:
migrate:
image: example/migrate:1
x-schedule: manual

YAML エイリアスを通じて到達したメンバーは完全に展開して書き出され、アンカーは運ばれません。そのため、アセンブルされたファイルが、対応するアンカーを欠いたエイリアスを持つことはありません。これにより、トップレベルのメンバーが、サービスのマージキー(<<: *base)が取り込むアンカーを保持できます。サービスのメンバーはそのサービスとともに移動します。トップレベルのメンバーは、ボリュームと同じ規則に従ってアセンブリパス内で和集合を取ります。2 つのフラグメントが同じ内容で 1 つのメンバーを書く場合は、ブロックスタイルかフロースタイルかにかかわらず単一のエントリが残ります。異なる内容で書く場合はビルドが TRANSLATION_ERROR で停止し、そのメンバーと提供元のすべての (boundary, node, fragment) タプルを示します。1 つのコンポーネントの 2 つのフラグメントも含まれます。2 つの宣言を同一にするか、どちらかに別の名前を付けてください。

profiles はサービスを Compose プロファイルの背後に置きます。 profiles: を列挙するサービスは、そのプロファイルのいずれかが有効でない限り docker compose up では起動されず、docker compose run --rm <service> によって要求に応じて起動されます。これは、オンデマンドで実行するタスクの compose における形です。リストはフラグメントが記述したとおり、その順序で運ばれます。

# a sourced compose file
services:
migrate:
image: example/migrate:1
profiles: [manual]

モデル

compose ファイルのトップレベルの models: セクションは、そのファイルのサービスが使用する AI モデルを宣言し、サービスには自身の models: エントリによってモデルが付与されます。プロバイダーは、フラグメントがソースとなる compose ファイルであっても、compose YAML に評価される artifacts: 本体であっても、その両方を Compose 本来の表記のままフラグメントからアセンブルされた docker-compose.yaml へ運びます。Workload はモデルを宣言しないため、Workload モードの Recipe はモデルを提供しません。

  • モデルの本体はフラグメントが書いたとおりに書き出されます。 model(モデルの OCI アーティファクト識別子)、context_size、runtime_flags は名前を保持し、x- 拡張を含むその他すべてのメンバーはそれらと並んで運ばれます。モデル内では名前付きの 3 つのメンバーが先に来て残りはキー順に続き、モデルは名前順に書き出されるため、同一の入力からはバイト単位で同一のファイルが生成されます。プロバイダーは本体の内容を何も読みません。識別子を検査せず、何がモデルを提供するかについても関知しません。
  • サービスの参照は形式を保持します。 短縮形はモデル名を列挙し(models: [llm])、長形式は各モデルを endpoint_var と model_var、つまりモデルランナーのアドレスとモデルの識別子を受け取る変数の名前に対応付けます。どちらもフラグメントが使った形式と順序で書き出され、そのサービスとともに運ばれます。長形式で変数名が指定されていない場合は、Compose がファイルの実行時に名前を付けます。
  • モデルはアセンブリパス内で、ボリュームと同じ規則に従って和集合を取ります。 2 つのコントリビューターが同じモデル名を、同一に出力される本体で宣言した場合、その名前の下には 1 つのエントリが残ります。異なる本体で宣言した場合、ビルドは TRANSLATION_ERROR で停止し、モデルと提供元のすべての (boundary, node, fragment) タプルを示します。1 つのコンポーネントの 2 つのフラグメントも、ここでは 2 つのコントリビューターです。両方のコントリビューターが 1 つのモデルを意図している場合は宣言を同一にし、そうでない場合はどちらかに別の名前を付けます。
  • すべての参照は宣言済みのモデルを指します。 アセンブリパスのフラグメントの和集合を取った後、そのパスのどのコントリビューターも宣言していないモデルを付与されたサービスがあると、ビルドは TRANSLATION_ERROR で停止し、そのサービスとモデルを示します。この検査は完成した和集合に対して行われるため、あるコンポーネントが、同じアセンブリパスの別のコンポーネントが宣言したモデルを自身のサービスに付与することができます。
  • omits: エントリでモデルを除外することはできません。 このプロバイダーが受け付ける種類は service、volume、config であり、モデルを指すエントリは、他の種類を指すエントリと同様にビルドを停止させます。

モデルはファイルのビルド時ではなく実行時に提供されます。Docker Model Runner など Compose モデルをサポートするプラットフォーム上の Docker Compose 2.38 以降は、サービスに付与された各モデルを pull して実行し(--all-resources を指定して起動しない限り、それ以外のモデルは除外します)、モデルを付与された各サービスで、参照が指定する変数にモデルランナーのアドレスとモデルの識別子を設定します。ビルドはファイルを実行するホストを見ることができないため、Compose のバージョンもプラットフォームも検査しません。モデルを含むファイルは、何が実行するかにかかわらず同じようにアセンブルされます。

コンポーネントにアタッチされた Feature は同じファイルに提供する

コンポーネントにアタッチされた Feature は、ホストコンポーネントのアセンブル先である docker-compose.yaml に、ホスト自身の Recipe と同じ条件で自身のサービスを提供します。その横に 2 つ目のファイルが作られることはありません。1 つのアセンブリパスは 1 つのドキュメントを生成するため、アタッチされた Feature のサービスはそのドキュメントに含まれるか、まったくデプロイされないかのどちらかです。Feature をデタッチすると、まさにそれらのサービスが削除され、ホストコンポーネント自身のサービスはそのまま残ります。

それらは他と同様にそのアセンブリパスのコントリビューターであるため、上記のすべて(サービス名の規則と、同じトップレベルのボリューム名や config 名を宣言する 2 つのコントリビューターはその内容について一致していなければならないという要件)がそのまま適用されます。また、バウンダリの他の要素と同じネットワークに参加するため、コンポーネントとそれにアタッチされた Feature は、追加の宣言なしにサービス名で互いに到達できます。

Feature が提供する各サービスは、ホストコンポーネントのアイデンティティではなく、そのアタッチメント用に構成されたアイデンティティを持つため、両者が提供した 1 つのドキュメント内でも 2 つは区別できます。そのアイデンティティの構築方法は Labels and annotations で説明しています。

これは Workload のコンテナレベルの attachments: ブロックとは異なる仕組みですが、同じ単語を共有しているため同一のものと読み違えやすくなっています。コンポーネントに Feature をアタッチすると、アセンブルされたドキュメントにサービスが追加されます。一方、コンテナの attachments: エントリは、スロットがその 1 つのコンテナに公開した認証情報を読み取るもので、Container fields で説明しています。

artifacts から出力される compose フラグメント

Recipe の artifacts: ブロックが compose YAML、つまり独自の services:、volumes:、configs:、models:、networks: ブロックを持つフラグメント(各エントリはインライン、またはエントリごとに $import: で読み込まれます)に評価される場合、(path, provider) ごとのアセンブリへのマージは形状ごとの規則に従います。

  • artifacts からの services: は、コンポーネントごとのサービスと並んでアセンブルされた compose ファイルにマージされます。 同じアセンブリパスで 2 つの異なるコンポーネントが提供したサービス名はビルドを停止させ、診断はすべての提供元を示します。単一コンポーネント内での衝突、つまりそのコンポーネント自身の artifact フラグメントとそのコンポーネント用に合成されたサービスとの衝突は検出されず、後の提供が先の提供を置き換えます。そのため、artifact で記述するサービス名は、シンセサイザーが生成する <component> および <component>--<container-name> の名前と区別してください(サイドカーまたは init サービスの命名方法を参照)。
  • artifacts からの volumes: は、トップレベルの volumes: ブロックにマージされます。 1 つの名前に到達する 2 つのエントリは、同一に宣言されていればその名前の下に単一のエントリを残します。これはコンポーネントごとのボリュームと同じ規則です。異なる宣言をする 2 つはビルドを停止させます。これは、2 つのコンポーネントから来た場合も、1 つのコンポーネントの 2 つのフラグメント(その artifacts: エントリ 2 つ、またはそのうちの 1 つとコンポーネント自身の compose ファイル)から来た場合も同じです。artifact フラグメントは独自の本体を記述するため、2 つの提供元の意見が食い違う可能性が最も高いのはこの経路です。artifact で記述するボリューム名は、導出が生成する <component>--<volume-name> の形状も含め、そのアセンブリパスの他の名前と区別してください。ただし、2 つの提供元が 1 つの共有ボリュームを記述することを意図している場合は、それらの宣言が一致している必要があります。
  • artifacts からの configs: は、トップレベルの configs: ブロックにマージされます。 これは、configmap ボリュームの背後にあるファイルがアセンブリに届く仕組みです。ボリュームは configmap を名指しするサービスレベルの configs: 参照になり、artifact フラグメントはその名前のエントリをインラインの content: とともに宣言します。アセンブリパスのフラグメントが統合された後、すべてのサービスレベルの参照は宣言されたエントリに解決される必要があり、そうでなければビルドは TRANSLATION_ERROR で停止し、未解決の各参照(サービス、config 名、マウントパス)を示します。このチェックはコンポーネントごとではなく完成した統合結果に対して実行されるため、あるコンポーネントが、同じアセンブリパスの別のコンポーネントが宣言する config を参照できます。統合は、提供元の意見が一致する場合に名前で調停されます。同一の content: で 1 つの config 名を宣言する 2 つは、両者が記述した単一のエントリを残します。異なる content: で 1 つの名前を宣言する 2 つは、TRANSLATION_ERROR でビルドを停止させ、その config と提供元となるすべての (boundary, node, fragment) タプル(1 つのコンポーネントの 2 つのフラグメントも含む)を示します。config エントリは常に内容を持つため、どちらかの宣言を残すと作成者が書いたファイルが破棄されてしまうからです。config 名はそのアセンブリパスのすべての提供元の間で区別するか、2 つの提供元が 1 つの共有ファイルを提供することを意図している場合は宣言を同一にしてください。
  • artifacts からの models: はトップレベルの models: ブロックにマージされ、サービスの models: 参照はそのサービスとともに移動します。これは Models の規則に従います。1 つのモデル名を宣言する 2 つの提供元は同一に宣言する必要があり、すべての参照はアセンブリパスのいずれかの提供元が宣言するモデルを名指しする必要があります。
  • artifacts からの networks: は拒否されます。 compose プロバイダーはネットワークを境界のアノテーションから導出します(異なる aggrega.ai/namespace アノテーションごとに 1 つのネットワーク、さらにアノテーションを持たないすべてのノードが参加する、compose ファイルのパスにちなんで命名されたネットワーク 1 つ。それぞれネットワーク名の導出方法に従って命名されます)。そのため、artifact が提供するネットワーク宣言はアセンブルされたファイルに置き場所がありません。どのエントリも、フラグメントが書くすべてのキーは運ばれるか拒否されるの規則に従い、エントリとフラグメントを示してビルドを停止させます。エントリを削除し、aggrega.ai/namespace アノテーションでネットワークを形作るか、x-aggrega-networks-of によって名前を指定したコンポーネントのネットワークにサービスを参加させてください。1 つの compose ファイル内でネットワークをまたぐルーティングが必要な作成者は、compose-bridge Feature を使用します。
  • artifacts からの拡張メンバーは運ばれます。 トップレベルの x- キーは、拡張メンバーは記述どおりに運ばれるの規則に従い、アセンブルされたファイルの他のセクションの後に、記述された順序で書き出されます。
  • artifacts からのその他のトップレベルキーはビルドを停止させます。 services:、volumes:、configs:、models: と拡張メンバーが、アセンブラがフラグメントから運ぶもののすべてです。secrets: ブロックとトップレベルの name: は、フラグメントが書くすべてのキーは運ばれるか拒否されるの規則に従い、いずれもキーとフラグメントを示してビルドを停止させます。
  • artifacts: の本体は 1 つのドキュメントです。 複数の YAML ドキュメントを持つ本体は、フラグメントとそれが持つドキュメント数を示してビルドを停止させます。各ドキュメントにそれぞれ専用の artifacts: エントリを与えてください。

最初の 4 つと networks: の非対称性は構造的なものです。services:、volumes:、configs:、models: は、アセンブラがアセンブルされたファイルに蓄積する Recipe ごとの内容を運びます。networks: は、アセンブラが境界の状態から導出する境界ごとのインフラストラクチャです。artifacts は前者を拡張できますが、後者を形作れるのは境界のアノテーションだけであり、そのため artifact 自身のネットワークエントリは拒否されます。拡張メンバーは Compose Specification が他のツールのために定義するデータであるため、記述どおりに運ばれます。それ以外はすべて、アセンブルされたドキュメントに置き場所のない形状であり、そのためマージされずに拒否されます。

compose provider が提供しないもの

  • 1 つの compose ファイル内でのネットワークをまたぐ L4 ルーティング。 プロバイダーは各ノードをそのネットワークに配置し、x-aggrega-networks-of が指定するネットワークにサービスを参加させますが、ネットワーク間のルーティングは自ら一切行いません。ネットワーク A のサービスが docker-compose のデフォルト DNS 以外の手段でネットワーク B のサービスに到達するには、compose-bridge Feature が必要です。その FeatureRecipe がゲートウェイと書き換えを記述します。
  • compose ファイルをまたぐルーティング。 異なるアセンブリパスに評価される boundary は、それぞれ別の docker-compose.yaml ファイルを生成します。compose ランタイムはそれらを独立したプロジェクトとして扱い、compose-bridge Feature も 2 つのファイル間の接続を記述どおりのままにします。ファイル間の通信はオペレーターの責任です(ホストポートの公開、外部ネットワークの共有、または共有の directory: によって boundary を 1 つのパスにまとめるなど)。
  • attachment からの環境変数の取得。 Compose にはそのためのプリミティブがないため、as: env を持つ Workload の attachments エントリは、実行時に解決される参照ではなく、空の値を持つ変数名を出力します。このプレースホルダーは意図的なものです。存在するが空の変数はコンテナをデバッグする人から見えますが、存在しない変数では調べる手がかりが何も残りません。また、ビルドはこれを発見に任せず明示します。そのような各エントリは、記述された座標(containers.<name>.attachments.<KEY> または initContainers[<i>].attachments.<KEY>)でエントリを示す unsupported-field 警告を発するため、作成者はどの変数が空で届き、それがどのコンテナに属するかを把握できます。この警告は助言的なものです。ビルドは成功し、レンダリングされたファイルは警告がない場合とバイト単位で同一です。--no-unsupported-field-warnings でこの種類の警告を抑止できます。as: file を持つ attachments エントリは影響を受けません。compose がそれをバインドマウントし、警告は発生しません。
  • Swarm モードの deploy: の内容。 deploy: 配下のレプリカ、配置制約、更新戦略は Swarm モードの機能であり、compose provider は単一ホストの compose のみを対象とするため、これらはいずれも出力しません。ただし deploy.resources は出力します。これはコンテナの resources が対応する予約と制限であり、docker compose は非 Swarm モードでもこれを尊重します(コンテナリソースを参照)。
  • uses エッジからのヘルス条件付き depends_on。 uses エッジから導出された依存関係は、条件なしで service_started のセマンティクスで出力されます。ターゲットのヘルスチェックが healthy を報告することを条件とはしません。これは uses エッジが何を意味するかの問題であり、provider が生成できない形の問題ではありません。長い形式は init コンテナの待機に対して出力され、デプロイメントウェーブでは、ターゲットがヘルスチェックを宣言している場合にターゲットのヘルスを条件とします。

記述例

uses から導出された depends_on エッジを持つ、2 つのサービスからなる compose デプロイメントです。

# release.yaml fragment
spec:
boundaries:
production:
annotations:
aggrega.ai/namespace: prod
components:
api: {}
db: {}
# api Recipe
apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: api
version: 1.0.0
spec:
capability: compose
implements: example/compute/api:1.0.0
workload: |
apiVersion: aggrega.ai/v1beta1
kind: Workload
containers:
main:
image: api:1.0
ports:
http: 8080
health:
live:
http: /healthz
services:
public:
type: NodePort
ports:
http: 8080
# Aggregate fragment — api uses db, on a socket api's Component declares
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
spec:
components:
api:
type: example/compute/api:1.0.0
uses:
backend:
db:
target: db
db:
type: example/datastore/db:1.0.0

compose プロバイダは、境界の評価済みパス(境界の directory: のデフォルトが dist/boundaries/<name>、subDirectory: のデフォルトが {{ .capability }} であるため、デフォルトは dist/boundaries/production/compose/docker-compose.yaml)に 1 つの docker-compose.yaml を生成し、その内容は次のとおりです。

  • services.api(メインの api サービス、ネットワーク prod、ポート 8080:8080、curl によるヘルスチェック、depends_on: [db])
  • services.db(メインの db サービス、ネットワーク prod)
  • networks.prod(境界の docker ネットワーク)