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

Workload

Workload 種別のアーキテクチャ上の役割(存在する理由、他の 2 つの Recipe 入力種別(sourced と artifacts)との組み合わせ方、およびスキーマ全体)は ../../architecture/16-recipe-input-composition.md で説明しています。このページでは Workload のオーサリングについて説明します。Recipe の作成者が Workload の内容をどのように記述するか、コンパイラがいつ何を評価するか、Workload のフィールドが Component の featuresSchema とどのように相互作用するか、そして Workload 内のテンプレートがどの柱を読み取れるかを扱います。

記述場所

Workload のコンテンツは、Recipe または FeatureRecipe(FeatureRecipe を参照)の中に、インラインまたはファイルから記述します。Recipe は workload: を最大 1 つ宣言します。FeatureRecipe も同様に、独自のものを最大 1 つ宣言します。

# Inline (block scalar)
spec:
workload: |
apiVersion: aggrega.ai/v1beta1
kind: Workload
# ...

または

# File-loaded via $import: (path relative to the Recipe directory)
spec:
workload:
$import: ./workload/workload.yaml

どちらの形式も、パース後には同じ Workload オブジェクトになります。どちらを選ぶかは記述のしやすさの問題です。3 つ目の形式は、複数の Recipes で共有される Workload を WorkloadLibrary のエントリから、そのベア名のアイデンティティによってインポートします: $import: <Library>#/workloads/<entry>。統一されたファイルインポートの語彙に従い、$import: は単一のソースを受け付けます。$ref: と $import: のより広い区別については ../vocabulary/cross-document-ref.md を参照してください。

Workload の YAML は、独立したカタログエンティティとしては記述しません。catalog/workload/ ディレクトリは存在せず、Workload の文法は Recipe または FeatureRecipe が利用するコンテンツ(インライン、その横のファイル、または WorkloadLibrary のエントリに記述されたもの)としてのみ存在します。YAML 内の apiVersion と kind の宣言(apiVersion: aggrega.ai/v1beta1、kind: Workload)は、スキーマ検証のために埋め込みコンテンツを識別するものであり、Workload を独立して参照可能にするものではありません。

テンプレートの評価

Workload のコンテンツは、パース前に完全なピラーコンテキストに対して Go テンプレートとして評価されます。Recipe の作成者が次のようなテンプレートを書いた場合…

replicas: {{ optional .infra `replicas` 1 }}

…コンパイラはレンダリングの Workload サブパスでそのテンプレートを評価し、.infra.replicas をノードの infra ペイロードに対して解決し、その結果の YAML を Workload ドキュメントとしてパースします。Recipe の locals は Workload が評価される前に解決されるため、Workload テンプレートは解決済みのそれらを .locals の下で読み取ります。

Workload テンプレート内でのピラーへのアクセス:

  • .values — Aggregate で宣言された、開発者が作成する認知的ペイロード。
  • .infra — Release で宣言された、Ops が作成する物理的なサイジング。
  • .parameters — 解決時にすでに補間済みです。Developer または Ops が作成時に .parameters.<name> を参照した箇所では、.values / .infra を通じて見えます。
  • .locals — locals プリアンブルで解決され、ソース解決時に公開される Recipe 専用の状態。Workload のすべてのテンプレート評価箇所で利用できます。
  • .context.instance_id — ノードのフラット化されたインスタンス ID。合成したリソースにアイデンティティに基づいて名前を付ける provider が出力するリソース名のプレフィックスです。
  • .context.rendered_name — 合成したリソースに独自の名前を導出する provider がそれらに付ける名前(helm のリリース名など)。provider が名前を報告する場合にのみ存在します。../templates/rendered-resource-names.md を参照してください。
  • .context.inject — インターセプト後のインジェクションパイプ。inject マッピングの際に FeatureRecipe の injectMapping によってすでに書き換えられています。
  • .context.uses — このノードから外向きの、拡充されたトポロジーエッジ。各エッジはターゲットの解決済みの provides、labels、カスケードするアノテーションを持ち、.context.uses.<alias>.features.<slot> の下にはその接続が運ぶアタッチメントを持ちます。
  • .features — ノード自身のアタッチメント。それぞれが type、values、infra、解決済みの provides を持ちます。Component が featuresSchema で宣言したスロットの名前を持つアタッチメントは、そのスロットを埋めます(後述)。接続が運ぶアタッチメントはこれに含まれません。それはその接続の下で読み取られ、Workload は接続を名指しすることでそれを配信します(接続が運ぶ認証情報の配信を参照)。

ピラーアクセスの契約の全容については ../vocabulary/data-pillars.md を、テンプレート評価の順序における Workload 評価の位置については ../templates/expansion-matrix.md を参照してください。

フィールドセマンティクスの要点

Workload の完全なスキーマは ../../architecture/16-recipe-input-composition.md の「The Workload Kind」にあります。以下の作成上の慣例は、Recipe の作成者が行うフィールドレベルの判断を扱います。

form

form は、ワークロードの抽象的なコントローラーの形、つまりターゲットプラットフォームに依存しない実行時ライフサイクルの種類を宣言します。単一の文字列で、stateless、stateful、daemon、scheduled、task、reference のいずれかを取り、省略時は stateless になります。

  • stateless — レプリカごとの識別子を持たない、交換可能で水平スケールするレプリカ(一般的な長時間稼働サービス)。
  • stateful — レプリカごとに安定した識別子とストレージを持つレプリカ。persistentTemplate ボリュームはこの form の付随要素です。
  • daemon — 対象となるホストごとに 1 インスタンス。
  • scheduled — 時刻をトリガーとする繰り返し実行。
  • task — 完了まで 1 回だけ実行。
  • reference — 独自のコンテナを持ちません。コンポーネントは外部エンドポイントを表し、それは endpoint(ホストまたは URL。記述どおりにそのまま渡されます)と省略可能な port で指定されます。helm プロバイダはこれを ExternalName タイプの Service として出力し、compose プロバイダはこれに対して何も出力しません。

form 自体はプラットフォームネイティブなリソース種別を持ちません。Workload を合成する各ターゲットのプロバイダが、form を独自のネイティブな形にマッピングします。

formKubernetes (helm)Compose
statelessDeploymentservice(永続ボリュームなし)
statefulStatefulSetservice + 名前付きボリューム
daemonDaemonSetビルドを停止する
scheduledCronJobビルドを停止する
taskJobビルドを停止する

terraform および cloudformation プロバイダは、sourced および artifacts のみの Recipes をレンダリングし、Workload を合成しません。workload: を宣言してそのいずれかにバインドされた Recipe は、そのプロバイダがサポートする入力種別を示してビルドを停止します。

ターゲットの provider がある form に対する明確なマッピングを持たない場合、ワークロードを意図を誤って表す形に劣化させるのではなく、ビルドを明示的に停止します。ターゲット境界が表現できない form を選ぶことは、暗黙のダウングレードではなくビルド時エラーです。compose provider は daemon、scheduled、task で停止します。helm provider は scheduled に対して CronJob を出力し(後述の schedule を参照)、スケジュールが存在しないか不正な場合にのみ停止します。

apiVersion: aggrega.ai/v1beta1
kind: Workload
form: stateful
containers:
db: { image: "postgres:16", ports: { db: 5432 } }
volumes:
data:
persistentTemplate:
size: "20Gi"
services:
headless:
type: Headless
ports:
db: 5432

schedule

schedule は form: scheduled のワークロードの cron スケジュールであり、繰り返しの form に繰り返し周期を与える付随フィールドです。1 つの正規形式の単一文字列です。

  • 標準的な 5 フィールドの crontab 式 — 分、時、日、月、曜日(例:毎日深夜 0 時なら 0 0 * * *、15 分ごとなら */15 * * * *)、または
  • マクロ @hourly、@daily、@weekly、@monthly、@yearly のいずれか。

schedule は form: scheduled のとき 必須 であり、そのときにのみ意味を持ちます。スケジュールのない form: scheduled ワークロード、5 フィールド式でも既知のマクロでもないスケジュール(秒を先頭に付けた 6 フィールド式、未知の @ トークン、不正な文字を含むフィールド)、または他の form に設定された schedule は、修正方法を示すビルド時の停止になります。helm provider は値をそのまま、出力する CronJob の spec.schedule に渡します。

apiVersion: aggrega.ai/v1beta1
kind: Workload
form: scheduled
schedule: "0 2 * * *" # daily at 02:00
containers:
report:
image: "reporter:1.0"
command: ["/report"]

suspend

