Helm Provider
Helm provider tạo ra YAML Kubernetes đã được render dạng phẳng cho các bên tiêu thụ GitOps (ArgoCD, Flux). Provider này lắp ráp theo từng (path, provider): YAML đã render của mọi node nhắm tới helm được chuyển tới bộ lắp ráp có khóa là directory: đã được đánh giá của boundary nối với subDirectory: của từng component, và bộ lắp ráp đó xuất ra một tệp YAML cho mỗi tài nguyên Kubernetes. Công cụ phía sau so sánh khác biệt và áp dụng trực tiếp các tệp mà không cần bước cài đặt Helm.
Khi syncWave: <integer> của boundary khác 0, mỗi tài nguyên Kubernetes được xuất ra mang giá trị đó dưới dạng annotation argocd.argoproj.io/sync-wave: "<N>"; các Helm hook còn mang thêm helm.sh/hook-weight: "<N>". ArgoCD đọc annotation sync-wave, còn Helm đọc trọng số của hook, mỗi bên sắp thứ tự tài nguyên theo đó; một boundary ở wave mặc định 0 không mang cái nào, điều mà cả hai công cụ đọc là wave 0.
Trang này là tài liệu tham khảo soạn thảo của helm provider. Về mô hình kết hợp đầu vào dùng chung cho các provider, xem architecture/16-recipe-input-composition.md. Về mức độ sẵn sàng của từng provider, xem Trạng thái của ngôn ngữ → Providers.
Các loại đầu vào được hỗ trợ
Helm provider chấp nhận cả ba loại đầu vào của Recipe với các vai trò khác nhau:
- Chế độ sourced. Một Recipe có
source: <chart-path>trỏ đến một thư mục Helm chart trên đĩa. Helm Go SDK nạp chart, từ điển values của bước kết xuất cơ sở được hợp nhất với các giá trị mặc định của chart, và các template của chart được kết xuất thành Kubernetes YAML phẳng. - Chế độ Workload (tổng hợp). Một Recipe có
workload:(nội tuyến hoặc được nạp bằng$import:) khai báo một tài liệu Workload. Provider tổng hợp một hoặc nhiều tài nguyên Kubernetes cho mỗi nút — một đối tượng controller được chọn theoformcủa Workload cùng với các Service cho từng dịch vụ và các PVC cho từng persistent volume — trực tiếp từ đặc tả Workload; xem Chế độ Workload (tổng hợp). - Chế độ chỉ có artifacts. Một Recipe có
artifacts:và không cósource:lẫnworkload:sẽ xuất ra các manifest do tác giả của nó viết, với các nhãn và chú thích nguồn gốc của bản build được chèn vào metadata riêng của từng tài nguyên.
Ba loại này kết hợp được với nhau: một Recipe có thể khai báo cùng lúc một chart, một Workload và artifacts:, và mỗi thứ được kết xuất và xuất ra độc lập, song song trong đầu ra của nút — xem Những gì mỗi provider chấp nhận, đầy đủ.
Bộ khóa source:
source: của helm provider đặt tên cho một chart, và nó chấp nhận cả hai dạng mà trường source: có: một chuỗi đường dẫn hệ thống tệp trần, và một đối tượng có cấu trúc mà url: của nó mang vị trí. Bất cứ khi nào vị trí đó là một đường dẫn hệ thống tệp, nó được neo vào thư mục chứa recipe.yaml khai báo nó, không phải vào thư mục nơi bản build được gọi, và nó phải nằm bên trong thư mục đó: một đường dẫn leo ra khỏi thư mục đó, hoặc một đường dẫn tuyệt đối, sẽ bị từ chối, vì mọi tệp mà một bản phát hành của Recipe mang theo đều được lấy từ thư mục của nó — xem entities/recipe.md “Content paths stay inside the Recipe’s own directory”. Một chart được đặt tên theo cách này được phát hành cùng Recipe, gồm mọi tệp bên dưới nó mà các quy tắc bỏ qua được ghi lại khi Recipe được ghim giữ lại — helm provider loại bỏ các thư mục quản lý phiên bản và các tệp ẩn dưới templates/ của chart, tuân theo .helmignore của chính chart, và .aggregaignore của tác giả có tiếng nói cuối cùng, như Which files ship with an entity mô tả — trong khi một tệp nằm cạnh Recipe mà không thứ gì nó khai báo đặt tên thì không. Quá trình render đọc chính các tệp mà bản phát hành mang theo, nên một chart render giống nhau từ thư mục của bạn và từ một registry. Dạng bạn viết không thay đổi điều đó: một source: có cấu trúc mà url: là ./charts/api-server được neo đúng như chuỗi trần ./charts/api-server.
spec: capability: helm source: ./charts/api-server # filesystem path to a chart directory valuesMapping: | image: "{{ .values.image }}" replicas: {{ optional .infra `replicas` 2 }}Một source: có cấu trúc nói cùng một điều bằng các trường có tên, và những gì url: của nó mang quyết định liệu có thứ gì được tải về hay không. Khi url: mang một scheme giao thức truyền tải — oci://… cho một chart OCI, một https://….tgz cho một tệp lưu trữ chart trực tiếp, hoặc một gốc repo https:// đi kèm với chart: — chart sẽ được tải về: loại được xác định từ scheme của URL hoặc từ một kind: tường minh, aggrega pull tải về và ghim chart trong lockfile, và bản build giải nén nó từ bộ nhớ đệm. Khi url: đặt tên cho một đường dẫn hệ thống tệp, không có gì được tải về và không có gì được ghim — chart được đọc từ đĩa, được neo đúng như dạng chuỗi trần ở trên.
spec: capability: helm source: kind: helm-oci-chart url: ./charts/api-server # a path, so nothing is fetched and nothing is pinned version: "1.0.0"Chỉ url: quyết định nơi một chart được đọc. Các trường khác chọn những gì sẽ được tải về, nên với một đường dẫn chúng không chọn gì cả — chúng vẫn đến được các template của chính Recipe dưới dạng .source.*.
Việc vendor một chart cục bộ được hỗ trợ như một lựa chọn thay thế cho việc tải về, và không bắt buộc. Schema chấp nhận một đối tượng có cấu trúc mở.
Chart tại đường dẫn nguồn phải chứa một Chart.yaml hợp lệ. Các lần render sourced không tải được chart sẽ hiển thị nguyên văn lỗi gốc của Helm SDK. Một source: "" rỗng không phải là vấn đề của helm: nó không đặt tên cho chế độ sourceless lẫn chế độ sourced, nên sự từ chối mà nó nhận được là như nhau bất kể Recipe nhắm tới provider nào, và nó xảy ra khi Recipe được đọc, trước khi bất kỳ chart nào được tải và trước khi provider này được điều phối. Những lệnh nào báo cáo nó được trình bày trong entities/recipe.md “Source field scheme inventory” và errors/fatal-halts.md “Recipe source: is an empty string (Trường source của Recipe là một chuỗi rỗng)”.
Chế độ sourced
Một Recipe có source: <chart-path> và valuesMapping: chạy quy trình sau khi kết xuất cơ sở:
- Chart tại
<chart-path>được nạp thông qua Helm Go SDK. - Template
valuesMappingđược đánh giá dựa trên ngữ cảnh template của Recipe. Đầu ra YAML của nó được coi là một lớp phủ giá trị (values overlay) cho chart. - Lớp phủ được hợp nhất với các giá trị mặc định trong
values.yamlcủa chart, một lần; khi xung đột, khóa của lớp phủ thắng (ngữ nghĩa chuẩnhelm install --valuescủa Helm). Một khóa mà lớp phủ đặt thànhnullsẽ xóa giá trị mặc định của chart cho khóa đó — ở cấp cao nhất, bên trong một bảng, hoặc trong các giá trị của một dependency — nhưhelm install --valueslàm, nên các template của chart đọc khóa đó là không có; mộtnulltại khóa mà chart không cho giá trị mặc định sẽ đến các template dưới dạngnull. - Helm SDK kết xuất các template của chart dựa trên các giá trị đã hợp nhất.
- Aggrega chèn siêu dữ liệu nguồn gốc của nó vào các manifest đã kết xuất bằng cách viết lại YAML sau kết xuất, bảo đảm đầu ra sourced mang cùng cách gắn nhãn như đầu ra ở chế độ workload. Các giá trị định danh trở thành nhãn (
app.kubernetes.io/name,aggrega.ai/component-id,aggrega.ai/provider,aggrega.ai/provider-version,aggrega.ai/environment, và — khi được đặt —aggrega.ai/aggregate-name,aggrega.ai/compiler-version), mỗi nhãn được viết ở dạng mà Kubernetes chấp nhận làm giá trị nhãn; các giá trị mà nhãn Kubernetes không biểu diễn được trở thành annotation (aggrega.ai/recipe-uri,aggrega.ai/boundary-path,aggrega.ai/sync-wavekhi wave khác0, và giá trị nguyên văn của bất kỳ nhãn nào có giá trị phải được viết lại — một Aggregate tênimported/flowđược gắn nhãnimported-flowvà annotationimported/flowdưới cùng khóa). Quy tắc viết lại được nêu tại well-known-annotations.md “Các nhãn nguồn gốc do nhà cung cấp phát ra”. - Các tệp đầu ra nằm phẳng trong thư mục đầu ra của Recipe, mỗi tệp cho một tài nguyên được kết xuất, đặt tên là
<name-basis>-<kind>[-<namespace>]-<name>.yaml— cùng cơ sở mà tên release bên dưới được suy ra, theo sau là kind của chính tài nguyên, namespace nếu có, và tên, mỗi phần được chuyển sang chữ thường với mọi chuỗi ký tự khác được rút gọn thành một dấu gạch nối. Với một component thông thường, cơ sở đó là danh tính của chính component, cũng là thứ mà nhãnaggrega.ai/component-idcủa tài nguyên mang; với một chart do tác giả của một attachment của Feature cung cấp, cơ sở vẫn là của component chủ, còn nhãn mang danh tính của chính attachment. Một tài liệu không có kind hoặc không có tên được đặt tên theo đường dẫn template của nó. Cấu trúc thư mục của chart được làm phẳng: không có thư mục contemplates/trong đầu ra đã kết xuất, và hai template ở các thư mục con khác nhau có cùng tên tệp vẫn là hai tệp vì tên lấy từ tài nguyên chứ không từ template. Một tệp mà khốiartifacts:của Recipe nêu tên không nằm ở đây: nó nằm sâu hơn một cấp, trong một thư mục mang tên component đã khai báo nó, vì tệp như vậy được đặt tên theo khóa mà tác giả viết chứ không theo tài nguyên nó mang — nên nếu không có thư mục đó, hai component gắn với một Recipe sẽ ghi vào cùng một đường dẫn, và không tác giả nào có thể tách chúng ra.
Namespace mà chart kết xuất dựa vào được đọc từ annotation aggrega.ai/namespace truyền xuống từ boundary và đến chart dưới dạng release namespace của nó; khi không boundary nào khai báo, chart kết xuất dựa vào default. Khi một boundary khai báo namespace, mọi tài nguyên có namespace (namespaced) mà chart kết xuất không kèm namespace — không có metadata.namespace, hoặc có nhưng để trống hay null — được xuất ra trong namespace đã khai báo, đúng là nơi việc cài đặt chart bằng Helm dưới release namespace đó đặt nó, và tệp của nó được đặt tên kèm phần namespace giống hệt như một tài nguyên có template ghi trường đó. Một tài nguyên có template ghi namespace sẽ giữ nguyên namespace đó, dù nó nêu namespace nào. Một tài nguyên phạm vi cluster (cluster-scoped) vẫn không có namespace. Việc một kind có namespace hay không được xác định bởi phạm vi của chính Kubernetes API đối với kind mà API tự phục vụ, và đối với kind tùy chỉnh là scope mà một CustomResourceDefinition trong cùng lần kết xuất khai báo cho nó — từ các template của chart hoặc từ thư mục crds/ của nó. Một tài nguyên thuộc kind mà cả hai nguồn đó đều không phân loại được sẽ được giữ nguyên như chart đã viết, và bản build báo cáo nó, một lần cho mỗi kind, nêu tên kind và API group của nó; tương tự với một tài liệu kind: List, mà các mục của nó không được đặt namespace. Khi không boundary nào khai báo namespace, không có gì được đặt và không có gì được báo cáo: một tài nguyên mà chart viết không kèm namespace được xuất ra không có namespace, và được đặt theo bất cứ thứ gì công cụ áp dụng chọn.
Báo cáo là một cảnh báo trên bản build, và bản build vẫn hoàn tất:
warning: node "store" (provider "helm"): resources of kind "Probe" in API group "monitoring.example.org" write no namespace and are left without one rather than placed in namespace "shop": the kind is not one the Kubernetes API serves itself, and no CustomResourceDefinition in this chart's render gives it a single scope, so whether it is namespaced is not known when the build runs, and they land wherever the tool applying the output places themKhi chart có một giá trị kết xuất CustomResourceDefinition của kind đó, hoặc một giá trị tự ghi namespace, việc đặt giá trị đó qua valuesMapping của Recipe sẽ đặt namespace cho tài nguyên như vậy.
Phiên bản Kubernetes mà một chart được render cho
Các template của một chart đọc phiên bản Kubernetes mà chúng được render cho dưới dạng .Capabilities.KubeVersion, và nhiều chart chọn một phiên bản API, một trường hay cả một cơ chế dựa vào nó — chẳng hạn một service-account token được chiếu (projected) từ 1.21 trở đi, và một token tự cấp ở phiên bản thấp hơn. Bản build không có cụm nào để hỏi, nên phiên bản là giá trị bạn khai báo, tại nơi Release cho biết một component triển khai ở đâu: annotation aggrega.ai/kubernetes-version trên một boundary, hoặc trên một component, nơi nó được ưu tiên hơn giá trị của boundary, và được kế thừa xuống đúng như aggrega.ai/namespace.
spec: boundaries: production: annotations: aggrega.ai/kubernetes-version: "1.31" components: api: {} legacy: annotations: aggrega.ai/kubernetes-version: "1.28" # this component deploys to an older clusterGiá trị được đọc theo cách helm template --kube-version đọc cờ của nó, nên nó chấp nhận các dạng mà cờ đó chấp nhận và chart đọc được đúng những gì cờ đó sẽ cung cấp: "1.31" được đọc là v1.31, "v1.31.2" là v1.31.2, và phần văn bản sau các con số được giữ nguyên trong .Capabilities.KubeVersion.Version — "1.29.3-gke.100" được đọc là v1.29.3-gke.100 — trong khi .Capabilities.KubeVersion khi in toàn bộ thì đọc phiên bản không có phần đó. Một chart so sánh .Capabilities.KubeVersion.Version bằng semverCompare sẽ đọc hậu tố như vậy là một pre-release, nên một ràng buộc không có mức sàn -0, chẳng hạn ">=1.21", không khớp với nó; và một giá trị có khoảng trắng bao quanh sẽ được đọc kèm khoảng trắng đó — " 1.30 " được đọc là "v 1.30 " — và thất bại hoàn toàn trong phép so sánh như vậy: hãy viết phiên bản trần ở nơi chart có so sánh nó. Một giá trị không phải là phiên bản — "one.two", "latest", một con số đơn lẻ — sẽ dừng bản build theo điều kiện dành cho một giá trị mà plugin không có cách biểu diễn, nêu tên giá trị, component và boundary của nó; chart không bao giờ được render cho một phiên bản khác thay thế. Xem A Kubernetes version the helm provider cannot render a chart for (Một phiên bản Kubernetes mà helm provider không thể render chart). Một giá trị rỗng được coi là chưa đặt.
Khi không có annotation nào nêu phiên bản, chart được render cho phiên bản mà helm template gốc của cùng bản phát hành helm render cho, tức là phiên bản của thư viện client Kubernetes mà provider được build cùng: một provider build với thư viện client v0.37 sẽ render cho Kubernetes v1.37.0. Vì vậy một chart được render trong Aggrega giống như helm template của chính các tác giả chart render nó, và giá trị mặc định chỉ thay đổi khi thư viện client mà provider được build cùng thay đổi. Hãy nêu phiên bản của cụm bạn triển khai mỗi khi nó khác: một chart được render cho phiên bản mới hơn phiên bản cụm đang chạy có thể sinh ra một phiên bản API mà cụm đó không phục vụ.
Chỉ có phiên bản được đặt theo cách này. Mọi capability khác mà chart đọc — .Capabilities.APIVersions và .Capabilities.HelmVersion — là giá trị dựng sẵn của thư viện helm, nên một API mà cụm phục vụ từ một CustomResourceDefinition đã cài đặt sẽ không được báo cho chart. Khoảng kubeVersion riêng của chart trong Chart.yaml không được so sánh với phiên bản: helm template từ chối một chart có khoảng loại trừ phiên bản mà nó render cho, còn bản build vẫn render chart đó. Annotation chỉ định hình một chart được render từ nguồn và không gì khác: một Workload được tổng hợp và một phần thân artifacts: không đọc .Capabilities, còn provider helm-chart chuyển chart của nó đi mà không render, để được render khi cài đặt.
Loại bỏ các tài liệu đã render. Provider này tuân theo các mục omits: mà một Recipe hoặc một FeatureRecipe khai báo, trong chế độ này và không trong chế độ nào khác: một Workload được tổng hợp và một phần thân artifacts: được render mà không áp dụng chúng. Mọi tài liệu mà chart render — từ một template hoặc từ một tệp trong thư mục crds/ của nó — được đối chiếu với từng mục áp dụng cho bản build, và một tài liệu được bất kỳ mục nào nêu tên sẽ bị loại bỏ. Một mục nêu tên tài liệu bằng những từ mà chính tài liệu mang, cũng là những từ dùng để tạo tên tệp đầu ra và các render fact của nó: kind, metadata.name của nó và, chỉ khi mục có nêu, namespace mà tài liệu thuộc về — namespace mà template của nó ghi, hoặc namespace được khai báo của boundary khi provider này đặt tài liệu như mô tả ở trên. Đó không bao giờ là namespace mà chart chỉ đơn thuần render theo: khi không khai báo namespace, chart render theo default, nhưng một tài liệu mà template không ghi namespace thì không thuộc namespace nào, nên một mục nêu default không khớp với nó. Một tài liệu không có kind hoặc không có name không khớp với mục nào. Các tài liệu bị loại bỏ vẫn được render rồi bị bỏ đi khi tên của mọi tệp đã được xác định, nên mỗi tài liệu được giữ lại được đặt tên và ghi ra đúng như khi không có các mục, và một tài liệu bị loại bỏ không đi tới bất cứ thứ gì bản build làm sau đó — không có tệp, không có tên trong phép so sánh từ chối hai bên đóng góp trùng một tên, không có render fact nào để một Feature đọc, không có gì được chuyển cho một bước pipeline. Provider báo cáo mỗi mục đã khớp bao nhiêu tài liệu, và một mục không khớp tài liệu nào sẽ dừng bản build; xem An omits entry left out nothing the source rendered (Một mục omits không loại bỏ được gì từ những gì nguồn đã render).
Bản phát hành Helm mà chart được render theo
Provider render bằng Helm 4 SDK, ở phiên bản v4.3, nên chart đọc đúng những gì helm template của chính Helm 4 cung cấp, và cùng một chart với cùng các giá trị sẽ render ra cùng các byte ở mọi lần build. Một chart được viết và kiểm tra với Helm 3 có thể gặp những hành vi sau của Helm 4:
.Capabilities.HelmVersionbáo cáo phiên bản của Helm 4,v4.3.- Phiên bản Kubernetes mặc định là v1.37.0, vì Helm 4 ở v4.3 được build với thư viện client v0.37, và
.Capabilities.APIVersionslà tập phiên bản API của thư viện client đó. Hãy chỉ định phiên bản mà cluster của bạn chạy, như mô tả trong Phiên bản Kubernetes mà chart được render cho. - Giá trị mặc định
nullcủa chart bị loại bỏ. Một khóa màvalues.yamlcủa chart đặt thànhnull— ở cấp cao nhất hoặc bên trong một bảng — sẽ vắng mặt trong.Valuestrừ khi các giá trị mà Recipe cung cấp đặt nó, nênhasKeybáo rằng nó không có,toYamlbỏ qua nó, vàvalues.schema.jsoncủa chart được kiểm tra với các giá trị không có nó. - Block scalar giữ dấu xuống dòng cuối cùng trước
---. Một tài liệu kết thúc bằng block scalar và được theo sau bởi một tài liệu khác từ cùng template sẽ giữ dấu xuống dòng cuối của scalar đó, nên nó được viết là|thay vì|-. .Chartlà một map với khóa là tên trường..Chart.Name,.Chart.Version,.Chart.AppVersionvà các trường khác vẫn đọc như trước, nhưngtoYaml .CharthoặctoJson .Chart.Maintainersin các khóa dưới dạngName,AppVersion, v.v., có cả các trường rỗng, và một trường mà metadata của chart không có sẽ được đọc là rỗng thay vì làm render thất bại..Capabilities.KubeVersion.Versiongiữ nguyên văn bản của phiên bản như khi được viết, như đã mô tả ở trên cho annotationaggrega.ai/kubernetes-version.- Một
values.yamlchứa nhiều tài liệu YAML được đọc toàn bộ, các tài liệu sau được hợp nhất đè lên các tài liệu trước. .Files.Linescủa một tệp rỗng trả về không dòng nào thay vì làm render thất bại.- Các hàm template được bổ sung trong Helm 4 —
mustToYaml,mustToJson,mustToToml,mustToDurationvà các phép chuyển đổiduration…— đều có sẵn cho các template của chart. - Một dependency được đặt alias hai lần cho mỗi alias một bản sao riêng của các dependency của chính dependency đó.
- Việc xác thực values-schema chỉ chấp nhận hoặc từ chối khác đi ở các trường hợp biên: phần local của email có dấu ngoặc kép,
NaNvà các số vô hạn, một số được so sánh với một giá trị không phải số trongenumvàconst, và vị trí được báo cáo chopropertyNames,contentSchemahoặc phần tử mảng phía sau bị lỗi.
Một template mà chính engine không thực thi được — chẳng hạn một giá trị được đọc qua một bảng không tồn tại — được báo cáo theo dạng của Helm 4: tệp, dòng và cột của template trên một dòng riêng, sau đó là phần đang được thực thi và thông điệp, thụt lề, cho mỗi template mà lỗi đi qua. fail hoặc required của chính chart vẫn giữ dạng một dòng execution error at (<file>:<line>:<col>): <message>, và lỗi do một hàm template trả về cũng vậy.
Cách suy ra tên release
Một chart dạng sourced được render theo một tên release, tên này đến với mọi template dưới dạng .Release.Name. Các chart thường đặt tên tài nguyên theo nó, nên tên release là một danh tính bên trong cluster chứ không phải một nhãn trên bản build.
Tên release là dạng mã hóa của cùng một cơ sở được dùng làm tiền tố cho tên tệp đầu ra của tài nguyên đã render, nên hai thứ là một tên được viết hai lần. Cơ sở đó là một instance_id đối với một component thông thường, và là danh tính tổng hợp mà một Feature gắn vào một boundary mang theo. Đối với một chart do tác giả của một phần gắn Feature cung cấp, đó là tên của component chủ: các template của chính chart được render theo tên release, nên nếu suy ra nó từ phần gắn thì sẽ đổi tên các tài nguyên mà chart khai báo, trong một cluster nơi chúng đã được triển khai. Các tài nguyên đó vẫn mang danh tính riêng của phần gắn trong nhãn aggrega.ai/component-id — một tài nguyên được gọi là gì và nó thuộc về đâu là hai câu hỏi riêng biệt ở đây, và chỉ với một component thông thường thì chúng mới có cùng câu trả lời. Tên release của Helm chấp nhận một tập ký tự hẹp hơn so với những gì một danh tính có thể mang: chữ thường, chữ số, dấu gạch nối và dấu chấm, bắt đầu và kết thúc bằng chữ thường hoặc chữ số, tối đa 53 ký tự. Thay vì thay thế một ký tự mà đích không chấp nhận, phép suy ra viết nó ra, nên hai danh tính component chỉ khác nhau về dấu câu hoặc chữ hoa/thường luôn cho ra hai tên release khác nhau.
- Chữ thường và chữ số được giữ nguyên đúng như khi khai báo.
- Dấu gạch nối được giữ nguyên như khi khai báo ở bất cứ đâu mà ký tự sau nó được giữ nguyên trực tiếp và không phải là chữ thường
z. Dấu gạch nối theo sau bởi chữ thườngzmở đầu một chuỗi thoát, nên một dấu gạch nối được khai báo ở vị trí đó sẽ tự nó được viết ra —api-zonetrở thànhapi-zhzone, đây chính là điều cho phép đọc ngược bất kỳ tên nào mà không cần đoán. Dấu gạch nối không có gì phía sau cũng được viết ra vì cùng lý do, nêndb-cho radb-zh. - Mọi ký tự khác được viết là
-ztheo sau bởi một chữ cái gọi tên nó:dcho dấu chấm,ucho dấu gạch dưới,scho dấu phân cách đường dẫn,hcho dấu gạch nối mà quy tắc trên không giữ lại. Mọi thứ khác — kể cả chữ hoa — được viết làxcùng mã điểm thập lục phân sáu chữ số của ký tự, và một byte không bắt đầu ký tự nào được viết làbcùng giá trị hai chữ số của chính nó. - Giá trị rỗng được viết là
-ze, điều mà không giá trị không rỗng nào có thể tạo ra.
Dấu chấm được viết ra thay vì giữ nguyên, dù Helm chấp nhận dấu chấm trong tên release, vì Helm yêu cầu một chữ thường hoặc chữ số ở mỗi bên dấu chấm còn phép suy ra lại chèn các dấu gạch nối của riêng nó.
Vì hai Features gắn vào một component đều render theo tên release của component đó, hai chart mà mỗi chart đặt tên một tài nguyên theo .Release.Name sẽ tạo ra hai tài nguyên cùng một tên. Provider này báo cáo tên mà mọi tài nguyên do chính nó render mang theo, giới hạn theo kind của tài nguyên đó và, với kind mà cluster giữ trong một namespace, theo namespace của nó, và bản build từ chối hai bên đóng góp rơi vào cùng một tên thay vì tạo ra đầu ra mà khi áp dụng cả hai chỉ còn lại cái cuối — xem ../errors/fatal-halts.md “The same name is derived more than once inside the output (Cùng một tên được suy ra nhiều lần bên trong đầu ra)”. Một kind mà cluster giữ bên ngoài mọi namespace — một ClusterRole, một CustomResourceDefinition, hoặc một kind tùy chỉnh mà một CustomResourceDefinition trong cùng lần render khai báo với phạm vi Cluster — chỉ được giới hạn theo kind của nó, được phân loại đúng như cách phần bố trí namespace ở trên phân loại, nên hai component của một đầu ra mà mỗi cái ghi một đối tượng như vậy dưới cùng một tên sẽ bị từ chối ngay cả khi Release đặt chúng vào các namespace khác nhau. Cách khắc phục là tổng hợp tên, và tọa độ cần dùng phụ thuộc vào cách bố trí. Hai phần gắn trên một component vốn đã chung host, nên chính phần gắn phải đến được template: truyền .attachment_name vào chart qua valuesMapping: của FeatureRecipe và đặt nó vào giá trị nào của chart mà tên tài nguyên được xây dựng từ đó. Một chart gắn vào hai component thì ngược lại — tên release vốn đã khác nhau theo từng host, nên một tài nguyên đặt tên theo .Release.Name mang một tên riêng trên mỗi host, còn một tên cố định thì không. Một FeatureRecipe cung cấp tài nguyên qua artifacts: cũng được báo cáo theo cùng điều kiện: provider này đọc tên mà mỗi tài liệu được tạo ra mang theo, bất kể tài liệu đó đến từ template của chart hay từ phần thân artifacts, nên một tên cố định trong phần thân như vậy gắn vào hai component cũng dừng lại. Phần thân artifacts là một template, vì vậy hãy tổng hợp tên từ .context.rendered_name — tên release của host, khác nhau theo từng host và được viết bằng các ký tự mà tên Kubernetes cho phép — và .attachment_name khi nó phải khác biệt theo từng host; trên một host chỉ đặt một tập artifact, vốn không báo cáo tên release, hãy tổng hợp nó từ .context.instance_id thay thế. Không phải mọi tên đều được báo cáo, nên một bản build không dừng lại chưa hẳn đã so sánh mọi thứ mà đầu ra của nó cuối cùng sẽ mang. Trường hợp bạn dễ gặp nhất khi viết chart là một tài nguyên khai báo generateName, được để cho cluster hoàn thiện nên chưa có gì để so sánh. Trang được liên kết ở trên liệt kê đầy đủ.
Vì vậy một instance_id là api cho tên release api, data.main-db cho data-zdmain-db, và db_host cho db-zuhost. Một danh tính chỉ được xây dựng từ chữ thường, chữ số và các dấu gạch nối mà phép suy ra giữ lại sẽ xuất hiện đúng như khi khai báo. Đầu vào giống nhau luôn tạo ra tên giống nhau.
Hai điều kiện của Helm là thuộc tính của cơ sở chứ không phải của phép suy ra: tên release phải bắt đầu bằng chữ thường hoặc chữ số, và dài tối đa 53 ký tự. Một cơ sở có ký tự đầu tiên bị viết ra sẽ bắt đầu tên bằng dấu gạch nối mà mọi chuỗi thoát mở đầu, và một cơ sở mang các ký tự bị viết ra sẽ được mã hóa dài hơn so với khi khai báo. Bản build hỏi provider này về cả hai điều, và hành động theo câu trả lời tại thời điểm build thay vì để cluster từ chối tại thời điểm apply — xem ../errors/fatal-halts.md “The target will not accept a name derived from an authored identity (Đích sẽ không chấp nhận một tên được suy ra từ một danh tính đã khai báo)”. Việc nó làm với câu trả lời phụ thuộc vào ai đã viết cơ sở. Một tên do bạn viết sẽ bị từ chối chứ không bị thay đổi, và thông báo từ chối nêu trường bạn đã viết cùng giới hạn bạn có; một tên do Aggrega tổng hợp sẽ được rút ngắn cho đến khi provider này chấp nhận.
Cluster áp dụng cho các tài nguyên được đặt tên theo một component một quy tắc chặt hơn của Helm: tên Service phải bắt đầu bằng một chữ cái, trong khi tên release có thể bắt đầu bằng chữ số. Một chart thường đặt tên các Service theo tên release, và các Service của một workload được tổng hợp cũng bắt đầu bằng nó, nên provider này cũng từ chối tên component bắt đầu bằng chữ số, báo cáo nó là một Service name mà đích không thể dùng. Không độ dài nào sửa được ký tự đầu tiên, nên thông báo từ chối đó không nêu độ dài nào. Vì vậy hãy bắt đầu instance_id bằng một chữ thường, và giữ nó đủ ngắn để dạng mã hóa vẫn vừa.
Việc thay đổi cơ sở mà tên release được suy ra từ đó sẽ đổi tên các tài nguyên cluster mà chart đặt tên theo .Release.Name, cùng mọi tài nguyên mà provider này tổng hợp cho component, và Kubernetes không đổi tên tài nguyên tại chỗ. Công cụ áp dụng tạo tài nguyên dưới tên mới và xóa tài nguyên dưới tên cũ, điều này đối với tài nguyên có trạng thái nghĩa là bộ lưu trữ gắn với tên cũ sẽ bị giải phóng. Hãy coi thay đổi như vậy là một sự thay thế cần lên kế hoạch — rút cạn, di chuyển dữ liệu hoặc lên lịch — chứ không phải một bản cập nhật để triển khai dần.
Chế độ Workload (tổng hợp)
Một Recipe có workload: (nội tuyến hoặc nạp bằng $import:) tổng hợp các tài nguyên Kubernetes từ ý định trừu tượng của Workload. Lược đồ Workload được mô tả tại entities/workload.md; phần này trình bày những gì helm provider phát ra.
Với mỗi nút:
- Một đối tượng controller được chọn theo
formcủa Workload:stateless(và mặc định) phát ra một Deployment,statefulmột StatefulSet,daemonmột DaemonSet,taskmột Job,scheduledmột CronJob cóspec.schedulelà trườngschedulecủa Workload (một biểu thức cron 5 trường hoặc một macro@); một workloadscheduledkhông có lịch, hoặc có lịch sai định dạng, sẽ dừng lại kèm báo lỗi rõ ràng. Một workloadscheduledkhai báosuspend: truephát ra CronJob của nó vớispec.suspend: true, nên không lần chạy nào bắt đầu từ lịch cho đến khi nó được tiếp tục, trong khi vẫn có thể tạo thủ công một Job từ CronJob; một workload không khai báo nó thì hoàn toàn không phát ra khóasuspend. Deployment và StatefulSet mang số bản sao; DaemonSet, Job và CronJob không mang. Một Workloadstatefulyêu cầu đúng một Servicetype: Headlessđược khai báo trong Workload để quản lý StatefulSet; provider nốiserviceNamecủa StatefulSet với tên đã render của Service đó, và bản build dừng lại nếu không có Service headless nào được khai báo (hoặc nếu có nhiều hơn một). Một volumepersistentTemplateđi kèm vớiform: stateful— khai báo nó trên bất kỳ form nào khác sẽ dừng lại với thông báo nêu cách khắc phục. - Một Service cho mỗi mục
services:được khai báo trên Workload, mở ra các cổng có tên mà đặc tả service liệt kê.typecủa mục trở thành loại của Service —ClusterIP,NodePortvàLoadBalancergiữ nguyên, cònHeadlessthành một ServiceClusterIPvớiclusterIP: None. Một mụcLoopbackthay vào đó sẽ dừng bản build, nêu tên nút và service: Service của Kubernetes không có loại nào gắn với địa chỉ loopback của máy chủ, và việc một ServiceNodePortlắng nghe trên những địa chỉ nào của nút là thiết lập của toàn bộ cluster, nên mục đó bị từ chối thay vì được render với phạm vi truy cập mà nó không yêu cầu. Xem A service type the helm provider cannot render (Một loại service mà helm provider không thể render). - Một PersistentVolumeClaim cho mỗi volume
persistent, có kích thước và hình dạng theo đặc tả của volume. Một volumepersistentTemplatekhông phát ra claim độc lập nào: nó trở thành một mụcvolumeClaimTemplatesbên trong spec của chính StatefulSet, đó là lý do nó đi kèm vớiform: stateful.
Tên tài nguyên. Mọi tài nguyên mà chế độ này phát ra cho một component đều được đặt theo tên release của component — cùng tên mà một chart có nguồn render dựa trên, được suy ra như Cách suy ra tên release mô tả — và provider báo tên đó cho bản build dưới dạng {{ .context.rendered_name }}. Đối tượng controller mang chính tên release; mỗi Service là <release name>-<service key>; mỗi claim độc lập là <release name>-<volume>, và volume của pod tham chiếu đúng claim đó; một secret được cung cấp dưới dạng tệp được mount từ một volume của pod tên là <release name>-secret-<slot>, với slot được viết bằng bảng chữ cái mà cluster chấp nhận, giống như tên release — nên slot server_certificate được mount từ <release name>-secret-server-zucertificate, và một slot đọc qua kết nối có dấu chấm sau tên kết nối được viết theo cùng cách; serviceName của một StatefulSet là tên của Service headless mà nó phát ra; và một Workload chỉ được mở ra qua tên ngoài phát ra một Service mang tên release. Vì vậy component api phát ra Deployment api và Service default là api-default, còn component my_api phát ra my-zuapi và my-zuapi-default — những tên cluster chấp nhận, trong khi định danh như đã viết thì không. Một Recipe công bố địa chỉ của một trong các Service đó sẽ dựng địa chỉ từ {{ .context.rendered_name }}, như ../templates/rendered-resource-names.md minh họa; với một component có tên không chứa dấu gạch dưới và chữ hoa, tên release bằng instance_id của nó, nên các tên của nó đọc đúng như định danh. Một workload do một phần đính kèm Feature tổng hợp là ngoại lệ duy nhất: nó được đặt theo định danh tổng hợp của chính phần đính kèm — giá trị mà nhãn aggrega.ai/component-id của nó mang — vì phần đính kèm render dựa trên component chủ của nó, và một tên release suy ra ở đó sẽ đặt tên workload của phần đính kèm theo component chủ và xung đột với workload của chính component chủ. Định danh đó không bao giờ chứa chữ hoa: một chữ hoa trong tên của component chủ hoặc của phần đính kèm được viết dưới dạng thoát, như mọi ký tự khác mà tên tài nguyên từ chối, nên phần đính kèm worker trên component myApi phát ra Deployment cfr--my-zx000041pi--worker và Service default là cfr--my-zx000041pi--worker-default, và mỗi tên mà workload mang đều là tên cluster chấp nhận.
Độ dài tên phụ thuộc vào Workload. Hai trong số các tên này bị cluster giới hạn theo mức riêng, và build kiểm tra cả hai ngay khi Workload được phân giải thay vì để cluster từ chối vào lúc áp dụng. Tên CronJob dài tối đa 52 ký tự, ngắn hơn các tên khác của cluster vì controller đặt tên Job của mỗi lần chạy theo CronJob kèm một hậu tố được nối thêm; tên này chỉ được kiểm tra với một Workload scheduled. Mỗi tên Service, <release name>-<service key>, dài tối đa 63 ký tự. Khi vượt quá một trong hai giới hạn, điều gì xảy ra phụ thuộc vào ai đã viết tên đó, giống hệt như với tên release: một tên component do bạn viết sẽ bị từ chối, build dừng tại khóa spec.components mà bạn đã viết, kèm loại tên, độ dài của nó và ngân sách mà tên của bạn có — xem ../errors/fatal-halts.md “The target will not accept a name derived from an authored identity (Target sẽ không chấp nhận một tên được suy ra từ một định danh do tác giả viết)”; một định danh được ghép, chẳng hạn định danh mà workload của một attachment Feature được đặt tên theo, sẽ được rút ngắn cho đến khi mọi tên đều vừa. Một tên Service được tạo từ tên component của bạn và một khóa mà workload khai báo — trong Recipe, hoặc trong một FeatureRecipe — nên một lần từ chối sẽ nêu khóa đó và nơi workload khai báo nó, spec.workload.services.<key>; một khóa không chừa chỗ cho bất kỳ tên component nào thì chính nó phải được rút ngắn. Vì vậy, một component mang một Workload scheduled có thể có tên đã mã hóa dài tới 52 ký tự, và một component web có thể mang các khóa Service dài tới 59 ký tự. Một Feature được gắn vào toàn bộ một boundary có định danh được xác định trước khi Workload của nó được phân giải, vì nơi đầu ra của nó được lắp ráp có thể phụ thuộc vào định danh đó, nên không giới hạn nào được kiểm tra cho các tài nguyên mà nó tổng hợp.
Mỗi tài nguyên được phát ra mang đầy đủ các nhãn và chú thích nguồn gốc của Aggrega cùng một cặp selector (app: <instance_id>) nối giữa Deployment/StatefulSet và các Service của nó. Giá trị nhãn chấp nhận định danh như đã viết, nên selector giữ nguyên nó trong khi các tên nêu trên dùng tên release. Tên container trong Deployment được render là các khóa container của Workload với các ký tự . và _ được thay bằng - (làm sạch tên theo Kubernetes).
Giao thức truyền của cổng. Một cổng container khai báo giao thức truyền sẽ phát ra nó nguyên văn dưới dạng protocol: trên containerPort được render, và mọi cổng Service nêu tên cổng container đó đều mang cùng giá trị — giao thức truyền được khai báo một lần, trên cổng container, nên phần mở ra không thể mâu thuẫn với nó. Một cổng không khai báo giao thức truyền không phát ra khóa protocol trên tài nguyên nào, để mặc định của cluster có hiệu lực. Cả ba giá trị mà Workload chấp nhận (TCP, UDP, SCTP) đều được phát ra nguyên văn; helm không cần hạ cấp, vì Kubernetes biểu đạt trực tiếp từng giá trị.
Chạy trên mạng của nút. Một Workload khai báo hostNetwork: true phát ra hostNetwork: true trên pod spec được render, nên pod chạy trong network namespace của chính nút và các cổng mà container của nó mở có thể truy cập trên các địa chỉ của nút. Kubernetes biểu đạt trực tiếp lựa chọn này, nên không có gì bị hạ cấp. Khai báo chỉ đến pod spec và không gì khác: nó không thêm, bỏ hay viết lại cổng nào, và các Service được phát ra giống hệt nhau dù có hay không có nó. Một Workload không khai báo nó thì hoàn toàn không phát ra khóa hostNetwork.
Lượng tài nguyên. Mọi lượng mà provider sao chép vào manifest đều được phát ra nguyên văn, và mỗi lượng được kiểm tra trước theo dạng lượng mô tả tại Workload → Lượng tài nguyên: các giá trị resources.requests và resources.limits của mỗi container và init container — cpu, memory và mọi tài nguyên mở rộng như nvidia.com/gpu — cùng ephemeral.sizeLimit, persistent.size và persistentTemplate.size của mỗi volume. Việc kiểm tra chạy trên Workload theo kết quả đánh giá của các template của Recipe, nên một giá trị đến qua infra hoặc một tham số Release được xét theo kết quả render của nó. Một giá trị không đúng dạng sẽ dừng bản build với TRANSLATION_ERROR nêu tên nút, đường dẫn của trường trong Workload và giá trị — ví dụ containers.main.resources.requests.cpu: "lots" is not a quantity: it does not begin with a number — trong khi nếu không thì chart sẽ build thành công và bị cluster từ chối khi cài đặt. Một cpu, memory hoặc sizeLimit để trống sẽ bị bỏ khỏi manifest và do đó không được kiểm tra; một giá trị tài nguyên mở rộng hoặc một kích thước persistent để trống vẫn sẽ được phát ra, nên nó bị từ chối. Việc kiểm tra chỉ xét dạng: cluster có thể lập lịch cho lượng đó hay không là điều provider không thể biết lúc build.
Việc đặt tên tệp đầu ra có hai dạng. Đối tượng controller được đặt tên theo tên release và kind của nó — <release name>-deployment.yaml, <release name>-statefulset.yaml, <release name>-daemonset.yaml, <release name>-job.yaml, <release name>-cronjob.yaml. Một tệp theo từng tài nguyên được đặt tên theo tài nguyên mà nó chứa, với kind ở cuối: <release name>-<svcName>-service.yaml và <release name>-<volName>-pvc.yaml, mỗi tên lấy từ metadata.name của chính tài nguyên đó theo quy ước đặt tên tổng hợp tại entities/workload.md. Một Workload chỉ được mở ra qua tên ngoài phát ra <release name>-service.yaml, vì không có khóa service nào để mang theo.
Render facts
Bên cạnh các tệp mà nó render, Provider này báo cáo bốn render facts về mỗi node: những gì các tài liệu Kubernetes mà nó phát ra nói về pod, selector, cổng của chúng và namespace mà mỗi tài liệu được phát ra vào. Một FeatureRecipe gắn vào component đọc các facts của chính component đó tại .context.render_facts; một FeatureRecipe đặt readsCallerRenderFacts: true còn đọc, trên mỗi mục của .context.used_by, các facts của một component kết nối tới host của nó, và một FeatureRecipe đặt readsTargetRenderFacts: true đọc, trên mỗi mục của .context.uses, các facts của một component mà host của nó được nối tới. Đó là cách một Feature có thể chỉ định các pod của những component gọi host của nó, hoặc của những component mà host của nó kết nối tới — chẳng hạn một network policy chỉ cho phép đúng những pod đó — dựa trên những gì các lần render của chúng thực sự đã phát ra, mà không ai phải viết lại một label bằng tay. Các tên và các mục dưới đây là hợp đồng của Provider này.
| Fact | Một mục cho mỗi | Mỗi mục chứa |
|---|---|---|
pod_template_labels | pod template được phát ra: spec.template của một Deployment, StatefulSet, DaemonSet, ReplicaSet hoặc Job, job template của một CronJob, và một Pod trần, vốn là template của chính nó | kind, name và namespace của tài nguyên chứa template; labels, các label của template |
controller_selectors | Deployment, StatefulSet, DaemonSet, ReplicaSet, Job và CronJob được phát ra | kind, name, namespace; match_labels, matchLabels của selector của nó |
service_selectors | Service được phát ra | name, namespace; selector, các label mà nó gửi lưu lượng tới |
container_ports | container của một pod template có khai báo danh sách ports, bao gồm cả init container | kind, name và namespace của tài nguyên chứa template; container, tên của container; ports, một mục cho mỗi cổng với name, container_port và protocol của nó |
Cách đọc các facts:
- Mỗi fact là một danh sách. Một template luôn duyệt qua một fact, kể cả khi nó chỉ chứa một mục; không có giá trị đơn lẻ nào để đọc riêng.
- Cả bốn, ở mọi lần render. Mỗi fact được báo cáo bất cứ khi nào Provider này render một node, dưới dạng danh sách rỗng khi lần render không phát ra thứ gì mà fact đó mô tả — một component có chart chỉ phát ra một ConfigMap sẽ báo cáo bốn danh sách rỗng. Lần render của một Provider khác không báo cáo tên nào trong số này, và một tên không ai báo cáo sẽ được đọc là không có gì.
- Đọc từ những gì đã được phát ra, trên mọi đường đi. Các facts đến từ các tài liệu mà lần render đã phát ra, bất kể chế độ nào tạo ra chúng: các manifest đã render của một chart, của một Workload được tổng hợp, và các manifest mà tác giả đặt qua
artifacts:, vốn báo cáo đúng những gì các manifest đó chứa. Chúng được đọc trong cùng một lượt, trên cùng các tài liệu, như các tên tài nguyên mà Provider này báo cáo cho bước kiểm tra tên trùng lặp của bản build. Các label nguồn gốc của chính một tài nguyên là một phần của những gì nó chứa, nênlabelscủa một Pod trần bao gồm chúng; pod template của một chart hoặc một artifact giữ nguyên các label mà tác giả của nó đã viết. - Các mục có thể đến từ lần render của chính component và từ các lần render của các Features của nó. Một component có thể được render bởi nhiều lần gọi — chẳng hạn một chart và một vị trí đặt
artifacts:— và các danh sách mà một tên nhận được từ các lần gọi đó được gộp thành một, theo thứ tự các lần gọi đã chạy. Trên.context.used_byvà.context.uses, các facts của component ở đầu kia của một kết nối còn gộp cả những gì các Features gắn vào nó đã render, sau phần của chính nó;.context.render_factschỉ chứa lần render của chính component. - Theo thứ tự được phát ra. Các mục tuân theo thứ tự mà lần render đã phát ra các tài nguyên. Một label map là một map có khóa như mọi map khác trong context, nên một template duyệt qua nó sẽ gặp các khóa theo thứ tự khóa.
- Những gì tài liệu bỏ qua, mục của nó cũng bỏ qua. Một tài nguyên được đặt tên bằng
generateNamekhông cóname; một tài nguyên không viếtmetadata.namespacekhông cónamespace, và tài nguyên viết nó rỗng hoặc null cũng không có, vì như vậy cũng không chỉ định namespace nào; một controller được viết không cómatchLabels— một Job dựa vào selector mà cluster tạo ra — không cómatch_labels; một Service không có selector thì không cóselector; một cổng không có tên hoặc protocol thì không có cả hai. Bất kỳ phần nào khác được viết rỗng sẽ được báo cáo là rỗng.protocolchỉ được báo cáo khi tài liệu có viết, nên một template cần nó sẽ tự viết giá trị mặc định của cluster,TCP.container_portlà một số ở bất cứ đâu tài liệu có viết nó. namespacelà namespace mà tài liệu viết, không bao giờ là phỏng đoán. Đó làmetadata.namespacecủa chính tài nguyên — với một pod template, là của tài nguyên chứa nó, cũng là nơi các pod của nó chạy; một namespace được viết bên trong chính pod template sẽ không được đọc. Một Workload được tổng hợp viết namespace mà boundary của nó khai báo trên mọi tài nguyên nó phát ra, nên các mục của nó mang namespace đó. Các mục của một chart mang những gì các tài liệu được phát ra của nó viết: nơi một boundary khai báo một namespace thì là namespace đó — dù các template của chart chiếu nó ra hay Provider đặt tài nguyên vào đó (xem Chế độ sourced) — trừ khi một template cố định một namespace riêng, khi đó mục sẽ mang namespace này; nơi không khai báo namespace nào thì là release namespace,default, nơi các template chiếu nó ra, và không có gì nơi chúng không viết namespace nào. Nơi không có gì được viết, mục sẽ không mangnamespacethay vì giá trị mặc định của boundary hay của cluster, vì một tài nguyên như vậy sẽ nằm ở bất cứ đâu công cụ áp dụng đầu ra đặt nó, điều không thể biết khi bản build chạy. Một template phân biệt hai trường hợp bằngoptional:{{ optional . "namespace" "" }}rỗng đúng khi tài liệu không viết namespace nào, nên một Feature đặt thứ gì đó cạnh các pod của một component có thể phân biệt component mà namespace của các pod đã biết với component chưa biết.- Nhận diện theo kind và API group.
PodvàServiceđược đọc trong core group, bốn controller trongapps,JobvàCronJobtrongbatch, ở bất kỳ phiên bản nào của group. Một custom resource thuộc group khác tình cờ mang một trong các tên kind này sẽ không được đọc như vậy.matchExpressionscủa một selector không được báo cáo, và một tài nguyên được bọc bên trong tài liệukind: Listhay một giá trị được viết qua YAML merge key cũng vậy.
Những gì các facts không thấy được. Chúng mô tả các tài liệu mà bản build phát ra, và không có gì mà cluster tạo ra sau đó. Các pod mà một controller tạo ra lúc chạy từ một custom resource — chẳng hạn một database cluster của một operator — không xuất hiện trong tài liệu nào được phát ra, nên chúng vắng mặt theo cấu trúc; bất kỳ label nào mà một mutating admission controller thêm vào khi các manifest được áp dụng cũng vậy. Một Feature cần cho phép các pod như vậy sẽ lấy label của chúng từ tài liệu riêng của custom resource, như một tác giả sẽ làm khi không có các facts này.
Một FeatureRecipe chỉ cho phép vào các pod của host đúng những pod của các component gọi nó, chọn các pod của chính host bằng selector controller của host:
apiVersion: aggrega.ai/v1beta1kind: FeatureRecipemetadata: name: admit-callers version: 1.0.0spec: capability: helm implements: example/admit-callers:1.0.0 readsCallerRenderFacts: true artifacts: allow-callers.yaml: | apiVersion: networking.k8s.io/v1 kind: NetworkPolicy metadata: name: {{ .context.rendered_name }}-allow-callers spec: podSelector: matchLabels: {{- range .context.render_facts.controller_selectors }} {{- range $k, $v := .match_labels }} {{ $k }}: {{ toJson $v }} {{- end }} {{- end }} policyTypes: - Ingress ingress: - from: {{- range .context.used_by }} {{- range .render_facts.pod_template_labels }} - podSelector: matchLabels: {{- range $k, $v := .labels }} {{ $k }}: {{ toJson $v }} {{- end }} {{- end }} {{- end }}Với một host api được gọi bởi một component web có Workload do Provider này tổng hợp, policy chọn app: "api" và cho phép một podSelector mang mọi label của pod template của web — cũng là các label mà spec.template.metadata.labels của Deployment được phát ra của nó chứa. Vì FeatureRecipe đặt khóa này, attachment của nó render khi mọi component đã render xong, nên các facts có sẵn bất kể bản build đến api hay web trước; nếu không có khóa, một template đọc render_facts trên .context.used_by sẽ dừng bản build trước khi bất cứ thứ gì được render.
Một podSelector trong from của một policy khớp với các pod trong chính namespace của policy, nên policy ở trên cho phép các caller được phát ra vào namespace mà nó được áp dụng. Một caller có các mục mang namespace khác được cho phép bằng cách ghép podSelector của nó với một namespaceSelector trên label kubernetes.io/metadata.name của namespace đó, label mà Kubernetes đặt trên mọi namespace.
Các đặc điểm riêng của Provider
-
Việc tải chart chỉ dùng các trình xử lý tích hợp sẵn của Helm. Một chart lấy từ kho Helm được tải xuống bằng chính các trình xử lý
httpvàhttpstích hợp sẵn của Helm. Một plugin tải xuống của Helm — dù được cài cho lệnhhelm, hay nằm trong thư mục mà bản build chạy từ đó — không bao giờ được tham chiếu, nên nội dung trong thư mục đó không thể thay đổi cách một chart được tải về. -
Chèn thông tin nguồn gốc. Đường dẫn sourced và đường dẫn synthesized hội tụ về cùng một tập nhãn và annotation; các bản render sourced chèn chúng bằng cách viết lại YAML sau render (sau khi Helm SDK đã render xong), nên tác giả chart không cần truyền các nhãn Aggrega qua template của chính họ.
-
Thứ tự biến môi trường — các mục đọc từ Secret đứng trước. Danh sách
envcủa một container được tổng hợp chứa hai loại mục: mỗi mụcattachmentsđược phân phốias: envđọc giá trị của nó từ một Secret quavalueFrom.secretKeyRef, và mỗi mụcvariablesmang mộtvaluethuần. Provider viết mọi mục đọc từ Secret trước và mọi biến thuần sau chúng, mỗi loại theo thứ tự được khai báo, và liệt kê các nguồnenvFromriêng dướienvFrom. Kubernetes khai triển một tham chiếu$(NAME)trong một giá trịenvtừ các mục được liệt kê trước nó trong cùng container, không bao giờ từ một mục liệt kê sau nó, nên thứ tự này cho phép một biến thuần ghép một giá trị đọc từ Secret bằng tham chiếu trong khi bản thân secret vẫn nằm trong Secret:containers:api:image: "api:1.0"variables:DATABASE_URL: "postgres://app:$(DB_PASSWORD)@db:5432/app"attachments:DB_PASSWORD: { from: db-credentials, as: env }Container được render liệt kê
DB_PASSWORDtrướcDATABASE_URL, nên tiến trình nhận được URL với mật khẩu đã có sẵn. Một biến cũng có thể tham chiếu bất kỳ biến nào được khai báo trước nó, điều này giữ cho thứ tự khai báo có ý nghĩa bên trongvariables. Init container tuân theo cùng thứ tự. Một container đặt một tên vừa là mụcvariablesvừa là mụcattachmentsđược phân phốias: envsẽ dừng bản build thay vì viết cả hai mục, vì khi đó chỉ riêng thứ tự này sẽ quyết định tiến trình thấy giá trị nào (xem A container gives one environment variable two values (Một container gán hai giá trị cho một biến môi trường)). -
Chuỗi kế thừa namespace — hai chế độ tác động đến tài nguyên theo cách khác nhau. Cả hai đều đọc
aggrega.ai/namespacetừ chuỗi kế thừa annotation của boundary, và không chế độ nào tự tạo ra một namespace khi không có boundary nào khai báo. Ở chế độ synthesized, provider viết trực tiếpmetadata.namespace, và bỏ hẳn trường này khi chuỗi kế thừa không cho ra giá trị nào. Ở chế độ sourced, provider cung cấp giá trị làm release namespace của chart —defaultkhi chuỗi kế thừa không cho ra giá trị nào — và chính template của chart quyết định có chiếu nó ra hay không; khi một namespace được khai báo, provider sau đó viết nó vào mọi tài nguyên có namespace mà chart đã render mà không có namespace (xem Sourced mode). Vì vậy khi có namespace được khai báo, cả hai chế độ đều đặt mọi tài nguyên có namespace vào đó — ngoại trừ namespace mà chart tự cố định, và kind mà provider không phân loại được. Khi không có namespace nào được khai báo, chúng khác nhau: một chart chiếu release namespace sẽ đặt tài nguyên của nó vàodefault, trong khi đầu ra synthesized không viết namespace nào, và một chart không viết namespace nào sẽ không đặt chúng vào namespace nào, nên chúng rơi vào nơi công cụ áp dụng manifest đặt chúng. Các chart cục bộ mà các FeatureRecipes của thư viện chuẩn mang theo thay vào đó đọc trực tiếp giá trị của chuỗi kế thừa quavaluesMappingcủa chúng: làm vậy cho phép chúng bỏ trường này khi không có boundary nào khai báo namespace, khớp với đầu ra synthesized, điều mà chỉ riêng release namespace không thể biểu đạt vì nó không bao giờ rỗng.
Ví dụ minh họa
Chế độ sourced — Recipe trỏ tới một chart được vendor:
apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: api-server-helm version: 1.0.0spec: capability: helm implements: core/api-server source: ./vendor/charts/api-server valuesMapping: | image: "{{ .values.image }}" replicaCount: {{ optional .infra `replicas` 2 }} service: type: ClusterIP port: {{ .values.port }} env: LOG_LEVEL: "{{ optional .values `log_level` "info" }}"Chế độ Workload — Recipe khai báo một Workload nội tuyến:
apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: api-server-workload version: 1.0.0spec: capability: helm implements: core/api-server workload: | apiVersion: aggrega.ai/v1beta1 kind: Workload replicas: {{ optional .infra `replicas` 2 }} containers: api: image: "{{ .values.image }}" ports: web: {{ .values.port }} services: svc: type: ClusterIP ports: web: {{ .values.port }}Tham chiếu chéo
entities/recipe.md— bề mặt soạn thảo Recipe và ba loại đầu vào.entities/workload.md— schema của Workload cho chế độ tổng hợp.providers/helm-chart.md— provider anh em, xuất ra khung Helm chart thay vì các manifest phẳng.providers/well-known-annotations.md— các annotation phổ biến mà provider helm áp dụng (aggrega.ai/namespace, v.v.).architecture/16-recipe-input-composition.md— Ma trận năng lực Provider giữa các provider.10-status.md#providers— phân loại mức độ sẵn sàng hiện tại.