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

認証情報モデル

単一のアタッチメントファミリー

Aggrega における資格情報は Feature です。他の Feature と同じ面に、同じキーワードで、同じ形で付与されます。次の例では、開発者が Aggregate でデータベースの資格情報を付与し、そのロケーターを values に記述しています。

# the Aggregate — its parameters and the components' own values left out
spec:
components:
api:
type: core/compute/server
db:
type: core/datastore/mariadb
features:
root_password: # a credential Feature
type: core/secret-value:1.0.0
values:
key: MARIADB_ROOT_PASSWORD
origin: "{{ .parameters.db_root_pass }}"

また、運用者は Release でサーバーにメトリクスのスクレイプ対象を付与します。core/prometheus-exporter が受け取る入力(スクレイプのポート、パス、間隔)はすべて運用上のものなので、infra に記述します。

# the Release — the api's own infra and the db's entry left out
spec:
components:
api:
features:
metrics: # an operational Feature
type: core/prometheus-exporter:1.0.0
infra:
port: http # the named port of the api's Service

アタッチメントのキーワードは 1 つ(features:)、レンダーコンテキストの形は 1 つ(.features.<name>、および接続に記述されたアタッチメントの場合は接続の下の同じ形 .context.uses.<alias>.features.<slot>)、実行順序は 1 つ、出力座標の組は 1 つです。コンポーネントへのアタッチメントの場合、出力座標は付与先のコンポーネント、次に付与時の名前であり、ターゲットのレイアウトがこの 2 つをコンポーネント自身のディレクトリと並ぶ <component>--<instance>/ ディレクトリとして持つか、<component>--<instance>-- というファイル名の接頭辞として持つかは問いません。アタッチメントごとに異なるのは何を生成するか(注入される値、参照可能なリソース、サイドカー、クラウド ID)であり、宣言される面ではありません。

資格情報の Feature は、カタログエンティティに feature.aggrega.ai/kind: secret というラベルを持ちます。このラベルは記述的なメタデータであり、読み手、カタログサイト、ラベルセレクターに対して、その Feature が何のためのものかを伝えます。このラベルを読むコンパイラの分岐はなく、このラベルによって変わる動作もありません。動作は、運用者がその Feature 型を対応付ける FeatureRecipe から生じます。

一文で表すメンタルモデルは次のとおりです。アタッチメントの種類は 1 つであり、異なるのはそれが何を生成するかである。

スロットとフリーアタッチメント

Component または Feature は、featuresSchema でスロットを宣言できます。

spec:
featuresSchema:
root_password:
required: true
inject: [] # blackbox — the Recipe delivers it
selector: "feature.aggrega.ai/kind=secret"
user_password:
inject: [env, file] # transparent — the developer may dictate delivery

インスタンス名が宣言済みのスロットと一致するアタッチメントは、そのスロットを埋めます。それ以外の名前のアタッチメントはフリーアタッチメントです。エンティティが要求したものではなく、エンティティが要求したものと並んでレンダリングされます。宣言済みスロットに対して生成されるスキーマは開いたままなので、スロットを 1 つ宣言してもブロックがフリーアタッチメントに対して閉じることはありません。ただし、1 つの形だけはレンダリングせずに停止します。それは、コンポーネント自体に書かれたアタッチメントで、その Feature が、そこで何もバインドしていないスロットの selector を満たしている場合です。これはフリーアタッチメントではなく、誤った名前で書かれた充填です。

スロットが制約できるものは 2 つあります。

  • inject — スロットを埋めるものに対して Workload が選択できる配信メカニズムです。空のリストはブラックボックススロットです。Recipe 自身の仕組み(たとえばチャートの existingSecret ノブ)がそれを配信し、Workload はコンテナからそれを参照できません。
  • selector — 充填する Feature のラベルが満たす必要のあるラベルセレクター文字列です。ここで kind=secret ラベルが役に立ちます。スロットをクレデンシャルだけで埋めたいエンティティ作成者はセレクターでそれを示し、そのチェックはコンパイラが静的解析中に行うラベルセットの評価です。

スロットにできる 3 つ目のことは、最終的にバインドされることを要求することです。required: true を指定すると、スロットの名前が必須になります。何もバインドしていない場合、コンパイラは静的解析中に停止し、そのスロットと、それを宣言したコンポーネントタイプを示す診断を出します。この要求は、すべてのスコープがカスケードした後にコンポーネントが最終的に持つアタッチメントの集合に対して評価されるため、コンポーネントより上で追加されたアタッチメントも、コンポーネントに直接書かれた充填とまったく同じようにスロットをバインドします。

別の面では、異なる要求を表現します。繰り返し指定できる Component アノテーション features.aggrega.ai/requiredType.<label> は、存在の義務を宣言します。少なくとも 1 つのアタッチメントが、アノテーションで指定された Feature タイプを、任意の名前、任意のスコープで持っている必要があり、何も満たさない義務は同じ静的解析中に独自の診断とともに停止します。この 2 つが互いの代わりになることはありません。スロットは名前付きのバインドポイントがバインドされているかを問い、義務は何らかのアタッチメントが名前付きのタイプを持っているかを問います。そのため、アタッチされたものを Recipe が読み取る必要があるエンティティはスロットを宣言し、契約として単にある機能の存在を要求するだけのエンティティは義務を宣言します。

コンパイラが保証すること、保証しないこと