suspend は、form: scheduled のワークロードの定期スケジュールを保留します。ブール値で、デフォルトは false です。suspend: true の場合も、スケジュールされたリソースは schedule を含めたままレンダリングされますが、再開されるまでそのスケジュールから実行が開始されることはなく、リソースから手動で実行を開始することは引き続き可能です。これは、誰かが要求したときにだけ実行すべきタスクのための形です。

helm プロバイダは、このフィールドを CronJob の spec.suspend: true として出力します。Kubernetes では、kubectl create job <name> --from=cronjob/<cronjob> で保留中の CronJob から実行を開始でき、spec.suspend が再び false になるとスケジュールが再開されます。suspend: false は suspend を省略した場合とまったく同じにレンダリングされるため、このフィールドは設定されるまで出力を一切変えません。compose プロバイダにはスケジュール実行の形がなく、保留の有無にかかわらず、あらゆる form: scheduled のワークロードでビルドを停止します。

他の form に suspend: true を指定すると、修正方法を示してビルド時に停止します。他の form には、保留の対象となるスケジュールがありません。

apiVersion: aggrega.ai/v1beta1
kind: Workload
form: scheduled
schedule: "0 2 * * *" # documents when it would run; nothing starts it while suspended
suspend: true
containers:
report:
image: "reporter:1.0"
command: ["/report"]

replicas

ワークロードのレプリカ数を表す単一の整数です。省略時は 1 になります。Ops が宣言したサイジングからレプリカ数を決めるには、テンプレート式を使います。

replicas: {{ optional .infra `replicas` 1 }}

containers と initContainers

containers はコンテナ名をキーとする順序付きマップです。コンテナ 0(最初のマップキー)は、Kubernetes 出力における pod spec の順序と、デフォルトコンテナのセマンティクスに影響します。initContainers は init コンテナのエントリの順序付きリストで、各エントリは name、image、およびメインコンテナと同じ変数/シークレット/ボリュームマウントの記述形を持ちます。

initContainers のエントリでは name は省略可能です。省略したエントリは init-<index> と命名され、index は 0 から数えたリスト内でのエントリの位置です。名前はレンダリング出力やそのコンテナを指す診断でコンテナを識別するため、参照する価値のあるエントリには明示的に名前を付ける価値があります。

作成者の記述順の保持は Workload モデルの重要な契約です。コンパイラは containers、volumes、services、コンテナの ports、コンテナの variables、コンテナの attachments を、どのビルドでも、それぞれ Recipe の作成者が宣言した順序で出力します。Recipe の作成者はこの順序付きの形に依存できます。実行時に起こることが順序に依存する場合(サイドカーの起動、環境変数での $(VAR) の連鎖、先に宣言したボリュームを参照する volumeMounts)、それぞれのコレクション内では記述順がそのまま実行時の順序です。コンテナの環境はそのうち 2 つを組み合わせ、2 つにまたがって、合成を行う provider はアタッチメント読み取りのエントリ(as: env で届けられる attachments)を先に、通常の variables をその後に、それぞれ記述順で書き込みます。そのため Kubernetes ターゲットでは、変数は $(NAME) として、そのコンテナのアタッチメント読み取り変数と、自身より前に宣言された変数を参照できます(helm provider の環境の順序を参照)。1 つの名前を variables エントリと as: env で届けられる attachments エントリの両方に与えたコンテナは、プロセスがどちらの値を見るかがその順序だけで決まってしまうため、ビルドを停止します(A container gives one environment variable two values(コンテナが 1 つの環境変数に 2 つの値を与えている)を参照)。

コンテナフィールドの記述は次の慣例に従います。

  • image は通常、.values.image(Developer が選択したイメージ)を参照するテンプレート式で、環境ごとのレジストリ接頭辞のために任意で .infra.* による上書きを伴います。
  • variables は環境変数のための単純な文字列 → 文字列マップです。このマップは Go テンプレート式を通じて 2 つの異なるデータソースを組み合わせます。developer-pillar リテラル(テンプレート式が .values / .infra / .locals を読むエントリ。Component の pillar に由来するペイロード)と、cross-component-pipe データ(テンプレート式が .context.inject.env.<KEY> を読むエントリ。別の component の provides: に由来し、トポロジーパイプを通じてルーティングされるペイロード)です。2 つのソースは同じ variables マップに流れ込み、作成者は値が component ローカルか component 間で導出されるかに応じてエントリごとにどちらかを選びます。よくあるパターン:LOG_LEVEL: "{{ .values.log_level }}" は developer-pillar(component ローカル)、DB_HOST: "{{ .context.inject.env.DB_HOST }}" は cross-component-pipe(値はターゲット component の provides.host に由来し、呼び出し側の uses[].inject.env.DB_HOST 宣言を通じてルーティングされます)。どちらの形も、レンダリングされた Deployment 上の単一の Kubernetes env: リストにコンパイルされます。二重ソースのセマンティクスは記述時にのみ存在します。
  • attachments は、Component の featuresSchema で宣言されたスロット、または接続を指定することでその接続のソケットが宣言するスロットを参照します(後述の統合のセクションを参照)。
  • ports は名前付きポートのマップ(web: 8080、admin: 9901)です。ポート名はコンテナスコープのポート名に一致し、services.<service>.ports.<portname> から参照されます。ターゲットのデフォルト以外のトランスポートを持つポートは、代わりに展開形で記述します。後述のポートのトランスポートプロトコルを参照してください。
  • volumeMounts は、Workload の volumes: セクションの別の場所で宣言されたボリュームを名前で参照します。
  • resources はコンテナの requests と limits、つまり cpu と memory の量、および任意で GPU やその他のデバイス用の拡張リソースキーを宣言します(後述の GPU とデバイスのワークロードを参照)。
  • health はインテントの形(http: /path、tcp: <port>、exec: [cmd, ...])を使います。後述のヘルスプローブのセクションを参照してください。

volumes

各ボリュームはちょうど 1 つの型を持ちます: ephemeral、configmap、secret、persistent、persistentTemplate のいずれかです。1 つのボリューム宣言の中でこれらの型は互いに排他的であり、型ごとにそれぞれの必須フィールドがあります:

volumes:
app-config:
configmap:
source: "{{ .locals.app_cm }}"
data:
persistent:
size: "10Gi"
class: "gp3"
cache:
ephemeral:
sizeLimit: "1Gi"

persistentTemplate は StatefulSet 形状への変換ではレプリカごとの PVC を生成します。compose への変換では単一の共有名前付きボリュームに縮退し、ビルドとともに警告が報告されます。生成されたファイル自体には縮退についての注記は含まれず、警告がない場合とバイト単位で同一です。

プロバイダーごとの変換。 各プロバイダーは 5 つのボリュームバリアントを、それぞれのネイティブな形状に変換します:

バリアントHelm / helm-chart (K8s)Compose失われるものについての注記
ephemeralemptyDir: { sizeLimit }マウントパスを指定するサービスレベルの tmpfs: エントリ(メモリ上)Compose の tmpfs は RAM をバックエンドとしますが、helm の emptyDir はデフォルトでノードのディスクをバックエンドとします。基盤となるストレージ媒体の意味が異なります。sizeLimit は compose の出力のどこにも反映されず、出力されるエントリはマウントパスのみです。sizeLimit を記述すると、それを名指しする unsupported-field 警告が発生し、生成ファイルに書き込まれるのではなくビルドとともに報告されます。
configmapConfigMap ボリューム参照(Recipe の artifacts: または Feature が出力する ConfigMap リソースを利用します)configmap を指定するサービスレベルの configs: 参照で、ボリュームマウントのパスにマウントされます。対応するトップレベルの configs: エントリは Recipe の artifacts: から得られますどちらのターゲットも configmap を名前で参照し、その内容は読まないため、記述の形状は対称です。compose で失われるのは K8s ConfigMap のロールアウト時更新のセマンティクスです。compose の config はビルドが出力した内容に固定されます。どのトップレベルエントリでも解決できない参照は、実行時にぶら下がるマウントを出力する代わりにビルドを停止させます。
secretSecret ボリューム参照(認証情報アタッチメントが指定する Secret を利用します。その FeatureRecipe が出力するもの、または既存のもの)env 形状のシークレットには env_file:、パス形状のシークレットにはバインドマウントされたシークレットファイルCompose には Kubernetes Secret のセマンティクスがファーストクラスとして存在しません。パス形状のシークレットは意図的に configmap バリアントの configs: 経路をとりません。インラインの config エントリはシークレットの値を出力される compose ファイルに平文で書き込んでしまいますが、コンパイラはシークレットを平文に解決することはありません。バインドソースは、オペレーターが compose ホスト上でアクセス可能にするパスであり、vault-fetch CRD のライフサイクルの外にあります。
persistentPVC リソース + volume.persistentVolumeClaim名前付きボリュームCompose の名前付きボリュームはフラットなホスト側の抽象です。helm の PVC はストレージクラス、アクセスモード、容量の宣言をサポートしますが、compose はそれらを無視します。
persistentTemplateStatefulSet.volumeClaimTemplates(レプリカごとの PVC。form: stateful に付随するもの)名前付きボリューム(縮退。レプリカ間で単一の共有ボリュームとなり、警告が報告されます)Compose はレプリカごとのテンプレートを表現できません。persistentTemplate が compose に変換されると単一の名前付きボリュームが出力され、忠実度の低下は生成ファイルに書き込まれるのではなく、ビルドとともに警告として報告されます。レプリカごとのボリューム分離に依存する Workloads は、compose のみのバウンダリをターゲットにすべきではありません。

