WorkloadLibrary
WorkloadLibrary は、再利用可能な Workload テンプレートの断片を保持するカタログエンティティです。同じワークロードの形(メトリクスを公開するサーバー、バッチジョブ、サイドカーのペアなど)をデプロイする Recipes と FeatureRecipes は、その形をライブラリで一度宣言し、利用時に workload: { $import: ... } ディレクティブで参照します。このライブラリエンティティは Tier 3 であり、Recipe をまたいでワークロードを再利用する必要があるカタログ向けのオプトイン機能です。各 Recipes がそれぞれ固有のワークロードの形を持つカタログは、WorkloadLibrary を一切含めずに提供されます。
WorkloadLibrary の役割
プラットフォームアーキテクトは、カタログの Recipes と FeatureRecipes にわたって繰り返し現れる Workload の内容を一元化するために WorkloadLibraries を作成します。ライブラリはデプロイ可能なビルド指示ではなく、定義の名前空間です。Recipe と FeatureRecipe の作成者は $import: ディレクティブによってライブラリのエントリを参照します。このディレクティブは一度記述すれば、インポートが解決される場所であればどこでも利用されます。
「ライブラリ」と「利用側」の分離は意図的なものです。Recipes はビルド指示(source、valuesMapping、artifacts)を表現します。FeatureRecipes は振る舞いの付加を表現します。WorkloadLibraries は Workload の内容のみを表現します。これは、プロバイダがプロバイダネイティブなマニフェストへと合成する workload の形です。3 つの役割を区別しておくことで、各エンティティ種別はそれぞれのペースで進化できます。共有の Workload 内容を必要としない作成者が、このライブラリエンティティに触れることはありません。
エンティティエンベロープ
WorkloadLibrary エンティティは、標準のカタログエンベロープを持ちます。apiVersion: aggrega.ai/v1beta1 と kind: WorkloadLibrary がエンティティの種類を示し、metadata.name は PascalCase の識別子、metadata.version は厳密なセマンティックバージョニングに従います。どちらも必須です。metadata.description、metadata.labels、metadata.annotations は任意です。labels と annotations は作成者が宣言する不透明なメタデータであり、ライブラリを読み取るものが照合に使えるように保持されます。コンパイラはその値を解釈しません。ライブラリの内容は spec.workloads の下に置かれます。これは必須のマップで、少なくとも 1 つのエントリを宣言する必要があります。
エンベロープは 3 つのレベルすべてで閉じています。ドキュメントのルート、metadata、spec のそれぞれが、スキーマで宣言されていないキーを拒否します。
apiVersion: aggrega.ai/v1beta1kind: WorkloadLibrarymetadata: name: BaseWorkloads version: 1.0.0spec: workloads: SimpleServer: | apiVersion: aggrega.ai/v1beta1 kind: Workload replicas: {{ optional .infra `replicas` 2 }} containers: app: image: "{{ .values.image }}" ports: web: {{ optional .values `port` 8080 }} services: http: type: ClusterIP ports: web: {{ optional .values `port` 8080 }}Workload エントリのオーサリング
各エントリは、YAML 文字列として記述される Go テンプレートのフラグメントです。エントリのレンダリング結果は完全な Workload ドキュメントであり、独自の apiVersion: aggrega.ai/v1beta1 と kind: Workload を持ちます。これは、Recipe の workload: フィールドが受け取るのは 1 つの完全な Workload であって周囲のドキュメントに継ぎ合わされるフラグメントではなく、インポートはフィールド全体を置き換えるためです。MappingLibrary のエントリも同様に完全なものであり、それをインポートすると Recipe の valuesMapping: 全体が置き換えられます。
本体はエンティティエンベロープからは不透明です。コンパイラは WorkloadLibrary のロード時に文字列をそのまま保存し、その時点ではテンプレートを解析しません。テンプレートパーサーは、Recipe または FeatureRecipe がエントリをインポートする消費時に実行されます。フラグメントをそのまま保存することで再出力時のオーサリングの忠実性が保たれ、またテンプレートのエラーはライブラリではなく、エントリが消費されピラーコンテキストが判明している箇所で表面化します。
Workload ドキュメントは複数行になるため、エントリでは YAML のリテラルスタイルのスカラー(|)を使用し、改行とインデントがラウンドトリップ後も保持されるようにします。
spec: workloads: BatchJob: | apiVersion: aggrega.ai/v1beta1 kind: Workload form: task containers: worker: image: "{{ .values.image }}" command: ["{{ .values.entrypoint }}"]エントリの値は文字列スカラーでなければなりません。本体の位置にマッピングやシーケンスを記述すると拒否されます。エントリ本体はテンプレートテキストであり、コンパイラが走査する構造化 YAML ではありません。
エントリ内では Go テンプレートの合成語彙をすべて使用できます。{{ define "name" }}...{{ end }} は単一のライブラリ内で再利用可能なブロックを宣言し、{{ template "name" . }} はそれを呼び出します。パイプラインと関数は標準の Go text/template パッケージに従います。エントリが読み取れるピラーコンテキスト(.values、.infra、.locals、.context、.features)は、あらゆる Workload テンプレートが読み取るものと同じコンテキストであり、Workload ページのテンプレート評価の項に記載されています。
対象のプロバイダーはワークロード合成をサポートしている必要があります。ライブラリエントリをインポートしているものの、Workload を合成できないプロバイダーにバインドされている Recipe は、劣化した形を出力するのではなく、レンダリング時に明示的に停止します。標準ライブラリのカタログは、文書化された契約として、これをサポートするプロバイダーに workloadSchema を宣言しています。
単一のオーサリングモード
WorkloadLibrary が提供するオーサリングモードは Go テンプレートの 1 つだけです。spec は並行するオーサリングの手段を受け付けず、ライブラリのレベルで表現力のためのエスケープハッチも提供しません。
その理由は、利用側の手段の統一性にあります。Recipes と FeatureRecipes は全体が Go テンプレートで書かれ、それら自身の内容も、インポートされたフラグメントを解決するのと同じ Go テンプレートエンジンで評価されます。並行するオーサリングの手段があると、作成者は 1 つの Recipe のレンダリングの中で評価モデルを切り替えなければならなくなります。Recipe 自身の内容には一方のモデルを、インポートしたライブラリエントリにはもう一方のモデルを使うことになります。手段を統一しておくことで、作成者は 1 つの評価モデルを習得し、それをあらゆる場所で適用できます。
Go テンプレートの合成の語彙を超える表現力が必要な作成者は、ライブラリ内で第二のオーサリング言語に頼るのではなく、より上位のレベルで合成します。つまり、ライブラリエントリを独自の実質的なバリエーションでラップする Components や Features を使います。
命名の慣例
ライブラリ名と workload エントリのキーは PascalCase に従います。エンティティエンベロープの JSON Schema は、この慣例を 2 か所でパターン制約によって強制します。
metadata.nameは^[A-Z][A-Za-z0-9]*$に一致します。spec.workloadsのマップキーは、propertyNamesによって同じパターンに一致します。
spec.workloads に PascalCase でないキーを持つ WorkloadLibrary は、ワークスペースの読み込み時にエンベロープの検証に失敗します。この強制は重要な役割を担っています。workload エントリのキーは #/workloads/<name> 参照フラグメントに現れるため、PascalCase でないキーは、そのエントリをインポートするすべての利用側に伝播してしまいます。
命名を統一することで、#/workloads/<name> フラグメントが読みやすく保たれます。#/workloads/BatchJob は一目で読み取れます。
ライブラリエントリの参照
Recipe と FeatureRecipe の作成者は、workload: { $import: ... } ブロック内で、ワークロードエントリをベア名の識別子で参照します。
# Inside a Recipe's spec:spec: workload: $import: "BaseWorkloads#/workloads/SimpleServer"#/workloads/<name> フラグメントはエントリを選択し、ワークロード参照を MappingLibrary の #/mappings/<name> や SchemaLibrary の #/schemas/<name> と区別します。参照にはレジストリホストを含めません。ホストを含む oci://… 形式はエンベロープスキーマと利用箇所の両方で拒否されるため、物理的なレジストリの場所が作成されたソースに入り込むことはありません。作成者は任意で最小バージョンの下限を <Library>:<version>#/workloads/<name> として指定できます。バージョンの区切り文字は : で、recipe/feature のマッピングやロックファイルのピンと一致します。代わりに @ と書くと、修正後の参照を示す診断とともに拒否されます。解決されるバージョンは Release ごとのロックファイルが提供し、ロックファイルは利用される各ライブラリを名前、バージョン、コンテンツダイジェストでピン留めします。物理的な場所は解決時に結び付けられます。
同じ workload: フィールドは、ほかに 2 つの形式を受け付けます。インラインの Go テンプレート文字列と、Recipe ディレクトリからの相対パスで指定するローカルファイルの $import: です。3 つの形式は内容の形によって区別され、いずれもパース後に同じ Workload を生成します。workload: が Recipe のほかの入力種別とどのように組み合わさるかについては Recipe を、より広い $ref: / $import: の区別については vocabulary/cross-document-ref を参照してください。
ライブラリ間の合成
WorkloadLibrary のエントリは フィールドルートの $import: リダイレクト にすることができます。その本体の最初のトークンは $import: <Library>#/workloads/<entry> であり、これはエントリ全体を参照先エントリの内容で置き換えます。これは同一性による再利用であり、その場でのテンプレート化ではありません。リダイレクトは WorkloadLibrary の読み込み時ではなく消費時に解決され、再帰的に解決されるため、インポートされたエントリ自体がフィールドルートの $import: であってもかまいません。自身に戻ってループするチェーンは、その循環を示す診断とともに停止します。$import: はエントリ全体に対してのみ使用でき、フラグメントの途中で使うテンプレート関数ではありません。単一のエントリ 内で テンプレートテキストを合成するには、Go テンプレートの define / template を使用します。
# In library A — alias an entry to a shared entry in another library:spec: workloads: StandardServer: | $import: PlatformWorkloads#/workloads/MetricsServer不明なライブラリ名と、解決できたライブラリに存在しないエントリ名は、別々の診断として報告されます。そのため、作成者は依存関係の欠落とエントリ名の綴り誤りを区別できます。
Tier の配置
WorkloadLibrary は、エンティティ Tier のドキュメントモデルにおける Tier 3 であり、Recipe をまたいだ workload の再利用を必要とするカタログ向けのオプトインです。Recipes がそれぞれ固有の workload コンテンツを持つカタログは、WorkloadLibrary エンティティを一切含めずに出荷されます。Tier の表示は、ドキュメント内のナビゲーションのために「上級者向け。不要ならスキップ」を示すものであり、機能を示すものではありません。コンパイラは WorkloadLibrary を他のカタログエンティティの種類と同等に扱います。ワークスペースのロード時には同じエンベロープ検証を、リリース時には同じ OCI 公開パイプラインを、そして名前、バージョン、コンテンツダイジェストによる同じロックファイルでの固定を適用します。
このライブラリの種類は、カタログレベルの一組のうちの 1 つです。SchemaLibrary は再利用可能なスキーマ定義を、MappingLibrary は再利用可能なマッピングフラグメントを、ArtifactLibrary は再利用可能なアーティファクトのバンドルを、WorkloadLibrary は再利用可能な workload コンテンツを保持します。それぞれ独立してオプトインでき、カタログは必要なものだけを含めて出荷し、それ以外は一切含めません。
WorkloadLibrary ではないもの
よくある誤解をいくつか先に解いておきます。
-
インラインの
workload:の代わりではありません。 ほとんどの Recipes は、インラインに置くのがふさわしいほど固有の workload コンテンツを持っており、作成者はそれを Recipe の他の部分と並べて読みます。WorkloadLibrary が役立つのは、同じ workload の形が多数の Recipes にわたって現れる場合です。一度きりのコンテンツには、インラインでの記述が適切な選択です。 -
部分的な断片を置く場所ではありません。 エントリは完全な Workload ドキュメントにレンダリングされます。Recipe の values ドキュメントは MappingLibrary に、補助ファイルのセットは ArtifactLibrary に、スキーマ定義は SchemaLibrary に置きます。ライブラリの種類は、再利用のパターンではなく内容の種類によって分かれています。
-
独立してデプロイできるエンティティではありません。 ライブラリのエントリは Workload の内容であり、Workload の内容はそれ単独で参照できることはありません。Recipe または FeatureRecipe が消費する入力として存在します。WorkloadLibrary を公開するとそのエントリはインポート可能になりますが、デプロイ可能にはなりません。
-
Go テンプレートの仕組みを超えたパラメトリックな再利用ではありません。 パラメトリックな変化が必要な作成者は、ライブラリのエントリ内で Go テンプレートの
{{ define }}+{{ template }}の仕組みを使うか、消費する側の Recipe が提供する pillar コンテキストを使います。ライブラリのエンティティ自体は、パラメトリックなヘルパーの仕組みを一切備えていません。