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

ArtifactLibrary

ArtifactLibrary は、再利用可能なアーティファクトバンドル(ひとまとまりで扱われる補助出力ファイルの名前付きセット)を保持するカタログエンティティです。同じ補助リソース(RBAC と ConfigMap を伴う CRD、HPA と組み合わせた NetworkPolicy など)を出力する Recipes と FeatureRecipes は、そのセットをライブラリで一度だけ宣言し、利用時には値が $import: ディレクティブである artifacts: エントリを介して参照します。このライブラリエンティティは Tier 3 であり、Recipe をまたいだアーティファクトの再利用を必要とするカタログが任意で採用するものです。各 Recipes がそれぞれ独自の補助ファイルを持つカタログは、ArtifactLibrary を一切使わずに提供されます。

ArtifactLibrary の役割

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

このライブラリ種別を他の 3 つと区別するのは、エントリの粒度です。SchemaLibrary のエントリは 1 つのスキーマ、MappingLibrary のエントリは 1 つのテンプレート断片、WorkloadLibrary のエントリは 1 つの Workload ドキュメントであり、いずれも単一の箇所で利用される単一の本体です。ArtifactLibrary のエントリはファイルの集合です。これは、グループ化されるリソースが組み合わせてはじめて役に立つためです。RBAC なしで CRD をインポートすると、機能しないマニフェストの集合ができあがります。そのため、バンドルが再利用の単位となり、単一の利用箇所が複数の出力に展開されます。

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

ArtifactLibrary エンティティは、標準のカタログエンベロープを持ちます。apiVersion: aggrega.ai/v1beta1 と kind: ArtifactLibrary がエンティティの種類を示し、metadata.name は PascalCase の識別子で、metadata.version は厳密なセマンティックバージョニングに従います。この両方が必須です。metadata.description、metadata.labels、metadata.annotations は任意です。labels と annotations は、ライブラリを読み取るものが照合に使えるように保持される、作成者が宣言する不透明なメタデータであり、コンパイラはその値を解釈しません。ライブラリの内容は spec.artifacts の下に置かれます。これは必須のマップで、少なくとも 1 つのバンドルを宣言する必要があります。

エンベロープは 3 つのレベルすべてで閉じています。ドキュメントのルート、metadata、spec のそれぞれが、スキーマで宣言されていないキーを拒否します。

apiVersion: aggrega.ai/v1beta1
kind: ArtifactLibrary
metadata:
name: PlatformArtifacts
version: 1.0.0
spec:
artifacts:
OperatorSupport:
crd.yaml: |
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
name: widgets.platform.example.com
spec:
group: platform.example.com
scope: Namespaced
rbac.yaml: |
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
name: "{{ .context.instance_id }}-operator"
rules:
- apiGroups: ["platform.example.com"]
resources: ["widgets"]
verbs: ["get", "list", "watch"]

アーティファクトバンドルの記述

spec.artifacts は 2 階層の構造で、各階層はそれぞれ異なる役割を持ちます。外側のキーはバンドル名で、利用側が参照する識別子です。内側のキーはファイル名で、内側の各値はそのファイルに出力される Go テンプレートの本体です。バンドルは少なくとも 1 つのファイルを宣言する必要があります。

spec:
artifacts:
NetworkBaseline:
deny-all.yaml: |
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
name: "{{ .context.instance_id }}-deny-all"
spec:
podSelector: {}
policyTypes: ["Ingress"]
allow-dns.yaml: |
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
name: "{{ .context.instance_id }}-allow-dns"

ファイル本体は、YAML 文字列として記述された Go テンプレートの断片です。マニフェストは複数行にわたるため、ファイル本体では YAML のリテラルスタイルのスカラー(|)を使い、改行とインデントがラウンドトリップで保持されるようにします。バンドルエントリの値は、ファイル名から文字列本体へのマッピングでなければなりません。バンドルを置くべき位置に裸の文字列やシーケンスを書くと拒否されます。利用側がインポートする単位はバンドルであり、単一のファイルではないためです。