コントローラーの形状は、ボリュームではなく workload の form によって選ばれます。StatefulSet は form: stateful のときに出力されます。persistentTemplate ボリュームはその form に付随するものであり、StatefulSet が提供するレプリカごとのアイデンティティをすでに持つ workload に、レプリカごとのストレージを宣言します。他の form(またはデフォルトの stateless)で persistentTemplate ボリュームを宣言すると、修正方法 declare form: stateful を示すビルド時エラーになります。逆は許可されており、form: stateful の workload は persistentTemplate ボリュームを宣言する必要はありません。StatefulSet のセマンティクスを求める作成者は、form: stateful を直接設定します。

helm プロバイダー上の form: stateful の workload には、ヘッドレスの管理用 Service が必要です。同じ Workload 内で type: Headless のサービスをちょうど 1 つ宣言してください。プロバイダーは StatefulSet の serviceName をそのヘッドレス Service に結び付けます(StatefulSet が必要とする、Pod ごとの安定したネットワークアイデンティティを提供します)。ヘッドレスサービスが宣言されていない場合(StatefulSet が指定すべき管理用 Service がない)や、複数宣言されて管理用 Service が曖昧になる場合、ビルドは停止します。StatefulSet の workload は、1 つのヘッドレス管理用サービスとは別に、ヘッドレスでないサービス(たとえばクライアントアクセス用の ClusterIP サービス)を追加で宣言することもできます。

リソース量

次の Workload の値は量(quantity)、すなわち Kubernetes がリソースに使う表記で書かれた数量です: コンテナ(または init コンテナ)の resources.requests と resources.limits における cpu、memory、およびすべての拡張リソースキーの値、そしてボリュームの ephemeral.sizeLimit、persistent.size、persistentTemplate.size です。Workload スキーマはそれぞれを文字列として型付けし、その形式を制約しません。ターゲット向けに Workload を合成するプロバイダーが、出力するすべての量を検査します。検査対象は Recipe のテンプレートが評価した後の Workload なので、infra、Release のパラメーター、その他のテンプレート入力から届いた値は、レンダリングされた文字列に基づいて判定されます。

量とは、前後に何も付かない次のものです:

  • 省略可能な符号 + または -。
  • 少なくとも 1 桁の数字を持つ数値 — 2、0.5、.5、1. など。
  • 指数 — e または E、省略可能な符号、続いて数字(1e3 や 5E-2 など) — または単位サフィックスのうち最大 1 つ: 10 進サフィックス n、u、m、k、M、G、T、P、E(10⁻⁹ から 10¹⁸ まで、1000 倍刻み)、または 2 進サフィックス Ki、Mi、Gi、Ti、Pi、Ei(1024 から 1024⁶ まで)。

500m、0.5、2、128Mi、1.5Gi、1e3、5n、4u は量ですが、lots、1.5 cores、1 gigabyte、10 GB、1e1.5 は量ではありません。指数は整数です。数値の後に単独で置かれた E は 10¹⁸ を表す 10 進サフィックスです(12E)。後ろに数字が続く場合は指数の開始となります(1E3)。

これは Kubernetes 自身の量パーサーが受け付ける形式ですが、意図的な相違が 1 つあります。数値に数字を含まない文字列 — m、Ki、+、.、e5 — は拒否されますが、Kubernetes はそれをゼロとして読みます。このような文字列は、補間する値が空のときにテンプレートが残すものそのものです: cpu が空の "{{ .infra.cpu }}m" は m にレンダリングされます。これを拒否することで、空の入力は、何も報告されないサイズゼロのリクエストではなく、フィールドを名指しする停止になります。

各ターゲットが量をどう扱うか:

  • helm は、上記の形式に対してそれぞれを検査したうえで、すべての量をそのまま出力します。形式に合わない値は、ノード、Workload 内のフィールドのパス(containers.main.resources.requests.cpu、initContainers[0].resources.limits.memory、volumes.data.persistent.size)、および値を示すエラーでビルドを停止させます。Helm Provider → Workload (synthesized) mode を参照してください。
  • compose は、パースした値から cpu と memory を独自の単位に変換します: cpus は 10 進のコア数(500m → 0.5)に、memory は正確なバイト数(1.5Gi → 1610612736)になります。量でない値はビルドを停止させ、compose が正確に表現できない量 — 負の量、整数バイトにならないメモリ量(1500m)、コアの小数点以下 9 桁より細かい cpu 量 — も同様に停止させます。エラーはそのどちらに該当したかを示します。nvidia.com/gpu の数も同じように読まれてデバイス数になるため、整数個のデバイスにならない値も停止します。compose はそれ以外の拡張リソースやボリュームサイズを出力しないため、それらは検査しません: その他の拡張リソースキーと ephemeral.sizeLimit は警告付きで破棄され、persistent のサイズは出力に何も影響しません。Compose Provider → Container resources を参照してください。

この検査は形式のみを判定します。クラスターがその量をスケジュールできるか、その量がデバイスに適しているかは、検査の対象外です。

services

サービス公開の順序付きマップです。各サービスはそのタイプ(ClusterIP、Headless、NodePort、LoadBalancer、Loopback)、つまりポートの到達範囲と、名前付きポートのマップを宣言します。ポート名は、Workload 内の別の場所で宣言されたコンテナポート名と一致する必要があります。

services:
http:
type: ClusterIP
ports:
web: 8080 # must exist in containers.<name>.ports

1 つの Workload に複数のサービスを置き、内部トラフィックと外部トラフィックを別々に公開するのは一般的です(クラスタ内の利用者向けの内部 ClusterIP、外部トラフィック向けの LoadBalancer、Prometheus のスクレイピング向けの ClusterIP)。

サービスのポートの到達範囲。 type がそれを示し、各ターゲットはそれを独自の形でレンダリングします。

type到達範囲helmcompose
ClusterIPターゲット自身のネットワーク上にある、ワークロードのピアタイプ ClusterIP の Service何も公開しません。ピアは compose ネットワーク上でポートに到達します
Headless同上、ただしクラスタアドレスなしclusterIP: None を持つタイプ ClusterIP の Service何も公開しません
NodePortターゲット自身のネットワークの外部タイプ NodePort の Service各ポートをすべてのホストインターフェイスに <service port>:<container port> として公開します
LoadBalancerターゲット自身のネットワークの外部タイプ LoadBalancer の ServiceNodePort と同じ
Loopbackホスト自身のループバックアドレスのみサービス名を示してビルドを停止します各ポートを IPv4 ループバックアドレスに 127.0.0.1:<service port>:<container port> として公開します

サービスポートの番号と、それが指定するコンテナポートは 2 つの別々の番号です。Kubernetes の Service の port と targetPort と同じです。helm はエントリの番号を Service の port として書き込み、コンテナポートをその名前で対象にします。compose はエントリの番号をホスト上で公開し、コンテナポートの番号に対応付けます。2 つの番号が等しい場合、compose は両側にその番号を書き込みます。

Loopback は、同じマシン上のもの(ホスト上で動作するブラウザやエージェント)が到達し、それ以外は到達すべきでないポートのためのものです。compose では、バインドは IPv4 ループバックアドレスのみです。IPv6 ループバックアドレス ::1 はバインドされないため、::1 に解決される可能性のある名前ではなく 127.0.0.1 でポートを指定してください。宣言されたトランスポートは、公開される他のポートと同様にエントリに記述されます(例:127.0.0.1:5514:5514/udp)。

2 つのエントリが同じポートを指定する場合は、より広い到達範囲が優先されます。NodePort または LoadBalancer のエントリが公開するポートは、Loopback のエントリも同じポートを指定していても、どちらが先に宣言されたかにかかわらず、すべてのインターフェイスに公開されます。

