認証情報の共有 — コンシューマーごと、共有、そしてその両方
1 つの OpenAI 互換ゲートウェイの背後にある 2 つの CrewAI エージェント。各エージェントの model
ソケットは credential スロットを宣言しているため、エージェントが到達するモデルに提示するキーは
その接続に付与されます。このワークスペースは、カタログエンティティを 1 つも変更せずに、このスロットを 3 通りの方法で埋めます。接続ごとのキー、すべての接続が指す 1 つの Secret、
そして 1 つの接続が上書きする共有デフォルトです。
2 つのコンシューマーであることが要点です。 コンシューマーが 1 つだけでは 3 つの形式は 区別できません。違いは各コンシューマーが最終的に どの Secret を指すかであり、 この問いはコンシューマーが複数になるまで意味を持ちません。
サンプルを生成する
このサンプルは以下のコマンドでビルドできます。または、AI アシスタントにビルドを任せることもできます。
例の名前を付けた新しいフォルダーに例を書き出します。
aggrega scaffold --example model-api-key-sharingその後、次に実行するコマンドを表示します。最初のコマンドは新しいフォルダーに移動します。
cd model-api-key-sharingビルド
3 つのリリースがあり、形式ごとに 1 つです。1 回の実行につき 1 つをビルドします。
aggrega build --release release-per-consumer.yaml --auto-pull # → dist/per-consumer/aggrega build --release release-shared.yaml --auto-pull # → dist/shared/aggrega build --release release-composed.yaml --auto-pull # → dist/composed/各リリースはそれぞれ専用のディレクトリに書き出すため、レンダリングされた 3 つのツリーはすべて共存でき、 互いに diff を取ることができます。
リリースはビルド前にロックファイルを必要とします。新しいチェックアウトでは、まずロックファイルを解決します。 独立したステップとして行うか、ビルドに埋めさせるかのいずれかです。
aggrega pull --release release-shared.yaml # resolve, then build normallyaggrega build --release release-shared.yaml --auto-pull # or resolve during the buildリリースはカタログエンティティを設定済みのカタログから解決するため、--catalog フラグは不要です。
3 つとも意図的に helm ターゲットでビルドします。3 つの形式を区別する観測点は
各エージェントのコンテナが参照する Secret の名前 であり、
helm では認証情報は、コンテナが名前で参照する名前付きの Kubernetes Secret です。
2 つの Manifests が認証情報をバインドします。コンシューマーごとのリリースでは manifest.yaml が
k8s-secret-from-parameter にバインドし、これはアタッチメントが運ぶ値から Secret をレンダリングします。共有および合成のリリースでは
manifest-existing-secret.yaml が k8s-existing-secret にバインドし、これは何もレンダリングせず、
各コンシューマーを namespace にすでに存在する Secret に向けます。
AI アシスタントを使う
Aggrega のツールでセットアップした AI アシスタントでも同じことができます。次のプロンプトを貼り付けてください。
Aggrega のツールだけを使い、フォルダーは自分で作成しないでください。ワークスペースフォルダーにまだ `model-api-key-sharing` フォルダーがない場合は、`example` を `model-api-key-sharing` に設定し、`dir` を指定せずに `scaffold` ツールを一度呼び出してください。これにより、例が新しい `model-api-key-sharing` フォルダーに書き込まれます。次に、`release-per-consumer.yaml`、`release-shared.yaml`、`release-composed.yaml` の順に、各 Release について `build` ツールを一度ずつ呼び出してください。毎回、`workspace_root` を `model-api-key-sharing`、`release` をそのファイル、`auto_pull` を true、`write` を true に設定します。各ビルドが書き込んだファイルを教えてください。ファイルは `model-api-key-sharing/dist/` の下にあります。コンシューマーごと — 各接続が独自のキーを保持する
aggregate-per-consumer.yaml は各エージェントの接続でスロットを埋め、
エージェントごとに異なる origin を指定します。
researcher: type: core/ai-agent/crewai uses: model: gateway: target: gateway features: credential: type: core/referenced-secret values: key: OPENAI_API_KEY origin: researcher-key-change-me接続上のアタッチメントはエージェント自身のアタッチメントの 1 つとなり、
接続とスロットにちなんで名付けられます(ここでは gateway.credential)。そのため Secret が
エージェントごとに 1 つずつ、計 2 つ出力され、それぞれがそのエージェント自身のマテリアルを保持します。
[… omitted: the apiVersion and the Secret kind]metadata: name: researcher-gateway.credential [… omitted: the labels and annotations every rendered document carries]stringData: OPENAI_API_KEY: "researcher-key-change-me"
# dist/per-consumer/helm/writer--gateway-zdcredential--writer-secret-writer-gateway-credential.yaml[… omitted: the apiVersion and the Secret kind]metadata: name: writer-gateway.credential [… omitted: the labels and annotations every rendered document carries]stringData: OPENAI_API_KEY: "writer-key-change-me"そして各 Deployment は自身の Secret を参照します。
- name: OPENAI_API_KEY valueFrom: secretKeyRef: name: researcher-gateway.credential key: OPENAI_API_KEY
# dist/per-consumer/helm/writer-deployment.yaml- name: OPENAI_API_KEY valueFrom: secretKeyRef: name: writer-gateway.credential key: OPENAI_API_KEY一方のエージェントのキーを失効させても、もう一方は動作し続けます。
共有 — 各接続から参照される 1 つの Secret
接続上の認証情報はその接続に記述されます。他の場所に付与されたものがそれを埋めることはありません。 そのため、複数のコンシューマーは 記述によって 1 つの認証情報を共有します。 各接続の認証情報は同じ値を読み取り、その値が 1 つの Secret を指定します。
aggregate-shared.yaml は 1 つのパラメーターを宣言し、両方の
接続でそれを読み取ります。
parameters: team_model_key: type: string default: team-model-keycomponents: researcher: uses: model: gateway: target: gateway features: credential: type: core/referenced-secret values: key: OPENAI_API_KEY origin: "{{ .parameters.team_model_key }}" writer: { ... } # the same credential, reading the same parameterこのリリースは認証情報を k8s-existing-secret にバインドします。これは origin
を namespace にすでに存在する Secret の名前として読み取ります。
Secret は一切レンダリングされず(ゲートウェイの Service と 2 つの Deployment のみが書き出されます)、
両方の Deployment はパラメーターが指定する 1 つの Secret を参照します。
- name: OPENAI_API_KEY valueFrom: secretKeyRef: name: team-model-key key: OPENAI_API_KEY
# dist/shared/helm/writer-deployment.yaml- name: OPENAI_API_KEY valueFrom: secretKeyRef: name: team-model-key key: OPENAI_API_KEYこれは物理的にちょうど 1 つの Secret であり、デプロイする人が Release の外部で作成し、 すべてのコンシューマーが読み取ります。キーのマテリアルが、記述されたファイルやレンダリングされた成果物を 通過することはありません。
パラメーターが運ぶものは、Manifest がバインドする実現方法に従います。
k8s-existing-secret の下では、それは Secret の名前です。代わりに
k8s-secret-from-parameter にバインドすると、1 つのパラメーターを読み取る同じ 2 つの接続は
キーそのものを運び、ビルドはコンシューマーごとに 1 つの Secret をレンダリングし、
それぞれが同じマテリアルを保持します。レンダリングはコンポーネントごとに実行され、その
実現方法はレンダリングする Secret を、消費側のコンポーネントと接続にちなんで名付けるためです。
1 つのパラメーターがコンシューマー同士の乖離を防ぎ、
どの実現方法がそれを読み取るかによって、リソースを共有するかどうかが決まります。クラスター内で
生成される認証情報も同じ方法で共有されます(1 つのリクエストと多数の
参照)。認証情報モデルを参照してください。
合成 — 共有デフォルトと、それを上書きする 1 つの接続
aggregate-composed.yaml は共有パラメーターをデフォルトとして維持し、1 つの
接続に独自の Secret を指定させます。
researcher: uses: model: gateway: target: gateway features: credential: type: core/referenced-secret values: key: OPENAI_API_KEY origin: researcher-model-key # this connection's own Secretwriter: uses: model: gateway: target: gateway features: credential: type: core/referenced-secret values: key: OPENAI_API_KEY origin: "{{ .parameters.team_model_key }}" # the shared default上書きはその 1 つの接続が記述するものです。何もそこへカスケードせず、
writer は共有 Secret をそのまま維持します。
- name: OPENAI_API_KEY valueFrom: secretKeyRef: name: researcher-model-key key: OPENAI_API_KEY
# dist/composed/helm/writer-deployment.yaml- name: OPENAI_API_KEY valueFrom: secretKeyRef: name: team-model-key key: OPENAI_API_KEY接続の認証情報はそれ自体で完全なアタッチメントであるため、上書きでは
必要なすべてのフィールド(ここでは Feature の型、key、origin)を改めて記述し、
デフォルトからは何も継承しません。
スロットがもたらすもの
core/ai-agent/crewai は model ソケットでスロットを 1 度だけ宣言し、
3 つの形式はすべて Aggregate で行われる選択です。
usesSchema: model: selector: "component.aggrega.ai/category in (ai-model, gateway), model.aggrega.ai/api" required: true inject: [env, file] featuresSchema: credential: selector: "feature.aggrega.ai/kind=secret" sensitive: true inject: [env]スロットは省略可能なので、4 つ目の形は何も付与しないことです。両方の接続から
features: ブロックを削除すると、レンダリングされたツリーからすべての
OPENAI_API_KEY env エントリがなくなり、2 つの Deployment とゲートウェイの Service が残ります。
欠落を埋めるために何かが作り出されることはありません。カタログエンティティはどの場合も同一で、
決めるのは作成者です。
これがビルドできるのは、ここでのゲートウェイ core/ai-model/openai-compatible に
component.aggrega.ai/hosting ラベルがないためです。カタログが managed とラベル付けしたターゲット
(たとえば core/ai-model/openai)に認証情報なしで到達する接続は、
エージェント自身のアサーションによってビルドを停止させます。ただし、接続がその
values でターゲットが認証情報を取らないこと(unauthenticated: true)を示している場合は除きます。
スロットはファミリーにも依存しません(feature.aggrega.ai/kind=secret はどちらの
認証情報ファミリーも受け入れます)。これにより、同じエージェントが helm では参照可能な
Secret を、compose では値注入型の認証情報を受け取れます。
認証情報の配送 — secretKeyRef のエンドツーエンド
はこのプロバイダーの分岐を扱っており、その否定的なリリースは、
参照不可能な認証情報に参照を満たすよう求めた場合に何が起こるかを示しています。
決定性
3 つのリリースはすべて --verify-determinism の下でビルドされます。これはすべてのノードを
2 回レンダリングし、出力されたバイトを比較します。
aggrega build --release release-shared.yaml --auto-pull --verify-determinism3 つのいずれをクリーンなツリーから再ビルドしても、レンダリング出力が バイト単位で再現されます。