このセクションは本章の要となる部分です。Aggrega は AOT (ahead-of-time) コンパイラであり、その保証は「secret」という語から読者が想定しがちな範囲よりも狭いものです。

コンパイラはクレデンシャルを解決しません。 クラウド API で認証することも、vault を読み取ることも、aggrega build の実行中にマテリアルを取得することもありません。クレデンシャルのアタッチメントの values と infra は不透明なスカラーとしてグラフを通り、レンダーコンテキストに渡されます。そして FeatureRecipe が、それらをターゲットプラットフォームが期待する任意のアーティファクトにレンダリングします。解決はその後、クラスタまたは IaC の状態管理ツールにおいて、レンダリングされたアーティファクトが指す先に対して行われます。

コンパイラはポインタとマテリアルの値を区別できません。 コンパイラはスカラーが何を意味するかに依存しません(05-invariants.md を参照)。ロケータにストアの座標(path、key、ARN)を持つクレデンシャルのアタッチメントは、その座標への参照をレンダリングします。一方、ロケータにマテリアルそのものを持つクレデンシャルのアタッチメントは、マテリアルをそのまま出力ファイルにレンダリングします。どちらも正当であり、コンパイラは両者を区別する手段を持たないため、同一に扱います。

したがって、保証を正直に述べると次のようになります。

Aggrega は、コンパイラが一切の解決を行わないことを保証します。レンダリングされた出力にマテリアルが含まれないことは保証しません。それは、どのクレデンシャル Feature がアタッチされ、その作成者(values では開発者、infra ではオペレーター)が何を入れたかに完全に依存します。

理解しておくべき 2 つの帰結があります。

  • レンダリングされたアーティファクトツリーは、最も多くのマテリアルを持つアタッチメントと同等の機密性を持ちます。dist/ はそれに応じて扱ってください。いずれかのアタッチメントがマテリアルをインラインで持つ場合、ツリーはマテリアルを保持します。
  • カタログ自身の core/secret-value および core/referenced-secret ファミリーには、値を直接受け付ける形式が含まれます。これらは実際のデプロイにローカル開発用の経路が必要なために存在し、そのことを隠していません。同梱の実例では明らかなプレースホルダー(dev-root-pw-change-me)を使用しており、レンダリングされた例のマテリアルが本物のクレデンシャルではないことが一目でわかるようにしています。マテリアルを持ってはならないデプロイでは、データを出力するものではなく、取得用リソース(ExternalSecret、vault 取得用のカスタムリソース、provider ネイティブのシークレット参照)を出力する FeatureRecipe を持つ、ストアに裏付けられたクレデンシャル Feature をアタッチしてください。

標準ライブラリの慣例では、クレデンシャルは values ブロックに書き込むのではなくアタッチメントとして要求します。これにより、ローカル開発用のフィルをストアに裏付けられたものに切り替えることが、開発者の意図の編集ではなく Manifest の変更で済みます。これはカタログが従う慣例であり、コンパイラが強制する規則ではありません。

宣言された機密性

前節で述べたとおり、コンパイラはポインタと実体の値を区別できません。しかし作成者は区別でき、それを表明できます。Aggrega における機密性は宣言に付与する注釈です。カタログエンティティの作成者が何が秘密の実体を持つかを表明し、コンパイラはその表明と、すでに構築済みの配線から残りを導出します。値から推論されるものは何もなく、フィールド名から推測されるものもありません。

機密性を記述する場所はちょうど 2 か所であり、それぞれが本質的に異なる主張を表します。

スキーマのリーフ上 — このデータは秘密の実体である。 values、infra、または provides のリーフが sensitive: true を宣言します。

spec:
schema:
values:
origin:
type: string
required: true
sensitive: true # the material
key:
type: string
default: value # a data key — a locator, not material

アタッチメントスロット上 — このポイントにバインドされるものはすべて秘密の実体を扱う。 featuresSchema のスロットが sensitive: true を宣言します。

spec:
featuresSchema:
password:
selector: "feature.aggrega.ai/kind=secret"
sensitive: true
inject: [env]

この 2 つのレベルは、便宜上の重複ではありません。その理由を示すのが、参照可能なクレデンシャルの形です。参照可能なクレデンシャルは provides.name と provides.key(リソースのロケータとその中のデータキー)を公開しますが、どちらも機密ではありません。Kubernetes Secret の名前は公開情報であり、その中のキーも同様です。どちらも secretKeyRef として、利用側自身のマニフェストに平文でレンダリングされます。それでも、そのクレデンシャルが埋めるスロットは疑いなく秘密の実体を扱います。一方のレベルだけでは両方の事実を表現できません。スロットを機密として読ませるために公開ロケータに印を付けると、ロケータについて誤った内容を表明することになり、その誤りは宣言が読まれるあらゆる場所に持ち込まれます。

これら 2 つの宣言から、コンパイラはアタッチメントごとに、そのアタッチメントが宣言済みの機密の実体を扱うかどうかを導出します。アタッチされた Feature が機密リーフを宣言している場合、またはバインド先のスロットが機密を宣言している場合に真となり、どちらか一方だけで十分です。この導出は、すべての作成スコープが畳み込まれた後のアタッチメントに対して行われます。そのため、より狭いスコープのフィルに置き換えられた広いスコープの宣言は残らず、スロットの要求は実際に採用されたフィルに適用されます。機密リーフをまったく宣言しないクレデンシャル Feature(ターゲットエンジンが実体を所有し、作成者が何も書かないため)であっても、機密スロットにバインドされれば機密のアタッチメントになります。

