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

独自の Webhook 証明書:チャートが生成する Secret を除外する

これは上級者向けの例です。Recipe のフィールド omits: を扱いますが、ほとんどの Recipes では必要ありません。このフィールドは、そのまま取り込むソース(ここではレジストリから 取得したチャート)が、Release に含めてはならないドキュメントをレンダリングする場合のためのものです。 そのような場合に出会ったときに使用してください。

このワークスペースは、Envoy Gateway が拡張サーバーとして呼び出すコントローラーである Envoy AI Gateway のコントロールプレーンを、 標準ライブラリの Recipe helm/envoy-ai-gateway-operator を通じて、その Webhook 証明書が取りうる 2 つのモードの両方でビルドします。一方のモードでは、プロジェクトのチャートが、レンダリングのたびに新しく生成する鍵と 証明書を保持する Secret をレンダリングし、Recipe の omits: エントリがその Secret をビルドから除外します。さらに 2 つの Releases が、このフィールドに関して 遭遇しうる 2 つの停止を示します。エントリが防ぐために存在する停止と、もはや何にも一致しなくなった エントリが引き起こす停止です。

構築されるもの

core/gateway/envoy-ai-gateway-operator の 1 つのコンポーネント ai-controller を、Kubernetes マニフェストにコンパイルします。Aggregate はどの Release でも同じです。各 Release はコントローラを envoy-ai-gateway-system に配置して証明書モードを選び、各 Manifest は Recipe を選びます。

Releaseその Manifest がバインドするもの証明書モード結果
release-cert-manager.yaml標準ライブラリの helm/envoy-ai-gateway-operatorcert-managerビルドされる
release-own-certificate.yaml標準ライブラリの helm/envoy-ai-gateway-operatorSecret ai-gateway-webhook-tlsビルドされ、ビルドごとにバイト単位で同一
release-negative-without-omits.yamlこのワークスペースの helm/envoy-ai-gateway-operator-without-omitsSecret ai-gateway-webhook-tls--verify-determinism を付けてビルドすると E0058 で停止
release-negative-stale-omits.yamlこのワークスペースの helm/envoy-ai-gateway-operator-stale-omitsSecret ai-gateway-webhook-tlsE0334 で停止

このワークスペースの catalog/ にある 2 つの Recipes は、標準ライブラリのものを教材用に変えたものです。どちらも同じチャートを同じリリースで取得し、同じマッピングで証明書モードを選びます。一方には omits: エントリがなく、もう一方にはチャートがレンダリングしない Secret を指定するエントリがあります。どちらも独自の名前を持つため、標準ライブラリの Recipe を覆い隠すのではなくその横に並び、Release が指定する Manifest によってどちらでビルドするかが決まります。

webhook に証明書を与える 2 つの方法

コントローラはクラスタの API サーバーが TLS 経由で呼び出す mutating webhook を実行するため、webhook は証明書を提供します。Component はそれを供給する 2 つの方法を用意しており、1 つの infra キー webhook_tls_secret によって選択します。

  • 未設定(デフォルト)。 チャートはコントローラの Service 名に対する cert-manager の Certificate と、それに署名する自己署名の Issuer をレンダリングします。そのため、cert-manager がクラスタ内ですでに動作している必要があります。
  • 設定済み。 webhook は、キーが指定する Secret 内の証明書を提供します。この Secret はデプロイする側が事前にコントローラの名前空間に作成し、tls.crt、tls.key、ca.crt を保持します。Certificate も Issuer もレンダリングされず、cert-manager は不要です。コントローラは起動時に、Secret の ca.crt を、API サーバーが webhook を検証する CA バンドルとして webhook 設定に書き込みます。

release-own-certificate.yaml はこれを設定します。

components:
ai-controller:
annotations:
aggrega.ai/namespace: envoy-ai-gateway-system
infra:
webhook_tls_secret: ai-gateway-webhook-tls

独自証明書モードでチャートがレンダリングするもの

