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

認証情報の共有 — コンシューマーごと、共有、そしてその両方

1 つの OpenAI 互換ゲートウェイの背後にある 2 つの CrewAI エージェント。各エージェントの model ソケットは credential スロットを宣言しているため、エージェントが到達するモデルに提示するキーは その接続に付与されます。このワークスペースは、カタログエンティティを 1 つも変更せずに、このスロットを 3 通りの方法で埋めます。接続ごとのキー、すべての接続が指す 1 つの Secret、 そして 1 つの接続が上書きする共有デフォルトです。

2 つのコンシューマーであることが要点です。 コンシューマーが 1 つだけでは 3 つの形式は 区別できません。違いは各コンシューマーが最終的に どの Secret を指すかであり、 この問いはコンシューマーが複数になるまで意味を持ちません。

サンプルを生成する

このサンプルは以下のコマンドでビルドできます。または、AI アシスタントにビルドを任せることもできます。

例の名前を付けた新しいフォルダーに例を書き出します。

Terminal window
aggrega scaffold --example model-api-key-sharing

その後、次に実行するコマンドを表示します。最初のコマンドは新しいフォルダーに移動します。

Terminal window
cd model-api-key-sharing

ビルド

3 つのリリースがあり、形式ごとに 1 つです。1 回の実行につき 1 つをビルドします。

Terminal window
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 を取ることができます。

リリースはビルド前にロックファイルを必要とします。新しいチェックアウトでは、まずロックファイルを解決します。 独立したステップとして行うか、ビルドに埋めさせるかのいずれかです。

Terminal window
aggrega pull --release release-shared.yaml # resolve, then build normally
aggrega 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 つ出力され、それぞれがそのエージェント自身のマテリアルを保持します。

dist/per-consumer/helm/researcher--gateway-zdcredential--researcher-secret-researcher-gateway-credential.yaml
[… 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 を参照します。

dist/per-consumer/helm/researcher-deployment.yaml
- 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-key
components:
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 を参照します。

dist/shared/helm/researcher-deployment.yaml
- 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 Secret
writer:
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 をそのまま維持します。

dist/composed/helm/researcher-deployment.yaml
- 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 回レンダリングし、出力されたバイトを比較します。

Terminal window
aggrega build --release release-shared.yaml --auto-pull --verify-determinism

3 つのいずれをクリーンなツリーから再ビルドしても、レンダリング出力が バイト単位で再現されます。