Sertifikat webhook milik Anda sendiri: mengecualikan Secret yang dihasilkan chart
Ini adalah contoh lanjutan. Contoh ini mengajarkan field Recipe omits:, yang tidak
dibutuhkan sebagian besar Recipes: field ini ditujukan untuk sumber yang Anda ambil apa adanya — di sini, chart yang diambil
dari registry — yang merender dokumen yang tidak boleh dikirimkan oleh Release Anda. Gunakan
field ini ketika Anda menghadapi kasus tersebut.
Workspace ini membangun control plane Envoy AI Gateway, yaitu controller yang dipanggil Envoy
Gateway sebagai server ekstensinya, melalui Recipe pustaka standar
helm/envoy-ai-gateway-operator, dalam kedua mode yang dapat digunakan
sertifikat webhook-nya. Dalam salah satu mode tersebut, chart proyek merender Secret yang berisi kunci dan
sertifikat yang dihasilkannya ulang pada setiap render, dan entri omits:
pada Recipe mengecualikan Secret tersebut dari build. Dua Releases lainnya menunjukkan dua penghentian
yang dapat Anda temui terkait field ini: penghentian yang hendak dicegah oleh entri tersebut, dan penghentian yang
dihasilkan oleh entri yang tidak lagi cocok dengan apa pun.
Apa yang dibangunnya
Satu komponen, ai-controller, dari core/gateway/envoy-ai-gateway-operator,
dikompilasi menjadi manifes Kubernetes. Aggregate-nya sama untuk setiap Release.
Setiap Release menempatkan controller di envoy-ai-gateway-system dan memilih
mode sertifikat; setiap Manifest memilih Recipe:
| Release | Manifest-nya mengikat | mode sertifikat | hasil |
|---|---|---|---|
release-cert-manager.yaml | helm/envoy-ai-gateway-operator, dari pustaka standar | cert-manager | berhasil di-build |
release-own-certificate.yaml | helm/envoy-ai-gateway-operator, dari pustaka standar | Secret ai-gateway-webhook-tls | berhasil di-build, identik byte demi byte dari satu build ke build berikutnya |
release-negative-without-omits.yaml | helm/envoy-ai-gateway-operator-without-omits, dari workspace ini | Secret ai-gateway-webhook-tls | berhenti dengan E0058 saat di-build dengan --verify-determinism |
release-negative-stale-omits.yaml | helm/envoy-ai-gateway-operator-stale-omits, dari workspace ini | Secret ai-gateway-webhook-tls | berhenti dengan E0334 |
Dua Recipes di catalog/ workspace ini adalah varian pengajaran dari Recipe
pustaka standar. Masing-masing mengambil chart yang sama pada rilis yang sama dan
memilih mode sertifikat dengan pemetaan yang sama: satu tidak memiliki entri omits:, dan
yang lain memiliki entri yang menyebut Secret yang tidak dirender oleh chart. Keduanya memiliki
nama sendiri, sehingga berada di samping Recipe pustaka standar alih-alih
menimpanya, dan Manifest yang disebut oleh sebuah Release menentukan Recipe mana yang digunakan untuk build.
Dua cara memberi webhook sebuah sertifikat
Controller menjalankan mutating webhook yang dipanggil oleh API server klaster melalui
TLS, sehingga webhook menyajikan sebuah sertifikat. Component menawarkan dua cara untuk
menyediakannya, yang dipilih oleh satu kunci infra, webhook_tls_secret:
- Tidak diatur, bawaannya. Chart merender sebuah
Certificatecert-manager untuk nama Service controller danIssuerself-signed yang menandatanganinya, sehingga cert-manager harus sudah berjalan di klaster. - Diatur. Webhook menyajikan sertifikat dalam Secret yang dinamai oleh kunci tersebut, yang
dibuat sebelumnya oleh siapa pun yang melakukan deployment di namespace controller, berisi
tls.crt,tls.key, danca.crt. Tidak adaCertificatemaupunIssueryang dirender, dan cert-manager tidak diperlukan: saat controller dimulai, controller menulisca.crtmilik Secret ke dalam konfigurasi webhook sebagai CA bundle yang digunakan API server untuk memeriksa webhook.
release-own-certificate.yaml mengaturnya:
components: ai-controller: annotations: aggrega.ai/namespace: envoy-ai-gateway-system infra: webhook_tls_secret: ai-gateway-webhook-tlsApa yang dirender chart dalam mode sertifikat sendiri
Dengan kunci tersebut diatur, chart milik proyek me-mount Secret dengan nama tersebut ke
pod controller di /certs — dan chart itu juga merender Secret miliknya sendiri dengan
nama yang sama, berisi sertifikat CA, sertifikat, dan kunci privat yang
dibuatnya saat merender. Dua build menghasilkan dua kunci yang berbeda, sehingga
output tidak lagi identik byte demi byte dari satu build ke build berikutnya; dan menerapkannya
akan mengganti Secret yang dibuat oleh operator dengan Secret yang dibuat oleh chart.
Chart tersebut diambil dari registry proyek dan digunakan apa adanya; sebuah Recipe tidak mengedit chart yang telah diambil. Sebagai gantinya, Recipe pustaka standar menyisihkan Secret tersebut:
# 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" "") "" }}'kinddannamemenamai dokumen sebagaimana chart merendernya: sebuahSecretyangmetadata.name-nya adalah nama yang ditetapkan oleh Release. Templatenamemembaca kunciinfrayang sama yang diberikan kepada chart, sehingga entri tersebut menamai Secret yang dihasilkan, apa pun nama yang diberikan oleh Release.whenmembuat entri hanya berlaku dalam mode ini. Dalam mode cert-manager, chart tidak merender Secret semacam itu; kondisinya bernilai false di sana, dan entri yangwhen:-nya bernilai false dibuang sebelum apa pun diperiksa. Satu Recipe melayani kedua mode.
Bagian lain dari chart tetap dirender secara penuh, dan hanya dokumen yang cocok yang dibuang dari apa yang ditulis oleh build. Menyisihkannya tepat di sini karena Secret yang di-mount oleh pod controller adalah milik operator sendiri, yang dibuat secara terpisah. Field tersebut menyisihkan sebuah dokumen; field itu tidak memeriksa bahwa apa pun yang diandalkan oleh bagian output lainnya ada di tempat lain.
Membuat contoh
Anda dapat mem-build contoh ini dengan perintah di bawah, atau meminta asisten AI Anda mem-build-nya untuk Anda.
Tulis contoh ke folder baru yang dinamai sesuai contoh itu:
aggrega scaffold --example ai-gateway-own-webhook-certificateKemudian ia mencetak perintah yang dijalankan berikutnya. Perintah pertama berpindah ke folder baru:
cd ai-gateway-own-webhook-certificateBuild
aggrega build --release release-cert-manager.yaml --auto-pullaggrega build --release release-own-certificate.yaml --auto-pullaggrega build --release release-negative-without-omits.yaml --auto-pull --verify-determinism # halts; exits 1aggrega build --release release-negative-stale-omits.yaml --auto-pull # halts; exits 1.aggrega-config.yaml mencantumkan catalog/ milik workspace sendiri, yang berisi dua Recipes pengajaran; Component dan Recipe pustaka standar di-resolve dari hub.aggrega.ai, registry default yang disebutnya. Dengan checkout katalog pustaka standar (cara mendapatkannya), sebutkan direktori aggrega-catalog miliknya dengan --catalog dan setiap entitas di-resolve dari kedua direktori tersebut.
--auto-pull mengisi lockfile setiap Release selama build; lockfile dan
output yang dirender dihasilkan, bukan dikirimkan. Me-resolve sebuah lockfile mengambil
chart controller dari Docker Hub, sehingga build pertama setiap Release memerlukan
jaringan.
Dengan asisten AI
Asisten AI yang disiapkan dengan tool Aggrega dapat melakukan hal yang sama: tempelkan prompt ini ke asisten tersebut.
Gunakan hanya tool Aggrega, dan jangan membuat folder apa pun sendiri. Jika folder workspace belum berisi folder `ai-gateway-own-webhook-certificate`, panggil tool `scaffold` sekali dengan `example` diatur ke `ai-gateway-own-webhook-certificate` dan tanpa `dir`: tool itu menulis contoh ke folder baru `ai-gateway-own-webhook-certificate`. Lalu panggil tool `build` sekali untuk setiap Release, dengan urutan ini — `release-cert-manager.yaml`, `release-own-certificate.yaml` — setiap kali dengan `workspace_root` diatur ke `ai-gateway-own-webhook-certificate`, `release` diatur ke file tersebut, `auto_pull` diatur ke true, dan `write` diatur ke true. Lalu panggil tool `cli-build`, yang menjalankan `aggrega build` dan menerima flag `--verify-determinism`-nya, dengan `workspace_root` diatur ke `ai-gateway-own-webhook-certificate`, `release` diatur ke `release-negative-without-omits.yaml`, `auto_pull` diatur ke true, dan `verify_determinism` diatur ke true: build ini memang dimaksudkan untuk ditolak, jadi bacakan penolakannya kepada saya. Lalu panggil tool `build` dengan cara yang sama seperti dua build pertama dengan `release` diatur ke `release-negative-stale-omits.yaml`: build ini juga dimaksudkan untuk ditolak, jadi bacakan juga penolakan itu kepada saya. Beri tahu saya file mana saja yang ditulis setiap build; file-file itu berada di bawah `ai-gateway-own-webhook-certificate/dist/`.Dua mode sertifikat, sebagaimana dirender
release-cert-manager.yaml, yang dibangun dengan --auto-pull, mencetak keluaran berikut, dengan
<workspace> mewakili folder contoh ini:
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>/distlalu ls dist/helm menampilkan:
ai-controllerai-controller-certificate-envoy-ai-gateway-system-self-signed-cert-for-mutating-webhook.yamlai-controller-clusterrole-ai-controller-envoy-ai-gateway-system.yamlai-controller-clusterrole-envoy-ai-gateway-inference-pool-reader-envoy-ai-gateway-system.yamlai-controller-clusterrolebinding-ai-controller-envoy-ai-gateway-system.yamlai-controller-clusterrolebinding-envoy-ai-gateway-inference-pool-reader-binding-envoy-ai-gateway-system.yamlai-controller-deployment-envoy-ai-gateway-system-ai-controller.yamlai-controller-issuer-envoy-ai-gateway-system-self-signed-issuer-for-mutating-webhook.yamlai-controller-mutatingwebhookconfiguration-envoy-ai-gateway-gateway-pod-mutator-envoy-ai-gateway-system.yamlai-controller-service-envoy-ai-gateway-system-ai-controller.yamlai-controller-serviceaccount-envoy-ai-gateway-system-ai-controller.yamlDirektori ai-controller berisi enam definisi sumber daya AI Gateway yang
dihasilkan Recipe di samping chart. release-own-certificate.yaml, yang dibangun dengan cara
yang sama, mencetak:
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>/distdan ls dist/helm menampilkan:
ai-controllerai-controller-clusterrole-ai-controller-envoy-ai-gateway-system.yamlai-controller-clusterrole-envoy-ai-gateway-inference-pool-reader-envoy-ai-gateway-system.yamlai-controller-clusterrolebinding-ai-controller-envoy-ai-gateway-system.yamlai-controller-clusterrolebinding-envoy-ai-gateway-inference-pool-reader-binding-envoy-ai-gateway-system.yamlai-controller-deployment-envoy-ai-gateway-system-ai-controller.yamlai-controller-mutatingwebhookconfiguration-envoy-ai-gateway-gateway-pod-mutator-envoy-ai-gateway-system.yamlai-controller-service-envoy-ai-gateway-system-ai-controller.yamlai-controller-serviceaccount-envoy-ai-gateway-system-ai-controller.yamlPohon mode cert-manager berisi sebuah Certificate dan sebuah Issuer dan tidak ada
Secret. Pohon mode sertifikat sendiri tidak berisi satu pun dari ketiganya: tidak ada Certificate
dan tidak ada Issuer, karena chart tidak merender keduanya dalam mode tersebut, dan tidak ada Secret,
karena entri Recipe menghilangkan satu-satunya yang dirender oleh chart. Yang dipasang oleh
controller sebagai gantinya adalah Secret yang dinamai oleh Release:
[… omitted: the chart's licence header, four comment lines]apiVersion: apps/v1kind: Deploymentmetadata: 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-tlsController membaca sertifikatnya dari /certs, yaitu volume certs, yang merupakan
Secret ai-gateway-webhook-tls — nama yang diteruskan oleh build sebagaimana tertulis
dan diresolusikan oleh cluster saat pod dimulai.
Byte yang sama dari satu build ke build berikutnya
Ketika di-build untuk kedua kalinya dengan --verify-determinism, release-own-certificate.yaml
mencetak:
[… omitted: the total build time, which differs per run]Build completed: 14 files written to <workspace>/dist--verify-determinism merender setiap komponen dua kali dari input yang sama dan
berhenti jika kedua hasil render berbeda. Pemeriksaan ini lolos di sini, dan pohon yang ditulisnya identik byte
demi byte dengan pohon yang ditulis build pertama. Keduanya berlaku karena satu-satunya dokumen yang
dibuat ulang oleh chart tidak pernah mencapai output.
Tanpa entri: build yang memeriksa determinisme berhenti
release-negative-without-omits.yaml adalah Release sertifikat-sendiri yang di-deploy
melalui manifest-without-omits.yaml, yang mengikat Recipe pengajaran tanpa entri
omits:. Di-build dengan --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 deterministicBuild keluar dengan 1. Kedua render controller berbeda, karena chart
menghasilkan kunci dan sertifikat yang berbeda setiap kali. Pull juga me-render
Release, untuk menemukan input eksternal yang perlu disematkan, dan mengalami penghentian yang sama
di sana; itulah sebabnya baris pull yang dihilangkan memuat kalimat tersebut untuk kedua kalinya.
Lockfile tetap ditulis.
Jika di-build tanpa flag tersebut, Release yang sama selesai. Pohonnya memuat dokumen chart yang dimuat oleh Release sertifikat-sendiri — dikurangi definisi sumber daya, yang tidak dikeluarkan oleh Recipe pengajaran — ditambah satu lagi, Secret yang dihasilkan chart:
apiVersion: v1kind: Secretmetadata: 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]Build dua kali dan kedua pohon berbeda tepat pada ketiga nilai tersebut. Build biasa me-render setiap komponen sekali, sehingga build menulis kunci mana pun yang dihasilkannya dan tidak menyadarinya; pemeriksaan itulah yang membuat perbedaannya terlihat. Jika diterapkan, file ini akan menggantikan Secret yang dibuat oleh operator.
Penghentian ini dijelaskan di bawah
A provider rendered the same input twice and produced different output (Sebuah provider me-render input yang sama dua kali dan menghasilkan output yang berbeda),
yang perbaikannya menyebutkan dua jalan keluar ketika perbedaannya adalah nilai yang dihasilkan chart yang Anda
jadikan sumber: berikan nilai tersebut melalui pengaturan yang ditawarkan chart, atau, jika
dokumen yang dihasilkan adalah dokumen yang tidak boleh dikirim oleh Release, keluarkan dengan entri
omits: — jawaban yang diambil oleh Recipe pustaka standar.
Entri yang tidak cocok dengan apa pun
release-negative-stale-omits.yaml adalah Release sertifikat sendiri yang di-deploy
melalui manifest-stale-omits.yaml, yang mengikat Recipe pengajaran yang entrinya
menamai Secret berdasarkan nama hasil render controller, bukan berdasarkan kunci:
# 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" "") "" }}'Hasil build:
[… 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 causeProvider dinamai dengan versi biner yang menjalankan build, sehingga eksekusi Anda sendiri menampilkan versi biner Anda di sana.
Build keluar dengan 1, dan baris-baris pull memuat kalimat yang sama dengan alasan
yang sama seperti di atas. Pesan tersebut dibaca dari kiri ke kanan sebagai petunjuk tempat mencari:
komponen, provider yang merendernya, Recipe yang mendeklarasikan entri dan
posisi entri dalam daftar omits:-nya, dihitung dari 0, lalu jenis dan
nama yang dihasilkan entri tersebut. Kondisi when: bernilai benar dalam mode ini, sehingga
entri berlaku; namanya dirender menjadi ai-controller-webhook-tls, chart
menamai Secret-nya ai-gateway-webhook-tls, dan entri tersebut tidak mengecualikan apa pun.
Setiap entri yang berlaku harus mengecualikan sesuatu, dan build berhenti pada entri
yang tidak melakukannya, karena entri yang tidak cocok dengan apa pun adalah pernyataan tentang sumber
yang sudah tidak benar lagi. Penyebab umumnya adalah peningkatan versi sumber yang mengganti nama
dokumen. Dokumen yang diganti namanya itu kemudian ada di keluaran dengan nama barunya — justru
dokumen yang hendak dikecualikan oleh entri tersebut — dan penghentian inilah yang mencegahnya
ikut dikirim tanpa disadari. Dalam build ini, Secret yang dihasilkan chart adalah dokumen
seperti itu: entri ditulis untuk mengecualikannya, tetapi menamai hal lain. Untuk
memperbaiki entri, bandingkan dengan apa yang dirender sumber saat ini: lakukan build
dengan entri dihapus, seperti yang dilakukan release-negative-without-omits.yaml tanpa
pemeriksaan, lalu baca nama dari berkas yang ditulis chart.
E0334 tercantum dalam referensi diagnostik sebagai
omit-matched-nothing, dan dijelaskan di bawah
An omits entry left out nothing the source rendered (Entri omits tidak mengecualikan apa pun yang dirender sumber).
Field itu sendiri — setiap field entri, konteks templat, apa yang dapat
ditentukan Release tentang sebuah entri, dan provider mana yang mematuhinya — ada di
Recipe → Field omits:.
Memeriksa setiap build
Pemeriksaan mandiri ini berjalan di checkout repositori dokumentasi, yang memuat skrip pembantu build bersama yang digunakannya; salinan yang ditulis oleh aggrega scaffold --example tidak menyertakan skrip pembantu tersebut.
./check.shcheck.sh membangun keempat Releases melalui ./build-release.sh dan memeriksa setiap
hasil terhadap hasil yang dijelaskan halaman ini. Setiap Release yang lolos dibangun
dua kali, kali kedua dengan --verify-determinism: kedua build harus keluar dengan 0 dan
menulis file yang sama, byte demi byte, dan pohonnya harus memuat, dihitung menurut kind
setiap dokumen yang dirender, sebuah Certificate dan sebuah Issuer serta tanpa Secret dalam
mode cert-manager, dan tidak satu pun dari ketiganya dalam mode sertifikat sendiri, dengan
volume certs milik Deployment controller menamai ai-gateway-webhook-tls. Sebuah
Release pengaman harus keluar dengan status bukan nol dengan tepat satu penghentian yang memuat kode
singkat dan kalimat yang ditunjukkan halaman ini untuknya, dan penghentian entri yang usang harus
menyebut entri tersebut. Skrip ini mencetak satu baris per Release dan keluar dengan 1 jika ada hasil yang
berbeda, sambil mencetak output build tersebut:
RELEASE EXIT EXPECTED VERDICT------------------------------------------------------------------------------------------------release-cert-manager.yaml 0/0 pass OK: byte-identical twice; Certificate=1 Issuer=1 Secret=0release-own-certificate.yaml 0/0 pass OK: byte-identical twice; Certificate=0 Issuer=0 Secret=0; certs volume: ai-gateway-webhook-tlsrelease-negative-without-omits.yaml 1 halt OK: E0058, the expected sentencerelease-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.Skrip ini membutuhkan apa yang dibutuhkan satu build: katalog pustaka standar, dan jaringan untuk chart. Skrip ini menggunakan binary yang di-resolve oleh ./build-release.sh, sehingga AGGREGA_BIN yang memilihnya; argumen setelah -- diteruskan ke setiap build. Skrip ini menolak berjalan selama ada dist/ di direktori ini, karena skrip membandingkan pohon yang ditulis build, dan tidak meninggalkan satu pun. Status keluarnya adalah keseluruhan putusan, sehingga pipeline dapat menjalankannya sebagai pengganti membangun setiap Release secara terpisah.
Bagian yang tidak ditafsirkan oleh kompiler
Kompiler tidak mengetahui apa itu Secret, apa yang dilakukan controller terhadapnya,
atau mengapa sebuah chart akan menghasilkannya. Kompiler mengevaluasi templat entri sebagaimana
ia mengevaluasi templat Recipe mana pun, menyerahkan kind dan nama hasil resolusinya kepada
provider helm bersama input komponen, lalu provider membuang dokumen hasil render
yang cocok dan melaporkan berapa banyak yang dibuang oleh setiap entri. Kompiler tidak pernah mencari
ai-gateway-webhook-tls di dalam klaster, tidak pernah membuatnya, dan tidak pernah memeriksa bahwa
ia memuat tiga entri yang dibaca controller: nama tersebut adalah string yang disediakan oleh
Release, yang diteruskan ke values chart dan ke entri. Memastikan Secret tersebut
sudah ada sebelum controller berjalan adalah tanggung jawab pihak yang melakukan deployment.
Berkas
aggregate.yaml— pengendali AI gateway, satu-satunya komponen; sama untuk setiap Release.manifest.yaml— mengikat pengendali ke Recipe pustaka standar; digunakan bersama oleh dua Releases yang lolos.manifest-without-omits.yaml,manifest-stale-omits.yaml— mengikatnya ke salah satu dari dua Recipes pengajaran.release-cert-manager.yaml,release-own-certificate.yaml— dua mode sertifikat.release-negative-without-omits.yaml,release-negative-stale-omits.yaml— mode sertifikat sendiri melalui masing-masing Recipe pengajaran; keduanya berhenti.catalog/recipe/helm/envoy-ai-gateway-operator-without-omits/1.0.0/— Recipe pengajaran tanpa entriomits:, danentity.lockyang mematok chart-nya.catalog/recipe/helm/envoy-ai-gateway-operator-stale-omits/1.0.0/— Recipe pengajaran yang entrinya tidak cocok dengan apa pun, besertaentity.lock-nya..aggrega-config.yaml— tumpukan pencarian katalog dan registri.build-release.sh— membangun satu Release, sambil menampilkan perintahaggrega buildyang setara.check.sh— membangun keempatnya dan memeriksa setiap hasilnya.