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

1 つの開発者の意図、2 つの認証情報の受け渡し形態

認証情報が実行中のコンテナに届く方法は、アプリケーションではなく デプロイ先 の性質です。あるクラスタにはシークレットストアがないため、 デプロイメントは Kubernetes Secret に機密データそのものを入れて送ります。別のクラスタではシークレットストアのオペレーターが動いているため、デプロイメントはポインタだけを送り、クラスタが リコンシル時に機密データを取得します。

このワークスペースは 1 つ の Aggregate を持ち、それを 2 つ のターゲット向けにビルドします。 Aggregate はターゲット間で変わりません。データベースが パスワードを参照する部分も変わりません。変わるのは Manifest の 1 行です。

変わるもの、固定されるもの

ファイルlocal ターゲットstore ターゲット
aggregate.yaml同じファイル同じファイル
Manifestmanifest-local.yamlmanifest-store.yaml
Releaserelease-local.yamlrelease-store.yaml

2 つの Manifests の違いは、それ自身の名前と 1 つのマッピングエントリだけです:

Terminal window
$ diff manifest-local.yaml manifest-store.yaml
7c7
< name: credential-shape-local-manifest
---
> name: credential-shape-store-manifest
16c16
< 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.0

2 つの Releases の違いは、それ自身の名前と、どの Manifest を指すかだけです:

Terminal window
$ diff release-local.yaml release-store.yaml
7c7
< name: credential-shape-local
---
> name: credential-shape-store
12c12
< 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-password

core/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: v1
kind: Secret
metadata:
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/v1
kind: ExternalSecret
metadata:
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/ を生成するコマンドは下の「ビルド」セクションにあります):

Terminal window
$ diff -r local store
Only in store/helm/helm: db--app-zuuser-zupassword--db-externalsecret-db-app-user-password.yaml
Only in local/helm/helm: db--app-zuuser-zupassword--db-secret-db-app-user-password.yaml
Only in store/helm/helm: db--password--db-externalsecret-db-password.yaml
Only in local/helm/helm: db--password--db-secret-db-password.yaml

4 行で、すべて 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 アシスタントにビルドを任せることもできます。

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

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

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

Terminal window
cd credential-shape-per-target

ビルド

Terminal window
aggrega build --release release-local.yaml --auto-pull
aggrega build --release release-store.yaml --auto-pull

--auto-pull は、初回ビルド時にカタログを解決して Release の隣にロックファイルを作成します。 同じ Release の以降のビルドではフラグは不要です。

どちらのターゲットも dist/ に書き出し、aggrega build はこれをクリアしないため、 2 つを比較するには実行ごとの出力を別の場所に退避しておきます:

Terminal window
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 回のレンダリング結果が 異なるとビルドが停止します。

Terminal window
aggrega build --release release-local.yaml --verify-determinism
aggrega build --release release-store.yaml --verify-determinism

AI アシスタントを使う

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 ターゲットではどちらも平文のまま出力にレンダリングされます。