Chứng chỉ webhook của riêng bạn: loại bỏ Secret do chart sinh ra
Đây là một ví dụ nâng cao. Ví dụ này hướng dẫn trường omits: của Recipe, trường mà hầu hết
Recipes không bao giờ cần đến: trường này dành cho một nguồn bạn dùng nguyên trạng — ở đây là một chart được tải
từ một registry — mà nguồn đó render ra một tài liệu Release của bạn không được phát hành. Hãy dùng
đến nó khi bạn gặp trường hợp đó.
Workspace này xây dựng control plane của Envoy AI Gateway, tức controller mà Envoy
Gateway gọi làm extension server của nó, thông qua Recipe của thư viện chuẩn
helm/envoy-ai-gateway-operator, ở cả hai chế độ mà chứng chỉ webhook của nó
có thể nhận. Ở một trong hai chế độ, chart của dự án render ra một Secret chứa một khóa và
một chứng chỉ được sinh mới ở mỗi lần render, và mục omits: của Recipe
loại Secret đó ra khỏi bản build. Hai Releases khác cho thấy hai lần dừng
mà bạn có thể gặp quanh trường này: lần dừng mà mục này tồn tại để ngăn chặn, và lần dừng
do một mục không còn khớp với bất cứ thứ gì gây ra.
Những gì ví dụ này xây dựng
Một component, ai-controller, của core/gateway/envoy-ai-gateway-operator,
được biên dịch thành các manifest Kubernetes. Aggregate giống nhau cho mọi Release.
Mỗi Release đặt controller vào envoy-ai-gateway-system và chọn chế độ
chứng chỉ; mỗi Manifest chọn Recipe:
| Release | Manifest của nó gắn với | chế độ chứng chỉ | kết quả |
|---|---|---|---|
release-cert-manager.yaml | helm/envoy-ai-gateway-operator, từ thư viện chuẩn | cert-manager | xây dựng thành công |
release-own-certificate.yaml | helm/envoy-ai-gateway-operator, từ thư viện chuẩn | Secret ai-gateway-webhook-tls | xây dựng thành công, giống hệt từng byte giữa các lần xây dựng |
release-negative-without-omits.yaml | helm/envoy-ai-gateway-operator-without-omits, từ workspace này | Secret ai-gateway-webhook-tls | dừng với E0058 khi xây dựng với --verify-determinism |
release-negative-stale-omits.yaml | helm/envoy-ai-gateway-operator-stale-omits, từ workspace này | Secret ai-gateway-webhook-tls | dừng với E0334 |
Hai Recipes trong catalog/ của workspace này là các biến thể minh họa của
Recipe trong thư viện chuẩn. Mỗi Recipe lấy cùng một chart ở cùng một bản phát hành và
chọn chế độ chứng chỉ theo cùng một ánh xạ: một Recipe không có mục omits:, và
Recipe kia có một mục chỉ đến một Secret mà chart không render. Chúng mang
tên riêng, nên chúng nằm cạnh Recipe của thư viện chuẩn thay vì
che khuất nó, và Manifest mà một Release chỉ định sẽ quyết định Release đó được xây dựng bằng Recipe nào.
Hai cách cung cấp chứng chỉ cho webhook
Controller chạy một mutating webhook mà API server của cluster gọi qua
TLS, nên webhook phục vụ một chứng chỉ. Component cung cấp hai cách để
cấp chứng chỉ đó, được chọn bằng một khóa infra là webhook_tls_secret:
- Không đặt, mặc định. Chart render một
Certificatecủa cert-manager cho tên Service của controller vàIssuertự ký dùng để ký nó, nên cert-manager phải đang chạy sẵn trong cluster. - Có đặt. Webhook phục vụ chứng chỉ trong Secret mà khóa này nêu tên, do
người triển khai tạo trước trong namespace của controller, chứa
tls.crt,tls.keyvàca.crt. Không cóCertificatehayIssuernào được render, và không cần cert-manager: khi controller khởi động, nó ghica.crtcủa Secret vào cấu hình webhook làm CA bundle mà API server dùng để kiểm tra webhook.
release-own-certificate.yaml đặt khóa này:
components: ai-controller: annotations: aggrega.ai/namespace: envoy-ai-gateway-system infra: webhook_tls_secret: ai-gateway-webhook-tlsChart render ra những gì ở chế độ chứng chỉ riêng
Khi khóa được đặt, chart của dự án mount Secret mang tên đó vào pod của
controller tại /certs — và nó cũng render một Secret của riêng nó dưới cùng
tên đó, chứa một chứng chỉ CA, một chứng chỉ và một khóa riêng tư mà nó
sinh ra trong lúc render. Hai lần build sinh ra hai khóa khác nhau, nên đầu ra
không còn giống hệt nhau từng byte giữa các lần build; và việc áp dụng nó sẽ
thay Secret mà người vận hành đã tạo bằng Secret do chart sinh ra.
Chart được tải về từ registry của dự án và được dùng nguyên trạng; một Recipe không chỉnh sửa chart đã tải về. Thay vào đó, Recipe của thư viện chuẩn loại bỏ 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" "") "" }}'kindvànamegọi tên tài liệu đúng như chart render ra nó: mộtSecretcómetadata.namelà tên mà Release đã đặt. Templatenameđọc cùng khóainfrađược truyền cho chart, nên mục này gọi đúng tên Secret được sinh ra, dù Release đặt tên nó là gì.whenkhiến mục này chỉ áp dụng ở chế độ này. Ở chế độ cert-manager, chart không render Secret nào như vậy; điều kiện ở đó là sai, và một mục cówhen:sai sẽ bị loại bỏ trước khi bất cứ thứ gì được kiểm tra. Một Recipe phục vụ cả hai chế độ.
Phần còn lại của chart vẫn được render đầy đủ, và chỉ tài liệu khớp bị loại khỏi những gì bản build ghi ra. Loại bỏ nó ở đây là đúng vì Secret mà pod của controller mount là Secret riêng của người vận hành, được tạo riêng. Trường này loại bỏ một tài liệu; nó không kiểm tra rằng những gì phần còn lại của đầu ra dựa vào có tồn tại ở nơi khác hay không.
Tạo ví dụ
Bạn có thể build ví dụ này bằng các lệnh bên dưới, hoặc để trợ lý AI của bạn build giúp bạn.
Ghi ví dụ vào một thư mục mới đặt theo tên của nó:
aggrega scaffold --example ai-gateway-own-webhook-certificateSau đó nó in ra các lệnh cần chạy tiếp theo. Lệnh đầu tiên chuyển vào thư mục mới:
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 liệt kê catalog/ của chính workspace, nơi chứa hai Recipes dùng để minh họa; Component và Recipe của thư viện chuẩn được phân giải từ hub.aggrega.ai, registry mặc định mà tệp này chỉ định. Khi có bản checkout catalog thư viện chuẩn (lấy ở đâu), hãy chỉ định thư mục aggrega-catalog của nó bằng --catalog, và mọi thực thể đều được phân giải từ hai thư mục đó.
--auto-pull điền lockfile của mỗi Release trong quá trình build; các lockfile và
đầu ra được render đều được sinh ra, không được phân phối kèm. Việc phân giải một lockfile sẽ tải
chart của controller từ Docker Hub, vì vậy lần build đầu tiên của mỗi Release cần
kết nối mạng.
Với trợ lý AI
Một trợ lý AI được thiết lập với các công cụ của Aggrega cũng có thể làm như vậy: hãy dán prompt này vào trợ lý.
Chỉ dùng các công cụ của Aggrega và không tự tạo thư mục nào. Nếu thư mục workspace chưa có thư mục `ai-gateway-own-webhook-certificate`, hãy gọi công cụ `scaffold` một lần với `example` đặt thành `ai-gateway-own-webhook-certificate` và không có `dir`: công cụ này ghi ví dụ vào một thư mục `ai-gateway-own-webhook-certificate` mới. Sau đó gọi công cụ `build` một lần cho mỗi Release, theo thứ tự này — `release-cert-manager.yaml`, `release-own-certificate.yaml` — mỗi lần với `workspace_root` đặt thành `ai-gateway-own-webhook-certificate`, `release` đặt thành tệp đó, `auto_pull` đặt thành true và `write` đặt thành true. Sau đó gọi công cụ `cli-build`, công cụ chạy `aggrega build` và nhận cờ `--verify-determinism` của nó, với `workspace_root` đặt thành `ai-gateway-own-webhook-certificate`, `release` đặt thành `release-negative-without-omits.yaml`, `auto_pull` đặt thành true và `verify_determinism` đặt thành true: lần build này được dự định là sẽ bị từ chối, vì vậy hãy đọc cho tôi lời từ chối. Sau đó gọi công cụ `build` theo cách giống như hai lần build đầu với `release` đặt thành `release-negative-stale-omits.yaml`: lần này cũng được dự định là sẽ bị từ chối, vì vậy hãy đọc cho tôi cả lời từ chối đó. Hãy cho tôi biết mỗi bản build đã ghi những tệp nào; chúng nằm trong `ai-gateway-own-webhook-certificate/dist/`.Hai chế độ chứng chỉ, như khi được kết xuất
release-cert-manager.yaml, khi được xây dựng với --auto-pull, in ra nội dung sau, trong đó <workspace> đại diện cho thư mục của ví dụ này:
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>/distvà sau đó ls dist/helm liệt kê:
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.yamlThư mục ai-controller chứa sáu định nghĩa tài nguyên AI Gateway mà Recipe xuất ra bên cạnh chart. release-own-certificate.yaml, khi được xây dựng theo cùng cách, in ra:
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>/distvà ls dist/helm liệt kê:
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.yamlCây thư mục của chế độ cert-manager chứa một Certificate và một Issuer và không có Secret. Cây thư mục của chế độ chứng chỉ riêng không chứa cái nào trong ba cái đó: không có Certificate và không có Issuer, vì chart không kết xuất cái nào trong chế độ đó, và không có Secret, vì mục của Recipe đã loại bỏ Secret mà chart có kết xuất. Thay vào đó, thứ mà controller gắn kết là Secret mà Release đã đặt tên:
[… 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 đọc chứng chỉ của nó từ /certs, tức volume certs, chính là Secret ai-gateway-webhook-tls — một cái tên mà bản dựng chuyển tiếp nguyên như được viết và cluster phân giải khi pod khởi động.
Cùng các byte từ lần build này sang lần build tiếp theo
Khi được build lần thứ hai với --verify-determinism, release-own-certificate.yaml
in ra:
[… omitted: the total build time, which differs per run]Build completed: 14 files written to <workspace>/dist--verify-determinism render mỗi component hai lần từ cùng một đầu vào và
dừng lại nếu hai lần render khác nhau. Ở đây nó vượt qua, và cây mà nó ghi ra giống từng byte
với cây mà lần build đầu tiên đã ghi. Cả hai điều này đều đúng vì tài liệu duy nhất mà
chart tạo mới mỗi lần không bao giờ đến được đầu ra.
Không có mục: bản dựng kiểm tra tính tất định bị dừng
release-negative-without-omits.yaml là Release dùng chứng chỉ riêng được triển khai
qua manifest-without-omits.yaml, tệp này gắn Recipe minh họa không có mục
omits: nào. Khi dựng với --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 deterministicBản dựng thoát với mã 1. Hai lần kết xuất của controller khác nhau, vì chart
đã sinh ra một khóa và một chứng chỉ khác nhau ở mỗi lần. Bước pull cũng kết xuất
Release để tìm mọi đầu vào bên ngoài cần được ghim, và gặp cùng điểm dừng đó
ở đó; đây là lý do các dòng pull được lược bỏ mang câu này lần thứ hai. Tệp
lockfile vẫn được ghi.
Khi dựng không có cờ này, cùng Release đó hoàn tất. Cây của nó chứa các tài liệu của chart mà cây của Release dùng chứng chỉ riêng chứa — trừ các định nghĩa tài nguyên, vốn Recipe minh họa không phát ra — cùng thêm một tài liệu nữa, Secret mà chart đã sinh ra:
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]Dựng hai lần thì hai cây khác nhau đúng ở ba giá trị đó. Một bản dựng thông thường kết xuất mỗi component một lần, nên nó ghi bất kỳ khóa nào đã sinh ra mà không nhận thấy; chính bước kiểm tra làm cho sự khác biệt lộ ra. Nếu được áp dụng, tệp này sẽ thay thế Secret mà người vận hành đã tạo.
Điểm dừng này được mô tả tại
A provider rendered the same input twice and produced different output (Một provider đã kết xuất cùng một đầu vào hai lần và tạo ra đầu ra khác nhau),
nơi cách khắc phục nêu hai lối ra khi sự khác biệt là một giá trị do chart mà bạn
lấy nguồn sinh ra: cung cấp giá trị qua một thiết lập mà chart hỗ trợ, hoặc, khi
tài liệu được sinh ra là tài liệu mà Release không được phát hành, loại nó ra bằng một mục
omits: — cách mà Recipe của thư viện chuẩn chọn.
Một mục không khớp với gì cả
release-negative-stale-omits.yaml là Release tự cấp chứng chỉ được triển khai
qua manifest-stale-omits.yaml, tệp này gắn Recipe minh họa có mục
đặt tên Secret theo tên đã kết xuất của controller thay vì theo khóa:
# 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" "") "" }}'Khi 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 được nêu tên kèm phiên bản của tệp nhị phân đã chạy bản build, nên lần chạy của bạn sẽ hiển thị phiên bản tệp nhị phân của bạn ở đó.
Bản build thoát với mã 1, và các dòng của bước pull mang cùng câu đó vì cùng
lý do như trên. Thông điệp đọc từ trái sang phải như chỉ dẫn nơi cần xem: component,
provider đã kết xuất nó, Recipe khai báo mục và vị trí của mục trong danh sách omits:,
đếm từ 0, rồi đến kind và tên mà mục được phân giải thành. Điều kiện when: là đúng
trong chế độ này, nên mục được áp dụng; tên của nó kết xuất thành ai-controller-webhook-tls,
chart đặt tên Secret của nó là ai-gateway-webhook-tls, và mục không loại bỏ được gì.
Mọi mục được áp dụng đều phải loại bỏ một thứ gì đó, và bản build dừng lại ở mục
không làm được điều đó, vì một mục không khớp với gì cả là một khẳng định về nguồn
không còn đúng nữa. Nguyên nhân thường gặp là một lần nâng cấp nguồn đã đổi tên
tài liệu. Khi đó tài liệu bị đổi tên nằm trong đầu ra dưới tên mới — chính là tài liệu
mà mục được viết ra để loại bỏ — và việc dừng là điều ngăn nó được phát hành mà
không ai hay biết. Trong bản build này, Secret mà chart sinh ra chính là một tài liệu
như vậy: mục được viết ra để loại bỏ nó, nhưng lại nêu tên một thứ khác. Để
sửa một mục, hãy so sánh nó với những gì nguồn kết xuất hiện nay: build
với mục đã bị gỡ bỏ, như release-negative-without-omits.yaml làm khi không có
bước kiểm tra, và đọc tên từ tệp mà chart đã ghi.
E0334 được liệt kê trong tài liệu tham chiếu chẩn đoán với tên
omit-matched-nothing, và được mô tả trong
An omits entry left out nothing the source rendered (Một mục omits không loại bỏ được gì mà nguồn đã kết xuất).
Bản thân trường này — mọi trường của mục, ngữ cảnh template, những gì một Release có thể
quyết định về một mục, và những provider nào tuân theo nó — được trình bày tại
Recipe → Trường omits:.
Kiểm tra mọi bản build
Bước tự kiểm tra này chạy trong một bản checkout của kho tài liệu, nơi chứa script trợ giúp build dùng chung mà nó sử dụng; một bản sao do aggrega scaffold --example ghi ra không có script trợ giúp đó.
./check.shcheck.sh build bốn Releases thông qua ./build-release.sh và đối chiếu từng
kết quả với kết quả mà trang này mô tả. Nó build mỗi Release thành công
hai lần, lần thứ hai với --verify-determinism: cả hai bản build phải thoát với mã 0 và
ghi ra cùng các tệp, giống nhau từng byte, và cây thư mục, khi đếm theo kind
của mọi tài liệu được render, phải chứa một Certificate và một Issuer và không có Secret nào ở
chế độ cert-manager, và không có cái nào trong ba cái đó ở chế độ tự cung cấp chứng chỉ, với
volume certs của Deployment controller trỏ tới ai-gateway-webhook-tls. Một
Release kiểm soát phải thoát với mã khác 0 với đúng một lần dừng mang mã ngắn
và câu thông báo mà trang này hiển thị cho nó, và lần dừng của mục lỗi thời phải
nêu tên mục đó. Nó in một dòng cho mỗi Release và thoát với mã 1 nếu có kết quả nào
khác đi, đồng thời in đầu ra của bản build đó:
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.Nó cần những gì một bản build đơn lẻ cần: catalog thư viện chuẩn, và kết nối mạng để tải chart. Nó dùng binary mà ./build-release.sh xác định, nên AGGREGA_BIN sẽ chọn binary đó; các đối số sau -- được chuyển tới mọi bản build. Nó từ chối khởi chạy khi có một dist/ trong thư mục này, vì nó so sánh các cây thư mục mà các bản build ghi ra, và nó không để lại cây nào. Mã thoát của nó là toàn bộ kết luận, nên một pipeline có thể chạy nó thay cho việc build riêng từng Release.
Nơi trình biên dịch không diễn giải
Trình biên dịch không biết Secret là gì, controller làm gì với nó,
hay vì sao một chart lại sinh ra nó. Trình biên dịch đánh giá các template của mục như cách
nó đánh giá mọi template của Recipe, chuyển kind và tên mà chúng phân giải thành cho
helm provider cùng với đầu vào của component, và provider loại bỏ các tài liệu đã render
khớp với chúng và báo cáo mỗi mục đã loại bỏ bao nhiêu tài liệu. Trình biên dịch không bao giờ tìm
ai-gateway-webhook-tls trong một cluster, không bao giờ tạo nó, và không bao giờ kiểm tra rằng nó
chứa ba mục mà controller đọc: tên đó là một chuỗi do Release
cung cấp, được truyền vào values của chart và vào mục. Việc Secret
tồn tại trước khi controller khởi động là việc phía triển khai phải lo liệu.
Các tệp
aggregate.yaml— bộ điều khiển AI gateway, thành phần duy nhất; giống nhau cho mọi Release.manifest.yaml— gắn bộ điều khiển với Recipe của thư viện chuẩn; được hai Releases thành công dùng chung.manifest-without-omits.yaml,manifest-stale-omits.yaml— gắn nó với một trong hai Recipes minh họa.release-cert-manager.yaml,release-own-certificate.yaml— hai chế độ chứng chỉ.release-negative-without-omits.yaml,release-negative-stale-omits.yaml— chế độ chứng chỉ riêng qua từng Recipe minh họa; cả hai đều dừng.catalog/recipe/helm/envoy-ai-gateway-operator-without-omits/1.0.0/— Recipe minh họa không có mụcomits:, và tệpentity.lockghim chart của nó.catalog/recipe/helm/envoy-ai-gateway-operator-stale-omits/1.0.0/— Recipe minh họa có mục không khớp với gì, và tệpentity.lockcủa nó..aggrega-config.yaml— ngăn xếp tìm kiếm catalog và registry.build-release.sh— build một Release, in ra lệnhaggrega buildtương đương.check.sh— build cả bốn và kiểm tra từng kết quả.