キーを設定すると、プロジェクトのチャートはその名前の Secret をコントローラーの Pod の /certs にマウントします。さらに、同じ名前で独自の Secret もレンダリングし、そこにはレンダリング時に生成する CA 証明書、証明書、秘密鍵が格納されます。2 回のビルドでは異なる 2 つの鍵が生成されるため、出力はビルドごとにバイト単位で同一ではなくなります。また、それを適用すると、オペレーターが作成した Secret がチャートの生成した Secret に置き換えられてしまいます。

チャートはプロジェクトのレジストリから取得され、そのまま使用されます。Recipe は取得したチャートを編集しません。代わりに、標準ライブラリの Recipe がその Secret を除外します。

# helm/envoy-ai-gateway-operator:1.0.0, its omits: field
omits:
- kind: Secret
name: "{{ .infra.webhook_tls_secret }}"
when: '{{ ne (optional .infra "webhook_tls_secret" "") "" }}'
  • kind と name は、チャートがレンダリングするとおりにドキュメントを指定します。つまり、metadata.name が Release で設定した名前である Secret です。name テンプレートはチャートに渡されるのと同じ infra キーを読み取るため、Release がどのような名前を付けても、エントリは生成された Secret を指定します。
  • when により、エントリはこのモードでのみ適用されます。 cert-manager モードではチャートはそのような Secret をレンダリングしません。そこでは条件が偽となり、when: が偽のエントリは何もチェックされる前に破棄されます。1 つの Recipe で両方のモードに対応できます。

チャートの残りの部分は引き続きすべてレンダリングされ、ビルドが書き出すものから一致したドキュメントだけが除外されます。ここで除外するのが正しいのは、コントローラーの Pod がマウントする Secret がオペレーター自身のもので、別途作成されるからです。このフィールドはドキュメントを除外するだけで、出力の残りの部分が依存するものが別の場所に存在するかどうかはチェックしません。

サンプルを生成する

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

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

Terminal window
aggrega scaffold --example ai-gateway-own-webhook-certificate

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

Terminal window
cd ai-gateway-own-webhook-certificate

ビルド

Terminal window
aggrega build --release release-cert-manager.yaml --auto-pull
aggrega build --release release-own-certificate.yaml --auto-pull
aggrega build --release release-negative-without-omits.yaml --auto-pull --verify-determinism # halts; exits 1
aggrega build --release release-negative-stale-omits.yaml --auto-pull # halts; exits 1

.aggrega-config.yaml は、2 つの教材用 Recipes を収めたワークスペース自身の catalog/ を挙げています。Component と標準ライブラリの Recipe は、このファイルが指定するデフォルトレジストリ hub.aggrega.ai から解決されます。標準ライブラリのカタログのチェックアウト(入手先)がある場合は、その aggrega-catalog ディレクトリを --catalog で指定すると、すべてのエンティティがこの 2 つのディレクトリから解決されます。

--auto-pull はビルド中に各 Release のロックファイルを埋めます。ロックファイルとレンダリングされた出力は生成されるものであり、配布されるものではありません。ロックファイルを解決するとコントローラーのチャートが Docker Hub から取得されるため、各 Release の最初のビルドにはネットワークが必要です。

AI アシスタントを使う

Aggrega のツールでセットアップした AI アシスタントでも同じことができます。次のプロンプトを貼り付けてください。

Aggrega のツールだけを使い、フォルダーを自分で作成しないでください。ワークスペースフォルダーにまだ `ai-gateway-own-webhook-certificate` フォルダーがない場合は、`example` を `ai-gateway-own-webhook-certificate` に設定し、`dir` を指定せずに `scaffold` ツールを 1 回呼び出してください。これにより、サンプルが新しい `ai-gateway-own-webhook-certificate` フォルダーに書き出されます。次に、Release ごとに 1 回ずつ、`release-cert-manager.yaml`、`release-own-certificate.yaml` の順で `build` ツールを呼び出してください。毎回 `workspace_root` を `ai-gateway-own-webhook-certificate`、`release` をそのファイル、`auto_pull` を true、`write` を true に設定します。次に、`aggrega build` を実行し、その `--verify-determinism` フラグを受け付ける `cli-build` ツールを、`workspace_root` を `ai-gateway-own-webhook-certificate`、`release` を `release-negative-without-omits.yaml`、`auto_pull` を true、`verify_determinism` を true に設定して呼び出してください。これは拒否されることを意図したものなので、その拒否内容を読み上げてください。次に、最初の 2 回のビルドと同じ方法で、`release` を `release-negative-stale-omits.yaml` に設定して `build` ツールを呼び出してください。これも拒否されることを意図したものなので、その拒否内容も読み上げてください。各ビルドが書き出したファイルを教えてください。ファイルは `ai-gateway-own-webhook-certificate/dist/` の下にあります。