helm では、Loopback のエントリは、実際とは異なるものとしてレンダリングされる代わりにビルドを停止させます。Kubernetes の Service には、ホストのループバックアドレスにバインドするタイプがありません(NodePort の Service がどのノードアドレスで待ち受けるかは、1 つの Service ではなくクラスタ全体の設定です)。そのため、ClusterIP の Service ではエントリが求める到達範囲が失われ、NodePort の Service ではクラスタが許可するすべてのノードアドレスにポートが公開されてしまいます。この停止はノードとサービスを示します。A service type the helm provider cannot render(helm provider がレンダリングできないサービスタイプ) を参照してください。

合成名の慣例。 helm provider が Workload のサービスを合成する際、各 Service の metadata.name は、ワークロード自身のコントローラーが持つ名前とサービスのオーサリングキーから決定論的に導出されます。コンポーネントの Workload では、その名前はノードのリリース名です:<release name>-<service-key>。リリース名は、コンポーネントのアイデンティティを Kubernetes の名前が許容する文字体系で書き直したものです(チャートがレンダリングに用いるのと同じ名前で、Recipe のテンプレートでは {{ .context.rendered_name }} として読み取れます)。そのため、アイデンティティにアンダースコアも大文字も含まれない場合は instance_id と一致します。ノード api-server 上で services.http を宣言する Workload は api-server-http という名前の Service を生成します。同じ Workload はノード billing 上では billing-http を、ノード my_api 上では my-zuapi-http を生成します。出力ファイル名も同じ慣例に従います:<release name>-<service-key>-service.yaml。このような Service のアドレスを公開する Recipe は、それを {{ .context.rendered_name }} から組み立て、{{ .context.instance_id }} からは組み立てません。両者が異なる場合、後者はどの Service も指さないためです。../templates/rendered-resource-names.md を参照してください。

Feature のアタッチメントの FeatureRecipe が合成する Workload は、リリース名ではなく、アタッチメント自身の合成されたアイデンティティにちなんで命名されます。これは、そのリソースが aggrega.ai/component-id ラベルに持つ値であり、ホストコンポーネントと features: の下に書かれたキーから合成され、先頭に cfr-- が付きます。そこで導出されるリリース名はホストのものになり、アタッチメントのリソースをホスト自身のリソースにちなんで命名してしまいます。そのため、ノード front-door 上のアタッチメント stats について、Workload が services.scrape を宣言する FeatureRecipe は、Deployment cfr--front-door--stats と Service cfr--front-door--stats-scrape を生成します。この先頭のセグメントは決して instance_id と一致せず、FeatureRecipe のテンプレートコンテキストのどのキーもそれを持ちません。アタッチメントのテンプレートでは、{{ .context.rendered_name }} と {{ .context.instance_id }} はどちらもホスト(front-door)を指し、{{ .attachment_name }} はキーそのもの(stats)です。そのため {{ .context.rendered_name }}-scrape は、ホストが宣言している場合はホスト自身の scrape Service を指し、アタッチメントのものを指すことはありません。../templates/rendered-resource-names.md を参照してください。出力ファイルは、アタッチメントが出力するすべてのファイルが持つプレフィックス(ホストの名前とアタッチメントの名前で、それぞれの後に -- が続きます)の後ろに置かれるため、その Service は front-door--stats--cfr--front-door--stats-scrape-service.yaml に書き込まれます。

この慣例には 2 つの実際的な帰結があります。第一に、ノード間の衝突は構造上起こりえません。名前のプレフィックスによって boundary 内のすべてのノードにわたってサービスが区別されます。2 つの異なるアイデンティティは常に 2 つの異なるリリース名になり、アタッチメントのアイデンティティはホストとキーの両方を含み、コンポーネント名は cfr-- で始めることができないためです(そう始まる名前があるとビルドは停止します。Component identity cannot be stamped on what it emits(Component のアイデンティティを出力物に刻印できない) を参照)。そのため、それぞれ services.http を宣言する 2 つの Workload は、名前の重ならない別個の K8s Service リソースを生成します。唯一残る例外は、ターゲットにとって長すぎるアタッチメントのアイデンティティです。これは全体のダイジェストを用いて短縮され、短縮された 2 つのアイデンティティは原理的には一致しうるためです。レンダリング出力に付与される来歴ラベルを参照してください。第二に、Workload は 1 つのサービスキーを 2 回宣言できません。キーを 2 回指定する services: マップは Workload の YAML のパース時に拒否され、ビルドはそのキーと行を示して停止します。

残る衝突リスクは K8s の名前長の境界にあります。Kubernetes の Service 名の上限は 63 文字であり、合成される <release name>-<service-key> 形式は、両方のセグメントが長い場合にこの上限を超えることがあります。Aggrega コンパイラはこの上限を強制しません。ビルドは Service を出力し、Kubernetes が適用時にそれを拒否します。深くネストしたインスタンス ID(例:data-layer.regional.eu-west.primary)に長いサービスキーを組み合わせる場合は、合計の長さを 63 文字未満に保ってください。アタッチメントの Workload についても同様です。ターゲットにとって長すぎる合成アイデンティティは短縮されますが、その後ろに付加されるサービスキーは短縮されないため、長いキーを持つアタッチメントの Service は依然として 63 文字を超えることがあり、ビルドは停止しません。

Provider 固有の注記(compose)。 compose provider は、IR の uses エッジから depends_on を自動的に導出します。これらのエントリはゲートなしで出力されます。つまり、ターゲットが healthcheck を宣言しているかどうかに関係なく service_started のセマンティクスを持ちます。そのため、依存関係がすべて uses エッジに由来するサービスは短縮形のリスト(depends_on: [<target>])を出力します。エッジから導出されたエントリをターゲットのヘルスでゲートする機能は実装されていません。エントリが条件を持つ場合には長い形式が出力され、init コンテナの待機はこの形で表現されます。providers/compose.md を参照してください。

ポートのトランスポートプロトコル

コンテナポートは、同等な 2 つの形式のいずれかで記述します。数値のみの形式は短縮形で、トランスポートを宣言しないため、ターゲットが独自のデフォルトを適用します。デフォルトを持つすべてのターゲットで TCP です:

containers:
main:
image: "{{ .values.image }}"
ports:
web: 8080

展開形は番号とトランスポートを併せて持ち、ポートがそのデフォルト以外のものを運ぶ場合に必要となる形式です:

containers:
main:
image: "{{ .values.image }}"
ports:
web: 8080 # short form — no transport declared
dns:
port: 53
protocol: UDP # TCP | UDP | SCTP
sigtran:
port: 2905
protocol: SCTP

1 つの ports マップの中で 2 つの形式は自由に混在でき、宣言するトランスポートのないポートは短縮形のままにします。

トランスポートはコンテナポート上で一度だけ宣言します。 services.<service>.ports のエントリはコンテナポートを名前で指定し、そのポートのトランスポートを引き継ぐため、サービスの公開がコンテナの開いたポートと食い違うことはありません。サービスポートには protocol キーがなく、記述すると拒否されます。

このフィールドが存在する理由。 デプロイターゲットは、指定のないトランスポートをストリーミング型として扱います。データグラムのポートを必要とするコンポーネント(リアルタイムメディア、電話、名前解決、プライベートネットワーク、ゲームサーバーなど)は、このフィールドがなければ番号しか宣言できず、トラフィックはデータグラムなのに開かれたポートはそうではないため、すべてのゲートを通過してデプロイされながら、どのクライアントも接続できない状態になります。トランスポートを宣言することで、これを表現できるようになります。

コンパイラは値を解釈しません。 ポートの名前からトランスポートを読み取ることはなく、宣言されたトランスポートをポートの背後のプロセスが実際に話すものと照合することもありません。この値は宣言したデータであり、ターゲットのエンジンがそれを出力します。protocol キーを持たない dns という名前のポートは TCP ポートであり、protocol: UDP を宣言した web という名前のポートは UDP ポートです。

ターゲットごとの動作。

ターゲットトランスポートが宣言されていないポート宣言されたトランスポート
helmcontainerPort と Service のポートは protocol キーを持ちませんコンテナポートと、それを指定するすべての Service ポートに protocol: としてそのまま出力されます
compose<host>:<container> として変更なしに公開されます<host>:<container>/tcp または /udp として公開されます。SCTP には compose での表記がないため、異なるトランスポートを運ぶポートを公開する代わりにビルドを停止します

どのサービスも公開しないコンテナポートは、compose ファイルのどこにも現れません。これはコンテナポートに対する compose の従来の動作です。そのため、そうしたポートに宣言されたトランスポートは記述される先がなく、停止も起こりません。

ヘルスプローブ — 意図の形

