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

MappingLibrary

MappingLibrary は、再利用可能な Go テンプレートの断片を保持するカタログエンティティです。valuesMapping: ドキュメント全体(同じチャートをソースとする複数の Recipes がそれぞれチャートに渡す values)を共有する Recipes と FeatureRecipes は、それをライブラリで一度だけ宣言し、利用時に valuesMapping: { $import: ... } ディレクティブで参照します。このライブラリエンティティは Tier 3 であり、Recipe をまたいだマッピングの再利用が必要なカタログのためのオプトイン機能です。繰り返されるテンプレート内容を持たないカタログは、MappingLibrary を一切含めずに提供されます。

MappingLibrary の役割

プラットフォームアーキテクトは、カタログの Recipes と FeatureRecipes にまたがって繰り返し現れる Go テンプレートフラグメントを一元化するために MappingLibraries を作成します。ライブラリはデプロイ可能なビルド命令ではなく、定義の名前空間です。Recipe と FeatureRecipe の作成者は $import: ディレクティブでライブラリのエントリを参照します。エントリは一度だけ記述され、インポートが解決される場所であればどこでも利用されます。

「ライブラリ」と「利用側」の分離は意図的なものです。Recipes はビルド命令(source、valuesMapping、artifacts)を表します。FeatureRecipes は振る舞いのアタッチメントを表します。MappingLibraries はテンプレートフラグメント、つまり他のエンティティがレンダリング時に利用する Go テンプレートの内容だけを表します。3 つの役割を区別しておくことで、各エンティティ種別はそれぞれのペースで進化できます。共有テンプレートの内容を必要としない作成者が、このライブラリエンティティに触れることはありません。

エンティティエンベロープ

MappingLibrary エンティティは、標準のカタログエンベロープを持ちます。apiVersion: aggrega.ai/v1beta1 と kind: MappingLibrary がエンティティの種類を示し、metadata.name は PascalCase の識別子、metadata.version は厳密なセマンティックバージョニングに従います。ライブラリの内容は spec.mappings の下に置かれます。これは必須のマップで、少なくとも 1 つのエントリを宣言する必要があります。

apiVersion: aggrega.ai/v1beta1
kind: MappingLibrary
metadata:
name: BaseMappings
version: 1.0.0
spec:
mappings:
SimpleValues: 'image: {{ .values.image }}'
Replicas: 'replicas: {{ optional .infra "replicas" 1 }}'

エントリは、それを利用する Recipe 自身のテンプレートエンジンによって、その Recipe のレンダリングコンテキストに対して評価されます。そのため、エントリは Recipe 自身の valuesMapping: が読むのと同じ小文字のピラー(.values、.infra、.context など)を読み、存在しないキーに対して存在を考慮する optional ヘルパーなど同じ関数を使います。Helm がチャートの values に使う表記である .Values は、このコンテキストが定義するルートではありません。これを読むエントリはビルドを停止し、その参照を示します。

マッピングエントリのオーサリング

各マッピングエントリは、YAML 文字列として記述される Go テンプレートのフラグメントです。フラグメントはエンティティエンベロープからは不透明です。コンパイラは MappingLibrary の読み込み時に文字列をそのまま保存し、Recipe または FeatureRecipe が valuesMapping: { $import: ... } を介してエントリをインポートする消費時にそれを解析します。インポートは Recipe の valuesMapping: 全体を置き換えます($import: マップは他のキーを持ちません)。そのため、エントリは 1 つの values ドキュメントに継ぎ足される断片ではなく、完全な values ドキュメントです。

短いフラグメントは 1 行に収まります。

spec:
mappings:
AppName: 'fullnameOverride: "{{ .context.rendered_name }}"'

複数行のフラグメントでは、改行とインデントがラウンドトリップ後も保持されるように、YAML のリテラルスタイルのスカラー(|)を使用します。

spec:
mappings:
ProbeBlock: |
readinessProbe:
httpGet:
path: /healthz
port: {{ .values.port }}
livenessProbe:
httpGet:
path: /healthz
port: {{ .values.port }}

フラグメント内では Go テンプレートの合成機能をすべて使用できます。{{ define "name" }}...{{ end }} は単一のライブラリ内で再利用可能なブロックを宣言し、{{ template "name" . }} はそれを呼び出します。パイプラインと関数は、標準の Go text/template パッケージに従ってサポートされます。

単一のオーサリングモード

MappingLibrary が提供するオーサリングモードは Go テンプレートの 1 つだけです。spec は並行するオーサリング面を受け付けず、ライブラリレベルでの表現力のエスケープハッチもありません。

理由は消費面の一様性です。Recipes と FeatureRecipes は全体が Go テンプレートであり、それ自体の内容は、インポートされたエントリを解決するのと同じ Go テンプレートエンジンで評価されます。そのため、エントリは Recipe 自身のテキストとまったく同じように読まれ、作成者は 1 つの評価モデルだけを学べば済みます。Go テンプレートの合成の語彙(ライブラリ内の {{ define }} と {{ template }}、および利用時の $import: ディレクティブ)が、ライブラリに必要な再利用可能なブロックとパラメーター付きの呼び出しを提供します。

Go テンプレートの合成語彙が提供する以上の表現力を必要とする作成者は、MappingLibrary 自体の内部で並行するオーサリング言語へと拡大するのではなく、より上位のレベルで合成します。つまり、ライブラリエントリを独自の実質的なバリエーションでラップする Components や Features を用います。