2 つの証明書モードのレンダリング結果

release-cert-manager.yaml を --auto-pull 付きでビルドすると、次のように出力されます(<workspace> はこのサンプルのフォルダを表します)。

Pull complete: release-cert-manager.lock (entities=5, source_artifacts=1, external_inputs=0)
[… omitted: the total build time, which differs per run]
Build completed: 16 files written to <workspace>/dist

続いて ls dist/helm を実行すると、次のように一覧されます。

ai-controller
ai-controller-certificate-envoy-ai-gateway-system-self-signed-cert-for-mutating-webhook.yaml
ai-controller-clusterrole-ai-controller-envoy-ai-gateway-system.yaml
ai-controller-clusterrole-envoy-ai-gateway-inference-pool-reader-envoy-ai-gateway-system.yaml
ai-controller-clusterrolebinding-ai-controller-envoy-ai-gateway-system.yaml
ai-controller-clusterrolebinding-envoy-ai-gateway-inference-pool-reader-binding-envoy-ai-gateway-system.yaml
ai-controller-deployment-envoy-ai-gateway-system-ai-controller.yaml
ai-controller-issuer-envoy-ai-gateway-system-self-signed-issuer-for-mutating-webhook.yaml
ai-controller-mutatingwebhookconfiguration-envoy-ai-gateway-gateway-pod-mutator-envoy-ai-gateway-system.yaml
ai-controller-service-envoy-ai-gateway-system-ai-controller.yaml
ai-controller-serviceaccount-envoy-ai-gateway-system-ai-controller.yaml

ai-controller ディレクトリには、Recipe がチャートと並べて出力する 6 つの AI Gateway リソース定義が入っています。release-own-certificate.yaml を同じ方法でビルドすると、次のように出力されます。

Pull complete: release-own-certificate.lock (entities=5, source_artifacts=1, external_inputs=0)
[… omitted: the total build time, which differs per run]
Build completed: 14 files written to <workspace>/dist

そして ls dist/helm は次のように一覧します。

ai-controller
ai-controller-clusterrole-ai-controller-envoy-ai-gateway-system.yaml
ai-controller-clusterrole-envoy-ai-gateway-inference-pool-reader-envoy-ai-gateway-system.yaml
ai-controller-clusterrolebinding-ai-controller-envoy-ai-gateway-system.yaml
ai-controller-clusterrolebinding-envoy-ai-gateway-inference-pool-reader-binding-envoy-ai-gateway-system.yaml
ai-controller-deployment-envoy-ai-gateway-system-ai-controller.yaml
ai-controller-mutatingwebhookconfiguration-envoy-ai-gateway-gateway-pod-mutator-envoy-ai-gateway-system.yaml
ai-controller-service-envoy-ai-gateway-system-ai-controller.yaml
ai-controller-serviceaccount-envoy-ai-gateway-system-ai-controller.yaml

cert-manager モードのツリーには Certificate と Issuer があり、Secret はありません。独自証明書モードのツリーには、この 3 つのいずれもありません。Certificate と Issuer がないのは、そのモードではチャートがどちらもレンダリングしないためであり、Secret がないのは、チャートが実際にレンダリングしたものを Recipe のエントリが除外したためです。代わりにコントローラがマウントするのは、Release が指定した Secret です。