上限を率直に述べる

「sensitive」という語は、機密保持の仕組みを期待させます。しかしそうではなく、保証は名前が示唆するよりも次の 5 つの点で狭いものです。

  • 暗号化しません。 何もラップ、封印、変換されません。
  • 1 つの例外を除き、ビルドの判定を変えません。 宣言がないことを理由にビルドが停止することはなく、クレデンシャルエンティティに宣言がないカタログも正常にビルドされます。宣言の有無によって値が受け入れられたり拒否されたりすることもありません。例外は、CloudFormation の Recipe または FeatureRecipe の valuesMapping が、取り込んだテンプレートのパラメータを埋めるために宣言済み機密値を読む場合です。このときマッピングがバインドするリテラルはすべて拒否されるため、宣言を追加すると成功していたビルドが停止するようになることがあります。A secret bound to a CloudFormation parameter would be written into the template(CloudFormation パラメータにバインドされたシークレットがテンプレートに書き込まれます)を参照してください。それ以外では、既存のカタログに宣言を追加しても、成功していたビルドはすべて引き続き成功します。
  • レンダリング出力に実体が含まれないことを保証しません。 前述の保証は変わりません。成果物が実体を含むかどうかは、どのフィルがアタッチされ、その作成者が何を入れたかによって決まります。インラインで与えられた宣言済み機密値は、ビルドがそれをレンダリングする場所ではどこでも、未宣言の値とまったく同じようにレンダリングされます(前述の CloudFormation の拒否はリテラルをレンダリングせずに止めるものであり、組み込み関数はその文字列も含めて与えられたとおりに書き出されます)。そして dist/ は、最も多くの実体を持つアタッチメントと同じだけ機密性が高いままです。
  • 配信の仕組みを強制しません。 宣言によってインラインの値をストア参照に変換することはできず、スロットの inject 許可リストが許すものを狭めることもありません。配信を強制すれば、作成者が宣言していないリソースを出力することになり、それはまさにゴーストインフラストラクチャ禁止の不変条件が禁じることです。05-invariants.md を参照してください。
  • ほとんどのターゲットでは、レンダリングされるバイトを一切変えません。そしてそれらのターゲットでは今後も変えることはありません。 出荷されている 2 つのレンダリングパスは、生成するものの中で宣言に基づいて動作します(Helm、Helm-Chart、Compose の各プロバイダーも宣言を読みますが、それはマークされた値を失敗時のテキストに含めないためだけです)。Terraform プロバイダーは、宣言済みの機密マテリアルを運ぶベンダリングされたモジュールの入力に Terraform 自身の機密属性を付けます。language-reference/providers/terraform.md の「Declared-sensitive module inputs」を参照してください。Recipe の valuesMapping、またはコンポーネントにアタッチされた Feature の FeatureRecipe のそれが入力名を作り出す場合、どの入力もその属性を持てないため、ビルドはその旨を伝える勧告を出力します。A declared-sensitive value reaches the target through a values mapping(宣言済みの機密値が値マッピングを通じてターゲットに到達します) を参照してください。また CloudFormation プロバイダーは前述のリテラルバインディングを拒否し、これはバイトを変えるのではなくビルドを停止させます。それ以外のすべての場所では、既存のカタログ全体に宣言を追加しても、レンダリングされるすべてのアーティファクトは同一のままです。それを超える上限は、何が構築済みかという問題ではなく構造的なものです。宣言がレンダリングされたアーティファクトに届きうるのは、そのターゲットプラットフォーム自身の言語が機密性の概念を持つ場合に限られます。つまり、そのプラットフォームが理解する宣言であり、値の保存方法ではなく表示方法を左右するものです。そのような概念を持たないターゲットでは、宣言が変換される先が何もないため、同一の入力は宣言の有無にかかわらず恒久的に同一にレンダリングされます。

宣言によって変わることの 1 つは、人が読むために CLI が表示する内容です。宣言済み機密値は、パスごとのトレースと inspect のレイアウトにおいて固定のプレースホルダーに置き換えられ、キーは残して値だけが伏せられます。これは誰もデプロイしない表示面での表示上の判断であり、レンダリング成果物はデプロイ対象そのものであるため、そのまま出力されます。

コンパイラがキーによって値を特定できる場合(宣言済みのリーフ、または宣言済みの provides キーから実体を運ぶ配信キー)、置換は正確です。テンプレートがすでに別のドキュメントに書き込んだ値には、置換すべきキーがありません。レンダリングされたドキュメントは、各文字がどの宣言に由来するかを何も記録しておらず、それを復元するには内容を検査する必要があるためです。そこでトレースは、宣言済み機密データがすでにプレースホルダーとして読まれるコンテキストに対して同じテンプレートをもう一度評価してそのドキュメントを示し、その結果をレンダリングされたものではなく再レンダリングとしてラベル付けします。値の内容で分岐するテンプレートはプレースホルダーに対しては異なるレンダリングになり、どの宣言も名指ししないデータはそのまま引き継がれます。これらの表示面、そのラベル付け、およびその限界については language-reference/vocabulary/compact-form-authoring.md の「Declaring a leaf sensitive」に記載しています。

したがって、この軸がもたらすものを率直に述べると次のとおりです。

機密性の宣言は、エンティティとともに伝わる作成者の意図の表明であり、ツールやポリシーがデプロイの扱う内容について推論できるようにするものです。それを保護する仕組みではありません。