各コンテナは、自身の health: キー(containers.<name>.health)の下に、抽象的な意図の形でプローブを宣言します。Workload にトップレベルの health はありません。各プロバイダは、合成時にその意図をネイティブのプローブの形に変換します。

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

3 つの意図の形式(http:、tcp:、exec:)は、1 つのプローブ宣言の中で相互に排他的です。明示的なポートを持たない http: のポート解決では、コンテナが containers.<name>.ports の下で宣言するポートの名前のうち、アルファベット順で最初のものを使います。これは両方のターゲットで同じ規則なので、どちらがレンダリングしてもプローブは同じポートを読みます。名前付きポートを宣言しないコンテナは HTTP プローブを持てません。その場合、問題のプローブを示す変換エラーでビルドが停止します。

プロバイダごとの変換。 各プロバイダは、合成時に抽象的なプローブの意図をネイティブの形に変換します。

意図Helm (K8s)Compose失われるものについての注記
http: /pathhttpGet.path: /path, httpGet.port: <alphabetically-first port name>CMD-SHELL "curl -f http://localhost:<port>/path"Compose にはネイティブの HTTP プローブの形がありません。CMD-SHELL ラッパーは、コンテナイメージに curl が存在することに依存します。
tcp: <port>tcpSocket.port: <port>CMD-SHELL "nc -z localhost <port>"Compose にはネイティブの TCP プローブの形がありません。CMD-SHELL ラッパーは、コンテナイメージに nc が存在することに依存します。
exec: [cmd, ...]exec.command: [cmd, ...]CMD [cmd, ...]1 対 1 のマッピングです。両方のプロバイダがコマンドリストをそのまま渡します。

Compose の CMD-SHELL ラッパーは、シェルで評価可能な述語によって HTTP と TCP のプローブを近似します。compose に欠けているのはネイティブのプローブの形であり、タイミングのフィールドではありません。記述された periodSeconds、timeoutSeconds、failureThreshold、initialDelaySeconds は、healthcheck 上の interval、timeout、retries、start_period に引き継がれます。フィールドごとのマッピングは providers/compose.md の「Probes」にあります。ネイティブの exec: の形はラッパーをまったく必要とせず、両方のターゲットで 1 対 1 に変換されます。

ラップされたプローブは暗黙的に変換されます。出力される docker-compose.yaml にはそれを示すものは何もなく、ラップを報告する診断もありません。この経路でビルドが報告するのは、出力にまったく到達しないプローブスロットです。compose のサービスは healthcheck を 1 つしか持たないため、Workload が ready:、live:、startup: のうち 2 つ以上を宣言している場合、優先されるスロットだけが変換され(live、ready、startup の順に優先)、unsupported-field 警告が変換されたスロットと破棄されたスロットを示します。

Provider 固有の注記(compose)。 compose を対象とする Workload に health: ブロックを記述しても、depends_on の順序付けはヘルスによってゲートされません。uses: エッジから導出される compose プロバイダーの depends_on エントリは、対象の Workload がヘルスプローブを宣言しているかどうかにかかわらず、常に service_started のセマンティクスを使用します。これらのエントリを対象のヘルスでゲートすることは実装されていません。そのような条件を保持する長い形式自体は init コンテナの待機のために出力されるため、欠けているのはそれを表現する形ではなく、エッジをヘルスでゲートするという選択です。推論規則の全体については providers/compose.md を参照してください。

K8s 形式のパススルーフィールド — scheduling、serviceAccount、podSecurityContext

Workload スキーマは、オプションのトップレベルフィールドを 3 つ受け付けます。これらは主に、Aggrega の構造的な形を保ったまま Kubernetes ネイティブのプリミティブを helm プロバイダーへ通すために存在します。compose プロバイダーは、Compose に対応するものがあるサブセットを変換し、残りは警告を出力して無視します。Aggrega は外側の形を検証しますが、内側の内容は検査しません(下記の検証の範囲を参照)。K8s ネイティブの内側の値は、helm がレンダリングする Pod 仕様へそのまま渡されます。

scheduling

scheduling は、4 つの K8s ネイティブのスケジューリングプリミティブ — nodeSelector、affinity、tolerations、topologySpreadConstraints — を、目的ごとにキーを付けた 1 つのブロックにまとめます。各サブフィールドは、対応する Kubernetes Pod 仕様フィールドとまったく同じ形をしています。

apiVersion: aggrega.ai/v1beta1
kind: Workload
scheduling:
nodeSelector:
disktype: ssd
region: us-east-1
tolerations:
- key: dedicated
operator: Equal
value: gpu-workloads
effect: NoSchedule
affinity:
podAntiAffinity:
preferredDuringSchedulingIgnoredDuringExecution:
- weight: 100
podAffinityTerm:
labelSelector:
matchLabels: { app: "{{ .context.instance_id }}" }
topologyKey: kubernetes.io/hostname
topologySpreadConstraints:
- maxSkew: 1
topologyKey: topology.kubernetes.io/zone
whenUnsatisfiable: ScheduleAnyway
containers:
app: { image: "..." }

Provider ごとの変換。 helm プロバイダは各サブフィールドをそのままレンダリングされた pod spec に渡します。compose プロバイダは 4 つのいずれも変換せず、scheduling ブロック全体を省略して、それを示す警告を出力します。

serviceAccount

serviceAccount は、ワークロードが実行される ServiceAccount の名前を保持するプレーンな文字列です。

apiVersion: aggrega.ai/v1beta1
kind: Workload
serviceAccount: "{{ .context.rendered_name }}-runner"
containers:
app: { image: "..." }

名前は {{ .context.rendered_name }} から組み立てられます。これは helm プロバイダーがワークロード自身のリソースの名前付けに使うリリース名であるため、コンポーネントの名前が何であってもクラスターが受け付ける名前になります。このフィールドは既存の ServiceAccount を参照するもので、新たに作成はしません。付随する RBAC リソース(ServiceAccount オブジェクト自体と、Role / RoleBinding / ClusterRole / ClusterRoleBinding)は、次の 2 つの経路のいずれかで提供してください。

  • Recipe の artifacts: — RBAC がこの Recipe に固有である場合(特定のジョブのために特定の Role が必要であることを Recipe が把握している場合)。
  • Resource Generation を伴う Features — RBAC が横断的である場合(Workload-Identity の FeatureRecipe が、特定のラベルを持つすべてのコンポーネントに IAM と結び付いた ServiceAccount を付与する場合など)。

指定した ServiceAccount が存在するよう手配せずに serviceAccount: を設定すると、ビルド時のエラーではなく、適用時に K8s のランタイムエラーになります。ワークロードのスキーマ検証は ServiceAccount の存在を照合しません(AOT 純粋性の不変条件により、コンパイル時にクラスターの状態へはアクセスしません)。

compose プロバイダーは serviceAccount: を警告とともに無視します。Compose には、これに相当するアイデンティティのバインド概念がありません。

podSecurityContext

podSecurityContext は、Pod 内のすべてのコンテナに適用される Pod レベルのセキュリティプリミティブ — UID、GID、fsGroup、supplementalGroups — を保持します。

apiVersion: aggrega.ai/v1beta1
kind: Workload
podSecurityContext:
runAsUser: 1000
runAsGroup: 3000
fsGroup: 2000
supplementalGroups: [4000, 5000]
containers:
app: { image: "..." }

フィールドのセマンティクス。 4 つのフィールドはすべて整数です(文字列ではなく数値の UID/GID)。runAsUser と runAsGroup はコンテナプロセスの実効 UID/GID を設定します。fsGroup は Pod にマウントされるボリュームのグループ所有権を設定します。supplementalGroups は各コンテナのプロセスグループに GID を追加します。

Provider ごとの変換。 helm プロバイダはこのブロックをそのままレンダリングされた pod spec に渡します。compose プロバイダには fsGroup や supplementalGroups に相当するものがなく、それぞれを警告とともに省略します。runAsUser/runAsGroup は、Workload が生成するすべてのサービス(サイドカーと init コンテナを含む)で Compose の user: 1000:3000 形式に変換され、隣に runAsUser のない runAsGroup は警告とともに省略されます。各コンテナと init コンテナも、それぞれ独自の securityContext(runAsUser、runAsGroup、runAsNonRoot、readOnlyRootFilesystem、allowPrivilegeEscalation、および capabilities.add / capabilities.drop)を持ちます。helm プロバイダはこれをコンテナ上に出力します。compose プロバイダは readOnlyRootFilesystem を read_only として、capabilities.add / capabilities.drop を cap_add / cap_drop として、runAsUser / runAsGroup をコンテナ自身の user として出力し、これが pod のものに取って代わります。runAsNonRoot、allowPrivilegeEscalation、および runAsUser なしで書かれた runAsGroup は、それぞれ警告とともに省略され、コンテナ自身の runAsUser によって pod の runAsGroup が外れる場合にも警告が出ます。フィールドごとの対応は providers/compose.md に記載されています。

