Aggrega Release スキーマ
自動生成されたリファレンスです。手動で編集しないでください。公開されている JSON Schema から再生成してください。
スキーマ ID: https://aggrega.ai/schemas/release-v1beta1.schema.json
Release エンティティの記述に関する解説は Release 記述リファレンスを参照してください。このページでは、そのリファレンスが説明する構造スキーマを記載します。
トップレベルの型: object
プロパティ
| プロパティ | 種類 | 必須 | 説明 |
|---|---|---|---|
apiVersion | const “aggrega.ai/v1beta1” | はい | 定数: "aggrega.ai/v1beta1" |
kind | const “Release” | はい | 定数: "Release" |
metadata | object | はい | |
spec | object | はい | Release がバインドしルーティングするもの: その Release がデプロイする Aggregate と Manifest(または extends のベース)、環境固有のパラメーターの充足、そしてそのコンポーネントのルーティング先となる境界です。 |
追加のプロパティは許可されません。
release.metadata
| プロパティ | 種類 | 必須 | 説明 |
|---|---|---|---|
name | string | はい | 1 文字以上。 |
environment | string | はい | |
version | string | はい | release の厳密なセマンティックバージョニング(例: 1.0.0)です。パターン: ^(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 | いいえ | このエンティティが何であり、何のためのものかを、使用するかどうかを判断する人に向けて記述します。まずそのものを名指しする一文で始め、次に読み手がそれを選択し正しく使うために必要なこと、つまりデプロイ先のプラットフォームに何を期待するか、その動作で意外な点は何かを加えます。通常は短い段落程度の長さです。 |
maintainers | object[] | いいえ | このエンティティを所有するメンテナーの一覧です。 |
license | string | いいえ | このエンティティが記述するソフトウェアのライセンスの SPDX 識別子です(MIT や AGPL-3.0 など)。記録するのはそのソフトウェアの条件であり、このファイルの条件ではありません。 |
repository | string | いいえ | ソースファイルが置かれている Git リポジトリの URL です。 |
home | string | いいえ | このエンティティのホームページ、wiki、またはドキュメントの URL です。 |
keywords | string[] | いいえ | UI での発見性を高めるための説明的なキーワードの一覧です。 |
追加のプロパティは許可されません。
release.metadata.maintainers[]
| プロパティ | 種類 | 必須 | 説明 |
|---|---|---|---|
name | string | はい | |
email | string | いいえ | |
url | string | いいえ |
追加のプロパティは許可されません。
release.spec
Release がバインドしルーティングするもの: その Release がデプロイする Aggregate と Manifest(または extends のベース)、環境固有のパラメーターの充足、そしてそのコンポーネントのルーティング先となる境界です。
| プロパティ | 種類 | 必須 | 説明 |
|---|---|---|---|
aggregate | string | いいえ | この release がデプロイする Aggregate(Developer Intent)への参照です。単なるトークンは ID によって解決されます。つまり参照先 Aggregate の metadata.name であり、Release 自身のディレクトリ、次にカタログの順で検索されます。’./’ または ’../’ で始まる値は、Release からの相対パスとして解決される明示的なローカルファイルです(例: サブディレクトリ内の release バリアント間で 1 つの Aggregate を共有する場合の ’../shared/app.yaml’)。 |
manifest | string | いいえ | この release のデプロイ対象となる抽象インターフェースを解決する Manifest への参照です。単なるトークンは ID によって解決されます。つまり参照先 Manifest の metadata.name であり、Release 自身のディレクトリで検索されます。’./’ または ’../’ で始まる値は、Release からの相対パスとして解決される明示的なローカルファイルです。Manifest はデプロイ側のものでカタログにインデックスされないため、Release のディレクトリまたは明示的なパスからのみ解決されます。 |
extends | string | いいえ | この Release がオーサリング面を継承するベース Release への参照です。継承されるのは、境界ツリーとその配下にあるコンポーネントごとの infra および Feature のアタッチメント、パラメーター、アノテーション、そして Manifest ポインターです。値はこの Release と同じ場所にあるファイルへのパスで、’./’ または ’../’ で始まります。Release はデプロイ側のものでカタログにインデックスされないため、単なる名前とレジストリ座標はどちらも拒否されます。継承した内容はキーごとに置き換えることができ、最初の分割不能な値(スカラー、リスト、テンプレート)まで下ると、その値は丸ごと置き換わります。null と記述したキーは継承した内容を削除します。metadata フィールドは引き継がれないため、子は独自の name、version、environment を持ちます。‘extends’ と併せて ‘aggregate’ を宣言することはこのスキーマで拒否されるため、子はベースと同じ Developer Intent をデプロイします。‘manifest’ は任意のままで、依存関係のロックファイルを差し替えるために上書きできます。 |
parameters | object | いいえ | 環境固有の変数を充足する契約で、内容の形状によるディスパッチで 2 つのオーサリングモードを持ちます。モード 1(インライン): 構造化されたネストしたパラメーター値を直接持つ YAML マップ。モード 2(ファイルインポート): ちょうど 1 つのキー $import: ./relative/path.yaml を持つ YAML マップで、パラメーター値を提供する単一のローカルファイルを指します。この箇所では単一ソースのみです。複数ファイルのレイヤリングは Release の extends: チェーンが担います(親 Release がベースのパラメーターを提供し、子が extends して上書きします)。 |
boundaries | boundary のマップ | いいえ | Aggregate のコンポーネントがルーティングされるルートの論理ボックスです。キー: 1 文字以上の英字、数字、アンダースコア、ハイフン。ドットは使用できません。パターン: ^[a-zA-Z0-9_-]+$。 |
components | boundary_component のマップ | いいえ | コンポーネントごとのオペレーター infra を持つトップレベルのコンポーネントインスタンスで、名前付き境界を持たない単一スコープの Release 向けです。boundaries とは相互排他です。フラットな Release には components を、複数ターゲットへのルーティングには boundaries を宣言し、両方を宣言してはいけません。components を使用すると、コンパイラはそれらを保持する default 境界を合成し、その成果物を dist/ にフラットに出力します。キー: 1 文字以上の英字、数字、アンダースコア、ハイフン。ドットは使用できません。パターン: ^[a-zA-Z0-9_-]+$。 |
追加のプロパティは許可されません。
定義
boundary_component
boundary にルーティングされる component インスタンスです。物理的なサイジングと feature のアタッチメントを任意で持ちます。
| プロパティ | 種類 | 必須 | 説明 |
|---|---|---|---|
description | string | いいえ | Release のこの boundary におけるこの component の役割を説明する、任意のドキュメントです。 |
subDirectory | string | いいえ | Component レベルのサブパスの上書きで、親 boundary のディレクトリに追加されます。boundary と component の両方で省略または空の場合、既定値は ’{{ .capability }}’ です。ここに空文字列を書いた場合は省略として扱われます。サブディレクトリの生成を無効にするには、’.’ または空文字列に評価されるテンプレートを設定します。 |
annotations | string、object、または null のマップ | いいえ | Component 固有の Operator アノテーションで、このコンポーネントについて boundary レベルのアノテーションを上書きします。boundary のアノテーションの上にディープマージされます(キーが衝突した場合はコンポーネントが優先され、構造化された値は構造化された親とサブキー単位でマージされます)。値は文字列、構造化オブジェクト、または null です。コンポーネントごとに provider の well-known アノテーションを上書きするために使用します(例: helm provider における aggrega.ai/namespace)。親 boundary から継承したキーに明示的に null を指定すると、継承したバインディングがこのコンポーネントから削除されます(アノテーション駆動の Feature のオプトアウト)。兄弟コンポーネントは継承したバインディングを保持します。 |
infra | object | いいえ | この component に厳密にローカルな物理的サイジングです(例: レプリカ数、ディスク IOPS)。 |
features | object のマップ | いいえ | Release を通じてこの component にアタッチされる Features です。Aggregate でも宣言されている feature については、infra のみを指定します(values は Aggregate から来ます)。Release のみの feature(Operator が注入するもの)では、type が必須です。キーは feature のインスタンス名で、完全な feature type URI を含めることができます(ドットとスラッシュを使用できます)。Release は feature に values を指定してはなりません。これは Developer の領分です。キー: 1 文字以上の英字、数字、アンダースコア、ドット、スラッシュ、またはハイフン。パターン: ^[a-zA-Z0-9_./-]+$。 |
uses | release_uses_block | いいえ | Operator のエッジサーフェスです。Architect が宣言した socket の範囲内で、Release は宣言済みで未バインドの socket を既存の component(target)に接続したり、エッジごとの infra を指定したりできます。values は指定できず(Release の values: 禁止が適用されます)、compute の作成もできません。developer が宣言したエッジの target を変更すると、ビルド時に停止します。 |
追加のプロパティは許可されません。
release_uses_block
Release が記述するエッジごとの uses サーフェスで、socket をキーとし、次に alias をキーとします(Aggregate の uses トポロジーの形を反映しています)。各接続には、target(宣言済みで未バインドの socket へのエッジを作成し、既存の component を指します)、infra(エッジごとの operator 設定で、Release の解決時に socket の infraSchema に対して検証されます)、features(socket が宣言するスロットを埋めるアタッチメント)を任意の組み合わせで設定できます。values は禁止されています(Release の values: 禁止)。developer が宣言したエッジの target を変更すると、ビルド時に明示的なガードレールが働きます。
キー: 1 文字以上の英字、数字、アンダースコア、またはハイフン。ドットは使用できません。パターン: ^[a-zA-Z0-9_-]+$。
値は map of object です。
その他のキーは使用できません。
release_connection_attachment
Release の接続エントリが持つ 1 つのアタッチメントです。接続の socket が宣言するスロットを埋める Feature と、それに対する operator のサイジングから成ります。
| プロパティ | 種類 | 必須 | 説明 |
|---|---|---|---|
type | string | いいえ | Feature の URI です。Release のみが行うアタッチメントでは必須です。両方が宣言している場合は、Aggregate の type と一致する必要があります。 |
description | string | いいえ | Operator がこの feature を接続にアタッチした理由を説明する、任意のドキュメントです。 |
infra | object | いいえ | このアタッチメントの運用上のサイジングで、Feature のスキーマ宣言によって検証されます。 |
追加のプロパティは許可されません。
aggregate_routing
ネストされた Aggregate サブモジュールの内部 component をこの boundary にルーティングします。再帰的な構成のために、boundary の component/aggregate 構造を反映しています。
| プロパティ | 種類 | 必須 | 説明 |
|---|---|---|---|
components | boundary_component のマップ | いいえ | この boundary にルーティングする、ネストされた aggregate 内の Component インスタンスです。キーは各コンポーネントがそのサブモジュール内で持つローカル名です。boundary 自身の components マップが ‘data.main-db’ として指定するコンポーネントであれば ‘main-db’ になります。そこで持つ名前はそれだけだからです。キー: 1 文字以上の英字、数字、アンダースコア、またはハイフン。ドットは使用できません。パターン: ^[a-zA-Z0-9_-]+$。 |
aggregates | map of aggregate_routing | いいえ | このサブ aggregate 内にさらにネストされた aggregate です(深くネストされたモジュール構成のため)。キー: 1 文字以上の英字、数字、アンダースコア、またはハイフン。ドットは使用できません。パターン: ^[a-zA-Z0-9_-]+$。 |
追加のプロパティは許可されません。
boundary
| プロパティ | 種類 | 必須 | 説明 |
|---|---|---|---|
description | string | いいえ | この boundary の目的と物理的なターゲットを説明する任意のドキュメント(例: ‘Primary production EKS cluster in us-east-1, PCI-DSS compliant’)。 |
directory | string | いいえ | GitOps アーティファクト生成のための物理的な出力パスです。Go テンプレート変数({{ .capability }}、{{ .boundary_name }}、{{ .parameters.X }})をサポートします。subDirectory とパス結合され、最終的なアーティファクトパスになります。 |
subDirectory | string | いいえ | directory に付加される boundary レベルのサブパスです。boundary と component の両方で省略または空の場合、CI/CD の自動分割のために ’{{ .capability }}’ がデフォルトになります。ここに書かれた空文字列は省略として扱われます。無効にするには ’.’、または空文字列に評価されるテンプレートを設定します。 |
syncWave | integer | いいえ | boundary ごとの任意のデプロイウェーブ(符号付き整数、デフォルトは 0)です。この boundary 内のすべての component は、boundary のウェーブを自身のノードに継承します。負の値も許可され(他のすべてより先に実行されます)、大きい値は小さい値の後に実行されます。K8s と Helm では、ウェーブがデプロイの順序を決めます。ウェーブは argocd.argoproj.io/sync-wave アノテーションになり、チャートがすでに Helm フックとしてマークしているリソースでは、そのフックの helm.sh/hook-weight にもなります。compose では、ウェーブはサービスラベルとして記録されるとともに、レンダリング先のファイル内のサービス間の depends_on によってそれらのサービスの順序を決めます。そのため、その 1 つのファイル内のすべてのサービスに及び、ファイル外には及びません。cloudformation では、ウェーブは boundary が組み立てられるスタックのプロビジョニング順序を決めます。各ウェーブ内のすべてのリソースは直前のウェーブのリソースに依存すると宣言され、これにより作成される順序と、その逆の削除される順序が決まります。これは作成と削除の順序にすぎません。スタックテンプレートにはリソースが準備完了であるという概念がないため、リソースが利用可能になるのを待つことはありません。terraform では、ウェーブは boundary が組み立てられるルート構成の module ブロックの順序を決めます。各ウェーブ内のすべての module は直前のウェーブの module に依存すると宣言され、これによりエンジンがアクションを実行する順序が決まります。これはアクションの順序にすぎません。構成にはリソースが準備完了であるという概念がないため、リソースが利用可能になるのを待つことはありません。また、この値はノードのビルドの来歴とともに記録されます。コンパイラは同じ値を boundary 内のすべてのノードにそのノードの sync_wave として引き継ぎ、そこでターゲットごとの動作がノード側から改めて説明されています。ネストされた boundary は暗黙には継承しません。それぞれが独自のウェーブを宣言します。 |
annotations | string、object、または null のマップ | いいえ | .context.annotations.release バケットへとカスケードする、boundary 全体の Operator アノテーションです。値は文字列、構造化オブジェクト、または null です。構造化された値はサブキーごとの設定を持ち、構造化された親と深くマージされ(サブキーごと、子が優先)、アノテーション駆動の Feature 展開を通じて流れます。レンダーコンテキストに現れるのはスカラー値のみです。親 boundary から継承したキーに明示的に null を指定すると、この boundary の実効アノテーションセットから継承されたバインディングが削除され(アノテーション駆動の Feature のオプトアウト)、より深い上書きがバインディングを再導入しない限り、この boundary にルーティングされたすべての component に伝播します。 |
features | object のマップ | いいえ | ネストされたすべての component に適用される boundary 全体の feature です(例: デフォルトのセキュリティメッシュ)。feature の uses ブロックは boundary 内のすべての component に投影されるため、共有の依存関係を各 component で繰り返さず、boundary で一度だけ宣言できます。キーは feature インスタンス名で、完全な feature タイプ URI を含めることができます(ドットとスラッシュが使用可能)。キー: 1 文字以上の英字、数字、アンダースコア、ドット、スラッシュ、またはハイフン。パターン: ^[a-zA-Z0-9_./-]+$。 |
boundaries | boundary のマップ | いいえ | ネストされた論理的な boundary です(例: クラスタ内の namespace)。キー: 1 文字以上の英字、数字、アンダースコア、またはハイフン。ドットは使用できません。パターン: ^[a-zA-Z0-9_-]+$。 |
components | boundary_component のマップ | いいえ | Aggregate のどの component をこの boundary に配置するかを指定します。キーは component インスタンス名です。サブ aggregate の component は、修飾されたドット区切りのパスで指定します(例: ‘data.main-db’。aggregate インスタンス名、ドット、component 名)。キー: 1 文字以上の英字、数字、アンダースコア、ドット、またはハイフン。パターン: ^[a-zA-Z0-9_.-]+$。 |
aggregates | map of aggregate_routing | いいえ | ネストされた Aggregate サブモジュールの component をこの boundary にルーティングします。キーは Aggregate の spec.aggregates マップに一致する aggregate インスタンス名です。boundary が定義されている場合、すべての aggregate インスタンスはちょうど 1 つの boundary に配置されなければなりません。キー: 1 文字以上の英字、数字、アンダースコア、またはハイフン。ドットは使用できません。パターン: ^[a-zA-Z0-9_-]+$。 |
追加のプロパティは許可されません。
uses_block
構造的トポロジー - Developer が所有。論理的なネットワークエッジと依存関係を宣言します。
キー: 1 文字以上の英字、数字、アンダースコア、またはハイフン。ドットは使用できません。パターン: ^[a-zA-Z0-9_-]+$。
値は string[] or map of object です。
その他のキーは使用できません。
inject_block
接続上の、非依存の注入ルーティングです。ローカル変数をターゲットの provides キーにマッピングします。各配信メカニズム(env、file、arg、または custom)は {in, from} エントリの配列として記述されます。provides の参照には明示的な ‘from’ を使います。カスタムメカニズムには all 以外の任意の名前を付けられます。テンプレートはすべてのメカニズムを 1 つのビューにマージしたものを .context.inject.all で読むため、その名前のメカニズムはそのビューに隠されてしまい、そうした名前を付けるとビルドが停止します。
| プロパティ | 種類 | 必須 | 説明 |
|---|---|---|---|
env | inject_delivery | いいえ | 単一の配信メカニズムで、エントリの配列として記述されます。各エントリは ‘in’(ローカル識別子:環境変数名、ファイルパス、引数フラグ、またはカスタムメカニズム固有のキー)に加えて、‘from’(解決する provides キー)または ‘value’ のどちらか一方を正確に 1 つ持ちます。Release では、すべてのエントリが接続上にあるため、‘from’ はターゲットの provides に対して解決され、‘value’ を持つエントリは拒否されます。 |
file | inject_delivery | いいえ | 単一の配信メカニズムで、エントリの配列として記述されます。各エントリは ‘in’(ローカル識別子:環境変数名、ファイルパス、引数フラグ、またはカスタムメカニズム固有のキー)に加えて、‘from’(解決する provides キー)または ‘value’ のどちらか一方を正確に 1 つ持ちます。Release では、すべてのエントリが接続上にあるため、‘from’ はターゲットの provides に対して解決され、‘value’ を持つエントリは拒否されます。 |
arg | inject_delivery | いいえ | 単一の配信メカニズムで、エントリの配列として記述されます。各エントリは ‘in’(ローカル識別子:環境変数名、ファイルパス、引数フラグ、またはカスタムメカニズム固有のキー)に加えて、‘from’(解決する provides キー)または ‘value’ のどちらか一方を正確に 1 つ持ちます。Release では、すべてのエントリが接続上にあるため、‘from’ はターゲットの provides に対して解決され、‘value’ を持つエントリは拒否されます。 |
inject_delivery
単一の配信メカニズムで、エントリの配列として記述されます。各エントリは ‘in’(ローカル識別子:環境変数名、ファイルパス、引数フラグ、またはカスタムメカニズム固有のキー)に加えて、‘from’(解決する provides キー)または ‘value’ のどちらか一方を正確に 1 つ持ちます。Release では、すべてのエントリが接続上にあるため、‘from’ はターゲットの provides に対して解決され、‘value’ を持つエントリは拒否されます。
型: object[]