実体の保護は、本章の残りで述べるとおり、引き続きシークレットストア、クラスタ、そしてレンダリングされたツリーを扱うパイプラインの役割です。

資格情報がコンテナに届く仕組み

配信の形は 2 つあり、開発者ではなくアタッチメントの FeatureRecipe が選択します。

注入される値。 FeatureRecipe は injectMapping を宣言し、リソースは宣言しません。その出力はベースの Recipe がレンダリングされる前に、消費側コンポーネントの配信パイプにディープマージされるため、.context.inject.env.<KEY> を読む Recipe はその値を受け取ります。単独で出力されるものはありません。

1 つのキーに 2 つの資格情報が配信されると、両方のアタッチメントを示してビルドが停止します。別のアタッチ済み Feature が、その Feature 自身のマッピングまたは自身の inject: ブロックを通じてすでに配信したキーに書き込むマッピングは、マージされずに拒否されます。そのため、ある資格情報が別の資格情報の代わりに提示されることはありません。この規則は、どこでアタッチされたか、コンポーネント上のスロットと接続上のスロットのどちらを埋めるかにかかわらず、すべてのアタッチメントで同じです。コンポーネント自身の inject: ブロックまたはその接続の 1 つが配信したキーを置き換えるマッピングは、ルーティング用の Features が依存するインターセプトであり、引き続き有効です。

参照可能なリソース。 FeatureRecipe は source、workload、artifacts、valuesMapping のいずれか、または複数を宣言するため、リソース(通常はプラットフォームネイティブの Secret)を出力します。そのリソースの識別情報を provides を通じて公開し、消費側はそれを .features.<name>.provides.name / .provides.key として読み戻します。リソース自身の名前も同じ公開された provides から導出されるため、消費側が読む名前とリソースが持つ名前は、食い違う可能性のある 2 つの導出ではなく、評価された 1 つの文字列です。

Recipe の Workload は、コンテナの attachments: マップを通じて参照可能なフィルを消費します。

workload: |
containers:
main:
attachments:
DB_PASSWORD:
from: root_password # a slot the Component declares
as: env

シンセサイザーは、スロットの公開された provides から参照を解決します。as: env の場合は Kubernetes の secretKeyRef、as: file の場合はシークレットに基づくボリュームです。Recipe の作成者が書くのはスロット名と仕組みだけです。

FeatureRecipe は両方を行うこともできます。つまり、配信パイプを書き換え、かつリソースを出力できます。また、Wasm ステップの pipeline を宣言することもでき、これはすべてのアタッチメントファミリーで同様に実行されます。資格情報のアタッチメントは、運用アタッチメントとまったく同じように、招かれた場合にホストコンポーネントのレンダリング済みドキュメントを変換できます。

誰がクレデンシャルを指定するか

クレデンシャルのロケーター(シークレットの名前、取得するストアエントリ、配信する値)は、それを知っている者が記述します。それが常に開発者とは限りません。Release が配線する接続には Aggregate 内にエントリがなく、Release はどこにも values を記述しません。そのため、ロケーターを values からのみ取得するクレデンシャルは、そのような接続上でも、Release が行ういかなるアタッチメント上でも、指定することができません。

そのため、呼び出し側のロケーターを保持する標準ライブラリのクレデンシャル Feature(core/referenced-secret、core/referenced-secret-set、core/secret-value、core/secret-provided)はいずれも、どちらの作成者からもロケーターを受け付けます。開発者は Aggregate 内でアタッチメントの values に、運用者は Release 内でその infra に記述します。リーフは両方のピラーで同じ名前、同じ形、同じ sensitive: true 宣言を持ち、すべての実現形態はそれを保持しているほうのピラーを読み取ります。Release の values: 禁止はそのままです。運用者のロケーターは infra です。ロケーターを取らない Features(core/random-password、core/generated-secret)は影響を受けません。

ちょうど 1 つであることは Feature が保持します。 アタッチメントはロケーターを 1 つのピラーに保持し、両方に保持することも、どちらにも保持しないこともありません。各ピラーは個別に検証されるため、どのピラーのスキーマもこれを表現できません。これを表現するのは各 Feature 自身の assertions ブロックであり、これに違反するアタッチメントは、その Feature、アタッチメント、コンポーネントを示してビルドを停止させます。これはカタログエンティティの契約であり、すべての Feature のアサーションと同じ方法で維持されます。コンパイラは Feature の作成者が記述したテンプレートを評価するだけで、クレデンシャル、ピラー、ロケーターに関する独自の規則は持ちません。

元の場所に留まるもの。 その他のフィールドはすべて元のピラーに留まります。参照可能なクレデンシャルのデータキーは引き続き values に記述されるため、Release のみが行うアタッチメントはそのデフォルトを読み取ります。また core/secret-provided は引き続きアタッチメント自身の inject: ブロックを通じてのみ配信されます。このブロックは Aggregate のみが記述し、接続のアタッチメントが持つことはありません。

1 つの認証情報を複数のコンシューマーで共有する

