このページは機械翻訳されています。英語の原文を読む。
Aggrega Infrastructure Base (FeatureRecipe) スキーマ
自動生成されたリファレンスです。手動で編集しないでください。公開されている JSON Schema から再生成してください。
スキーマ ID: https://aggrega.ai/schemas/featurerecipe-v1beta1.schema.json
抽象的なカタログ Feature を、1 つの provider 機能に対する、バージョン管理された具体的な実装に対応付ける、Ops が作成する定義です。物理的な provider およびカタログの feature と厳密に 1:1 で対応します。
FeatureRecipe エンティティの作成に関する解説は FeatureRecipe 作成リファレンスを参照してください。このページでは、そのリファレンスが説明する構造スキーマを記述します。
トップレベルの型: object
プロパティ
| プロパティ | 種類 | 必須 | 説明 |
|---|---|---|---|
apiVersion | const “aggrega.ai/v1beta1” | はい | 定数: "aggrega.ai/v1beta1" |
kind | const “FeatureRecipe” | はい | 定数: "FeatureRecipe" |
metadata | object | はい | |
spec | object | はい | FeatureRecipe のプロバイダー機能バインディング、マッピング、パイプライン、および inject マッピングです。Recipe と同じ 3 種類の入力(sourced、synthesized、artifacts)に加えて、FeatureRecipe 専用の injectMapping を持ちます。capability と implements のみを宣言する純粋な配線用の FeatureRecipe は有効であり、何もレンダリングしません。 |
追加のプロパティは許可されません。
featurerecipe.metadata
| プロパティ | 種類 | 必須 | 説明 |
|---|---|---|---|
name | string | はい | 1 文字以上。 |
version | string | はい | FeatureRecipe の厳密なセマンティックバージョニング(例: 1.2.5)。パターン: ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$。 |
description | string | いいえ | このエンティティが何であり、何のためのものかを、使用するかどうかを判断する人に向けて書きます。まずそれが何かを示す一文で始め、次に読者がそれを選び正しく使うために必要なこと、つまりそれをデプロイする Release に何を期待するか、そしてその振る舞いについて意外な点を加えます。通常は短い段落程度の長さです。 |
maintainers | object[] | いいえ | このエンティティを所有するメンテナーの一覧です。 |
license | string | いいえ | このエンティティが記述するソフトウェアのライセンスの SPDX 識別子です(MIT や AGPL-3.0 など)。記録するのはそのソフトウェアの条件であり、このファイルの条件ではありません。 |
repository | string | いいえ | ソースファイルが置かれている Git リポジトリの URL です。 |
home | string | いいえ | このエンティティのホームページ、wiki、またはドキュメントの URL です。 |
keywords | string[] | いいえ | UI での発見性を高めるための説明的なキーワードの一覧です。 |
追加のプロパティは許可されません。
featurerecipe.metadata.maintainers[]
| プロパティ | 種類 | 必須 | 説明 |
|---|---|---|---|
name | string | はい | |
email | string | いいえ | |
url | string | いいえ |
追加のプロパティは許可されません。
featurerecipe.spec
FeatureRecipe のプロバイダー機能バインディング、マッピング、パイプライン、および inject マッピングです。Recipe と同じ 3 種類の入力(sourced、synthesized、artifacts)に加えて、FeatureRecipe 専用の injectMapping を持ちます。capability と implements のみを宣言する純粋な配線用の FeatureRecipe は有効であり、何もレンダリングしません。
| プロパティ | 種類 | 必須 | 説明 |
|---|---|---|---|
capability | string | はい | この recipe がバインドする明示的なプロバイダー機能(例: ‘helm’、‘terraform’、‘compose’)、つまりこれをレンダリングするプロバイダーの種類です。 |
implements | string | はい | この recipe が実装できるカタログの Feature の種類を宣言します(feature.aggrega.ai/kind: secret のラベルが付いた認証情報の Features を含みます。正確なバージョン、メジャー互換の範囲 ’^‘、またはバージョンなしを指定できます)。コンパイラはこれを使って Manifest のマッピングを検証し、診断とエディターの補完で候補を提示します。ビルドを解決することはありません。Manifest のマッピングはユーザーによる明示的な実装の選択であり、Release のロックファイルに固定されます。 |
locals | string のマップ | いいえ | Private Ops State です。この FeatureRecipe のテンプレート内でのみ ‘.locals.*’ として利用できる内部計算結果です。各エントリはそれ自体が Go テンプレートであり、自己完結したコンテキストに対して評価されます。コンテキストは、‘.context.instance_id’(このアタッチメントの解決対象であるホストコンポーネント。すべてのテンプレートサーフェスでこの参照が表すものです)、‘.attachment_name’(解決中のアタッチメントインスタンス。local からその名前に到達する唯一の経路です)、アタッチメント自身の ‘.values’ と ‘.infra’、そしてこの同じブロックでそれまでに解決されたエントリです。エントリは記述された順序で解決され、エントリは自身より上で定義された兄弟エントリを読み取ることができます(MAY)。その際、兄弟のテンプレートテキストではなく解決済みの値を受け取ります。あるエントリが別のエントリを読み取る場合、記述順序は契約の一部です。定義をその読み取り側より下に移動するとビルドが壊れ、参照を解決させるためにブロックが並べ替えられることはありません。このブロックが後で定義するエントリへの ‘.locals. |
provides | string のマップ | いいえ | 公開 Developer API です。下流の Caller による inject 解決で利用できる、契約上の出力変数です。executionScope が boundary の場合、provides は boundary アタッチメントについて、boundary スコープのテンプレートコンテキストに対して一度だけ評価され、アタッチメントが到達するすべてのコンポーネントは、その 1 回の評価結果を ‘.features. |
source | string または object | いいえ | インフラストラクチャコードへの任意のパスです。URI 文字列、またはオープンな構造化オブジェクトを受け付けます。valuesMapping と併せて指定された場合、コンパイラはこれをレンダリングし、レンダリングされたドキュメントは、パイプラインステップの実行前に FeatureRecipe の出力に加わります。 |
valuesMapping | string または object | いいえ | 内容の形によるディスパッチで 3 つの記述モードを持つ values マッピングの内容です。モード 1(インライン): プロバイダーが期待する values 形式を生成する Go テンプレートの文字列スカラー。モード 2(ファイルインポート): ローカルの Go テンプレートファイルを指す、キーがちょうど 1 つの YAML マップ $import: ./relative/path.tmpl。モード 3(ライブラリインポート): MappingLibrary のエントリを素の名前によるアイデンティティで参照する、キーがちょうど 1 つの YAML マップ $import: <Library>#/mappings/<entry>(バージョンは Release ごとのロックファイルが提供し、参照にレジストリホストは含まれません)。オブジェクト形式では、$import は ^oci:// に一致してはならず、一致する値は拒否されます。 |
workload | string または object | いいえ | 内容の形によるディスパッチで 3 つの記述モードを持つ Workload YAML の生成元です。モード 1(インライン): 出力が ‘aggrega.ai/v1beta1 Workload’ として解析される Go テンプレートの文字列スカラー。モード 2(ファイルインポート): ローカルの Go テンプレートファイルを指す、キーがちょうど 1 つの YAML マップ $import: ./relative/path.yaml。モード 3(ライブラリインポート): WorkloadLibrary のエントリを素の名前によるアイデンティティで参照する、キーがちょうど 1 つの YAML マップ $import: <Library>#/workloads/<entry>(バージョンは Release ごとのロックファイルが提供し、参照にレジストリホストは含まれません)。対象の Provider はワークロード合成をサポートしている必要があります。標準ライブラリのカタログは、そのようなプロバイダーに文書化された契約として workloadSchema を宣言しています。合成できないプロバイダーにバインドされた workload: を持つ FeatureRecipe は、レンダリング時に明示的に停止します。合成された FeatureRecipe のワークロードは、プロバイダーネイティブのマニフェストをフィーチャーの出力ディレクトリ配下に出力します。オブジェクト形式では、$import は ^oci:// に一致してはならず、一致する値は拒否されます。 |
artifacts | string または object のマップ | いいえ | エントリ名からアーティファクト内容の記述へのマップです。各エントリの値は、内容の形によるディスパッチで 3 つのモードのいずれかを取ります。モード 1(インライン):出力がアーティファクト本体となる Go テンプレート文字列スカラー。モード 2(ファイルインポート):キーがちょうど 1 つの YAML マップ $import: ./relative/path.yaml で、ローカルの Go テンプレートファイルを指します。モード 3(ライブラリインポート):キーがちょうど 1 つの YAML マップ $import: <Library>#/artifacts/<entry> で、ArtifactLibrary のバンドルをベア名の識別子で参照します(バージョンは Release ごとのロックファイルが提供し、参照にレジストリホストは現れません)。バンドルはファイルごとに 1 つの出力へ展開され、それぞれがエントリのキーの下に <key>/<filename> として配置されます。キーはエントリの出力を名付けます。モード 1 またはモード 2 のエントリのキーはその出力ファイル名で、書かれたとおりに使われます。モード 2 のエントリがインポートするファイルは内容を提供しますが出力を名付けないため、同じ名前を持つ別々のファイルをインポートする 2 つのエントリは、2 つの別個の出力になります。リソースを生成する FeatureRecipe が出力する補助リソース(ConfigMap、ServiceMonitor、NetworkPolicy、ExternalSecret CRD など)はアーティファクトの形をしており、artifacts: が主要なリソース生成の仕組みです。アーティファクトのエントリ、バンドルのファイル、source の出力、ワークロード合成の間で衝突が起きると、そのノードのレンダリング時にビルドが停止します。artifacts ブロックは Recipe と FeatureRecipe で同一に記述します。3 つのモード、キーから出力への規則、衝突時の動作はすべて同じで、そのためこの説明のこの部分は両方の種類で同じ内容になっています。一方のために書いた例は、そのままもう一方に適用できます。オブジェクト形式では、$import は ^oci:// に一致してはならず、一致する値は拒否されます。キー:キーはエントリの出力を名付けるため、単一のファイル名に制限されます。英字または数字で始まり、英字、数字、ドット、ハイフン、アンダースコアが続きます。先頭以外のドットにより、アーティファクトのキーが持つ拡張子(main.tf、template.yaml、serviceaccount.yaml)を保持できます。/ があると 1 つのキーがファイルではなくパスを名付けることになり、先頭の . を許すと .. を受け入れることになります。これは出力ディレクトリの外の場所を指すため、先頭文字のクラスによって両方が拒否されます。ライブラリインポートの場合、キーはバンドルのファイルが配置されるディレクトリを名付けるため、同じ制限が適用されます。パターン:^[A-Za-z0-9][A-Za-z0-9._-]*$。 |
omits | object[] | いいえ | この FeatureRecipe の source がレンダリングするもののうち、除外するものです。そのまま取り込んだ source が、Release に含めてはならないものをレンダリングする場合に使います。たとえば、取得したチャートがレンダリングするドキュメント(レンダリングのたびにチャートが新たに生成する鍵を保持する Secret など)、取得した compose ファイルに含まれる service、volume、config、取得した CloudFormation テンプレートが宣言するリソースです。ほとんどの FeatureRecipes では必要ありません。各エントリは、source がレンダリングする 1 つの単位を、その種類、名前、およびエントリが指定する場合は名前空間と由来するサブチャートによって名付けます。いずれも source をレンダリングする provider の語彙で表します。チャートでは、ドキュメント自身の kind と metadata.name によるドキュメント、compose ファイルでは、services:、volumes:、configs: の下のキーによる service、volume、config、CloudFormation テンプレートでは、Type と論理 ID によるリソースです。その provider はエントリに一致するすべての単位を除外します。エントリが何に一致するか、またエントリを理由に provider が何を拒否するかは、その provider 自身が文書化した契約です。何も除外できない provider は、このキーを宣言する FeatureRecipe を、何もレンダリングする前に拒否します。フィルタされるのは source: がレンダリングするものだけで、workload: や artifacts: のエントリは決してフィルタされません。そのため、このキーには source が必要です。すべての値はテンプレートで、valuesMapping が評価されるのと同じコンテキストで評価されます。エントリの when が最初に評価され、when が偽となる値をレンダリングしたエントリは除外されます。有効なまま残るエントリはすべて何かを除外しなければなりません。source がレンダリングしたものに何も一致しない有効なエントリは、そのエントリを名指ししてビルドを停止させます。source は引き続き完全にレンダリングされます。チャートのすべてのテンプレートは実行されるため、失敗するテンプレートはビルドを失敗させます。除外されるのはその出力だけです。このキーは Recipe と FeatureRecipe で同一に記述します。エントリは 1 つ以上必要です。 |
injectMapping | string | いいえ | Pre-Render Interception フェーズで評価される、任意のインライン Go テンプレートです。アタッチメントが到達する各コンポーネントについて 1 回ずつ、そのコンポーネントのテンプレートコンテキストに対して評価されます。executionScope の指定にかかわらず、コンポーネントの ‘.context’ と ‘.features’、およびアタッチメントの ‘.attachment_name’、‘.values’、‘.infra’、‘.locals’ を読み取ります。どのコンポーネントのコンテキストにも含まれない ‘.boundary’ を参照するとビルドが停止します。JSON/YAML の辞書を出力し、Go コンパイラがそれを呼び出し元の ‘.context.inject’ メモリパイプにネイティブにディープマージします。Wasm を使わずに、呼び出し元側で環境変数や配信契約を変更するために使います。 |
pipeline | object[] | いいえ | レンダリング後に、レンダリングされたドキュメントセットに対して順に実行される Wasm パイプラインステップのリストです。各ステップは RFC 6902 パッチと副作用を返します。 |
executionScope | string (enum) | いいえ | この FeatureRecipe のリソース生成を、コンポーネントごと(デフォルト)に実行するか、境界のアタッチメントごとに 1 回実行するかを指定します。境界スコープの FeatureRecipes は (boundary_path, FeatureRecipe インスタンス) で重複排除され、injectMapping 以外のすべてのテンプレートは境界スコープのテンプレートコンテキストを読み取ります。つまり、コンポーネントごとの .context.* の柱ではなく .boundary.* の柱を読み取り、前者を参照するとビルドが停止します。injectMapping は executionScope にかかわらず、アタッチメントが到達する各コンポーネントについて 1 回ずつ実行されるため、そのコンポーネントのコンテキストを読み取り、.boundary は決して読み取りません。許可される値:"component"、"boundary" デフォルト:"component" |
readsCallerRenderFacts | 真偽値 | いいえ | この FeatureRecipe のテンプレートが、アタッチ先のコンポーネントに接続している Components がレンダリングしたもの、つまりそれらの呼び出し元それぞれの provider が自身の出力について報告するレンダリングファクトを読むことを宣言します。true で、かつ FeatureRecipe がコンポーネントごとにレンダリングする場合、そのアタッチメントはそれぞれ、アタッチ先の Component の直後ではなく、ビルド内のすべての Component がレンダリングされた後にレンダリングされます。そのため、アタッチメントが評価される前に各呼び出し元のレンダリングは完了しています。false または未指定の場合、‘.context.used_by’ 上のどの呼び出し元のエントリもレンダリングファクトを持たず、readsTargetRenderFacts が true でない限りアタッチメントはその Component の直後にレンダリングされます。また、この FeatureRecipe にインラインで書かれたテンプレートが ‘.context.used_by’ の下の呼び出し元のレンダリングファクトを読むと、ビルドは停止します。デフォルト:false |
readsTargetRenderFacts | 真偽値 | いいえ | この FeatureRecipe のテンプレートが、アタッチ先のコンポーネントの接続先である Components がレンダリングしたもの、つまり ‘.context.uses’ の各エントリ上で、それらの接続先それぞれの provider が自身の出力について報告するレンダリングファクトを読むことを宣言します。true で、かつ FeatureRecipe がコンポーネントごとにレンダリングする場合、そのアタッチメントはそれぞれ、アタッチ先の Component の直後ではなく、ビルド内のすべての Component がレンダリングされた後にレンダリングされます。そのため、アタッチメントが評価される前に各接続先のレンダリングは完了しています。これは readsCallerRenderFacts が引き起こすのと同じ遅延レンダリングであり、どちらか一方または両方のキーを設定すると、アタッチメントはその時点でレンダリングされます。false または未指定の場合、‘.context.uses’ 上のどのエントリもレンダリングファクトを持たず、readsCallerRenderFacts が true でない限りアタッチメントはその Component の直後にレンダリングされます。また、この FeatureRecipe にインラインで書かれたテンプレートが ‘.context.uses’ の下の接続先のレンダリングファクトを読むと、ビルドは停止します。デフォルト:false |
assertions | string のマップ | いいえ | ビルド時のフィールド横断検証です。各エントリは名前付きのアサーションです。キーはエラーメッセージに表示される安定したルール識別子で、値は {{ fail "message" }} による停止のセマンティクスを持つ Go テンプレート文字列です。エンティティごとの複数の名前付きアサーションは、インスタンスごとに作成者が宣言した順序で評価され、最初に失敗したアサーションがビルドを停止させます。FeatureRecipe のアサーションは、recipe のバインディング後かつ provides の評価後、レンダリング前に評価され、FeatureRecipe が取り込む特定のチャートやモジュールの実装上の不変条件を表します。テンプレートコンテキスト:.values / .infra / .uses / .features / .metadata と .provides / .locals / .recipe。評価器は missingkey=error を使うため、未定義のキーへの参照は no-such-key 診断で停止します。素の参照はフォールバックが実行される前に停止するため、この面では単純な default は任意フィールドのフォールバックになりません。参照を hasKey で保護するか、存在確認を直接行う optional ヘルパーを使ってください。index でキーを読んでもフォールバックにはなりません。index はマップが保持していないキーに対して、そのキーを名指しして停止します。 |
追加のプロパティは許可されません。
featurerecipe.spec.omits[]
| プロパティ | 種類 | 必須 | 説明 |
|---|---|---|---|
kind | string | はい | 除外するユニットの種類です。ソースをレンダリングする provider の語彙で指定します。chart の場合はレンダリングされたドキュメント自身の kind(Secret など)、compose ファイルの場合は service、volume、config のいずれか、CloudFormation テンプレートの場合はリソースの Type(AWS::S3::Bucket など)です。ソースがレンダリングする種類を指定するものであり、構造化された source: が持つ kind: とは無関係です。テンプレートです。 |
name | string | はい | 除外するユニットの名前です。ソースをレンダリングする provider の語彙で指定します。chart の場合はレンダリングされたドキュメント自身の metadata.name、compose ファイルの場合は services:、volumes:、configs: の下にあるそのユニットのキー、CloudFormation テンプレートの場合はリソースの論理 ID、つまり Resources の下にあるそのキーです。テンプレートです。 |
namespace | string | いいえ | 除外するユニットが属する namespace です。エントリーがその namespace 内のユニットだけにマッチすべき場合に指定します。chart のレンダリング済みドキュメントのように、出力が namespace を持つ provider 向けです。省略された場合、または空文字列にレンダリングされた場合、エントリーは namespace にかかわらず、その種類と名前を持つユニットにマッチします。compose ファイルと CloudFormation テンプレートには namespace がなく、それらの provider は namespace を指定したエントリーを拒否します。テンプレートです。 |
subchart | string | いいえ | 除外する単位の由来となるサブチャートです。エントリが 1 つのサブチャートがレンダリングするコピーにだけ一致すべき場合に使います。チャートがサブチャートから組み立てられるように、入れ子になった source から組み立てられる source が対象です。チャートの場合は、サブチャート自身の名前、または親の依存関係が与える別名を指定し、入れ子のサブチャートの名前は最も外側から / でつなぎます(operator や operator/webhooks)。その場合、エントリはそのサブチャート自身の templates/ または crds/ からレンダリングされたドキュメントに一致し、チャート自身がレンダリングするドキュメントにも、その中に入れ子になったサブチャートがレンダリングするドキュメントにも一致しません。省略した場合、または空文字列にレンダリングされた場合、エントリは由来にかかわらず、その種類と名前の単位に一致します。その名前のサブチャートをレンダリングしないチャートは、エントリを名指ししてビルドを停止させます。compose ファイルと CloudFormation テンプレートにはサブチャートがなく、それらの provider はサブチャートを指定するエントリを拒否します。テンプレートです。 |
when | string | いいえ | エントリーの他のフィールドより先に評価されるインライン Go テンプレートです。偽と評価される値にレンダリングされた場合、エントリーは破棄されます。その他のフィールドは評価されず、このエントリーによって何も除外されず、マッチすることも要求されません。when が空または省略されている場合、エントリーは保持されます。真偽の判定は、真偽値のようなテンプレート出力に対する標準的な慣例に従います。文字列 true/True/TRUE、0 以外の数値、その他の空でない文字列は真、false/False/FALSE、空文字列、0 は偽です。レンダリングに失敗した when はビルドを停止します。 |
追加のプロパティは許可されません。
featurerecipe.spec.pipeline[]
| プロパティ | 種類 | 必須 | 説明 |
|---|---|---|---|
id | string | はい | このステップのプログラム上の識別子で、このパイプラインのステップの中で一意です。2 つのステップで同じ id を宣言しているドキュメントは、読み込み時に拒否されます。同じパイプラインの後続ステップは、このステップの出力を .steps.<id>.outputs として読み取ります。パターン:^[a-zA-Z0-9_]+$。 |
plugin | string | はい | このステップが実行する Plugin エンティティへの参照です。常にプラグイン自身のソケット種別でスコープされます。形式は <pluginType>/<name> で、parser/yaml や parser/yaml:1.0.0 のように任意でバージョンを付けます。スコープは複数ある形式の一つではなく必須です。スコープのない name:version は拒否されます。2 つのソケットが同じ名前のプラグインを持つ場合があり、エンティティを解決可能にするのはスコープだからです。ビルドはエンティティを、コンテンツアドレス指定された .wasm アーティファクト(プラグインの識別子と設定されたレジストリから場所を特定し、そのダイジェストはロックファイルに固定されます)に解決し、バイト列を読み込みます。単独の .wasm やアーティファクトへの参照はここでは受け付けられません。 |
function | string | はい | 呼び出すエクスポート済みの Wasm 関数です。 |
with | string | いいえ | このプラグインの明示的な入力スキーマを厳密に満たす JSON/YAML マップに評価されるインライン Go テンプレートです。 |
optional | 真偽値 | いいえ | true の場合、このステップの失敗(ゲストのトラップ、セットに存在しないドキュメントを対象とするパッチ、不正な形式のパッチ、または停止レベルの診断)は目立つ警告に格下げされます。ステップ実行前のドキュメントセットが復元され、このステップの出力は破棄され、パイプラインは続行します。false または省略の場合、ステップが失敗するとステップ実行前のドキュメントセットを復元した後にビルドが停止します。 |
when | string | いいえ | パイプラインの走査時に評価されるインライン Go テンプレートです。偽と評価される値にレンダリングされた場合、ステップはスキップされます。これはパススルーであり、ドキュメントセットは変更されずに次のステップへ渡され、パッチ、副作用、ステップ記録は一切生じません。when が空または省略されている場合、ステップは常に実行されます。真偽の判定は、真偽値のようなテンプレート出力に対する標準的な慣例に従います。文字列 true/True/TRUE、0 以外の数値、その他の空でない文字列は真、false/False/FALSE、空文字列、0 は偽です。when と optional は独立しており、1 つのステップで両方を宣言できます。 |
追加のプロパティは許可されません。