既知のアノテーション
Providers は、プラットフォーム固有のコンテキストを設定するために、特定のアノテーションを読み取ります。これらは Release の境界または Release のコンポーネントエントリに設定されるか、Aggregate 内でサブシステムまたはコンポーネントインスタンスに宣言されます。コンパイラ自体はこれらのアノテーションの値に依存しません。値は不透明な文字列としてそのまま渡されます。各 provider は、どのアノテーションを読み取るか、どのスコープで読み取るか、アノテーションがない場合にどのデフォルトが適用されるかを宣言します。この宣言は provider レンダリングを行う Plugin の spec.provider.wellKnownAnnotations に置かれ、意図的に狭く定められています。provider がキーを列挙するのは、そのキーを読み取る場合に限られます。これらをいずれも読み取らない provider は、代わりに spec.provider.readsNoWellKnownAnnotations: true を宣言します。
この章のサポートマトリクスは、これらの宣言から生成されたものであり、宣言が持つ粒度、つまり provider ごと入力の種類ごとに示されます。provider は、デプロイ単位を合成するときにはキーを読み取れても、ベンダリングされた成果物をレンダリングするときにはそれを読み取る手段を持たないことがあるためです。ここにあるマトリクスに従って記述してください。セルは、その provider がその経路で何を読み取るかを示します。セルは provider が宣言していないことを何も示せないためです。provider 自身のレンダリング動作の契約がレンダリングしない入力の種類を挙げた宣言は、Plugin エンティティの読み込み時に拒否されるため、この 2 つの主張が食い違うことはありません。
予約語彙はより広い集合であり、代わりに 2 か所に置かれています。1 つはこの章で、どの provider も読み取らないものも含め、予約されたすべてのキーを挙げています。もう 1 つは、公開時の lint がチェックする予約プレフィックスの集合です。
不変条件
- コンパイラは、provider のウェルノウンアノテーションの値を解釈も検証もしません。キーとその値をカスケードを通じて運び、ターゲットがそのキーに基づいて動作しない場合に警告します。
- 各 provider は、どの annotation を読み取り、どのデフォルトを適用するかを文書化します。
- annotation はバウンダリ内で一様に適用されます。値が component ごとに異なる場合、その値は component レベルの annotation(バウンダリの annotation を上書きします)か、component の
infraに置きます。 - Provider の well-known アノテーションが component ラベルと重複することはありません。Component ラベルは component が何であるか を記述します。boundary アノテーションは component がどこにデプロイされるか を記述します。
- Recipes は provider の well-known annotation を扱いません。provider は、Recipe がコンテンツを生成した後に、配置コンテキスト(namespace、レジストリプレフィックス、サービスアカウント)を自動的に適用します。
aggrega.ai/プレフィックスは標準ライブラリ用に予約されています。企業独自の annotation は独自のプレフィックスを使用します。- Release 内の Component レベルのアノテーションは、boundary レベルのアノテーションを上書きします(ディープマージで、component 側が優先されます)。provider が複数の boundary の出力を 1 つのアーティファクトに組み立てる場合、その provider は、アノテーションがそれらの boundary 全体で一様に解決されることを要求する場合があります。
helm-chartprovider はアンブレラチャートの名前をaggrega.ai/chart-nameから取得します。複数の boundary が同じチャートに寄与し、それらがこのアノテーションを異なる値に解決した場合、1 つのチャートが 2 つの名前を持つことはできないため、ビルドは不一致の boundary を示して停止します。 - Aggregate が宣言するアノテーションは、Release のアノテーションより低い優先度で同じキーに届きます。サブシステムまたはコンポーネントインスタンスで宣言されたキーは、Aggregate 自体で宣言されたものでも、Aggregate がインポートするモジュール内で宣言されたもの(この場合はモジュール自身のコンポーネントに届きます)でも、Release がそのキーに値を設定していない限り、そのコンポーネントに適用されます。Release が境界またはコンポーネントのエントリで値を設定している場合は、Release の値が適用されます。カタログエンティティ自身のアノテーションがこれを設定することはありません。
aggrega.ai/chart-nameは Aggregate が届く範囲の例外です。これはコンポーネントではなくアセンブリを名付けるものであり、そのアセンブリに寄与する Release の境界から読み取られます。
完全なアノテーションマトリクス
このマトリクスの読み方
以下の 6 つのカテゴリ表は、予約済みの aggrega.ai/ 語彙に含まれるすべてのアノテーションについて、それが何を制御するか、そしてそれがない場合に provider が何を行うかを示します。特定の provider が特定のキーを適用するかどうかは、より細かい問題です。provider は複数の 入力種別 をレンダリングするためです。すなわち、ベンダリングされたアーティファクト(sourced)、provider 自身が合成する Workload(synthesized)、またはノードの出力全体としての Recipe の artifacts:(artifacts-only)であり、あるキーはこれらの経路の一つでは読み取られても、別の経路では到達できないことがあります。どの provider がどの入力種別をレンダリングするかは ../../architecture/16-recipe-input-composition.md にあります。それぞれが何を適用するかは、後述の provider と入力種別ごとのサポート にあり、これがこのページの正式な記述です。
このグリッドの各セルは、次の 3 つの段階のいずれかを持ちます。
- 適用される — provider はこの入力種別でキーを適用し、その結果としてレンダリングされた出力が決定的に変化します。
- 条件付きで適用される — コンパイラはアーティファクトを編集する代わりに、対象アーティファクトの横に追加的なオーバーライドを出力します。そのため、値が効果を持つかどうかは、そのアーティファクトが対応する独自のキーを公開しているかどうかに依存します。実際には効果がありますが、保証ではありません。条件付きセルを実装している provider はなく、宣言の仕組みにもそれを表現する手段がないため、以下の生成されたグリッドには他の 2 つの段階のみが出力されます。この段階に名前を付けているのは、ベンダリングされたアーティファクトに対してこの経路が実際に存在するためであり、2 段階の語彙では、マトリクスは保証できないことを保証すると主張するか、経路の存在自体を否定するかのどちらかを強いられるためです。
- 適用されない — この経路ではどの provider もキーを適用しません。対象にはそこにキーのためのレンダースロットがないため、配置の仕組みはレンダリングされる内容に何も寄与せず、代わりに得られるものはカテゴリ表の デフォルト 列に記載されています。値は不透明な文字列として、変更されずにビルドを通過します。この段階は値の行方ではなく仕組みに基づいて名付けられています。それらは別の問題であり、セルが答えられるのは前者だけだからです。provider が何を適用するかは、その対象のレンダースロットの性質であり、それこそが各セルの背後にある宣言が述べていることです。
スコープは 2 つあり、入力種別が意味のある軸となるのはそのうち一方だけです。
- ノードスコープ —
aggrega.ai/namespace、aggrega.ai/image-registry、aggrega.ai/image-pull-secret、aggrega.ai/service-account、aggrega.ai/kubernetes-versionは、一つのコンポーネント自身のレンダリング出力を形作ります。この出力は、その入力種別が選択する経路によって生成されます。これらがグリッドの列です。 - アセンブリスコープおよび参照スコープ —
aggrega.ai/chart-nameはアンブレラチャートが組み立てられる際に一度だけ解決され、3 つのaggrega.ai/aws-*キーは参照が境界を越える際に解決されます。どちらについても入力種別は軸ではありません。値は、寄与する各ノードがどのようにレンダリングされたかにかかわらず、アセンブリまたは参照の時点で読み取られます。これらには アセンブリごと・参照ごとに解決されるキー に独自の表があります。
カテゴリ 1 — 配置
| アノテーション | 適用元 | 目的 | デフォルト |
|---|---|---|---|
aggrega.ai/namespace | helm(sourced、synthesized)、compose(sourced、synthesized) | Kubernetes の namespace(helm)、Docker ネットワーク名(compose) | 存在しない場合は注入されない(helm)。compose ファイルのパスにちなんで命名され、そのファイル内でアノテーションを持たないすべてのノードが共有するネットワーク(compose) |
aggrega.ai/project-name | 予約済み。どの provider も読み取らない | Docker Compose のプロジェクト名用に予約 | — |
aggrega.ai/region | 予約済み。どの provider も読み取らない | 配置スコープでのクラウドリージョン用に予約 | — |
aggrega.ai/account-id | 予約済み。どの provider も読み取らない | 配置スコープでのクラウドアカウント識別子用に予約 | — |
aggrega.ai/kubernetes-version | helm(sourced) | コンポーネントのデプロイ先クラスタの Kubernetes バージョン。ソースからレンダリングされるチャートは、これを .Capabilities.KubeVersion として読み取ります | 同じ helm リリースの標準の helm template がレンダリング対象とするバージョン。すなわち、provider のビルドに使われた Kubernetes クライアントライブラリのバージョン |
aggrega.ai/namespace は設計上、二つの目的を持ちます。同じ論理的分離の意図 — 「この境界のリソースは、独自のアドレス可能なスコープに存在する」 — を、各対象固有の形式で表現します。helm では Kubernetes の metadata.namespace、compose では Docker のネットワーク名です。Recipe の作成者は一つのアノテーションを設定し、各 provider がそれを対象に応じて適切に具体化します。compose の場合、ネットワーク名はノードごとにそのノードのアノテーションから解決され、ノードにアノテーションがない場合は compose ファイルのパスにフォールバックします。そのため、1 つの compose ファイルを共有するアノテーションのない境界は 1 つのネットワークを共有し、それらを分けるのが aggrega.ai/namespace です。どちらが識別子を提供する場合でも、その識別子は compose のネットワーク名が受け付ける文字で書き出されます。それ以外の文字は置換されるのではなくエスケープとして書き出されるため、少しでも異なる二つの識別子は二つのネットワークに分かれたままとなり、識別子の大文字・小文字は作成時のまま保持されます。compose provider リファレンス では、エンコードされた名前の読み方や名前変更に伴うコストを含め、導出方法を詳しく説明しています。
aggrega.ai/kubernetes-version は、コンポーネントがクラスタ内のどこに配置されるかではなく、デプロイ先クラスタの性質を表します。チャートテンプレートは、レンダリング対象のバージョンによって API バージョン、フィールド、あるいは仕組み全体を選択しますが、ビルドには問い合わせるクラスタがありません。helm provider は、helm template --kube-version がそのフラグを読み取るのと同じ方法で値を読み取り、バージョンでない値に対してはビルドを停止します。値が指定されていない場合、チャートは同じ helm リリースの helm template がレンダリング対象とするバージョン向けにレンダリングされます。helm provider リファレンス では、受け付けられる形式とデフォルトについて説明しています。
カテゴリ 2 — レジストリ
| アノテーション | 適用元 | 目的 | デフォルト |
|---|---|---|---|
aggrega.ai/image-registry | helm、compose — synthesized のみ | コンテナイメージのレジストリプレフィックス。合成されるすべてのコンテナイメージ参照に適用されます | プレフィックスなし |
aggrega.ai/image-pull-secret | helm — synthesized のみ | Kubernetes の imagePullSecrets 名。合成される Pod の既存のエントリに和集合として追加されます | なし |
カテゴリ 3 — ネットワーク
| アノテーション | 適用元 | 目的 | デフォルト |
|---|---|---|---|
aggrega.ai/cluster-domain | 予約済み。どの provider も読み取らない | namespace をまたぐサービスディスカバリ用の DNS サフィックスとして予約 | — |
aggrega.ai/ingress-class | 予約済み。どの provider も読み取らない | Ingress リソース上の Kubernetes IngressClass 用に予約 | — |
aggrega.ai/service-mesh | 予約済み。どの provider も読み取らない | メッシュのサイドカー注入アノテーション用に予約 | — |
カテゴリ 4 — セキュリティ
| アノテーション | 適用元 | 目的 | デフォルト |
|---|---|---|---|
aggrega.ai/service-account | helm — synthesized のみ | 合成される Pod の Kubernetes ServiceAccount。両方が設定されている場合、Recipe の workload.serviceAccount をオーバーライドします | Recipe の workload.serviceAccount。Recipe が何も宣言しない場合は未設定 |
aggrega.ai/pod-security-standard | 予約済み。どの provider も読み取らない | Pod Security Standards のレベル用に予約 | — |
aggrega.ai/iam-role | 予約済み。どの provider も読み取らない | ワークロードに紐付けられるクラウド ID ロール用に予約 | — |
カテゴリ 5 — パッケージング
| アノテーション | 適用元 | 目的 | デフォルト |
|---|---|---|---|
aggrega.ai/chart-name | helm-chart — アセンブリごと | アンブレラチャート名 | Aggregate 名とアンブレラのアセンブリパスを結合したもの。チャート名の解決を参照 |
aggrega.ai/chart-version | 予約済み。どの provider も読み取らない | Helm チャートのバージョン用に予約 | — |
aggrega.ai/stack-name | 予約済み。どの provider も読み取らない | 明示的に名前を付けたスタック用に予約 | — |
aggrega.ai/tf-backend | 予約済み。どの provider も読み取らない | Terraform の state バックエンド識別子用に予約 | — |
カテゴリ 6 — クラウドターゲット
| アノテーション | 適用元 | 目的 | デフォルト |
|---|---|---|---|
aggrega.ai/aws-account | cloudformation — 境界をまたぐ参照ごと | スタック(境界)のデプロイ先となる AWS アカウント | 同一アカウント — スタック間参照は同一アカウントのスタックエクスポートのインポートによって解決されます |
aggrega.ai/aws-region | cloudformation — 境界をまたぐ参照ごと | スタック(境界)のデプロイ先となる AWS リージョン | 同一リージョン — スタック間参照は同一リージョンのスタックエクスポートのインポートによって解決されます |
aggrega.ai/aws-assume-role-arn | cloudformation — 境界をまたぐ参照ごと | クロスアカウントのスタック読み取りが、ピアスタックのエクスポート値にアクセスするために引き受ける IAM ロール ARN | クロスアカウント参照にロールは指定されません |
各 CloudFormation 境界は一つのスタックにレンダリングされます。uses エッジがある境界から別の境界へまたがる場合、cloudformation provider は参照を形作るために、ピアスタックがどこにあるかを知る必要があります。同じアカウントおよびリージョンにある二つのスタックは、スタックのエクスポートとインポートを通じて値を交換します。異なるアカウントまたはリージョンにあるピアには、クロスアカウントのスタック出力の読み取りが必要で、必要に応じて引き受けたロールの下で行われます。これらのアノテーションがその配置コンテキストを伝えます。各アノテーションは、provider がそのような参照を形作る時点で読み取られ、その時点で通常のアノテーションカスケードを通じて解決されます。コンポーネントに設定された値は境界に設定された値より優先され、Release が設定した値は Aggregate が宣言した値より優先されます。したがって、境界レベルの値はこれらを表現する一般的な方法ですが、唯一の方法ではありません。これらは不透明なスカラーのポインタ文字列です。provider はこれらを構築する参照にそのまま渡し、稼働中の AWS の状態に対して解決することはありません。アカウント、リージョン、ロールは Release によって提供されるか Aggregate で宣言され、最終的な物理的な読み取りは実行環境が解決します。すべてのアノテーションがない場合、provider はピアを同一アカウントかつ同一リージョンとして扱い、ロールを指定しません。
provider と入力種別ごとのサポート
ノードスコープのキーを、provider ごと・入力種別ごとに示します。列見出しでは、すべてのキーに付く aggrega.ai/ プレフィックスを省略しています。applied と — は前述の段階を表し、— は適用されないことを意味します。n/a は provider がその入力種別をまったくレンダリングしないことを意味し、そのためキーが適用される、あるいは適用されない経路自体がそこには存在しません。
| Provider | 入力種別 | namespace | image-registry | image-pull-secret | service-account | kubernetes-version |
|---|---|---|---|---|---|---|
helm | sourced | applied | — | — | — | applied |
helm | synthesized | applied | applied | applied | applied | — |
helm | artifacts-only | — | — | — | — | — |
compose | sourced | applied | — | — | — | — |
compose | synthesized | applied | applied | — | — | — |
compose | artifacts-only | — | — | — | — | — |
helm-chart | sourced | — | — | — | — | — |
helm-chart | synthesized | n/a | n/a | n/a | n/a | n/a |
helm-chart | artifacts-only | n/a | n/a | n/a | n/a | n/a |
terraform | sourced | — | — | — | — | — |
terraform | synthesized | n/a | n/a | n/a | n/a | n/a |
terraform | artifacts-only | — | — | — | — | — |
cloudformation | sourced | — | — | — | — | — |
cloudformation | synthesized | n/a | n/a | n/a | n/a | n/a |
cloudformation | artifacts-only | — | — | — | — | — |
コンパイラとともに配布されるすべての provider がここに行を持ちます。配置アノテーションをまったく読み取らない provider も含まれます。行が空では、まだ誰も記述していない provider と区別できないためです。別途提供される provider も同じ方法で読み取る内容を宣言しますが、ここには記載されません。公開されたページは、見たことのない provider を列挙できないためです。
Recipe は複数の入力種別を同時に宣言できます。たとえば、workload: と並べて artifacts: を宣言する場合です。グリッドは種別ごとに読んでください。そのようなノードの合成された出力は synthesized 行、アーティファクトファイルはアーティファクトの場合に該当します。artifacts-only 行は、Recipe が artifacts: だけを宣言する入力種別です。
確認のためにグリッドを参照する必要はありません。 あるレンダーの対象が、そのレンダーのどの入力種別でも読み取らないキーを設定すると、キー、対象、そのレンダーが宣言するすべての入力種別を示す警告が出力されます。そのため、誤って該当してしまったセルは、ここを確認しようと思い立つのを待つことなく、ビルドした時点で明らかになります。
warning: node "frontend" (provider "helm-chart"): target "helm-chart" does not support annotation aggrega.ai/namespace on sourced input and ignored it複数の入力種別を宣言するレンダーでは、警告はその一部ではなく、レンダー全体に関するものです。 種別は加算的に組み合わされるため、いずれか一つの種別で対象がキーを読み取れば、キーは実際に適用され、そのレンダーの出力に結果が反映されます。そのため警告は発生しません。警告は、そのレンダーが宣言するすべての種別でキーが適用されない場合にのみ表示され、それらすべてを示します。
warning: node "backend" (provider "helm"): target "helm" does not support annotation aggrega.ai/cluster-domain on sourced or synthesized input and ignored itしたがって、source: と並べて workload: を宣言するだけで、そのノードで aggrega.ai/service-account が効果を持つようになり、ビルドはそれについて何も報告しません。値は合成される側に届き、出力されるマニフェストに現れるため、これは正確な報告です。
グリッドはコンポーネントごとではなく、レンダーごとに読んでください。 ノードに付加された feature は、自身の FeatureRecipe が指定する対象を通じ、その FeatureRecipe が宣言する入力種別でリソースを生成します。そのため、このグリッドの独自の行に該当し、それはホストコンポーネントが該当する行と同じとは限りません。Workload を合成するコンポーネントに、付加された feature が artifacts: を追加する場合、コンポーネント自身のマニフェストには synthesized 行、付加物のファイルには artifacts-only 行が該当し、前者で適用されるキーが後者では適用されないことがあります。警告も同じように分かれ、それぞれについて個別に通知します。両者は異なるファイルだからです。名前付きコンポーネントではなく境界に付加された feature も、同じようにグリッドを読みます。
値は変更されずにそのまま通過し、ビルドは停止しません。異種の対象にまたがるコンポーネントを含む境界には、特定のキーに対応できないレンダーが必ず存在し、それは誤りではなく通常の Release だからです。境界のアノテーションはカスケードするため、記述した 1 行から、それに対応できないレンダーごとに一つの警告が生成されます。これにより、出力のどの部分が影響を受けるかがわかります。この警告は unsupported-field クラスに属し、そのクラスのフラグで抑制できます。詳細は 警告 を参照してください。知っておくべき制限が二つあります。チェックされるのは素の aggrega.ai/ キーのみです。サブプレフィックス付きのキーは独自の語彙だからです。また、サポートの宣言をまったく持たない provider は警告を生成しません。記述した内容と比較する対象がないためです。これらのキーをいずれも読み取らないと宣言する provider は、このようには沈黙しません。その Plugin エンティティ上の readsNoWellKnownAnnotations: true はどのキーも対象としないサポートの宣言であるため、そのレンダーのいずれかに到達する素のキーはすべて警告の対象になります。terraform provider はこれを宣言しています。
ベンダリングされたアーティファクトで適用されるキーが少ない理由。 ノードスコープのアノテーションは、provider がそのためのレンダースロットを持つ場所で適用されます。provider がデプロイメント単位を自ら合成する場合、結果のすべてのフィールドを所有するため、レジストリプレフィックス、プルシークレット、サービスアカウントのいずれにも反映先があります。一方、ベンダリングされたアーティファクト(Helm チャート、compose ファイル、Terraform モジュール)は独自の設定インターフェースを持ち、コンパイラはそのインターフェースを読み取らないため、レジストリプレフィックスやサービスアカウントがアーティファクトのどのキーに対応するかを知ることができません。周囲のレンダー呼び出しが制御する配置は引き続き適用されます。そのため、ソースからレンダリングされるチャートには aggrega.ai/namespace が適用されます。他者のアーティファクト内のどこに値が属するかを決めることになる配置は適用されず、作成者はそのアーティファクト自身の values を通じて指定します。sourced 行がまばらで synthesized 行が埋まっているのはこのためであり、今後追加されるキーについても同じ形が想定されます。
アセンブリ単位および参照単位で解決されるキー
同梱のキーのうち 4 つはノードスコープではないため、上のグリッドに組み込まず、その外に置いています。これらのキーにとって入力の種類は意味のある軸ではなく、入力の種類ごとに行を設けると 1 つのセルを 3 回繰り返すことになり、存在しない区別があるかのように見えてしまいます。各キーは boundary スコープを宣言しており、下の表はその宣言から生成されています。
| アノテーション | 適用元 | 目的 | デフォルト |
|---|---|---|---|
aggrega.ai/chart-name | helm-chart | アセンブルされるアンブレラ Helm チャートの名前。 | Aggregate 名と、アンブレラチャートのアセンブリパス(dist/ 配下の出力ディレクトリ。例: boundaries/data/helm-chart)が使用され、それぞれエンコードされて連結されます。 |
aggrega.ai/aws-account | cloudformation | スタック(boundary)のデプロイ先となる AWS アカウント。boundary をまたぐ参照は、ピアのスタックが同じアカウントにあるかどうかを判断するためにこれを読み取ります。 | ピアは同一アカウントとして扱われ、スタック間参照はクロスアカウントのスタック出力読み取りではなく、同一アカウントのスタックエクスポートのインポートを通じて解決されます。 |
aggrega.ai/aws-region | cloudformation | スタック(boundary)のデプロイ先となる AWS リージョン。boundary をまたぐ参照は、ピアのスタックが同じリージョンにあるかどうかを判断するためにこれを読み取ります。 | ピアは同一リージョンとして扱われ、スタック間参照は同一リージョンのスタックエクスポートのインポートを通じて解決されます。 |
aggrega.ai/aws-assume-role-arn | cloudformation | クロスアカウントのスタック読み取りが、ピアのスタックのエクスポート値にアクセスするために引き受ける IAM ロール ARN。 | ロールは指定されず、クロスアカウント参照は assume-role を持ちません。 |
各キーが解決されるタイミングは、宣言自体には含まれません。aggrega.ai/chart-name はアンブレラチャートのアセンブリごとに 1 回、boundary のアノテーションカスケードから解決されます。1 つのアセンブリに寄与するすべてのものは同じ値に解決されなければならず、値が一致しない場合は該当する boundary を示してビルドが停止します。3 つの aggrega.ai/aws-* キーは、component が boundary より優先される順位のもとで boundary をまたぐ参照ごとに解決されるため、component の値が boundary の値より優先されます。各キーが形作る参照については上の Category 6 で説明しています。
どの provider も読み取らない予約名
上のマトリクスでは 11 個のキーが予約済み。どの provider も読み取らないとされています: aggrega.ai/project-name、aggrega.ai/region、aggrega.ai/account-id、aggrega.ai/cluster-domain、aggrega.ai/ingress-class、aggrega.ai/service-mesh、aggrega.ai/pod-security-standard、aggrega.ai/iam-role、aggrega.ai/chart-version、aggrega.ai/stack-name、aggrega.ai/tf-backend。
これらを Release または Aggregate に設定してもレンダリング出力には影響しません。どの provider もこれらを読み取らず、代わりにデフォルトが適用されることもありません。特に、aggrega.ai/cluster-domain に対して DNS サフィックスは適用されないため、クラスタドメインを必要とする Recipe はこのアノテーションに頼らず、通常の値として指定する必要があります。これらの動作のいずれかを必要とする Recipe の作成者は、それを Recipe の値または component の infra フィールドとして表現します。
これら 11 個を宣言している provider はありません。 provider の wellKnownAnnotations には
その provider が読み取るものだけが列挙されるため、11 個のいずれもそこには現れません。
helm、helm-chart、compose、cloudformation の Plugin を開いた読者には、機能するキーだけが見え、
それ以外は見えません。これが狭い宣言の意図です。宣言されたキーは機能するキーであり、その横のスコープがどの経路で機能するかを示します。
予約名のうち 2 つは有効なキーと似ていますが、互換ではありません。aggrega.ai/region と aggrega.ai/account-id は配置スコープでリージョンとアカウントを指すもので、どの provider にも届きません。cloudformation provider が読み取るのは、Category 6 にあるクラウド名前空間付きの aggrega.ai/aws-region と aggrega.ai/aws-account です。CloudFormation のスタック間配置コンテキストを意図する場合は、aws- 形式を記述してください。接頭辞のないペアは衝突を避けるために確保されているだけで、何にも接続されていません。さらに 2 つの予約名は、アノテーションではなく別の仕組みで扱われています: aggrega.ai/stack-name は予約されていますが、cloudformation boundary のレンダリング先となるスタック名は release と boundary の識別情報から決定的に導出されます。また、workload のクラウド ID ロールは、aggrega.ai/iam-role を通じてではなく、バインディングを出力する Feature 上の通常のオペレーター設定フィールドとして指定されます。
これらの名前が引き続き予約され、引き続きここに記載されているのは、aggrega.ai/ 接頭辞が予約されているためです。エンタープライズカタログは、これらのキーを独自の意味で再利用してはなりません。プラットフォームがそのキーを独自の意味のために確保しているためです。このマトリクスと、公開時の lint がチェックする予約接頭辞セットが合わせて予約台帳となっており、両者は両方を読み取って食い違いがあれば失敗するチェックによって同じ名前のセットに保たれています。したがって、11 個のいずれかを記述しても、検証に失敗することも、「接頭辞のない aggrega.ai/ 接頭辞を使用しない」というルールに抵触することもなく、単に効果がないだけです。
helm-chart boundary が出力するアンブレラチャートのバージョンは常に 0.1.0 です。これは aggrega.ai/chart-version のデフォルトではなく、固定値です。
注:
aggrega.ai/接頭辞を使う Manifest のfeatures.annotationsバインディングは、読み込み時に拒否されます。この接頭辞は、 本章で説明する provider のウェルノウンアノテーション専用に予約されています。 アノテーション駆動の Feature バインディングの作成者は、標準ライブラリのショートカットにはfeature.aggrega.ai/を、 エンタープライズのショートカットには独自ドメインを 使用します。注: Release のアノテーションに明示的な
nullを指定すると、上書きする boundary または component から 継承されたバインディングが削除されます(アノテーション駆動の Feature のオプトアウト)。同じ boundary 内でオプトアウトしていない 兄弟 component は継承されたバインディングを保持し、指定されていないキーは 通常どおり親のカスケードから継承され続けます。
コンパイラが読み取るカタログ記述のアノテーション
ここまでに挙げたものはすべて provider アノテーションです。Release 上に記述されるか Aggregate 内で宣言され、コンパイラによって不透明な文字列としてそのまま渡され、provider によって読み取られます。2 つ目の、はるかに小さな語彙は逆方向に働きます。Architect が カタログエンティティ自身の metadata.annotations に記述し、コンパイラ が読み取り、provider からは一切見えません。上記の不変条件 1 は provider の語彙に関するものであり、これらには適用されません。コンパイラはここに挙げたキーだけを読み取り、それ以外は読み取りません。
これらのキーは裸の aggrega.ai/ プレフィックスではなく <scope>.aggrega.ai/ サブプレフィックスの下に置かれるため、上記のマトリクスが保持する予約台帳の対象外であり、公開時の lint が裸のプレフィックスのキーに適用する予約プレフィックスのルールの対象外でもあります。
| アノテーション | 記述先 | 読み取り元 | 目的 |
|---|---|---|---|
features.aggrega.ai/requiredType.<label> | Component の metadata.annotations | コンパイラ(確定後のグラフに対して) | 存在の義務付け を宣言します。この Component のすべてのインスタンスは、型がアノテーションの値と等しいアタッチメントを少なくとも 1 つ持たなければなりません。<label> は作成者が選ぶサフィックスで、診断メッセージで要件を識別するためのものです。スロット名ではなく、何もこれを参照解決しません。複数の義務付けを宣言するには、異なるラベルでキーを繰り返します。 |
この義務付けは、どのスコープのアタッチメントでも満たされます。コンポーネントレベルまたはサブシステムレベルの features: ブロック、Release の boundary レベルまたはコンポーネントレベルのブロック、あるいはアノテーション駆動の展開のいずれでも構いません。これは、各アタッチメントがどこから来たかではなく、インスタンスの最終的なアタッチメント集合を検査するためです。義務付けが満たされない場合、ラベルと必要な型を示してビルドが停止します。値が Feature の型 URI でない場合、またはプレフィックスの後にラベルのないキーの場合は、別個の不正な宣言の診断で停止します。記述方法の詳細と、義務付けが featuresSchema スロットとどう異なるかについては、entities/component.md の「Presence mandates」を参照してください。
プロバイダーが出力する来歴ラベル
上記のアノテーションはビルドの中へ流れ込みます。Release または Aggregate がそれらを記述し、provider がそれらを消費します。Providers はさらに、ビルドの外へ向かう並行したラベルのセットも出力し、それらをレンダリングされた出力に付与します。これにより、下流のツールはランタイムリソースを、それを生成したカタログのコンテンツへと遡って特定できます。これらの来歴ラベルは Release 上で記述されるものではありません。ビルド自身の状態(Recipe の識別子、境界パス、aggregate 名、環境、sync wave、コンパイラのバージョン)から導出され、レンダリング時に provider によって出力されます。
provider が出力するセットで、helm provider がレンダリングするすべての Kubernetes マニフェスト、helm-chart provider がサブチャートに追加する $import: で読み込まれたすべての artifact、そして compose が出力するすべてのサービスに付与されます。helm-chart のサブチャート自身のテンプレートは作成者が書いたとおりにコピーされるため、その作成者が書いた内容をそのまま持ちます:
| ラベル | ソース | 出力 |
|---|---|---|
app.kubernetes.io/name | ノード ID(FeatureRecipe が出力するリソースの場合は、そのアタッチメントに対して導出された識別子。後述を参照) | helm と helm-chart のみ。Kubernetes 標準のラベルであり、compose のサービスには出力されません |
aggrega.ai/component-id | ノード ID(FeatureRecipe が出力するリソースの場合は、そのアタッチメントに対して導出された識別子。後述を参照) | 3 つのプロバイダーすべて |
aggrega.ai/recipe-uri | 生成元の Recipe(FR が出力したリソースの場合は生成元の FeatureRecipe)の <recipe-name>:<recipe-version> | 3 つのプロバイダーすべて。生成元のエンティティに名前とバージョンの両方が設定されている場合。helm と helm-chart ではアノテーション |
aggrega.ai/boundary-path | コンポーネントのルーティング先の境界パス | 3 つのプロバイダーすべて。境界パスが空でない場合。helm と helm-chart ではアノテーション |
aggrega.ai/aggregate-name | Aggregate の metadata.name | 3 つのプロバイダーすべて。設定されている場合 |
aggrega.ai/compiler-version | ビルド時に刻印されるコンパイラのバージョン | 3 つのプロバイダーすべて。設定されている場合 |
aggrega.ai/provider | リソースをレンダリングした provider | 3 つのプロバイダーすべて |
aggrega.ai/provider-version | その provider のバージョン | 3 つのプロバイダーすべて |
aggrega.ai/environment | Release の metadata.environment | 3 つのプロバイダーすべて。すべての Release がこれを宣言します |
aggrega.ai/sync-wave | 境界ごとの syncWave 整数値 | 3 つのプロバイダーすべて。0 以外の場合。helm と helm-chart ではアノテーション |
aggrega.ai/aggregate-name、aggrega.ai/environment、aggrega.ai/compiler-version、aggrega.ai/provider、aggrega.ai/provider-version の値は、ビルドが Kubernetes のラベル値の規則に従わせない文字列から来ます。たとえば imported/flow という名前の Aggregate、eu/prod という名前の環境、開発ビルドの (devel) バージョンです。helm と helm-chart では、値がすでに有効なラベル値である場合、これらの各ラベルは値を書かれたとおりに保持します。有効なラベル値とは、英字、数字、-、_、. からなり、両端が英字または数字で、最大 63 文字のものです。そうでない場合、ラベルはその形式に書き換えられた値を保持し(それ以外の各文字は - になり、連続する - は 1 つにまとめられ、両端は英字または数字まで切り詰められ、結果は最大 63 文字に切り詰められます)、書かれたとおりの値が同じキーのアノテーションとして追加されます。したがって、imported/flow という名前の Aggregate には aggrega.ai/aggregate-name: imported-flow というラベルと aggrega.ai/aggregate-name: imported/flow というアノテーションが付きます。ラベルが保持する文字を 1 つも含まない値は、アノテーションだけで保持されます。セレクターはレンダリングされた出力に現れるとおりのラベル値に一致し、正確な名前を必要とするツールは、アノテーションがある場合はそれを読み取ります。ラベル値に制約のない Compose は、書かれたとおりの値をラベルとして保持します。
プロバイダーごとの出力に関する注記
helm— ラベルは、レンダリングされたすべての Kubernetes リソース(Deployment、Service、PVC など)のmetadata.labelsに付与され、ラベル値では保持できないキー(aggrega.ai/recipe-uri、aggrega.ai/boundary-path、aggrega.ai/sync-wave、および上述のとおり書き換えられたラベルの書かれたとおりの値)はmetadata.annotationsに付与されます。ソースモード(ポストレンダーでのラベル注入を伴う Helm SDK によるレンダリング)、合成モード(ワークロードの合成)、artifacts:のいずれのパスでも、同じセットが生成されます。helm-chart— 同じラベルとアノテーションが、provider がサブチャートのtemplates/に追加する、$import:で読み込まれた各 artifact に付与されます。ソースチャート自身のテンプレートと、サブチャートのルートに置かれたインラインコンテンツの artifact には、いずれも付与されません。helm-chart.md を参照してください。compose— ラベルは、出力されたすべての compose サービスのservices.<name>.labelsに付与されます。ソースモード(マージされたベースと valuesMapping ドキュメントに対するマージ後のラベル注入)と合成モード(ワークロードの合成がサービスの labels ブロックを直接設定)のどちらでも、同じセットが生成されます。Kubernetes 固有のapp.kubernetes.io/nameは compose の出力からは省かれます。
FeatureRecipe が出力するリソースの場合、aggrega.ai/component-id の値はホストコンポーネントの名前ではなくアタッチメントから構築されます。これは FeatureRecipe がそれらのリソースを提供するあらゆる方法に当てはまるため、アタッチメントのリソースがラベルによってホストコンポーネント自身のリソースと区別できなくなることはありません。その識別情報がそれらのリソースの名前の基にもなるかどうかは、提供方法によって異なります。Aggrega が合成するワークロードはその識別情報に基づいて命名されますが、アタッチメントの作成者が提供したチャートやフラグメントは、ホストコンポーネントの Helm リリース名と出力ファイルのプレフィックスを維持します。作成者自身のテンプレートがその名前に対してレンダリングされるためです。値の構成方法、すなわち 2 つの書き出し、各部分とその -- による結合、ラベルが保持できない文字の書き表し方、対象に対して長すぎる値の短縮方法、そしてどの名前の基になり、どの名前の基にならないかは、プロバイダーに依存しません。そのため、ここでは繰り返さず、vocabulary/labels-and-annotations.md の「Provenance labels emitted on rendered output」で一度だけ説明しています。このページが扱うのはもう半分、すなわち各プロバイダーのレンダリング出力のどこにラベルが付与されるかです。
aggrega.ai/recipe-uri は、消費側の Recipe の識別情報ではなく、FeatureRecipe 自身の name:version に解決されます。生成元のエンティティを特定するためにこのラベルを読む下流のツールは、コンポーネントが出力したものと FR が出力したもののどちらについても正しい来歴を得られます。
Sync-wave アノテーション
上記の aggrega.ai/sync-wave キーは、下流のツールが適用する順序を決めるために読み取る sync-wave アノテーションと対になっています。compose ではこのキーはラベルであり、セレクタクエリ用に wave の値を公開します。helm と helm-chart ではアノテーションであり、対になるアノテーションは各ツールが慣例として読み取る場所にその値を示します。
| アノテーション | 出力 | 使用するツール |
|---|---|---|
argocd.argoproj.io/sync-wave | helm(レンダリングするすべての Kubernetes リソースに付与)と helm-chart($import: で読み込まれた各 artifact に付与)。寄与する境界で syncWave が 0 以外である場合 | ArgoCD の sync-wave による順序付け |
helm.sh/hook-weight | helm のみ。syncWave が 0 以外の場合に、すでに helm.sh/hook アノテーションを持つチャートテンプレート由来のマニフェストに付与 | フックフェーズ内での Helm の hook-weight による順序付け |
helm.sh/hook-weight の出力は経路に依存する
chart の作成者が注意すべき細かな点があります。helm.sh/hook-weight は、chart テンプレート経由のパス、つまり Helm SDK でレンダリングされる chart の templates/ ディレクトリを通じてレンダリングされたマニフェストにのみ出力されます。artifacts パス(helm provider では Recipe の artifacts: ブロックの各エントリで、インラインのコンテンツか $import: で読み込まれたものかを問いません。helm-chart では $import: で読み込まれたエントリ)を通じて生成された Manifests には、argocd.argoproj.io/sync-wave アノテーションと来歴ラベルの全セットが付与されますが、helm.sh/hook-weight は付与されません。これは artifact が helm.sh/hook アノテーションを持つ場合も同様です。
この違いは構造的なものです。helm.sh/hook と helm.sh/hook-weight は、チャートテンプレート由来のフックリソースに適用される Helm ランタイムの順序付けプリミティブです。Recipe 作成者のアーティファクトは Recipe の層で宣言される追加のリソースであり、デフォルトでは Helm のフックのライフサイクルには参加しません。
フックリソースに Helm の hook-weight による順序付けが必要な場合は、そのリソースを artifacts: のエントリとしてではなく、helm provider がレンダリングする Recipe の source: ディレクトリ配下のチャートテンプレートとして作成してください。helm-chart のサブチャートのテンプレートは書かれたとおりにコピーされ、どちらのアノテーションも付与されません。チャートテンプレートには、寄与する境界の syncWave の値に一致する argocd.argoproj.io/sync-wave と helm.sh/hook-weight の両方が付与されます。
記述例
境界レベルの配置とレジストリ設定:
spec: boundaries: production: annotations: aggrega.ai/namespace: prod-east aggrega.ai/image-registry: registry.corp.com aggrega.ai/image-pull-secret: corp-registry-creds components: api: {} worker: {}コンポーネントごとのオーバーライド(同じアノテーションキーでは、コンポーネントが境界より優先されます):
spec: boundaries: production: annotations: aggrega.ai/namespace: prod-east components: api: {} legacy-thing: annotations: aggrega.ai/namespace: legacy-east # override — this component deploys elsewhereAggregate 側のアノテーションのカスケード
アノテーションは Aggregate のオーサリング面にも存在します。サブシステムのスコープ(spec.subsystems.<name>.annotations)と、コンポーネントインスタンスのスコープ(spec.subsystems.<name>.components.<name>.annotations、またはトップレベルのコンポーネントの場合は spec.components.<name>.annotations)です。Aggregate 側のカスケードは、Developer が記述したアノテーションをサブシステムのツリーを通じて、含まれるコンポーネントへと伝えます。
カスケードのルール
サブシステムレベルのアノテーションは、そのサブシステムのサブツリー内にあるすべてのネストされたサブシステムと、含まれるすべてのコンポーネントに伝播します。より近いレベルのアノテーションは、キー単位の粒度で外側のレベルのアノテーションを上書きします。コンポーネントレベルのアノテーションは、同じキーについて継承されたサブシステムレベルのアノテーションを上書きしますが、兄弟のキーや兄弟のコンポーネントには影響しません。
スコープにおけるアノテーションキーは、次の 3 つの状態のいずれかです:
- キーなし — そのスコープはこのアノテーションに値を宣言しません。ネストされたサブシステムと含まれるコンポーネントは、祖先スコープからバインディングを継承します。
- 文字列値 — そのスコープは値を宣言します。ネストされたサブシステムと含まれるコンポーネントは、独自の値を宣言するかオプトアウトしない限り、この値を継承します。
- 明示的な YAML
null— そのスコープは、このキーについて継承されたバインディングをサブツリーから取り除きます。兄弟のコンポーネントと兄弟のサブシステムはそれぞれ独立した継承を保持し、バインディングを失うのはオプトアウトしたスコープのサブツリーだけです。
spec: subsystems: data: annotations: feature.myco/db-pool: "shared-pool" # propagates to api and worker components: api: # inherits feature.myco/db-pool: "shared-pool" worker: annotations: feature.myco/db-pool: null # opts out for this component only special: annotations: feature.myco/db-pool: "vip-pool" # closer-level overrideAggregate で宣言された Provider アノテーション
上のマトリクスのキーは Aggregate を通じてもカスケードし、プロバイダーはカスケードが各コンポーネントに残したものを適用します。サブシステムの aggrega.ai/namespace はその配下のすべてのコンポーネントの配置先を決め、コンポーネントインスタンス自身の値は代わりにそのコンポーネントの配置先を決めます。Aggregate がインポートするモジュールは独自のカスケードを持ちます。そのサブシステムとコンポーネントインスタンスはモジュール自身のコンポーネントに届き、インポートする側の Aggregate が宣言するものはモジュールの内部には一切届きません。
Release はすべてのキーにおいて Aggregate より上位にあります。Release がコンポーネントに対してキーを設定している場合(その境界、またはコンポーネント自身のエントリーで)は Release の値が適用され、設定していない場合は Aggregate の値が適用されます。両者はキーごとに重なるため、aggrega.ai/namespace だけを設定する Release は、Aggregate が宣言した aggrega.ai/image-registry を有効なまま残します。
Release 内の明示的な null は、Release 自身の値だけを取り消します。aggrega.ai/namespace: null と記述したコンポーネントエントリーは、その Release の境界が渡すはずだった名前空間を取り除き、コンポーネントはその Aggregate が宣言する値を受け取ります。Aggregate も宣言していない場合は値を持ちません。Release は Aggregate が宣言した値を取り除くことはできず、その上に自身の値を設定できるだけです。
# Aggregatespec: subsystems: billing: annotations: aggrega.ai/namespace: billing # api and worker render into billing components: api: type: core/server:1.0.0 worker: type: core/server:1.0.0 annotations: aggrega.ai/namespace: billing-batch # worker renders into billing-batch# Releasespec: boundaries: production: components: api: annotations: aggrega.ai/namespace: prod-billing # the Release's value wins: api renders into prod-billing worker: {}aggrega.ai/chart-name は、この範囲の外にある唯一のキーです。これは複数のコンポーネントから組み立てられるアンブレラチャートの名前を指定するため、コンポーネントのアノテーションからではなく、常にそのチャートに寄与する Release の境界から読み取られます。
Recipe または FeatureRecipe のテンプレートは、アノテーションのバケットを名前で読み取ります。.context.annotations.aggregate、.context.annotations.release、.context.annotations.catalog はそれぞれ、その側が記述したものを保持します。そのため、1 つのバケットから配置キーを読み取るテンプレートは、その側の値だけを参照します。
サイドとピラーの区分
Aggregate-as-Authoring-Surface の不変条件により、Aggregate 側のアノテーションは values ピラーに制限されます。Manifest のアノテーションバインディングは、maps.infra(Release 側のルーティング)または maps.values(Aggregate 側のルーティング)の下にルーティングパスを宣言します。バインディングが maps.infra のパスだけを宣言している Aggregate 側のアノテーションは、アノテーションキー、ルーティング先のピラー、オーサリング側を示す明確な診断とともにビルドを停止します。Release 側にも対称的なルールが適用されます。Release 側のアノテーションは maps.infra を通じてのみルーティングでき、values のみのバインディングに対する Release 側のアノテーションは対応するエラーを発生させます。各診断は、アノテーションの値が記述されたドキュメントのドメインに分類されます。Aggregate からなら [DEVELOPER_ERROR]、Release からなら [OPS_ERROR] です。これにより、先頭の表示が開くべき面を示します。
両方のピラーにパスを宣言するバインディングは、各パスでサイドに適合する部分集合をルーティングします。Aggregate 側のアノテーションは values ピラーのパスのみを、Release 側のアノテーションは infra ピラーのパスのみを発火させます。サイドをまたぐ合成(Aggregate からの values、Release からの infra)では、(Component, Feature) のペアごとに 1 つの Feature アタッチメントが生成され、両方のピラーが埋められ、リーフごとの来歴にはどちらのサイドが各リーフを提供したかが記録されます。
オーサリング例 — サブシステムのアノテーションを values にルーティングする
# Manifest bindingspec: mappings: features: type: core/db-pool: db-pool-helm:1.0.0 annotations: feature.myco/db-pool: feature: core/db-pool:1.0.0 maps: values: - pool # routes to values.pool# Aggregatespec: subsystems: data: annotations: feature.myco/db-pool: "shared-pool" components: api: type: core/server:1.0.0 worker: type: core/server:1.0.0アノテーションの展開後、api と worker はどちらも合成された feature.myco/db-pool Feature アタッチメントを持ち、その values.pool フィールドは "shared-pool" になります。ビルドグラフ(aggrega validate --release <release> --ir-graph)は、各リーフを origin: annotation、side: aggregate、annotation_source: aggregate.yaml:subsystems.data.annotations.feature.myco/db-pool とともに記録します。
構造化されたアノテーション値
設定可能なフィールドを複数持つ Feature では、そのうち複数のフィールドの値を一度に運ぶ単一のアノテーションキーを使いたくなります。構造化アノテーション形式を使うと、1 つのキーを 1 回の宣言で複数のバインディングパスへルーティングできます。
# Aggregate Subsystem — Developer's intent for db-pool (values-pillar subkeys)subsystems: data: annotations: feature.myco/db-pool: db_name: "prod-db" read_replicas: 5# Release Boundary — Operator's sizing for db-pool (infra-pillar subkeys)boundaries: prod: annotations: feature.myco/db-pool: pool_size: 20 max_connections: 100Manifest のバインディングは、4 つすべてのサブキーのルーティングを、ピラーごとにグループ化された maps: リストで宣言します。
# Manifestspec: mappings: features: annotations: feature.myco/db-pool: feature: core/db-pool:1.0.0 maps: values: - db_name - read_replicas infra: - pool_size - max_connectionsアノテーション値の形状は、次の 3 つの形式のいずれかです。
- スカラー文字列 — 単一の値です。バインディングは合計でちょうど 1 つのパスを宣言する必要があり、スカラーはそのパスへルーティングされます。
- 構造化オブジェクト — サブキーからサブ値へのマップです。各サブキーのパスは、バインディングの
maps.infraまたはmaps.valuesリストに含まれている必要があります。サブ値は、宣言されたピラーで指定された Feature スキーマフィールドへルーティングされます。 - 明示的な YAML
null— このカスケードスコープについて、継承されたバインディング全体をオプトアウトします。
構造化値内の各サブキーは、バインディングの maps リストに対して個別に解決されます。maps.infra と maps.values のどちらにも存在しないサブキーは、問題のサブキーと宣言されたパスを示す明確なエラーでビルドを停止させます。
構造化値のカスケードマージ
構造化アノテーションは、サブキー単位のディープマージでカスケードします。子カスケードスコープのアノテーションは親のアノテーションとサブキーごとにマージされ、より近いレベルがサブキー単位で親を上書きします。
subsystems: data: annotations: feature.myco/db-pool: db_name: "data-default" read_replicas: 3 components: api: annotations: feature.myco/db-pool: db_name: "api-override" # overrides parent at this subkey only # read_replicas not listed → inherits 3 from parent analytics: annotations: feature.myco/db-pool: read_replicas: null # per-subkey opt-out: removes inherited subkey # db_name not listed → inherits "data-default" from parentカスケード後の有効なアノテーション:
- Component
api:{ db_name: "api-override", read_replicas: 3 } - Component
analytics:{ db_name: "data-default" }—read_replicasはこのスコープでオプトアウトされています
値がスカラーである子カスケードレベルは(構造化された親に対して)、マージではなく全体を置き換えます。カスケードレベル間の形状の不一致は、より近いレベルの値が優先されて解決されます。コンパイラは形状の不一致について警告しません。
値全体の null とサブキー単位の null
カスケードには、粒度の異なる 2 つのオプトアウトの仕組みがあります。
# Whole-value null — opts out wholesale at this scopecomponents: api: annotations: feature.myco/db-pool: nullこのコンポーネントではアノテーションバインディング全体が抑制され、このスコープではこのアノテーションキーから合成 Feature アタッチメントは合成されません。兄弟コンポーネントは継承したバインディングを保持します。
# Per-subkey null — opts out just one subkeycomponents: api: annotations: feature.myco/db-pool: db_name: "api-db" read_replicas: nullアノテーションはこのスコープで引き続き寄与しますが、read_replicas サブキーは抑制されます。その他のサブキー(このスコープで宣言されたもの、または親カスケードレベルから継承されたもの)はそのまま残ります。
記述のガイダンス: あるスコープでアノテーション駆動の Feature アタッチメントを無効にするには、値全体の null を使用します。アノテーションの寄与の大部分を保持しつつ、1 つ以上の特定のフィールドを抑制したい場合は、サブキー単位の null を使用します。
サブキー単位のサイドとピラーの区分
アノテーション値が構造化されている場合、Aggregate-as-Authoring-Surface 不変条件はサブキー単位で適用されます。各サブキーのピラー(バインディングの maps 宣言による)は、記述サイドと互換である必要があります。
- Aggregate サイドのアノテーションは、
maps.valuesへルーティングするサブキーのみを持つことができます。 - Release サイドのアノテーションは、
maps.infraへルーティングするサブキーのみを持つことができます。
互換性のないピラーへルーティングするサブキーは、該当するサブキーとピラーを示す明確なエラーでビルドを停止させます。エラーチェーンは停止する前にアノテーションごとに互換性のないサブキーをすべて収集するため、オペレーターは修正と再ビルドを繰り返すことなく、ビルドサイクルごとにすべての問題を確認できます。
サブキー単位の型検証
各サブキーの実行時の値は、ルーティング先のピラーにおける対象 Feature の spec.schema で宣言された型に対して検証されます。サポートされる宣言型は string、integer、number、boolean、object、array、null です。YAML の型がスキーマの宣言型と一致しないサブ値は、サブキー、実際の型、宣言型を示す明確なエラーでビルドを停止させます。
型の照合は厳密で、型変換は行われません。整数型のスキーマフィールドに対する文字列 "20" はビルドを停止させます。作成者は Feature スキーマで型を正しく宣言するか、文字列としてそのまま渡されるスカラーアノテーションを使用します。
厳密な検証のための記述上の手段。 Feature の spec.schema で type が宣言されていないプロパティは、ネストされたマップを含むあらゆる実行時の値の形状を受け入れます。スキーマが制約を宣言していない場合、ビルドは制約を作り出しません。サブキー単位の厳密な型検証を求める作成者は、spec.schema のすべてのプロパティに type を宣言します。下流の FeatureRecipe レンダリング層は、アノテーションの寄与がどのような形状であっても処理します。
サイド間の合成
Aggregate サイドのアノテーション(values サブキー)と Release サイドのアノテーション(infra サブキー)の両方が同じ Component 上の同じ Feature アタッチメントを対象とする場合、ビルドはそれらの寄与を、両方のピラーが設定された単一の Feature アタッチメントにマージします。リーフ単位の来歴は各サブキーのソースを記録します。合成されたアタッチメントは、Aggregate の記述箇所に帰属する values.db_name と、Release の記述箇所に帰属する infra.pool_size を持ちます。
サイド間の合成パターンは、開発者の意図とオペレーターのサイジングのフィールドが混在する Features の標準的な記述形状です。Aggregate は認知的な選択(どのデータベースか、アプリケーションレベルでのレプリカ数)を宣言し、Release は物理的なサイジング(プールの大きさ、インフラストラクチャレベルでの接続数)を宣言します。1 つの Manifest バインディングが、単一の maps 宣言のセットでこれらを結び付けます。
関連リファレンス
- Provider アーキテクチャ — プロバイダープラグインのアーキテクチャと、プロバイダーのレンダリングを担う Plugin の役割。
- ../entities/release.md — 境界とコンポーネントのアノテーションを記述する Release のオーサリング面。
- ../entities/aggregate.md — サブシステムとコンポーネントレベルのアノテーションを記述する Aggregate のオーサリング面。
- ../entities/manifest.md — アノテーションバインディングが
maps:のルーティングを宣言する、Manifest のmappings.features.annotationsマップ。 - ../../architecture/11-governance-and-compliance.md — 作成者が制御するアノテーションを補完する、コンパイル時の来歴スタンプの仕組み。