コンシューマーが認証情報を保持してもかまいません。 スロットは認証情報を必要とするエンティティに属し、それは呼び出される側ではなく呼び出し側であることがよくあります。外部に接続する際にキーを提示するコンポーネントは、そのキーのスロットを自身のカタログエンティティ上、接続に使うソケット上に宣言します。これにより、キーはそれが提示される接続上に保持されます。また、uses エッジに関する何物も、ターゲット側にキーの供給を義務づけません。core/ai-agent/crewai が出荷されている形です。その model ソケットは、feature.aggrega.ai/kind=secret セレクター、inject: [env]、sensitive: true を持つ省略可能な credential スロットを宣言し、Aggregate はそれを接続の下、uses.model.<alias>.features.credential で埋めます。標準ライブラリのモデルコンポーネントがコンシューマーに読ませるために公開するのは、提供場所とモデル名であって認証情報ではありません。そのため、エージェントがそのエンドポイントを呼び出すときに提示するキーは、エージェントが宣言し、その接続上に保持します。このスロットは省略可能ですが、カタログが component.aggrega.ai/hosting: managed とラベル付けしたモデルに到達する接続が認証情報を持たない場合、その接続自身の values がモデルに認証情報が不要であること(unauthenticated: true)を示さない限り、ビルドは停止します。これはエージェントのカタログエンティティが持つアサーションであり、コンパイラは他のアサーションと同様に評価し、ラベルを文字列として読み取ります。接続先のモデルコンポーネントは、自身の呼び出し元のために独自のキーを保持することがあります。core/ai-model/vllm はまさにそのために api_key スロットを宣言します。この 2 つは別々のバインドポイントです。アタッチメントは、スロットが宣言されている場所(コンポーネント上または接続上)で名前によってスロットをバインドするため、一方を埋めても他方には何の影響もありません。

この配置があるからこそ、以下の 2 つの形がデプロイ時の選択になります。スロットがコンシューマー側にあるので、あるビルドでは各コンシューマーに個別のキーを与え、別のビルドではすべてに同じキーを与えることができ、その間でカタログエンティティは一切変わりません。

同じカタログエンティティが両方の形に対応し、どちらにするかは作成者が選びます。

  • コンシューマーごと。 各コンシューマーは、自身のスロットを自身の認証情報アタッチメントで埋めます。コンポーネント上で、またはスロットがソケットのものである場合はその接続上で埋めます。それぞれが個別のレンダリング済みリソースを得ます。
  • 共有。 コンポーネントが宣言するスロットの場合、1 つの認証情報を共有スコープ(Aggregate ではサブシステム、Release ではバウンダリ)で一度アタッチすると、そのスコープ内のすべてのコンポーネントにカスケードします。ソケットが宣言するスロットは接続ごとに埋められ、接続の中には何もカスケードしないため、そこでは共有の形を各接続上で記述します。すべての接続の認証情報が 1 つのパラメーターを読み取ります。コンシューマーが 1 つの物理リソースを参照する必要がある場合は、そのパラメーターがそれを指定します。既存 Secret の実現にバインドされた core/referenced-secret は、すべての接続を名前で 1 つの Secret に向けます。生成される認証情報は、後述のとおり、1 つのリクエストと多数の参照になります。

共有形式のレンダリングについては、誤解しやすいため正確に述べておきます。共有アタッチメントはコンシューマーごとに 1 つのリソースをレンダリングします。それぞれが、1 つの宣言から得た同じ素材を持ちます。レンダリングはコンポーネントごとに実行されるため、{{ .context.instance_id }}-{{ .attachment_name }} から導出されるリソース名はコンシューマーごとに異なります。共有されるのは単一の宣言であり、出力されるリソースが 1 つに重複排除されるわけではありません。各接続で 1 つのパラメーターを読み取る場合も、リソースをレンダリングする実現のもとでは同じようにレンダリングされます。接続ごとに 1 つで、アタッチメント名は接続のエイリアス、ドット、スロットとなります。

デプロイで、複数のコンシューマーが読み取るちょうど 1 つの物理 Secret が必要な場合は、FeatureRecipe がバウンダリスコープ(executionScope: boundary)で実行される認証情報 Feature でそれを表現します。これはコンポーネントごとに 1 回ではなく、バウンダリに対して 1 回レンダリングします。

接続の両端が保持するキー

キーを検証するサーバーと、それを呼び出すコンポーネントは、それぞれ自分の側でそのキーを保持します。サーバーは、検証するキーを自身の Component のスロットに保持します。core/ai-model/vllm、core/ai-model/tei、core/ai-model/tgi はそれぞれ api_key を宣言し、LiteLLM のモデルとゲートウェイも、LiteLLM がマスターキーと呼ぶキーのために同様に宣言します。そしてその Recipe は、スロットを埋めたものを、サーバーが読み取る変数として渡します。呼び出し側は、提示するキーを自分の側で保持します。それを提示する接続上で、そのソケットが宣言するスロットに保持するか(core/ai-agent/crewai の model ソケットが credential を宣言するように)、または Component が自身にキーを宣言している場合はそのスロットに保持し、行うすべての接続で使います。どちらの端も相手のアタッチメントを見ません。接続上のアタッチメントは呼び出し側にのみ適用され、サーバーのレンダリング出力は、到達する接続が何を持っていても同じです。サーバーは呼び出し側がどのキーを保持しているかを知ることはなく、呼び出し側はサーバーが公開するもの(アドレスとモデル名)だけを読み取ります。両端が一致するのは、Aggregate が 1 つのパラメーターから両方に供給するためです。

spec:
parameters:
model_key_secret: { type: string }
components:
model:
type: core/ai-model/vllm
values: { model: Qwen/Qwen2.5-0.5B-Instruct }
features:
api_key: # the key the server verifies
type: core/referenced-secret
values:
origin: "{{ .parameters.model_key_secret }}"
key: api-key
router:
type: local/gateway/model-router # its `models` socket declares a `credential` slot
uses:
models:
local:
target: model
features:
credential: # the key the caller presents
type: core/referenced-secret
values:
origin: "{{ .parameters.model_key_secret }}"
key: api-key