本体はエンティティのエンベロープからは不透明です。コンパイラは ArtifactLibrary の読み込み時に各文字列をそのまま保存し、その時点ではテンプレートを解析しません。テンプレートパーサーが実行されるのは利用時、つまり Recipe または FeatureRecipe がバンドルをインポートしたときです。本体をそのまま保存することで再出力時に記述内容が忠実に保たれ、またテンプレートのエラーはライブラリではなく、バンドルが利用されピラーのコンテキストが判明している場所で表面化します。

バンドル内のファイルの順序は作成者が書いた順序であり、読み込みと利用を通じて保持されるため、出力されるファイルの集合はビルド間で安定します。

ファイル本体の中では、Go テンプレートの合成用の語彙をすべて使用できます。{{ define "name" }}...{{ end }} は再利用可能なブロックを宣言し、{{ template "name" . }} はそれを呼び出します。パイプラインと関数は標準の Go text/template パッケージに従います。ファイル本体が読み取れるピラーのコンテキスト(.values、.infra、.locals、.context、.features、および利用側の Recipe が宣言している場合の .workload と .source)は、利用側の Recipe 自身の artifacts: エントリが読み取るコンテキストと同じであり、Recipe ページの artifacts: フィールドの項に記載されています。利用側の Recipe が workload: を宣言していないのに .workload を読み取る本体、または source: を宣言していないのに .source を読み取る本体は、解決できなかった参照を示す診断とともに停止します。各ピラーは個別にチェックされるため、一方を宣言しても他方を読み取れるようにはなりません。

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

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

その理由は、利用側の手段を統一するためです。Recipes と FeatureRecipes は全体が Go テンプレートであり、それら自身の内容は、インポートされたバンドルを解決するのと同じ Go テンプレートエンジンで評価されます。並行するオーサリング手段があると、作成者は 1 つの Recipe のレンダリングの中で評価モデルを切り替えなければならなくなります。Recipe 自身の内容には 1 つのモデル、インポートしたバンドルには別のモデルを使うことになります。手段を統一しておけば、作成者は 1 つの評価モデルを学び、それをどこにでも適用できます。

Go テンプレートの合成語彙を超える表現力を必要とする作成者は、ライブラリ内で第 2 のオーサリング言語に頼るのではなく、より上位のレベルで合成します。つまり、ライブラリのバンドルを独自の実質的なバリエーションでラップする Components や Features を使います。

命名の慣例

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

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

PascalCase でないバンドル名を持つ ArtifactLibrary は、ワークスペースの読み込み時にエンベロープの検証に失敗します。この強制には重要な役割があります。バンドル名は #/artifacts/<name> 参照フラグメントに現れるため、PascalCase でない名前は、そのバンドルをインポートするすべてのコンシューマーに波及してしまいます。

命名を統一することで、#/artifacts/<name> フラグメントは読みやすく保たれます。#/artifacts/OperatorSupport は一目で読み取れます。

バンドル内のファイル名は、それぞれがファイルを指している限り自由形式です。 ファイル名は PascalCase ではなく、スキーマのパターンによる制約もありません。これは、ビルドの出力が最終的に持つファイルの名前だからです。crd.yaml、deny-all.yaml、values-override.json はいずれも有効です。ファイル名に求められるのは、素直に書かれた通常の相対ファイル名であることです。Referencing Library Entries で説明するとおり、それ自体のファイルを指さない名前はビルドが拒否します。2 つのレベルの制約が異なるのは、それぞれが異なる読み手に向けたものだからです。バンドル名は他のエンティティが引用する識別子であり、ファイル名はバンドルがインポートされたディレクトリ内でコンシューマーが目にする名前です。

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

Recipe と FeatureRecipe の作成者は、値が $import: マップである artifacts: エントリの中で、バンドルのベア名によるアイデンティティを使ってバンドルを参照します。