GPU およびデバイスを使うワークロード

GPU やその他のベンダー提供デバイスなど、特殊なハードウェアを必要とするワークロードは、2 つの独立した関心事を表現します。デバイス対応ノードが公開する Pod レベルのランタイム(runtimeClassName)と、ワークロードが要求するコンテナごとのデバイス数量(コンテナの resources の下にある拡張リソースキー)です。典型的な GPU ワークロードは両方を併せて宣言しますが、それぞれは独立しており、どちらか一方だけを記述することもできます。

どちらのフィールドもコンピュート、つまり Pod とデバイス上で動作するコンテナを記述するため、コンテナを実行するワークロードに属します。外部エンドポイントのみを持ち、自身のコンテナを宣言しないワークロードには、これらを付与する Pod もコンテナもありません。このようなエンドポイントのみのワークロードに runtimeClassName を設定するとビルドが停止し、runtimeClassName と、その Workload で宣言した Recipe の名前が示されます。また、コンテナがないため、デバイスのリソース要求を置く場所もありません。

runtimeClassName

runtimeClassName は、Pod が実行される RuntimeClass を指定する単一の文字列です。これはデバイス対応ノードが公開するコンテナランタイムで、たとえば nvidia という名前の GPU ランタイムです。これは Pod レベルのセレクターであり、ワークロード内のすべてのコンテナに適用されます。コンパイラはこの名前を決定的なポインタとしてそのまま渡し、クラスタはスケジュール時に、管理者が設定した RuntimeClass へと解決します。Aggrega は一致する RuntimeClass が存在するかを検査しません(コンパイル時にクラスタの状態へアクセスできないため)。そのため、設定済みの RuntimeClass が存在しない名前は、ビルド時エラーではなく、適用時のスケジューリングエラーとして現れます。

拡張リソースキー

コンテナの resources.requests と resources.limits には、通常の cpu と memory の数量に加えて、拡張リソースキーを記述できます。これは、nvidia.com/gpu や amd.com/gpu のような完全修飾の <domain>/<name> 形式の名前をキーとする、ベンダーまたはドメインにスコープされたデバイス数量です。ドメイン部分には少なくとも 1 つのドットが含まれ、このドットによって拡張キー(nvidia.com/gpu)と素の cpu および memory の数量が区別されます。各値は文字列の数量("1"、"2")で、コンパイラはそのまま渡し、helm プロバイダーは出力前にその形式を検査します(リソース数量を参照)。デバイスはスケジュール時にクラスタのデバイスプラグインが解決し、割り当てます。

実例 — GPU 推論ワークロード

apiVersion: aggrega.ai/v1beta1
kind: Workload
runtimeClassName: nvidia
containers:
inference:
image: "{{ .values.image }}"
resources:
requests:
cpu: "2"
memory: "8Gi"
nvidia.com/gpu: "1"
limits:
nvidia.com/gpu: "1"

このワークロードは、Pod に nvidia ランタイムを選択し、inference コンテナに GPU を 1 つ要求します。GPU の数量は requests と limits の両方に記述されます。デバイスはオーバーサブスクライブできないため、要求と上限を同じ値に設定します。

プロバイダーによる変換。 これらは Kubernetes ネイティブの概念です。helm プロバイダーは、runtimeClassName をレンダリングされた Pod spec に出力し、各拡張リソースキーをコンテナの resources.requests / resources.limits の下にそのまま出力するため、これらは Kubernetes の出力を通じてクラスタに届きます。compose プロバイダーは、nvidia.com/gpu の数を、コンテナのサービス上でその数の NVIDIA GPU として予約します(Compose Provider → コンテナリソースを参照)。単一ホストにはランタイムクラスの概念がなく、その他の拡張リソースキーに相当するものもないため、runtimeClassName やその他のキーを宣言したワークロードは、compose ターゲットではそれらを除いてレンダリングされます。

ノードのネットワーク上での実行

デフォルトでは、workload は独自のネットワーク名前空間で実行されます。そのコンテナは自身のインターフェースのみを参照し、トラフィックはターゲットのアドレス変換を経由して届きます。hostNetwork: true はもう一方の構成を要求します。workload は ノード自身のネットワーク名前空間 で実行されるため、 ノードのインターフェースを参照でき、コンテナが開くポートは間に変換を挟まずにノード自身の アドレスで到達可能になります。

これは、ある種類のソフトウェア全体が必要とするものです。リアルタイムメディア、電話、仮想プライベートネットワーク などのトラフィックはペアのアドレスをペイロード内に含むため、転送中に書き換えられたアドレスは ペアが到達できない場所を示した状態で届きます。ノードのアドレス上で実行することで、 両者の整合性が保たれます。

apiVersion: aggrega.ai/v1beta1
kind: Workload
hostNetwork: true
containers:
media:
image: "{{ .values.image }}"
ports:
rtp:
port: 7881
protocol: UDP

宣言するもの、宣言しないもの

hostNetwork が選択するのは ネットワーク名前空間 であり、それがすべてです。

  • ポートは宣言しません。 workload が開くポートは、これを指定しない場合とまったく同じく、引き続き containers.<name>.ports の下で宣言され、意味も変わりません。 hostNetwork を宣言しても、ポートが追加されることはなく、ポートを宣言する必要がなくなることもありません。
  • ポートの 数 も宣言しません。 多数の連続したポートを必要とするアプリケーション(たとえば、マシンのプロセッサ数に応じて範囲を決めるメディア サーバー)は、起動時に読み込む他の設定と同じように、運用者が指定する値をもとに、その範囲を自身の 設定本体で構成します。これは workload の設定ではなくアプリケーションの設定であり、workload の コントラクトに置くものではありません。
  • 何も推論されません。 コンパイラはこの値から意味を読み取らず、また他のものからこの値を導出することもありません。 ポートの名前からも、component の種類やラベルからも、宣言されたポートの数からも導出しません。workload がノードのネットワーク上で実行されるのは、そう指定した場合に限られます。

hostNetwork はコンピュートを記述するため、コンテナを実行する workload に属します。外部エンドポイントのみを持つ workload はコンテナを宣言しないため、選択すべきネットワーク名前空間がありません。 エンドポイントのみの workload で hostNetwork を宣言するとビルドが停止し、hostNetwork と、 その Workload を宣言した Recipe が示されます。

Provider での変換

helm provider は、レンダリングされた pod spec に hostNetwork: true を出力します。これは Kubernetes で同じ選択を表す方法です。この宣言が及ぶのは pod spec のみで、それ以外には影響しません。出力される Service は、指定の有無にかかわらず同一です。

compose provider は、workload 自身のサービスに network_mode: host を出力します。compose がネットワークを モデル化する方法から、1 つの帰結が生じます。このモードのサービスはバウンダリネットワークに接続されません。 compose では、ネットワークへの接続とホストの名前空間の採用は、併用ではなく択一として扱われるためです。 そのため、ピアはサービス名ではなくホスト自身のアドレスでこのサービスに到達します。これはどのターゲットでもホストネットワークが意味することです。また、 バウンダリ上の他のサービスには影響しません。

このターゲットでは、2 つの形態がこれと組み合わされます。サイドカーコンテナは、何も宣言せずにメインサービスに続いて ホストのネットワークに入ります。メインサービスを名前で指定してその名前空間を引き継ぐためです。init コンテナはそうなりません。init コンテナはメインサービスが待機する サービスになるため、待機が循環してしまう名前空間を採用するのではなく、独立してバウンダリネットワークに参加します。そのため、hostNetwork と initContainers の両方を宣言した workload では、 自身のサービスはノードのネットワーク上で実行され、init サービスはバウンダリネットワークに留まります。これは pod の形態が提供する単一の共有名前空間よりも限定的な構成であり、compose provider は実行時に発覚させるのではなく unsupported-field 警告でこれを示します。

hostNetwork を宣言しない workload は、出力にそのキーを持ちません。キーは false として出力されるのではなく、存在しません。

Component の featuresSchema とのアタッチメント統合

Workload の containers.<name>.attachments ブロックは、Component の featuresSchema で宣言された認証情報スロットを参照します。接続を指定するエントリの場合は、その接続のソケットが宣言するスロットを参照します(接続が運ぶ認証情報の配信を参照)。新しいスロットは宣言しません。featuresSchema の記述方法については ../entities/component.md を参照してください。from はスロットを指定するものであり、生成される Secret の名前ではありません。