それが 1 つのシークレットになるか 2 つになるかは、両端がシークレットを解決する場所によって決まります。プロバイダーは、シークレットスコープ内で参照によってシークレットを解決します。helm では Kubernetes の名前空間、compose では Compose プロジェクト、terraform ではバウンダリのルート構成、cloudformation ではデプロイ先の AWS アカウントとリージョンにあるスタックです。両端が 1 つのスコープにある場合、両者は 1 つのシークレットリソースを参照します。異なるスコープにある場合、各端は同じストアエントリから実現された独自のシークレットリソースを保持します。各端の実現は Manifest が選択します。Feature の型によって、または 1 つのアタッチメントに対してはその名前によって選択し、接続のアタッチメントの場合その名前は <alias>.<slot>(上記では local.credential)です。1 つのパラメーターが両方に供給するため、2 つの実現は origin を同じ種類のロケーターとして読み取ります。両方とも Secret の名前、両方ともストアエントリのキー、または両方とも値そのものです。

helm で両端が 1 つの名前空間にある場合、core/referenced-secret を helm/k8s-existing-secret にバインドし、その名前空間にある Secret の名前 model-keys でパラメーターを満たすと、両端はそれを名前で参照し、Secret はレンダリングされません。サーバーのコンテナは次を持ちます。

- name: VLLM_API_KEY
valueFrom:
secretKeyRef:
name: model-keys
key: api-key

そしてルーターの Recipe は、同じ名前とキーを接続から .context.uses.local.features.credential.provides で読み取ります。両端が異なる名前空間にある場合は、helm/k8s-external-secret にバインドし、ストアエントリのキーでパラメーターを満たすと、各端はそれぞれの名前空間に独自の ExternalSecret を持ち、両方がその 1 つのエントリを取得します。compose では、両端が同じ ${VAR} 参照を持ち、Docker Compose は 1 つのプロジェクトの起動時の環境からそれを置換します。この配置は標準ライブラリのカタログが従う慣例であり、コンパイラは両端の間で何も比較しません。

1 つのキーがすべての呼び出し側に対応します。 vLLM、TEI、TGI はそれぞれ単一のキーを検証するため、すべての呼び出し側が同じキーを提示し、到達する接続がいくつあってもサーバーは呼び出し側を区別できません。これはサーバー自身の制約です。TGI は大文字と小文字を区別せずにキーを照合するため、大文字小文字だけが異なる 2 つのキーは TGI にとって 1 つのキーです。LiteLLM のモデルとゲートウェイは、管理用データベースがアタッチされている間、自身が発行したキーも受け付けます。

ターゲットが生成するクレデンシャル

Release がクレデンシャルを供給しない場合、カタログエンティティは開発用のデフォルト値、つまり Recipe 内のインライン値やモジュールのパラメータのデフォルト値にフォールバックすることがよくあります。その値はカタログを読むすべての人にとって同じであり、評価用途には許容できますが、それ以外には使えません。core/random-password はその必要をなくします。ターゲットがクレデンシャルを生成するため、誰もクレデンシャルを書く必要がありません。

パスワードはビルドで作ることができません。ビルドの出力は入力の純粋関数であり、シークレットの値を決して含まないため、ビルド時に生成したパスワードはビルドのたびに変わり、レンダリングされたファイルに残ってしまいます。そこで FeatureRecipe は代わりにリクエスト、つまり値を格納するシークレットリソースを指定するジェネレーターリソースをレンダリングし、ターゲットがデプロイ時に値を生成します。

  • helm では、クラスタ内のコントローラーです。ExternalSecret を通じて調整される External Secrets Operator のパスワードジェネレーター、または StringSecret を調整する kubernetes-secret-generator コントローラーです。
  • terraform では、random プロバイダーの random_password で、設定の適用時に生成されます。
  • cloudformation では、スタックによる作成時に自身の文字列を生成する Secrets Manager シークレットです。

いずれの場合も、レンダリングされた出力はジェネレーターとシークレットリソースを指定するだけで、値を含みません。これはビルドが追加する保護ではなく、ビルドが持つものの性質です。値はターゲットが作るまで存在しません。その後ターゲットが値をどこに保持するかはターゲット次第です。Terraform はプランとステートに、クラスタは Secret に保持します。

ターゲットで稼働している必要があるもの。 リクエストは、それを処理するものがある場所でのみ満たされます。helm ではそれはコントローラーですが、コンパイラはクラスタを検査してコントローラーが稼働しているかを知ることができません。そのため helm の FeatureRecipes は、Release がアタッチメント上で infra.control_plane_present: true によって前提条件を明示しない限り、ビルドを停止します。terraform と cloudformation では、apply またはスタック自体が値を生成するため、事前に稼働している必要のあるものはありません。

使用できない場所。 Compose はコントローラーを実行せず、値を生成するリソースも持たないため、そこで core/random-password を実現する FeatureRecipe は存在せず、compose 上でそれをバインドするビルドは FeatureRecipe がないために停止します。compose をターゲットとする Release は、core/secret-value を通じてクレデンシャルを供給します。通常は、スタックの起動時に Docker Compose が置換する変数参照として供給します。