# Inside a Recipe's spec:
spec:
artifacts:
operator-support:
$import: "PlatformArtifacts#/artifacts/OperatorSupport"

#/artifacts/<name> フラグメントはバンドルを選択し、artifacts の参照を MappingLibrary の #/mappings/<name>、SchemaLibrary の #/schemas/<name>、WorkloadLibrary の #/workloads/<name> と区別します。参照はレジストリのホストを持ちません。ホストを含む oci://… 形式はエンベロープスキーマでも利用箇所でも拒否されるため、物理的なレジストリの場所が作成されたソースに入り込むことはありません。作成者は任意の最小バージョンの下限を <Library>:<version>#/artifacts/<name> として指定できます。バージョンの区切り文字は : で、他のライブラリ種別やロックファイルのピンと一致します。代わりに @ と書くと、修正後の参照を示す診断とともに拒否されます。解決されるバージョンは Release ごとのロックファイルが提供し、ロックファイルは利用する各ライブラリを名前、バージョン、コンテンツダイジェストでピン留めします。物理的な場所は解決時に結び付けられます。

バンドルはそのファイル名を所有し、利用側のキーはファイルが配置されるディレクトリを所有します。 バンドルをインポートする 1 つの artifacts: エントリは、そのバンドル内のファイルごとに 1 つの出力に展開され、それぞれが利用キーの下に <key>/<filename> としてネストされます。利用箇所のキー(上の例では operator-support)は、個々のファイルではなく利用全体を指します。この例は operator-support/crd.yaml と operator-support/rbac.yaml を出力します。したがって、バンドル名は参照箇所での読みやすさのために選ばれ、ファイル名は出力ディレクトリを読む人のために選ばれ、両者が一致する必要はありません。利用キー自体は単一のファイル名に制限されています。先頭は英字または数字で、その後に英字、数字、ドット、ハイフン、アンダースコアが続き、この文字集合から外れるキーはエンベロープ検証で失敗します。そのためキーはちょうど 1 つのディレクトリセグメントを指し、そのセグメントより下はすべてバンドルから来ます。これにより、キーを厳格に保ちながらバンドルのファイル名を自由形式にできます。ファイル名はバンドル内で一意であり、キーはドキュメント内で一意であり、キーはエントリが出力するすべてのパスの最初のセグメントであるため、2 つの artifacts: エントリが同じ出力を指すことはありません。自由形式とは、そのセグメント内で自由という意味です。ファイル名は独自のネストしたレイアウトを持つことができます(crds/widget.yaml は <key>/crds/widget.yaml に配置されます)が、キーの下にある通常の相対ファイル名を素直に書いたものでなければならず、そうでないファイル名は、利用側の Recipe が指定していない場所にファイルを置く代わりにビルドを停止させます。これにより、キーより上に遡る名前や絶対位置を指す名前が拒否されます。また、. や ./、および x/.. のようにキーに戻ってしまう名前も拒否されます。これらはキー内のファイルではなくキー自体のディレクトリを指すためです。さらに、末尾または二重の / や、. または .. の部分を含む名前(x/、a//b、./a、a/../b)も拒否されます。これらは別の名前が持ちうるファイルの別表記であり、a/b と並ぶ a//b は 1 つのパスに 2 つのファイルを置くことになるためです。診断メッセージには、バンドルファイルと、それがインポートされたキーが示されます。実際に同じファイル名を持つ 2 つの出力は、ノードのレンダリング時にビルドを停止させます。これは、2 つの異なる入力種別が 1 つのファイル名を提供した場合に起こります。artifacts: が Recipe の他の入力種別とどのように組み合わさるか、およびライブラリ以外の 2 つのオーサリングモードについては Recipe を、より広い $ref: / $import: の区別については vocabulary/cross-document-ref を参照してください。

ライブラリ間の合成

バンドルファイルの本体は終端コンテンツです。 MappingLibrary や WorkloadLibrary のエントリとは異なり、バンドルファイルはフィールドルートの $import: リダイレクトにはできません。単一のファイルスロットには別のバンドルが持ち込む複数のファイルを収める余地がないため、コンパイラはこの形を、作成者が書いていないものへと解決するのではなく拒否します。最初のトークンが $import: である本体は、バンドルとファイルを示す診断を出して停止します。

合成は代わりに、その余地がある消費側で行われます。2 つのバンドルを必要とする Recipe は 2 つの artifacts: エントリを宣言し、それぞれが独立して展開されます。

# Inside a Recipe's spec — compose bundles where the outputs land:
spec:
artifacts:
operator-support:
$import: "PlatformArtifacts#/artifacts/OperatorSupport"
network-baseline:
$import: "PlatformArtifacts#/artifacts/NetworkBaseline"

未知のライブラリ名と、解決できたライブラリに存在しないバンドル名は、別々の診断として報告されます。そのため作成者は、依存関係の欠落とバンドル名の綴り誤りを区別できます。

Tier の配置

ArtifactLibrary は、エンティティ Tier のドキュメントモデルにおける Tier 3 であり、Recipe をまたいだアーティファクトの再利用を必要とするカタログ向けのオプトイン機能です。Recipes がそれぞれ独自の補助ファイルを持つカタログは、ArtifactLibrary エンティティを一切含めずに配布できます。Tier の区分は、機能ではなくドキュメントの案内のために「上級向け。不要ならスキップ」を示すものです。コンパイラは ArtifactLibrary を他のカタログエンティティの種類と同等に扱います。ワークスペース読み込み時のエンベロープ検証も、リリース時の OCI 公開パイプラインも、名前・バージョン・コンテンツダイジェストによるロックファイルのピン留めも同じです。

このライブラリの種類によって、カタログレベルのセットが揃います。SchemaLibrary は再利用可能なスキーマ定義を、MappingLibrary は再利用可能なマッピングの断片を、WorkloadLibrary は再利用可能なワークロードの内容を、ArtifactLibrary は再利用可能なアーティファクトバンドルを保持します。それぞれ独立してオプトインでき、カタログは必要なものだけを含め、それ以外は含めずに配布します。

ArtifactLibrary ではないもの

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

  • インラインの artifacts: の代わりではありません。 ほとんどの Recipes は、インラインに置くのがふさわしいほど固有の補助ファイルを持ちます。インラインであれば、作成者は Recipe の残りの部分と並べてそれらを読めます。ArtifactLibrary が役立つのは、同じファイルのセットが多くの Recipes に付随する場合です。一度きりの内容には、インラインでの記述が適切な選択です。

  • バンドル内のファイル名を変更する手段ではありません。 ファイル名はバンドルに属します。利用側はファイルが配置されるディレクトリを選べます(それが利用キーの役割です)が、個々のファイルの名前は選べません。別のファイル名が必要な利用側は、そのファイル名を宣言しているバンドルを使うか、ファイルをインラインで記述します。

  • workload、mapping、schema の内容を置く場所ではありません。 Workload ドキュメントは WorkloadLibrary に、Recipe の values ドキュメントは MappingLibrary に、schema 定義は SchemaLibrary に属します。ライブラリの種類は、再利用のパターンではなく内容の種類によって分かれています。

  • 横断的なリソースのための仕組みではありません。 どの Recipe が実現するかに関係なく多くのコンポーネントに適用される補助リソース(すべてのデータストアに付加されるバックアップ用サイドカーなど)は、FeatureRecipe のリソース生成に属します。これは Recipe ではなく Feature 単位で付加されます。entities/featurerecipe.md を参照してください。ArtifactLibrary は、複数の Recipes がそれぞれ自身のために出力するファイルを切り出すものです。

  • 独立してデプロイ可能なエンティティではありません。 バンドルはアーティファクトの内容であり、アーティファクトの内容は単独でアドレス指定されることはありません。それは Recipe または FeatureRecipe が利用する入力として存在します。ArtifactLibrary を公開するとそのバンドルはインポート可能になりますが、デプロイ可能にはなりません。