containers.<name>.attachments のエントリは、Secret リソースへの参照としてレンダリングされます。Kubernetes の secretKeyRef(as: env の場合)または Secret を基にしたボリューム(as: file の場合)であり、いずれも Secret を 名前で 指します。シンセサイザーは、その名前とデータキーをスロットが公開する provides から解決します。エントリのレンダリングされた secretKeyRef.name はスロットの .features.<slot>.provides.name であり、データキーは .features.<slot>.provides.key です。Recipe の作成者が記述するのは from: <slot> と as: env のみです。シンセサイザーは解決済みの provides を読み取り、名前を再導出することはありません。これは、ソース Recipe が existingSecret のために使用するのと同じ .features.<slot>.provides.<key> の読み取りです。単一の認証情報スロットが、ソース Recipe のコンシューマーと合成された Workload のコンシューマーの両方に同じように供給されます(ソース/workload の対称性)。

この統合には 4 つの検証ルールが適用されます。

  • すべての attachments.<KEY>.from の値は、Component の featuresSchema、または接続を指定するエントリではその接続のソケットで宣言されたスロット名と一致する必要があります。不明なスロット名はロード時エラーになります。
  • as: の配信方式(env または file)は、Component が宣言したスロットの inject: 許可リストに含まれている必要があります。featuresSchema のエントリで inject: [env] を指定しているスロットに対して as: file を宣言する Workload は、ロード時エラーになります。
  • Component の featuresSchema で inject: [](ブラックボックス配信)とマークされたスロットは、Workload の attachments: ブロックにはまったく記述できません。これらのスロットは、Workload による公開ではなく、Recipe 内部の仕組み(たとえば Helm チャートの existingSecret パラメーター)によって配信されます。
  • 参照されるスロットは 参照可能 である必要があります。つまり、そのフィルが Secret リソース(その実現が出力するもの、またはすでに存在するもの)に対する provides ロケーター(name、key)を公開している必要があります。inject で配信される認証情報(inject パイプに値を書き込み、ロケーターを公開しないもの)で満たされたスロットには、指す対象がありません。Workload の attachments: エントリからこれを参照するとロード時エラーになります。inject で配信される認証情報は、attachments: エントリではなく、スロットの inject パイプ(.context.inject.env.<KEY> を読み取る variables エントリ)を通じてコンテナに届きます。

Provider に関する注記。 Helm は上記の secretKeyRef/Secret ボリュームの参照をレンダリングします。compose provider には Secret から環境変数を設定するネイティブのプリミティブがありません。compose を対象とする Workload の as: env アタッチメントエントリは、空の値を持つ環境エントリとしてレンダリングされ、そのエントリを示す警告が出されます(compose provider のページを参照)。ただし、参照可能性のルール(ケイパビリティに依存しない)は引き続き適用されます。

例:

# In the Component catalog entity
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's Workload
workload: |
containers:
main:
attachments:
DB_PASSWORD: # OK — db_password slot allows env inject
from: db_password
as: env
# ROOT_PASSWORD: ... # rejected at load time: blackbox slot

接続が運ぶ認証情報の配信

Component のソケットは、usesSchema.<socket>.featuresSchema で、そのソケットを通じて配線された各接続が満たすスロットを宣言できます。これにより、複数のターゲットに到達する component は、すべてに 1 つではなく、接続ごとに 1 つの認証情報を保持します。このようなアタッチメントは component 自身の .features には含まれず、その接続の下の .context.uses.<alias>.features.<slot> に置かれます。Workload のエントリは、スロットと並べて接続を指定することでこれを配信します。

  • コンテナの attachments エントリでは、from: <slot> と並べて connection: <alias> を指定します。
  • コンテナの envFrom エントリでは、secret: <slot> と並べて connection: <alias> を指定します。connection は secret と並べた場合にのみ受け付けられます。

どちらの形式も、すべてのコンテナとすべての init コンテナで受け付けられます。<alias> は、Aggregate または Release 上の component の uses ブロックで接続が記述されている名前(Recipe が .context.uses の下で接続を読み取るキー)であり、<slot> は、その接続が配線されているソケットが宣言するスロットです。

上記のいずれかのルールが Workload を読み取る前に、接続を指定する各エントリは、その接続がそのスロットで運ぶアタッチメントが component 上で持つ名前、すなわちエイリアス、ドット、スロット(gpt.credential)に書き換えられます。その後、すべてのルールは、Component 自身のスロットを指定するエントリに対するのとまったく同じように、書き換えられたエントリに対して実行されます。ソケットスロットの inject: 許可リストが as: を制御し、inject: [] を宣言するソケットスロットは参照できず、それを満たすアタッチメントは参照可能である必要があり、provider は Secret の名前とデータキーをそのアタッチメントの解決済み provides から解決します。したがって、各接続のエントリはその接続自身の認証情報を参照します。sensitive: true を宣言するソケットスロットは、Component のスロットの宣言とまったく同じようにエントリに対して読み取られます。provider が受け取るのは書き換えられたエントリであり、connection キーは provider には届きません。

次の 3 種類のエントリは拒否され、それぞれ指定した内容が示されます。

  • component が使用しない接続を指定するエントリ。拒否メッセージには、その接続、スロット、および component が使用する接続が示されます。
  • 接続のソケットが宣言しないスロットを指定するエントリ。拒否メッセージには、そのスロット、接続、ソケット、およびソケットが宣言するスロットが示されます。
  • 合成された名前(from: gpt.credential)を直接記述するエントリ。接続のスロットは接続を指定することで指定されるため、合成された名前がそこに到達する別の方法になることはありません。

スロットにアタッチメントを持たない接続では、エントリに参照する対象がなく、参照可能性のルールによって拒否されます。FeatureRecipe がレンダリングする Workload は、それが実装する Feature が宣言するスロットに限定され、それらはホスト component のどの接続にも到達しません。そのため、そこで接続を指定するエントリは、component が使用しない接続を指定するものとして拒否されます。

例:

# In the Component catalog entity
spec:
usesSchema:
models:
featuresSchema:
credential:
sensitive: true
inject: [env]
# In the Recipe's Workload — the component draws connections `gpt` and `nim`
# through the `models` socket, each carrying its own `credential`
workload: |
containers:
main:
attachments:
MODEL_KEY_GPT:
from: credential
connection: gpt
as: env
MODEL_KEY_NIM:
from: credential
connection: nim
as: env

helm では、MODEL_KEY_GPT は gpt 接続の認証情報が公開した Secret を指す secretKeyRef としてレンダリングされ、MODEL_KEY_NIM は nim 接続の認証情報が公開した Secret を指すものとしてレンダリングされます。compose では、接続を指定する as: env エントリは空の値で出力され、Component 自身のスロットを指定するエントリと同じ部分サポートの通知が出されます。

検証の対象範囲

すべての Workload は、レンダリングが実行される前の Recipe 読み込み時に検証されます。検証は 2 段階で行われます。

  • スキーマ検証。 Workload の値は、組み込みの aggrega.ai/v1beta1 Workload スキーマに対して単一化されます。エラーにはフィールドパスと違反した制約が含まれます(例: .containers.main.health.ready: multiple oneOf branches matched (branches [0, 1] of 3): expected exactly one)。スキーマ検証は、スキーマで宣言されたすべての型、列挙、範囲、選言を強制します。これには、閉じた集合であるコントローラの form(stateless、stateful、daemon、scheduled、task、reference のいずれか)、閉じた集合であるサービスの type(ClusterIP、Headless、NodePort、LoadBalancer、Loopback のいずれか)、整数のポート範囲(1..65535)、プローブ形状の選言(http、tcp、exec のうちちょうど 1 つ)、ボリュームバリアントの選言(ephemeral、configmap、secret、persistent、persistentTemplate のうちちょうど 1 つ)が含まれます。
  • 相互参照の検証。 Workload の attachment 参照は、Component の featuresSchema に対して(connection を指定するエントリの場合は、その connection の socket が宣言するスロットに対して)チェックされ(スロットの所属、as: 配信の許可リスト、ブラックボックスの除外)、さらに参照される各スロットの解決済み provides に対してチェックされます(参照可能性: fill が name/key を公開している必要があります)。これらはエンティティ間のチェックであり、スキーマのみの検証では実行できません。

どちらの段階も、CATALOG_ERROR で始まる同じ形式のメッセージを出力します。失敗するとレンダリング出力が生成される前にビルドが停止します。Recipe の作成者は、失敗した正確なフィールドとそれを拒否した制約を特定する的確なフィードバックを得られます。

