シークレット
このページでは、クレデンシャルがそれを必要とするコンポーネントにどのように届くかという 1 つの考え方を説明します。実行可能なワークスペースではありません。高度なプラットフォーム — 複数の境界を持つ Kubernetes プラットフォーム では、自分で構築するワークスペースで両方の配信モデルを示しています。次のコマンドで自分のフォルダーに書き出します:
aggrega scaffold --example advanced-platformその後、次に実行するコマンドを表示します。
cd advanced-platformaggrega pull --release release.yamlaggrega build --release release.yamlシークレット配信チェックリスト
クレデンシャルは、実行中のコンテナに届くまでに 6 つのサーフェスを通過します。新しいクレデンシャルを配線する際に確認すべきタッチポイントは次のとおりです:
| ステップ | 画面 | アクション |
|---|---|---|
| 1 | Component featuresSchema: | クレデンシャルのスロットを宣言します。名前、required かどうか、そして inject: 許可リストを指定します。許可リストはアタッチメントが指定できる配信メカニズムで、透過的なスロットでは [env] または [env, file]、不透明なスロットでは [] です。 |
| 2 | クレデンシャル Feature schema: | 作成者が提供するものを定義します。標準ライブラリのクレデンシャル Features は feature.aggrega.ai/kind: secret ラベルを持ち、クレデンシャルのロケーターを origin として、データキーを key として受け取ります。 |
| 3 | Aggregate features: | 他のすべての Feature と同じ features: キーワードの下でクレデンシャルを要求します。指定するのは type、values、そして透過的なスロットの場合に限り、アプリケーションがそれをどう読み取るかを示す inject: ブロックです。 |
| 4 | FeatureRecipe | ターゲットに合わせて実現します。コンポーネントが読み取る場所に値を書き込むか、値を保持するリソースをレンダリングするか、シークレットストアから値を取得するリソースをレンダリングします。 |
| 5 | Manifest mappings.features.type | クレデンシャル Feature を、他のすべての Feature と同じ階層で、その FeatureRecipe にバインドします。 |
| 6 | Recipe | 不透明なスロットの場合に読み取ります。コンポーネントの Recipe は、クレデンシャルが公開するロケーター .features.<slot>.provides.name を読み取り、チャートの existingSecret など、製品自身のメカニズムに渡します。 |
透過的なスロットは最初の 5 つを使用し、不透明なスロットは 6 つすべてを使用します。後者は、ベンダーのチャートのようなパッケージ化されたインフラストラクチャでは一般的なケースです。
透過的なスロットと不透明なスロット
透過的なスロットでは、アプリケーションがクレデンシャルをどう読み取るかを開発者が指定できます。不透明なスロットは配信を Recipe に任せ、そこに inject: ブロックを書いたアタッチメントはビルドを停止させます。この例では、core/datastore/mariadb がそれぞれを 1 つずつ宣言し、Aggregate が両方を満たします。以下はコメントを省いた aggregate.yaml からの抜粋です:
db: type: core/datastore/mariadb features: root_password: type: core/secret-value values: key: MARIADB_ROOT_PASSWORD origin: dev-root-pw-change-me user_password: type: core/secret-provided values: origin: dev-app-pw-change-me inject: env: - in: MARIADB_PASSWORD from: valueroot_password は不透明です。core/secret-value は、アタッチメントが指定するキーの下に値を渡し、データベースの Recipe はそこで値を読み取ります。user_password は透過的です。core/secret-provided は値を value として公開し、アタッチメント自身の inject: ブロックがそれを MARIADB_PASSWORD に渡します。スロットが列挙していないメカニズムを指定する inject: ブロックはビルドを停止させます。何も公開も読み取りもしないキーを指定するブロックも同様です。
参照可能なクレデンシャルで満たされた不透明なスロットでは、コンポーネントの Recipe は名前を導出するのではなく、公開されたロケーターを読み取ります(existingSecret: "{{ .features.root_password.provides.name }}")。そのため、FeatureRecipe が出力する Secret とそれへの参照は 1 つの文字列になります。MariaDB(Bitnami チャート)— 複数キーのクレデンシャル Secret を 1 つ では、ベンダーのチャートに対してその流れを構築します。
クレデンシャルの実現:リソース、または 2 段階のパイプライン
標準ライブラリの Kubernetes 向けの実現は、FeatureRecipe の隣にある小さなチャートからクレデンシャルのリソースをレンダリングします。helm/k8s-secret-from-parameter は作成者が提供した値を保持する Secret を、helm/k8s-external-secret は External Secrets Operator がシークレットストアから調整する ExternalSecret をレンダリングします。クレデンシャル Features でそれぞれを順に説明しています。
代わりに、FeatureRecipe は 2 つのステップからなる pipeline: でクレデンシャルを実現することもできます。各ステップはプラグインです。1 つ目のフェッチャーは、ストア固有のリソース(たとえば ExternalSecret)を書き出し、アタッチメントの値が示すストアのエントリを指定します。2 つ目のインジェクターは、コンポーネントのレンダリング済みワークロードにパッチを適用し、結果として得られる Secret をそのコンテナにマウントします。マウント先は、アタッチメントの inject: ブロックが指定する変数またはファイルで、ステップはそれを .inject で読み取ります。別のシークレットストアに移行する場合はフェッチャーを置き換え、インジェクターはそのまま残ります。ステップは、追加するリソースを副作用として、レンダリング済みドキュメントへの変更をパッチとして返します。Wasm プラグインコントラクト が両方の形を定めています。
Feature 自身のクレデンシャル
Feature が独自のクレデンシャルを必要とすることがあります。たとえば、上流サービスに対して認証するガードレールプロキシや、取り込みトークンを持つログシッパーです。Feature は、Component とまったく同じように、自身の featuresSchema にスロットを宣言します。そして、それにバインドされた FeatureRecipe は、Feature のワークロードをレンダリングする際に、そのスロットを満たすものを読み取ります。
アタッチメントは入れ子になりません。 クレデンシャルは Feature の隣、つまり同じコンポーネント上に、Feature のスロットが宣言する名前でアタッチされます。両者を結び付けるのはスロット名です。以下のガード Feature とコンポーネントはワークスペース独自のエンティティであり、core/referenced-secret は標準ライブラリのものです。
# The Feature declares the slotkind: Featuremetadata: name: local/guardspec: appliesTo: "component.aggrega.ai/type in (server, worker)" featuresSchema: guard_api_key: selector: "feature.aggrega.ai/kind=secret" sensitive: true inject: [env]---# The Aggregate fills it beside the Featurespec: components: finance-agent: type: local/compute/guarded-worker features: ai-guard: type: local/guard guard_api_key: type: core/referenced-secret values: origin: dev-guard-key-change-me key: api-keyガードの FeatureRecipe は、コンテナがスロットを参照するワークロード(attachments: { GUARD_API_KEY: { from: guard_api_key, as: env } })をレンダリングします。そのため、参照はガードのコンテナにのみ置かれ、他のコンテナには置かれません。ホストコンポーネントの Recipe はスロットを参照できません。スロットは Feature に属するためです。スロットを参照しようとするワークロードは、そのスロットを示してビルドを停止させます。何も満たしていないスロットを指定するワークロードのエントリもビルドを停止させます。解決すべき公開済みのロケーターが存在しないためです。
Feature が引く接続についても同じことが言えます。Feature 自身の uses: ブロック内の接続はアタッチメントを持たないため、そうした接続が必要とするクレデンシャルは Feature が宣言するスロットとなり、Feature の隣で満たされます。
接続自身のクレデンシャル
2 つのモデルに接続するゲートウェイは、それぞれに異なるキーを提示することも、一方にはキーを、もう一方には何も提示しないこともあります。ゲートウェイのスロットはコンポーネント全体で 1 つのクレデンシャルを保持するため、クレデンシャルは代わりに接続に置きます。ゲートウェイのソケットが、そこを通るすべての接続が埋めることのできるスロットを宣言し、各接続はそれぞれ独自にそのスロットを埋めるか、埋めないかを決めます。
spec: components: router: type: core/gateway/litellm uses: models: gpt: target: gpt features: credential: # a slot the models socket declares type: core/referenced-secret values: key: api-keyゲートウェイの Recipe は、接続からアタッチメントを .context.uses.gpt.features.credential で読み取ります。そのため、複数のモデルに接続するゲートウェイは、各モデル固有のキーを読み取ります。core/gateway/litellm は各キーをそれぞれ独立した変数として渡し、その変数名はルーティングテーブル内の接続のエントリが指定します。ソケットがスロットを宣言していない名前の下にあるアタッチメントは、ソケットが宣言しているスロットを示してビルドを停止させます。Manifest は、インスタンスごとの階層で <connection>.credential をキーとして、ある接続のクレデンシャルを他とは異なる方法で実現できます。接続上のクレデンシャル — 接続ごとのキーと、両端で共有する 1 つのキー でこれを構築します。また、Release がそのような接続を配線し、アタッチメントの infra でシークレットを指定することもできます。これについては クレデンシャル Features で説明しています。