コンシューマーによる読み取り方。 core/random-password は core/referenced-secret と同じ provides.name と provides.key を公開し、同じ feature.aggrega.ai/kind: secret ラベルを持ちます。そのため、クレデンシャルファミリーを選択するスロットはそれを受け入れ、コンシューマーは生成されたクレデンシャルを既存のクレデンシャルとまったく同じように読み取ります。

複数のコンシューマーで共有する方法。 ジェネレーターはリクエストごとに新しい値を生成するため、前のセクションの共有ルールはより厳しく適用されます。共有スコープで、または各コンシューマー上でアタッチされた生成クレデンシャルは、コンシューマーごとに 1 つのリクエストをレンダリングし、各リクエストは異なるパスワードを生成します。これではデータベースとそのクライアントは使えません。複数のコンシューマーが共有する 1 つの生成クレデンシャルは、1 つのリクエストと多数の参照として表現します。1 つのコンポーネントに core/random-password を置き、その name の値で格納先の Secret を固定し、他のコンポーネントには既存 Secret の実現にバインドしてその同じ名前を指す core/referenced-secret を置きます。1 つのパラメータから記述すれば両者が食い違うことはなく、レンダリング結果には、すべてのコンシューマーが参照するリクエストがちょうど 1 つだけ含まれます。

core/random-password は core/generated-secret とは異なります。後者の Feature は、ライフサイクル全体をすでに管理しているエンジン(マネージドデータベースやデータベースコントローラーなど)にクレデンシャルを渡すもので、何もレンダリングしません。core/random-password は、Recipe がクレデンシャルを渡されることを前提とするワークロードのために、リクエスト自体をレンダリングします。

アタッチメントの優先順位

アタッチメントは複数のスコープで同時に宣言できます。競合するフィールドの所有権は、次の 3 つの規則をこの順に適用して決まります。

  1. 起源。 明示的に記述されたフィールドは、どちらがどのスコープから来たかにかかわらず、アノテーション駆動の展開によって提供されたフィールドに優先します。
  2. 構成の権限。 デプロイしている Aggregate 内の宣言は、その Aggregate が構成する Aggregate 内の宣言に優先します。構成される側のドキュメントがより狭いスコープで宣言していても同様です。
  3. 具体性。 同じ記述レベルの中では、より狭いスコープがより広いスコープをフィールドごとに上書きします。コンポーネントレベルの指定は、同じインスタンス名を持つサブシステム全体またはバウンダリ全体のアタッチメントを、その指定が言及するフィールドについてのみ上書きし、省略したフィールドはより広いスコープの値を保持します。

開発者側は values を、運用者側は infra を提供するため、両者が同じフィールドで競合することはありません。どちらの側からでもロケーターを受け取るクレデンシャルの Feature は、それを柱ごとに 1 つずつ、2 つのフィールドとして宣言し、自身のアサーションによって両方を持つアタッチメントを拒否します。そのため、ここでも優先順位が解決すべき同点は生じません。優先順位が決めるのはフィールドの値だけです。評価の順序は変えず、評価は 10-compilation-pipeline.md のカスケード手順に従います。

書式化された文字列を要求するレガシーなチャート

