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

Credential Features

このページでは 1 つの考え方、すなわち標準ライブラリのクレデンシャル Features と、それぞれを何が実現するかを Manifest がどう選ぶかを説明します。実行可能なワークスペースではありません。1 つの開発者の意図、2 つのクレデンシャル配信形態 は、同じクレデンシャルの 2 つの実現に対して 1 つの Aggregate をビルドします。次のようにして自分のフォルダーに書き出せます:

Terminal window
aggrega scaffold --example credential-shape-per-target

その後、次に実行するコマンドを表示します。

Terminal window
cd credential-shape-per-target
aggrega build --release release-local.yaml --auto-pull
aggrega build --release release-store.yaml --auto-pull

クレデンシャルは、Component が自身の featuresSchema で宣言するスロットを埋めます(entities/component.md を参照)。スロット、それを埋める Feature、Manifest がバインドする FeatureRecipe が、作成者のアタッチメントから実行中のワークロードまでの経路全体を形成します。

クレデンシャル Feature ファミリー

クレデンシャル Feature は feature.aggrega.ai/kind: secret ラベルを持ちます。このラベルはアタッチメントが何を生成するかを記述するカタログのメタデータです。このラベルを読むコンパイラの分岐はなく、クレデンシャル Feature は他の Feature と同様に features: の下にアタッチされます。アタッチするのは、Aggregate では開発者、Release では運用者です。

標準ライブラリは、クレデンシャル Features を、実現がシークレットをどう扱うかによって分けています。

  • core/secret-value は値をコンポーネントの inject パイプに渡し、そのコンポーネントの Recipe がそこで値を読み取ります。チャートの値や環境変数がこれにあたります。
  • core/secret-provided も値を生み出しますが、代わりにそれを provides キーとして公開します。そのため、透過的なスロット上のアタッチメント自身の inject: ブロックが値の行き先を指定します。
  • core/referenced-secret はシークレットリソース(Kubernetes Secret、AWS Secrets Manager のシークレット、Vault のエントリ)を指定します。このリソースはその実現が作成するか、すでに存在するものです。そして、そのリソースの name と key を公開し、利用側はそれらを .features.<slot>.provides.name と .features.<slot>.provides.key として読み取ります。
  • core/referenced-secret-set は、作成者が指定するデータキーのセットを保持するそのようなリソースを 1 つ実体化し、そのロケーターだけを公開します。読み取るキー名がターゲット側ですでに決まっている利用側向けです。Docker Compose にはそのようなリソースがないため、そこでの実現は後述のとおり、代わりにキーを値として渡します。MariaDB(Bitnami チャート)— 複数キーを持つ 1 つのクレデンシャル Secret がこれを使用しています。
  • core/generated-secret は何も生成しません。マネージドデータベースが管理者パスワードについて行うように、ターゲットエンジン自身がクレデンシャルを生成し管理します。運用者はこれを Release でアタッチします。エンジンがクレデンシャルを所有するかどうかは Manifest が選ぶ Recipe によって決まるためです。Terraform RDS(インライン HCL アーティファクト) はこの方法で必須スロットをバインドしています。
  • core/random-password は、ターゲットがパスワードを生成してシークレットリソースに格納するためのリクエストをレンダリングし、core/referenced-secret と同じようにそのリソースのロケーターを公開します。誰もクレデンシャルを書かず、レンダリングされた出力にもクレデンシャルは含まれません。

これらは対等です。ラベルもアタッチメントの面もスロットも同じなので、スロットは常に埋まっており、Releases の間で変わるのはそれを何が埋めるかです。provides コントラクトを宣言するクレデンシャル Feature は、それを実装するすべての FeatureRecipe にそれらのキーの公開を義務付け、公開しないものがあればビルドは停止します。これが利用側の読み取りを安全にしています。

ビルドが値を生成することはないため、core/random-password には値を生成するものがターゲット側に必要です。Kubernetes では、Release が infra.control_plane_present: true で存在を確認するコントローラー(External Secrets Operator または kubernetes-secret-generator)、Terraform では random_password リソース、CloudFormation では自身の文字列を生成する Secrets Manager のシークレットです。Docker Compose 向けの実現は提供されていないため、そこでこれをバインドするビルドは停止します。リクエストはそれぞれ独自の値を生成するため、2 つのコンポーネントが生成された 1 つのパスワードを共有するには、name を固定して 1 回だけアタッチし、ほかの場所では helm/k8s-existing-secret にバインドした core/referenced-secret を通じて読み取ります。

資格情報を指定するのは誰か: values または infra のいずれか一方のみ

core/secret-value、core/secret-provided、core/referenced-secret、core/referenced-secret-set は、どちらの作成者からでもクレデンシャルのロケーターを受け付けます。開発者は Aggregate 内のアタッチメントの values に、運用者は Release 内のアタッチメントの infra に記述します。リーフはどちらでも同じ(origin、セットの場合は entries)で、すべての実現はロケーターを持つ方のピラーを読み取ります。

運用者側の形式により、開発者がクレデンシャルを記述できない場所でもクレデンシャルを使えるようになります。つまり、Release が配線する接続と、Release だけが作るアタッチメントです。Release は values をどこにも記述しないためです。