dist/helm/ai-controller-deployment-envoy-ai-gateway-system-ai-controller.yaml
[… omitted: the chart's licence header, four comment lines]
apiVersion: apps/v1
kind: Deployment
metadata:
name: ai-controller
namespace: envoy-ai-gateway-system
[… omitted: the labels and annotations every rendered document carries]
spec:
[… omitted: the replica count, the selector, and the pod template's labels, service account, host-network setting and security settings]
containers:
- name: ai-gateway-helm
[… omitted: the container's security settings, its image and pull policy, and its ports]
args:
[… omitted: the controller's logging, external-processor, gateway-namespace and endpoint arguments]
- --tlsCertDir=/certs
- --tlsCertName=tls.crt
- --tlsKeyName=tls.key
[… omitted: the controller's webhook-port, leader-election, prefix, cache, namespace, quota and session-encryption arguments]
[… omitted: the probes, the environment and the resources]
volumeMounts:
- mountPath: /certs
name: certs
readOnly: true
volumes:
- name: certs
secret:
secretName: ai-gateway-webhook-tls

コントローラは証明書を certs ボリュームである /certs から読み込みます。このボリュームは Secret ai-gateway-webhook-tls です。この名前はビルドが記述どおりにそのまま渡し、Pod の起動時にクラスタが解決します。

ビルドごとに同じバイト列

--verify-determinism を付けて 2 回目のビルドを行うと、release-own-certificate.yaml は次のように出力します。

[… omitted: the total build time, which differs per run]
Build completed: 14 files written to <workspace>/dist

--verify-determinism は、すべてのコンポーネントを同じ入力から 2 回レンダリングし、 2 回のレンダリング結果が異なる場合は停止します。ここではチェックを通過し、書き出されるツリーは 最初のビルドが書き出したツリーとバイト単位で同一です。どちらも成り立つのは、チャートが毎回新たに生成する唯一のドキュメントが出力に含まれないためです。

エントリがない場合:決定性を検査するビルドは停止する

release-negative-without-omits.yaml は、独自証明書の Release を manifest-without-omits.yaml を通じてデプロイするものです。この Manifest は、omits: エントリを持たない教材用の Recipe をバインドします。--verify-determinism を付けてビルドすると、次のようになります。

[… omitted: the pull's lines]
[TRANSLATION_ERROR E0058] instance ai-controller
rendering node "ai-controller"
caused by: wasmengine: node "ai-controller" (provider "helm"): two renders of identical input produced different output: provider render is not deterministic

ビルドは 1 で終了します。チャートが毎回異なる鍵と証明書を生成したため、コントローラーの 2 回のレンダリングが一致しません。pull も、固定する必要のある外部入力を見つけるために Release をレンダリングし、そこで同じ停止に遭遇します。省略した pull の行にこの文がもう一度現れるのはそのためです。ロックファイルはそれでも書き出されます。

フラグなしでビルドすると、同じ Release は完了します。そのツリーには、独自証明書の Release のツリーが持つチャートのドキュメント(ただし、教材用の Recipe が出力しないリソース定義を除く)に加えて、もう 1 つ、チャートが生成した Secret が含まれます。

dist/helm/ai-controller-secret-envoy-ai-gateway-system-ai-gateway-webhook-tls.yaml
apiVersion: v1
kind: Secret
metadata:
name: ai-gateway-webhook-tls
namespace: envoy-ai-gateway-system
[… omitted: the labels and annotations every rendered document carries]
data:
[… omitted: the three base64-encoded entries ca.crt, tls.crt and tls.key]

2 回ビルドすると、2 つのツリーはちょうどこの 3 つの値だけが異なります。通常のビルドは各 component を 1 回だけレンダリングするため、生成されたいずれかの鍵を書き出し、違いに気付きません。違いを可視化するのはこの検査です。このファイルを適用すると、オペレーターが作成した Secret が置き換えられてしまいます。

この停止については A provider rendered the same input twice and produced different output(provider が同じ入力を 2 回レンダリングし、異なる出力を生成しました) で説明しています。その修正方法では、違いが取り込んだチャートの生成する値である場合の 2 つの対処法を挙げています。チャートが提供する設定を通じてその値を与えるか、生成されたドキュメントが Release に含めてはならないものである場合は omits: エントリで除外するかです。後者が標準ライブラリの Recipe の採る方法です。

何にも一致しないエントリ

release-negative-stale-omits.yaml は、manifest-stale-omits.yaml を通じてデプロイされる独自証明書の Release です。この Manifest がバインドする教材用の Recipe では、エントリが Secret をキーに基づいてではなく、コントローラのレンダリングされた名前に基づいて命名しています。

# catalog/recipe/helm/envoy-ai-gateway-operator-stale-omits/1.0.0/recipe.yaml, its omits: field
omits:
- kind: Secret
name: "{{ .context.rendered_name }}-webhook-tls"
when: '{{ ne (optional .infra "webhook_tls_secret" "") "" }}'

ビルドすると次のようになります。

[… omitted: the pull's lines]
[TRANSLATION_ERROR E0334] instance ai-controller
rendering node "ai-controller"
caused by: [CATALOG_ERROR] instance ai-controller
an omits entry left out nothing the source rendered (node "ai-controller", provider "provider/helm:0.8.8-75-g9e6ef4e0", "envoy-ai-gateway-operator-stale-omits" omits[0], kind "Secret", name "ai-controller-webhook-tls"). correct the entry so it names something the source renders, or remove it; a source upgrade that renamed or removed it is the usual cause

プロバイダは、ビルドを実行したバイナリのバージョンとともに示されるため、各自の実行ではその箇所に各自のバイナリのバージョンが表示されます。

ビルドは 1 で終了し、pull の行にも上記と同じ理由で同じ文が現れます。メッセージは左から右へ、確認すべき場所の順に読めます。コンポーネント、それをレンダリングしたプロバイダ、エントリを宣言している Recipe と、その omits: リスト内でのエントリの位置(0 から数えます)、そしてエントリが解決された kind と名前です。このモードでは when: 条件が真であるため、エントリは適用されます。その名前は ai-controller-webhook-tls にレンダリングされますが、チャートは Secret を ai-gateway-webhook-tls と命名しており、エントリは何も除外しませんでした。

適用されるすべてのエントリは何かを除外しなければならず、そうでないエントリがあるとビルドは停止します。何にも一致しないエントリは、もはや真ではないソースについての記述だからです。よくある原因は、ドキュメントの名前を変更したソースのアップグレードです。その場合、名前の変わったドキュメントは新しい名前で出力に含まれます。これはまさにエントリが除外するために書かれたドキュメントであり、停止はそれが気付かれないまま出荷されるのを防ぎます。このビルドでは、チャートが生成した Secret がそのようなドキュメントです。エントリはそれを除外するために書かれましたが、別のものを指しています。エントリを修正するには、ソースが現在レンダリングする内容と比較します。release-negative-without-omits.yaml がチェックなしで行うように、エントリを削除してビルドし、チャートが書き出したファイルから名前を読み取ります。

E0334 は診断リファレンスに omit-matched-nothing として掲載されており、An omits entry left out nothing the source rendered(omits エントリがソースのレンダリングした内容を何も除外しなかった)で説明されています。フィールド自体(すべてのエントリフィールド、テンプレートコンテキスト、Release がエントリについて決定できること、およびどのプロバイダがそれに従うか)については、Recipe → omits: フィールドを参照してください。

すべてのビルドの確認

このセルフチェックは、使用する共有ビルドヘルパーを含むドキュメントリポジトリのチェックアウトで実行されます。aggrega scaffold --example が書き出したコピーには、そのヘルパーは含まれません。

Terminal window
./check.sh

check.sh は ./build-release.sh を通じて 4 つの Releases をビルドし、それぞれの結果をこのページが説明する結果と照合します。成功する各 Release は 2 回ビルドされ、2 回目は --verify-determinism 付きです。両方のビルドが終了コード 0 で終了し、同じファイルをバイト単位で同一に書き出す必要があります。また、レンダリングされた各ドキュメントの kind ごとに数えて、ツリーには cert-manager モードでは Certificate と Issuer が含まれ Secret は含まれず、独自証明書モードではこの 3 つのいずれも含まれず、コントローラの Deployment の certs ボリュームが ai-gateway-webhook-tls を指定している必要があります。ガードレールの Release は、0 以外の終了コードで終了し、このページがその Release について示す短いコードと文を持つ halt がちょうど 1 つである必要があり、古いエントリの halt はそのエントリを示す必要があります。Release ごとに 1 行を出力し、いずれかの結果が異なる場合はそのビルドの出力を表示して終了コード 1 で終了します。

RELEASE EXIT EXPECTED VERDICT
------------------------------------------------------------------------------------------------
release-cert-manager.yaml 0/0 pass OK: byte-identical twice; Certificate=1 Issuer=1 Secret=0
release-own-certificate.yaml 0/0 pass OK: byte-identical twice; Certificate=0 Issuer=0 Secret=0; certs volume: ai-gateway-webhook-tls
release-negative-without-omits.yaml 1 halt OK: E0058, the expected sentence
release-negative-stale-omits.yaml 1 halt OK: E0334, the expected sentence, naming "envoy-ai-gateway-operator-stale-omits" omits[0]
check: every build ended as expected.

必要なものは単一のビルドと同じで、標準ライブラリのカタログと、チャートを取得するためのネットワークです。./build-release.sh が解決するバイナリを使用するため、AGGREGA_BIN でバイナリを選択できます。-- 以降の引数はすべてのビルドに渡されます。ビルドが書き出すツリーを比較するため、このディレクトリに dist/ があるあいだは開始を拒否し、終了後にも何も残しません。終了ステータスがそのまま判定結果となるため、パイプラインでは各 Release を個別にビルドする代わりにこれを実行できます。

コンパイラが解釈しない箇所

コンパイラは、Secret が何であるか、コントローラがそれで何をするか、あるいはなぜチャートがそれを生成するのかを知りません。コンパイラはエントリのテンプレートを任意の Recipe テンプレートと同じように評価し、それらが解決した kind と名前をコンポーネントの入力とともに helm プロバイダに渡します。プロバイダは一致するレンダリング済みドキュメントを取り除き、各エントリがいくつ取り除いたかを報告します。コンパイラはクラスタ内で ai-gateway-webhook-tls を探すことも、それを作成することも、コントローラが読み取る 3 つのエントリをそれが保持しているかを確認することもありません。その名前は Release が与える文字列であり、チャートの値とエントリに渡されるだけです。コントローラが起動する前に Secret が存在するよう手配するのは、デプロイする側の役割です。

ファイル

  • aggregate.yaml — AI ゲートウェイコントローラ、唯一のコンポーネントです。どの Release でも同じです。
  • manifest.yaml — コントローラを標準ライブラリの Recipe にバインドします。成功する 2 つの Releases で共有されます。
  • manifest-without-omits.yaml、manifest-stale-omits.yaml — コントローラを 2 つの教材用 Recipes のいずれかにバインドします。
  • release-cert-manager.yaml、release-own-certificate.yaml — 2 つの証明書モードです。
  • release-negative-without-omits.yaml、release-negative-stale-omits.yaml — それぞれの教材用 Recipe を通した独自証明書モードです。どちらも停止します。
  • catalog/recipe/helm/envoy-ai-gateway-operator-without-omits/1.0.0/ — omits: エントリを持たない教材用 Recipe と、そのチャートを固定する entity.lock です。
  • catalog/recipe/helm/envoy-ai-gateway-operator-stale-omits/1.0.0/ — エントリが何にも一致しない教材用 Recipe と、その entity.lock です。
  • .aggrega-config.yaml — カタログの検索スタックとレジストリです。
  • build-release.sh — 1 つの Release をビルドし、同等の aggrega build コマンドを表示します。
  • check.sh — 4 つすべてをビルドし、それぞれの結果を確認します。