1 つの開発者の意図、2 つの認証情報の受け渡し形態
認証情報が実行中のコンテナに届く方法は、アプリケーションではなく デプロイ先 の性質です。あるクラスタにはシークレットストアがないため、 デプロイメントは Kubernetes Secret に機密データそのものを入れて送ります。別のクラスタではシークレットストアのオペレーターが動いているため、デプロイメントはポインタだけを送り、クラスタが リコンシル時に機密データを取得します。
このワークスペースは 1 つ の Aggregate を持ち、それを 2 つ のターゲット向けにビルドします。 Aggregate はターゲット間で変わりません。データベースが パスワードを参照する部分も変わりません。変わるのは Manifest の 1 行です。
変わるもの、固定されるもの
| ファイル | local ターゲット | store ターゲット |
|---|---|---|
aggregate.yaml | 同じファイル | 同じファイル |
| Manifest | manifest-local.yaml | manifest-store.yaml |
| Release | release-local.yaml | release-store.yaml |
2 つの Manifests の違いは、それ自身の名前と 1 つのマッピングエントリだけです:
$ diff manifest-local.yaml manifest-store.yaml7c7< name: credential-shape-local-manifest---> name: credential-shape-store-manifest16c16< core/referenced-secret:1.0.0: helm/k8s-secret-from-parameter:1.0.0---> core/referenced-secret:1.0.0: helm/k8s-external-secret:1.0.02 つの Releases の違いは、それ自身の名前と、どの Manifest を指すかだけです:
$ diff release-local.yaml release-store.yaml7c7< name: credential-shape-local---> name: credential-shape-store12c12< manifest: credential-shape-local-manifest---> manifest: credential-shape-store-manifest両方の Releases は同じ environment を宣言しています。これは意図的なものです。環境名はレンダリングされるすべてのドキュメントにラベルとして付与されるため、これを固定しておくと、動かせるものはちょうど一つ、Manifest がバインドする FeatureRecipe だけになります。実際の Releases の組であれば当然それぞれ独自の環境名を付けますが、認証情報の形はまったく同じように異なります。
開発者側の記述は 1 回だけ
aggregate.yaml は、PostgreSQL の Component の 2 つの認証情報スロットの両方を、
同じ参照可能な認証情報 Feature で埋めます:
features: password: type: core/referenced-secret values: key: POSTGRES_PASSWORD origin: postgres-superuser-password app_user_password: type: core/referenced-secret values: key: APP_USER_PASSWORD origin: postgres-app-passwordcore/referenced-secret はシークレット リソース を指定します。これはその FeatureRecipe の出力が
作成するもの、または既に存在するもののどちらかです。そして、そのリソースのロケーター、つまり
name とその中のデータの key を、provides 契約を通じて公開します。
利用側の Recipe はそのロケーターを読み取ります。独自にリソース名を導出することはなく、
どの FeatureRecipe がそれを生成したかを問うこともありません。
各ターゲットが出力するもの
各ビルドは 6 つのファイルを書き出します。そのうち 4 つ、つまり StatefulSet、2 つの Service、 初期化用の ConfigMap は、両ターゲットからバイト単位で同一の内容が出力されます。 残りの 2 つは認証情報リソースで、埋められたスロットごとに 1 つずつあり、 ここがターゲット間で異なる部分です。
local ターゲット、k8s-secret-from-parameter から、
dist/helm/helm/db--password--db-secret-db-password.yaml に出力:
apiVersion: v1kind: Secretmetadata: name: db-password [… omitted: the labels and annotations naming the aggregate, component, environment, compiler and provider versions, boundary and Recipe — the same set every rendered document carries]stringData: POSTGRES_PASSWORD: "postgres-superuser-password"store ターゲット、k8s-external-secret から、
dist/helm/helm/db--password--db-externalsecret-db-password.yaml に出力:
apiVersion: external-secrets.io/v1kind: ExternalSecretmetadata: name: db-password [… omitted: the same label and annotation set as above]spec: refreshInterval: "1h" secretStoreRef: name: platform-secret-store kind: ClusterSecretStore target: name: db-password creationPolicy: Owner data: - secretKey: POSTGRES_PASSWORD remoteRef: key: "postgres-superuser-password"API グループも、kind も、本体も異なります。local ターゲットでは、
認証情報の機密データがレンダリングされたドキュメントに含まれ、デプロイメントを読める人なら誰でも
読めます。そのため、この形態は本番クラスタではなくローカルや開発用のクラスタに
適しています。store ターゲットでは、レンダリングされたドキュメントには
エントリ名だけが含まれます。機密データはストアに留まり、オペレーターがそれを
db-password という名前の Secret にリコンシルします。
2 つの出力ツリーを比較すると、違いと、その違いがどこで止まるかがわかります
(local/ と store/ を生成するコマンドは下の「ビルド」セクションにあります):
$ diff -r local storeOnly in store/helm/helm: db--app-zuuser-zupassword--db-externalsecret-db-app-user-password.yamlOnly in local/helm/helm: db--app-zuuser-zupassword--db-secret-db-app-user-password.yamlOnly in store/helm/helm: db--password--db-externalsecret-db-password.yamlOnly in local/helm/helm: db--password--db-secret-db-password.yaml4 行で、すべて 1 つのディレクトリ内にあります。このターゲットでは、アタッチメントのファイルがサブディレクトリではなく
コンポーネント自身のファイルの隣に置かれるためです。2 つの座標を担うのは
ファイル名です。db--password-- は db 上の password アタッチメントを、
db--app-zuuser-zupassword-- は app_user_password のアタッチメントを表します。
ここでは座標とファイル自身の名前が 1 つの文字列を共有するため、
アンダースコアは -zu としてエンコードされます。
4 行で、それ以外はありません。2 つの認証情報リソースは local
ターゲットのツリーにのみ、別の 2 つは store ターゲットのツリーにのみ存在します。diff -r は、2 つのツリーが共有する
どのファイルにも内容の違いを報告しないため、共通の 4 つのドキュメントは
単に似ているのではなく同一です。
変わらない参照
データベースコンテナは、両方の認証情報を secretKeyRef に基づく環境変数として
読み取ります。このブロックは両ターゲットでバイト単位で同一です:
- name: POSTGRES_PASSWORD valueFrom: secretKeyRef: name: db-password key: POSTGRES_PASSWORD- name: APP_USER_PASSWORD valueFrom: secretKeyRef: name: db-app-user-password key: APP_USER_PASSWORDこれが同一になるのは、利用側の Recipe が分岐しないためです。Recipe はスロットに
公開された name と key を問い合わせ、それを書き出します。両方の FeatureRecipes は、
Feature がこの 2 つのキーを宣言しているため同じキーを公開します。したがってどちらも利用側の要件を満たします。
そして store ターゲットでは、オペレーターが ExternalSecret をその名前の Secret に調整した時点で参照が解決されます。
この不変性こそが、2 つの形態を置き換え可能にしています。 もし利用側が Secret 名を自ら導出していたなら、バインディングを入れ替えると、その名前ではもう存在しない リソースを指したままになっていたでしょう。
origin の意味は FeatureRecipe が定める
core/referenced-secret は origin を機密データの取得元として宣言し、
その解釈を FeatureRecipe に委ねます:
k8s-secret-from-parameterは、それを機密データとして Secret に書き込みます。k8s-external-secretは、それをストアから取得するキーとして読み取ります。
コンパイラは文字列をそのまま受け渡します。与えられた文字列がそのどちらであるかには依存しません。 これにより、開発者側で一切編集することなく、1 つのアタッチメントが両方の形態に対応できます。 また、バインディングを入れ替える前に確認すべき点でもあります。 同じ記述済みの文字列が、それを読む FeatureRecipe のどちらにとっても意味を持つ必要があるためです。
公開される名前と、スロット名のアンダースコア
Component は 2 つ目の認証情報スロットに app_user_password という名前を付けています。Kubernetes の
オブジェクト名にはアンダースコアを含められないため、公開される provides.name は
アンダースコアをハイフンに正規化し、リソースは
db-app-user-password として作成されます:
- name: APP_USER_PASSWORD valueFrom: secretKeyRef: name: db-app-user-passwordどちらの FeatureRecipes も同じように正規化するため、バインディングを入れ替えても 利用側の参照は変わりません。名前は生成側で 1 回だけ公開され、 出力されるリソースと利用側の参照はどちらも、その 1 つの公開値から解決されます。
store ターゲットがクラスタに求めるもの
ExternalSecret はカスタムリソースです。store ターゲットの出力をクラスタに適用するには、
そこでシークレットストアのオペレーターが動作しており、
platform-secret-store という名前の ClusterSecretStore が存在している必要があります。このワークスペースは
どちらもインストールしません。この例は、そのようなクラスタが利用するものをレンダリングし、
形態がどのように選ばれるかを示すものです。
クラスタがどのストアをどの名前で動かすかは、アプリケーションではなくターゲットの
性質です。そのため k8s-external-secret にはそのための記述キーがありません。
ストアの名前が異なるクラスタには、そのストアを指定する FeatureRecipe で対応します。
サンプルを生成する
このサンプルは以下のコマンドでビルドできます。または、AI アシスタントにビルドを任せることもできます。
例の名前を付けた新しいフォルダーに例を書き出します。
aggrega scaffold --example credential-shape-per-targetその後、次に実行するコマンドを表示します。最初のコマンドは新しいフォルダーに移動します。
cd credential-shape-per-targetビルド
aggrega build --release release-local.yaml --auto-pullaggrega build --release release-store.yaml --auto-pull--auto-pull は、初回ビルド時にカタログを解決して Release の隣にロックファイルを作成します。
同じ Release の以降のビルドではフラグは不要です。
どちらのターゲットも dist/ に書き出し、aggrega build はこれをクリアしないため、
2 つを比較するには実行ごとの出力を別の場所に退避しておきます:
out=$(mktemp -d)rm -rf dist && aggrega build --release release-local.yaml --auto-pull && cp -r dist "$out/local"rm -rf dist && aggrega build --release release-store.yaml --auto-pull && cp -r dist "$out/store"( cd "$out" && diff -r local store )各ターゲットが決定的にレンダリングされることを確認するには、--verify-determinism を追加します。
すべてのノードが 2 回レンダリングされ、いずれかのノードの 2 回のレンダリング結果が
異なるとビルドが停止します。
aggrega build --release release-local.yaml --verify-determinismaggrega build --release release-store.yaml --verify-determinismAI アシスタントを使う
Aggrega のツールでセットアップした AI アシスタントでも同じことができます。次のプロンプトを貼り付けてください。
Aggrega のツールだけを使い、フォルダーは自分で作成しないでください。ワークスペースフォルダーにまだ `credential-shape-per-target` フォルダーがない場合は、`example` を `credential-shape-per-target` に設定し、`dir` を指定せずに `scaffold` ツールを 1 回呼び出してください。これにより、例が新しい `credential-shape-per-target` フォルダーに書き込まれます。次に、各 Release について `build` ツールを 1 回ずつ、`release-local.yaml`、`release-store.yaml` の順に呼び出してください。毎回、`workspace_root` を `credential-shape-per-target`、`release` をそのファイル、`auto_pull` を true、`write` を true に設定します。各ビルドが書き込んだファイルを教えてください。ファイルは `credential-shape-per-target/dist/` の下にあります。ファイル
aggregate.yaml— 開発者の意図: 型core/datastore/postgresのdbコンポーネントが 1 つあり、両方の認証情報スロットがcore/referenced-secretで埋められています。両方の Releases で変更なしに使われます。manifest-local.yaml—core/referenced-secretをk8s-secret-from-parameterにバインドします。これは記述された機密データから Kubernetes Secret をレンダリングします。manifest-store.yaml— 同じ Feature をk8s-external-secretにバインドします。これは ストアのエントリを指定する ExternalSecret をレンダリングします。それ自身の名前とその 1 行を除いてmanifest-local.yamlと同一です。release-local.yaml、release-store.yaml— 2 つの Releases です。それ自身の名前と、 それぞれがどの Manifest を指すかを除いて同一です。.aggrega-config.yaml— カタログのエンティティの解決元となるハブレジストリを指定します。
ここでの origin の値はプレースホルダーです。実在するサービスの認証情報ではなく、
local ターゲットではどちらも平文のまま出力にレンダリングされます。