# Release: the operator wires the connection and names the secret.
spec:
components:
router:
uses:
models:
gpt:
target: gpt
features:
credential:
type: core/referenced-secret
infra:
origin: openai-team-a

2 つのうちちょうど 1 つ。 各ピラーは単独で検証されるため、どちらのスキーマもロケーターを必須にはできません。代わりに各 Feature 自身の assertions がこのルールを保持し、ロケーターを両方のピラーに持つ、またはどちらにも持たないアタッチメントは、Feature、アタッチメント、コンポーネントを示してビルドを停止させます(E0033)。これはカタログエンティティの契約です。コンパイラはそのアサーションを、他の Feature のアサーションと同様に評価します。

それ以外はすべて自身のピラーにとどまります。 key は values のリーフのままなので、Release だけが作るアタッチメントはデフォルトのデータキー value を読み取ります。origin を両方のピラーで宣言することは、まさにピラー重複アドバイザリが検出する対象です。そのため、これらの Features を読み込むとアドバイザリ(LINT: Feature "core/referenced-secret" ... declares property "origin" in both values: and infra: pillars)が報告されます。ここでは重複が契約です。このアドバイザリは判定もレンダリング結果のバイトも一切変えません。

Manifest が実現を選択する

同じターゲットに対して複数の FeatureRecipes が 1 つの Feature を実装でき、どれを使うかは Manifest が選びます。core/referenced-secret には Kubernetes 上に 3 つあり、どれを選ぶかはクレデンシャルがどこにあるかで決まります。

  • helm/k8s-secret-from-parameter は、作成者が指定した値を自身が出力する Secret に書き込むため、機密情報はレンダリング出力に含まれます。評価やローカル作業向けです。
  • helm/k8s-external-secret は、シークレットストア内のエントリを指定する ExternalSecret をレンダリングし、クラスタ内の External Secrets Operator がそれを Secret に調整します。
  • helm/k8s-existing-secret は何も出力しません。origin をすでに存在する Secret の名前として読み取り、記述どおりに公開します。

最初の 2 つは、ホストのレンダリング名とスロットの名前から、同じ方法で Secret の名前を導出します。そのため、利用側はどちらからでも同じロケーターを読み取り、レンダリングされる参照も変わりません。例が示しているのはこの点です。3 つ目は既存の Secret 自体の名前を公開するため、これをバインドすると利用側の参照は意図的に変わります。

core/secret-value は Docker Compose では compose/dotenv-secret によって実現されます。これは値を記述どおりにサービスの環境に書き込みます。${DB_PASSWORD} として書かれた origin はその参照のまま書き込まれ、スタックの起動時に Docker Compose がシェルまたは .env ファイルから埋めます。Kubernetes では、helm/env-secret が値を inject パイプに渡し、helm/k8s-secret-from-value はさらに値を Secret に書き込んでそのロケーターを公開します。これはクレデンシャルを参照で読み取る利用側向けです。どちらの Kubernetes の実現も Compose の変数参照は受け付けません。そこではそれを埋めるものが何もないためです。

core/referenced-secret は、Docker Compose では compose/dotenv-referenced-secret によって実現されます。Compose には参照先となるシークレットリソースがないため、origin は Secret の名前ではなく認証情報そのものです。これはアタッチメントの key の名前で inject パイプに渡され、スロットを読み取る Compose の Recipe が記述どおりに出力ファイルへ書き込みます。そのため、${DB_PASSWORD} と書かれた origin はその参照のまま書き込まれます。リソースは作成しないため、公開する名前は空で、公開するキーは values.key です。

core/referenced-secret-set は、Docker Compose では compose/dotenv-secret-set によって実現されます。これは各エントリをそのキーの名前を持つ変数として inject パイプに渡し、記述どおりにサービスの環境へ書き込みます。そのため、値が ${GITHUB_TOKEN} のエントリはその参照のまま書き込まれます。リソースは作成しないため、公開するロケーターは空です。Compose 上の利用側は、Secret を名前で参照するのではなく、自身の inject パイプからエントリを読み取ります。1.1.0 以降の compose/mcp と compose/mcp-stdio-bridge は、Model Context Protocol サーバーの server_env に対してこのように動作します。

複数のターゲット向けに提供される FeatureRecipe 名(provided-secret など)は、Manifest ではターゲットを付けて compose/provided-secret:1.0.0 のように指定します。プレフィックスのない名前は両方に一致するためです。

1 つの名前を 1 回だけ公開する

利用側の Recipe は、クレデンシャルが生成する Secret の名前を導出することはありません。クレデンシャルが公開するロケーターを existingSecret: "{{ .features.root_password.provides.name }}" のように読み取ります。名前は FeatureRecipe の provides で 1 回だけ記述されるため、名前の組み立て方を変える場合もそこだけを編集すれば済みます。クレデンシャルの配信 — secretKeyRef のエンドツーエンド は Kubernetes 上で参照可能な経路を、Docker Compose 上で注入される経路を構築し、クレデンシャルの共有 — 利用側ごと、共有、その両方 は複数の利用側がそれぞれ独自のキーを持つ場合や 1 つを共有する場合を示します。