命名の慣例

ライブラリ名とマッピングエントリのキーは PascalCase に従います。エンティティエンベロープの JSON Schema は、パターン制約によって 2 か所でこの慣例を強制します。

  • metadata.name は ^[A-Z][A-Za-z0-9]*$ に一致します。
  • spec.mappings のマップキーは、propertyNames によって同じパターンに一致します。

spec.mappings に PascalCase でないキーを持つ MappingLibrary は、ワークスペースの読み込み時にエンベロープの検証に失敗します。この強制には重要な役割があります。マッピングエントリのキーは #/mappings/<name> 参照フラグメントに現れるため、PascalCase でないキーは、そのエントリをインポートするすべての利用側に伝播します。

命名の統一性により、#/mappings/<name> フラグメントは読みやすく保たれます。#/mappings/ProbeBlock は一目で読み取れます。

ライブラリエントリの参照

Recipe および FeatureRecipe の作成者は、valuesMapping: { $import: ... } ブロック内で、マッピングエントリをそのベア名アイデンティティによって参照します:

# Inside a Recipe's valuesMapping block:
spec:
valuesMapping:
$import: "BaseMappings#/mappings/ProbeBlock"

#/mappings/<name> フラグメントはエントリを選択し、マッピング参照を SchemaLibrary の #/schemas/<name> と区別します。この参照は、SchemaLibrary の $ref: と同じベア名アイデンティティモデルを使用し、<Library>#/mappings/<name> の形でレジストリホストを含みません。バージョンは Release ごとのロックファイル(名前 + バージョン + コンテンツダイジェスト)によって提供されます。作成者は任意の最小バージョンの下限を <Library>:<version>#/mappings/<name> として指定できます(バージョン区切り文字は : で、recipe/feature のマッピングおよびロックファイルのピンと一致します)。物理的な場所は解決時にバインドされます。

ライブラリ間の合成

MappingLibrary のエントリは フィールドルートの $import: リダイレクト にすることができます。この場合、本体の最初のトークンは $import: <Library>#/mappings/<entry> であり、エントリ全体を参照先エントリの内容で置き換えます。これはその場でのテンプレート展開ではなく、アイデンティティによる再利用です。リダイレクトは MappingLibrary の読み込み時ではなく消費時(Recipe のレンダリング時)に解決され、再帰的に解決されます。インポートされたエントリ自体がフィールドルートの $import: であってもかまいません。$import: はエントリ全体のみを対象とし、フラグメントの途中で使うテンプレート関数ではありません。単一のフラグメント内でテンプレートテキストを合成するには、Go テンプレートの define / template を使用します。

# In library A — alias an entry to a shared entry in another library:
spec:
mappings:
StandardProbe: |
$import: MonitoringLibrary#/mappings/PrometheusAnnotations

ライブラリは互いに自由に参照できます。自分自身に戻ってくるチェーンは、それを利用する Recipe のレンダリング時に停止し、循環の各ステップを示す診断を出します。

Tier の配置

MappingLibrary は、エンティティ Tier のドキュメントモデルにおける Tier 3 です。Recipe をまたいでマッピングを再利用する必要があるカタログ向けのオプトイン機能です。繰り返し使われるテンプレート内容を持たないカタログは、MappingLibrary エンティティを一切含めずに出荷されます。Tier の表示はドキュメント上のナビゲーションのために「上級者向け。不要ならスキップ」を示すものであり、機能の有無を示すものではありません。コンパイラは MappingLibrary を他のカタログエンティティの種類と同等に扱います。ワークスペースの読み込み時には同じエンベロープ検証が行われ、リリース時には同じ OCI 公開パイプラインが使われます。

このライブラリの種類は、カタログのレベルで SchemaLibrary と自然に対になります。SchemaLibrary は再利用可能なスキーマ定義を保持し、MappingLibrary は再利用可能なテンプレートフラグメントを保持します。両方が必要なカタログは両方を含めて出荷し、どちらも必要ないカタログはどちらも含めずに出荷します。

MappingLibrary ではないもの

よくある誤解をいくつか先に解いておきます。

  • インラインの valuesMapping: の代替ではありません。 ほとんどの Recipes は単純な valuesMapping: の内容を持ち、それらはインラインで記述するほうが適しています。Recipe が自己完結し、作成者は Recipe の他の部分と並べてマッピングの内容を読めるからです。MappingLibrary が役立つのは、同じ断片が多数の Recipes にわたって現れる場合です。一度きりのマッピングには、インラインでの記述が適切な選択です。

  • スキーマの内容を置く場所ではありません。 スキーマ定義(JSON Schema 2020-12)は SchemaLibrary に属し、テンプレート断片はここに属します。ライブラリの種類は、再利用のパターンではなく内容の種類によって分かれています。

  • Go テンプレートの仕組みを超えるパラメトリックな再利用ではありません。 パラメトリックな変化が必要な作成者は、ライブラリエントリの内部で Go テンプレートの {{ define }} + {{ template arg }} の仕組みを使うか、独自の変化を加えてライブラリエントリをラップする Components / Features を組み合わせます。ライブラリエンティティ自体は、パラメトリックなヘルパーの仕組みを提供しません(SchemaLibrary の spec.templates によるパラメトリックヘルパーに相当する templates ブロックはありません)。Go テンプレートの合成の語彙が同じユースケースをカバーします。