K8s 形状のパススルーフィールド(scheduling.affinity、scheduling.tolerations、scheduling.topologySpreadConstraints、ConfigMap および Secret ボリューム内の items リスト、ライフサイクルの httpGet フック)は構造的にのみ検証されます。Aggrega のスキーマはそれらの存在と外側の形状を制約しますが、K8s API で定義されるこれらの値の内側の形状は provider の責任です(helm provider はそれらをそのまま K8s の Pod spec に渡し、compose provider は必要に応じて拒否または縮退させます)。不正な形状の affinity 値を使う Workload は Aggrega の検証を通過し、代わりに provider による合成の際にエラーが表面化します。

リソース量も同様に、スキーマにとっては文字列です。どちらの段階もその形式をチェックしません。チェックするのは合成を行う provider で、評価済みの Workload に対して行い、量の形式から外れた値があると停止します。リソース量を参照してください。

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

Workload はワークロードの形状のみを記述します。つまり、コンテナ、ボリューム、サービス、レプリカ、スケジューリング、セキュリティコンテキスト、サービスアカウントです。additionalResources フィールドはなく、ConfigMap / Secret / CRD をインラインで宣言することもできません。

Recipe の作成者は、Workload の外にある 2 つの経路を通じて補助リソースを出力します。

  • Recipe レベルの artifacts: — この Recipe に固有のリソース向けです(Recipe の Workload が参照する特定の ConfigMap や、Recipe が必要とする一度限りの CRD 登録など)。このフィールドは名前付きエントリのマップで、各エントリはインラインで記述するか、エントリごとの $import: で読み込みます。3 つの記述モードについては、../../architecture/16-recipe-input-composition.md の Artifacts Mechanism のセクションを参照してください。
  • リソース生成を伴う Features — Release のセレクターを介してアタッチされる横断的な関心事向けです(メトリクスを公開するすべてのコンポーネントにアタッチされる ServiceMonitor Feature や、すべての本番ワークロードにアタッチされる NetworkPolicy Feature など)。FeatureRecipe の記述方法については ../entities/featurerecipe.md を参照してください。

Workload はワークロードの形状に専念し、横断的なマニフェストや Recipe 固有の補助マニフェストには、それぞれ専用の記述場所があります。

一般的な Workload パターン

Workload のスキーマは幅広く、単一コンテナの HTTP サーバー、複数コンテナのサイドカーパターン、init コンテナのチェーン、バッチジョブ、永続ボリュームを持つステートフルサービスをカバーします。3 つのパターンは頻繁に現れるため、Recipe ごとに定型部分をゼロから記述するのは無駄です。以下のブロックは、Recipe の作成者が個々のコンポーネントに合わせて調整できる、コピー&ペースト用のテンプレートです。

複数の Recipes が共有するパターンは、WorkloadLibrary のエントリとして一度公開し、$import: <Library>#/workloads/<entry> でインポートできます。ここに示すテンプレートは、調整して使うための出発点であり、そのように公開するための出発点でもあります。

パターン 1 — メトリクスを公開するサーバー

1 つのポートでアプリケーショントラフィックを処理し、別のポートで Prometheus がスクレイプするメトリクスを公開する、典型的な Web アプリケーションです。Workload 内にアプリケーション用とメトリクス用の 2 つのサービスを置くことで、サービスメッシュのポリシーとロードバランサーの設定をきれいに分離できます。

apiVersion: aggrega.ai/v1beta1
kind: Workload
replicas: {{ optional .infra `replicas` 2 }}
containers:
app:
image: "{{ .values.image }}"
ports:
web: {{ optional .values `port` 8080 }}
metrics: {{ optional .values `metrics_port` 9090 }}
variables:
LOG_LEVEL: "{{ optional .values `log_level` "info" }}"
health:
ready:
http: /healthz
timeoutSeconds: 5
live:
http: /healthz
timeoutSeconds: 5
services:
http:
type: ClusterIP
ports:
web: {{ optional .values `port` 8080 }}
metrics:
type: ClusterIP
ports:
metrics: {{ optional .values `metrics_port` 9090 }}

メトリクスサービスには通常、Release 側での Feature のアタッチによって Prometheus のディスカバリー用のアノテーションが付与されます(例: feature.aggrega.ai/prometheus-scrape: "true")。Workload 自体には、プロバイダー固有のスクレイプ用アノテーションを含めません。

パターン 2 — バッチジョブ

トラフィックを無期限に処理するのではなく、完了まで実行されるワークロードです。このパターンは form: task を設定し、services: を完全に省略し(バッチジョブはポートを公開しません)、対象プロバイダーのタスク形状に依拠します(helm プロバイダーでは Kubernetes Job。compose プロバイダーにはタスク形状がなく、form: task でビルドを停止します)。Job の Pod はデフォルトの Always を使用できないため、helm プロバイダーは Job として有効な Pod の restartPolicy(コンテナが OnFailure を宣言しない限り Never)を固定します。

apiVersion: aggrega.ai/v1beta1
kind: Workload
form: task
containers:
worker:
image: "{{ .values.image }}"
command: ["{{ .values.entrypoint }}"]
args:
- "--config"
- "/etc/config/job.yaml"
variables:
JOB_ID: "{{ .context.instance_id }}-{{ .metadata.release_name }}"
volumeMounts:
- name: config
path: /etc/config
volumes:
config:
configmap:
source: "{{ .context.instance_id }}-config"

config ボリュームは、Recipe が artifacts: を介して Workload と並べて出力することが想定される ConfigMap を参照します(上記「Workload の外に置く補助リソース」を参照)。Workload 自体は消費側のみを宣言します。compose のように識別子にちなんでワークロードに名前を付けるプロバイダーでは、識別子がその名前になります。ワークロードのリソースにリリース名にちなんだ名前を付ける helm では、代わりに ConfigMap の名前を(ここでもアーティファクト内でも){{ .context.rendered_name }} から組み立ててください。そうすれば、コンポーネントの名前が何であってもクラスターが受け入れる名前になります。

パターン 3 — サイドカーのペア

メインコンテナがアプリケーションロジックを処理し、サイドカーが横断的な関心事(TLS 終端、ログ転送、サービスメッシュのプロキシ、AI ガードレール)を処理する、2 コンテナ構成の Pod です。containers: での記述順序は重要な意味を持ちます。helm プロバイダーはコンテナを宣言順に出力し、最初のキー(ここでは main)が kubectl logs や同様のツールのデフォルトコンテナの対象になります。

apiVersion: aggrega.ai/v1beta1
kind: Workload
replicas: {{ optional .infra `replicas` 2 }}
containers:
main:
image: "{{ .values.app_image }}"
ports:
app: {{ optional .values `app_port` 8080 }}
variables:
UPSTREAM_URL: "http://localhost:{{ optional .values `app_port` 8080 }}"
sidecar:
image: "{{ .values.sidecar_image }}"
ports:
proxy: {{ optional .values `proxy_port` 9000 }}
variables:
PROXY_TARGET: "http://localhost:{{ optional .values `app_port` 8080 }}"
services:
external:
type: ClusterIP
ports:
proxy: {{ optional .values `proxy_port` 9000 }}

Service は(メインコンテナではなく)サイドカーのポートを公開し、外部トラフィックをサイドカー経由で localhost を通じてメインコンテナへルーティングします。2 つのコンテナは Pod のネットワーク名前空間を共有するため、localhost:<port> で相手のコンテナに直接到達できます。認証情報の注入が必要なサイドカー(標準的な AI ガードレールのパターン)では、認証情報は通常、メインコンテナではなくサイドカーの attachments: ブロックに置かれ、認証情報のスコープをサイドカーのプロセス境界内に保ちます。

パターンの選択

3 つのパターンは、それぞれ異なる提供形態上の関心事に対応します。

  • メトリクスを公開するサーバー — クラスターが稼働を維持する長時間実行のサービス。トラフィック分離のために複数の Service で公開します。
  • バッチジョブ — 有限の実行。Service による公開はありません。入力には Recipe が出力する ConfigMap または外部の状態に依拠します。
  • サイドカーのペア — ネットワーク名前空間を共有する複数コンテナの Pod。サイドカーの Service が横断的な関心事を公開します。

4 つ目のパターンである 永続ボリュームを持つステートフルサーバー は、form: stateful を設定し、volumes.<name>.persistentTemplate でレプリカごとのストレージを宣言します。helm プロバイダーはステートフル形式に対して StatefulSet を出力します(providers/helm.md を参照)。このパターンの形状は「メトリクスを公開するサーバー」と同一で、form: stateful、追加の persistentTemplate ボリューム、および StatefulSet を統括するちょうど 1 つの type: Headless サービスが加わります(これがないとビルドは停止します)。このパターンが必要な作成者は、3 つの宣言すべてを加えてパターン 1 を調整します。

相互参照