チャートによっては、マテリアルを埋め込んだ単一の接続文字列(oracle://admin:PASSWORD@HOST:1521/DB)を求めることがあります。AOT(事前)コンパイラはマテリアルを一切保持しないため、ストアの座標からこの文字列を組み立てることはできません。サポートされている方法は次の 2 つです。

クラスタ側でのテンプレート処理。 認証情報の FeatureRecipe は、vault オペレーター自身のテンプレート機能を使って文字列をクラスタ内で書式化するリソースを出力します。アプリケーションは生成されたプラットフォームの Secret を名前で参照し、コンパイラはマテリアルを一度も保持することなくその関係を配線します。

{
"apiVersion": "external-secrets.io/v1beta1",
"kind": "ExternalSecret",
"metadata": { "name": "oracle-dsn-secret" },
"spec": {
"target": {
"name": "oracle-formatted-dsn",
"template": {
"engineVersion": "v2",
"data": { "ORACLE_DSN": "oracle://admin:{{ .password }}@10.0.5.55:1521/PROD_DB" }
}
},
"data": [
{ "secretKey": "password", "remoteRef": { "key": "arn:aws:secretsmanager:prod/oracle" } }
]
}
}

パラメーターの巻き上げ。 Aggregate が型付きのパラメーターを宣言し、周囲の CI パイプラインがビルド時に Release の parameters: を通じてその値を渡します。たとえば、パイプラインが書き出したファイルを Release が parameters: { $import: ./ci-parameters.yaml } でインポートします。これは明示的なエスケープハッチであり、トレードオフを可視化します。マテリアルがビルドを通過するようになるため、レンダリングされた出力にはマテリアルが含まれ、それに応じた取り扱いが必要になります。

ローカル開発

ローカル開発の標準的な経路では、開発者の意図はそのままにバインディングを差し替えます。Aggregate は同じ資格情報の Feature 型をアタッチし続け、ローカルの Manifest はその型を、ストアに裏付けられた FeatureRecipe ではなくローカルの FeatureRecipe にマッピングします。コンパイラは引き続き何も取得しません。ローカルの FeatureRecipe は、ローカルのランタイムが解決するプロバイダーネイティブの構文を渡すだけです。Compose の場合、それはサービスの環境に書き込まれる ${SECRET_NAME} のような変数参照であり、Docker Compose はスタックの起動時にシェル環境または .env ファイルからこれを置換します。環境の切り替えは Manifest の編集で行えます。

認証情報をめぐるデータガバナンス

Aggrega はデータスキーマをモデル化しません。行、列、ファイルはアプリケーションの関心事です。Aggrega はデータのガバナンス上のアイデンティティをラベルでモデル化し、標準ライブラリの慣例は次のとおりです。

  • データは、オントロジーラベルによってステートフルまたはリソース的であると示されたコンポーネント(component.aggrega.ai/type: stateful-server、resource)に置かれます。キューに入ったペイロードを保持するメッセージブローカーもその一つです。自身のディスクを所有する場合は stateful-server を持ち、Release がホスト型のものを接続する場合は resource を持ちます。また、それが閲覧上分類される messaging の棚は、別の component.aggrega.ai/category 軸です。
  • compliance.aggrega.ai/data-class(public、internal、restricted)は、そのデータに意味的なアイデンティティを与えます。この慣例が定めるのはキーとその値であり、どのコンポーネントがそれを持つかではありません。標準ライブラリの Component はどれもこれを持ちません。コンポーネントが保持するデータのクラスは、製品の性質ではなく、組織がそのコンポーネントをどう使うかについての記述であるため、組織は自らの Components 上でそれを記述します。これは通常のラベルです。ラベルセレクターはこれを評価し、運用者が接続したガバナンスプラグインはこれを読んでビルドを拒否できます。コンパイラ自体はこれを解釈せず、どのクラスも他より上位に位置付けません。どのクラスが存在し、どう順位付けされるかは、../language-reference/examples/policy-data-class-route/ にあるように、接続されたポリシー自身の設定です。

data-class と sensitive は二つの別の軸であり、まとめると情報が失われます。 両者は隣り合っていて一つの仕組みと誤解しやすいため、区別を保ってください。

compliance.aggrega.ai/data-classsensitive
形段階的 — public / internal / restricted真偽値
粒度ノード全体一つのスキーマリーフ、または一つのアタッチメントスロット
示す内容コンポーネントが保持するデータがどのガバナンス上のアイデンティティを持つかこのデータが秘密情報であること、またはこのバインディングポイントがそれを扱うこと
記述方法metadata.labels 内のラベル宣言上のキーワード

どちらも他方の代わりにはなりません。機密性を段階的なラベルに押し込めば、順序のない事実に順序を課すことになり、データクラスをリーフに押し込めば、分類が持たない粒度を課すことになります。エンティティは両方を持つことができ、認証情報スロットが sensitive と宣言された、restricted データを保持するコンポーネントは、別々の二つの真実を述べています。リーフとスロットのキーワードは、../language-reference/vocabulary/compact-form-authoring.md の「Declaring a leaf sensitive」と ../language-reference/entities/component.md の「Declaring a slot sensitive」で説明しています。

保存時の暗号化は、意図的に開発者の意図の外、そしてコンパイラの外に置かれています。これはステートフルなコンポーネント向けの Ops Recipe と、ノードのラベルを読んで暗号化されたストレージ設定を出力するレンダリングプラグインの役割です。この配置は、その関心事がどこに属するかについての設計上の指針であり、コンパイラはどの Recipe もそれに従っているかを検査しません。

ここで独自な点と、そうでない点

読者が判断を調整できるよう、公的な位置付けを平易かつ限定的に述べておく価値があります。

独自な点:ソケットの契約はインラインで宣言されるのではなく、公開されます。 クレデンシャルが満たすべき契約(スロット、その配信許可リスト、そのラベルセレクタ)は、それを公開した者が カタログエンティティ 上に記述し、第三者が保守するカタログに置かれます。利用側は自身の設定の中で契約をインラインに記述しません。他者が公開した契約を充足し、コンパイラはその充足を公開された宣言に照らして検査します。利用側と契約の作成者は別の人であり、別のリポジトリで、別のリリースサイクルで作業します。

独自な点:充足はラベルセレクタによって制約されます。 スロットは特定の実装を名指しする代わりに、どのような種類のもの がそれを充足できるかを示せます(selector: "feature.aggrega.ai/kind=secret")。検査はラベル集合の評価であるため、エンティティは見たことのない充足のファミリーを受け入れることができ、新しい充足は適切なラベルを持つことで適格になります。

独自でない点:inject マッピング。 「このローカル環境変数名があの生成された値を受け取る」というマッピングはよく知られたパターンであり、いくつもの設定ツールやデプロイツールが同じ考え方を独自の構文で表現しています。Aggrega の版は事前に評価されて配信パイプにマージされるマッピングですが、その考え方自体はエコシステムのものであり、私たちのものではありません。

独自でない点:事前の静的生成。 上位レベルの記述からデプロイ成果物を静的に生成し、生成時にライブクラスタへアクセスしないことは、Aggrega の発明ではありません。他のツールもそれを行っており、Aggrega が存在する以前から行っていました。Aggrega が加えるのはその上にある公開契約の層であり、静的生成そのものではありません。

セキュリティ境界ではありません。 この章のどの内容も機密保持の仕組みではありません。クレデンシャルモデルは 配線 モデルです。ポインタや値がどこから来るか、誰がそれを制約できるか、そしてそれがどのようにコンテナに届くかを決めます。機密情報を保護するのは、シークレットストア、クラスタ、そしてレンダリングされたツリーを扱うパイプラインの役割です。

相互参照