Recipe
Vai trò khái niệm của thực thể Recipe (mẫu chuyển đổi do Ops soạn, ánh xạ Developer Intent sang định dạng vật lý) được trình bày trong architecture/04-entity-taxonomy.md. Trang này trình bày bề mặt soạn thảo Recipe — con trỏ (source), bộ ánh xạ (valuesMapping:), hỗ trợ IaC gốc và các ví dụ minh họa.
Kiến trúc Recipe: con trỏ và bộ ánh xạ
Một Recipe đảm nhận đúng hai chức năng:
- Con trỏ (
source): Cho trình biên dịch biết chính xác mã hạ tầng nằm ở đâu. - Bộ ánh xạ (
valuesMapping): Đưa ngữ cảnh trừu tượng của Aggrega vào các biến cụ thể mà mã bên dưới mong đợi. Trường này là một bề mặt Go template duy nhất với ba chế độ soạn thảo — block scalar nội tuyến,$import:tệp, hoặc$import:thư viện — được phân luồng theo hình dạng nội dung. Xem TrườngvaluesMapping— ba chế độ soạn thảo bên dưới.
Vì một Recipe tương ứng nghiêm ngặt 1:1 với một năng lực render, năng lực đó (spec.capability) được khai báo tường minh ở cấp gốc, bảo đảm trình biên dịch Go biết chính xác cần gọi plugin render Wasm hạ nguồn nào.
spec.implements khai báo loại component trong catalog mà Recipe có thể hiện thực. Trình biên dịch dùng nó để kiểm tra các ánh xạ Manifest (implements của một Recipe được ánh xạ phải khớp với loại được ánh xạ) và để gợi ý ứng viên — các recipe được liệt kê trong chẩn đoán thiếu ánh xạ và được xếp đầu trong tính năng hoàn thành của trình soạn thảo. Nó không bao giờ quyết định một bản build: ánh xạ Manifest là lựa chọn triển khai tường minh của người dùng, được ghim trong lockfile. Một Recipe có implements không có phiên bản, chính xác, hoặc là một khoảng tương thích major vẫn chỉ đề xuất chính nó cho một loại; người dùng ghim lựa chọn. FeatureRecipe.spec.implements mang vai trò y hệt cho các loại feature.
A. Schema nguồn do Wasm điều khiển
Để giữ các thiên kiến hiện thực ngoài trình biên dịch, khối source không phải là một tập trường hạ tầng cố định. Trường source hỗ trợ hai định dạng:
- Chuỗi phổ quát (nhanh và gọn): Phù hợp nhất cho đường dẫn cục bộ, artifact OCI và kho Git. Trình biên dịch suy ra phương thức tải từ tiền tố và hậu tố của chuỗi (
./src,https://github.com/example/module.git,oci://...): một URL kết thúc bằng.git, hoặc được viết vớigit://hayssh://, là một kho Git được tải tại nhánh mặc định của nó, và một URLhttps://không chỉ tới kho nào, cũng không chỉ tới chart.tgzhay phân đoạn.yamlnào, sẽ bị từ chối vì không rõ ràng. - Đối tượng có cấu trúc mở: Một từ điển mở (
additionalProperties: true) có các khóa do provider định nghĩa và được đưa vào các template của Recipe dưới dạng.source.*(ví dụ.source.chart). Ý đồ thiết kế là socket WebAssembly của mỗi provider tự định nghĩa và kiểm tra hình dạng nguồn của mình (ví dụregistry/chart/appVersioncho Helm).
Những gì lõi phân giải. Không provider nào kiểm tra các khóa nguồn của riêng mình. Một nguồn được tải được phân giải bởi một định danh dựng sẵn có kind chọn một bộ phân giải — helm-oci-chart, helm-https-chart, compose-https-fragment và git-repository. Một nguồn dự định được tải phải mang kind và url; tọa độ nào khác chọn nội dung tùy thuộc vào kind. Các kind chart và fragment nhận version, và ghim nó đúng như đã viết. git-repository nhận ref — một tag, một nhánh hoặc một commit — và tùy chọn module_subdir, chỉ thư mục bên trong kho là artifact; vì chỉ một commit mới chỉ định nội dung không thể bị trỏ lại, tham chiếu được phân giải lúc khóa và lockfile ghi lại cả tham chiếu đã được viết lẫn commit mà nó phân giải tới. Một module_subdir vượt lên trên kho như đã viết — dấu gạch chéo ngược được tính là dấu phân cách — bị từ chối trước khi bất cứ thứ gì được tải. Kho được lưu trữ từ bản checkout của chính nó: một liên kết tượng trưng mà kho commit được lưu trữ như tệp hoặc thư mục mà nó trỏ tới nếu đích nằm trong kho, còn liên kết dẫn ra ngoài kho sẽ dừng thao tác pull, nêu tên liên kết theo vị trí của nó trong kho. Một nguồn có cấu trúc có url: chỉ một đường dẫn hệ thống tệp thì không được tải: nó được đọc từ đĩa với cùng điều kiện như một chuỗi đường dẫn trần, với url: tương đối được neo vào thư mục chứa tệp entity khai báo nó. Một nguồn có cấu trúc bỏ qua kind/url cũng không được tải, và nếu đã dự định tải thì bản build dừng rõ ràng ở bước duyệt nguồn lúc khóa thay vì âm thầm phân giải thành rỗng. Nội dung luôn được ghim trước; trình biên dịch không bao giờ tải trạng thái runtime trực tiếp.
Những gì được ghim bên cạnh Recipe. Với một nguồn được tải có kind, url, chart, module_subdir, version và ref đều được viết ra thay vì dùng template, aggrega pin ghi digest của những gì nó đã tải vào entity.lock, một tệp trong thư mục riêng của Recipe mà bạn commit bên cạnh nó. Việc ghim là bước của tác giả Recipe, và không cần Release; một thao tác pull trên một Recipe mà lock không ghi lại pin sẽ dừng và nêu tên nó, trừ khi thao tác pull được yêu cầu chạy cùng bước đó. Một bản build so sánh digest đó với digest mà lockfile của Release ghi cho cùng nguồn, và dừng khi hai giá trị không khớp — ngoại trừ nguồn được viết tại một git ref:, có dòng được ghi tại commit mà ref phân giải tới và không được so sánh. Một nguồn được tải có tọa độ được điền từ template thì được ghim theo từng Release, trong lockfile của mỗi Release. Một nguồn chỉ một thư mục hoặc một tệp bên cạnh Recipe thì không được tải: aggrega pin ghi một digest cho mỗi tệp mà nó đóng góp vào nội dung một bản phát hành của Recipe mang theo — mọi tệp trong thư mục của Recipe, đối với nguồn được viết dưới dạng template — và khi lock đã ghi chúng, bản build so sánh nguồn với chúng trước khi provider đọc, dừng lại khi có tệp được thêm, thay đổi hoặc xóa kể từ lúc ghim — với E0305, hoặc trước hết với E0130 khi lockfile của Release, được ghi trước thay đổi, ghi lại Recipe theo những gì nó mang. Một lock không ghi pin cho nguồn như vậy khiến bản build không có gì để so sánh, và một thao tác pull hoặc phát hành không ghim sẽ từ chối nó. Bản thân tệp Recipe không bao giờ bị ghi. aggrega pull mô tả tệp này và cách xử lý từng lần dừng.
spec.capability có thể mang một ghim phiên bản theo các dạng mà implements nhận — chính xác (helm:<version>) hoặc một khoảng caret (helm:^<version>) — để chọn phiên bản nào của plugin provider render Recipe; một ghim mà không phiên bản khả dụng nào thỏa mãn sẽ dừng bản build. Khi không ghim (spec.capability: "helm"), phiên bản khả dụng cao nhất sẽ render nó. Các phiên bản khả dụng là những phiên bản mà aggrega plugin list hiển thị: các provider tích hợp sẵn trong aggrega mang phiên bản của chính trình biên dịch. Ghim không phải là một phần tên của Recipe: một Manifest ánh xạ một Recipe khai báo capability: "compose:1.2.3" thành compose/<name>:<version>, y như một Recipe không ghim, và việc thay đổi ghim không bao giờ đổi tên nó; một giá trị ánh xạ viết ghim vào tên (compose:1.2.3/<name>:<version>) bị từ chối như một tham chiếu recipe sai định dạng (E0095) trước khi bất cứ thứ gì được tra cứu.
Mô hình tư duy: spec.capability chỉ định định dạng đầu ra bạn muốn (ví dụ helm, terraform, compose); trình biên dịch phân giải nó thành plugin Wasm render định dạng đó (ví dụ provider/helm). Bạn khai báo định dạng; Aggrega gắn công cụ.
B. Chèn ngữ cảnh: tầng ánh xạ ngữ nghĩa
Để ngăn trình biên dịch thực hiện các phép deep-merge nguy hiểm, không tất định trên nhiều môi trường, một Recipe chỉ cho phép một nguồn sự thật duy nhất cho tầng ánh xạ của nó.
Kỹ sư vận hành viết nội dung ánh xạ để chuyển đổi ngữ cảnh trừu tượng trước khi plugin kết xuất Wasm thực thi. Ngôn ngữ ánh xạ là Go template (text/template + Sprig); thư viện Sprig được đăng ký sẵn; các action chuẩn define và template được hỗ trợ, còn include không được đăng ký.
| Tên trường | Phạm vi và giai đoạn thực thi | Trường hợp sử dụng tốt nhất |
|---|---|---|
injectMapping (chỉ FeatureRecipe) | Chặn trước kết xuất. Được đánh giá trong bộ nhớ Go trước Recipe cơ sở. Deep-merge nguyên bản từ điển đầu ra của nó một cách nghiêm ngặt lên trên ống .context.inject của bên gọi. Cố ý không có trong schema Recipe cơ sở — xem entities/featurerecipe để biết lý do kiến trúc. | Viết lại chính xác các biến env được chèn hoặc định dạng FQDN cho một bên gọi mà không cần Wasm JSONPatch. |
valuesMapping | Kết xuất cơ sở (Go template). Được đánh giá để ánh xạ các biến vào chart/module hạ tầng source bên dưới. Một trường duy nhất, ba chế độ viết (inline, file $import:, thư viện $import:). Xem tiểu mục bên dưới về cơ chế phân phối. | Ánh xạ các biến chuẩn (như số bản sao hoặc tag image) vào một Helm chart trực tiếp trong YAML của Recipe, hoặc tham chiếu một template dùng chung qua $import: để tái sử dụng giữa các Recipe. |
Lưu ý: injectMapping chỉ dành cho FeatureRecipes và tách việc chặn biến khỏi valuesMapping. valuesMapping của Recipe cơ sở tiêu thụ các chuỗi .context.inject đã được viết lại do các khối injectMapping của FeatureRecipe tạo ra mà không hề biết điều đó, nên hai phần vẫn tách rời.
Một khóa mà valuesMapping ghi là null sẽ đến provider dưới dạng null, và việc nó làm gì ở đó là do provider quyết định, vì vậy mỗi trang provider đều nêu rõ điều này: helm xóa giá trị mặc định của chart cho khóa đó, helm-chart ghi nó vào values của umbrella, compose ghi nó vào tệp compose, terraform ghi nó thành một đối số module null, và cloudformation từ chối nó.
Trường valuesMapping — ba chế độ viết
valuesMapping: của một Recipe là một bề mặt Go template duy nhất chấp nhận ba chế độ phân phối. Trình biên dịch phân phối dựa trên hình dạng nội dung của trường; không cần chú thích $mode:.
Chế độ 1: Go template inline (YAML block scalar). Giá trị của trường là một chuỗi được viết ở dạng block-scalar | của YAML:
spec: valuesMapping: | {{- with .values -}} image: tag: {{ optional .image `tag` "11.4.4-debian-12-r0" }} pullPolicy: {{ optional .image `pullPolicy` "IfNotPresent" }} architecture: {{ optional . `architecture` "standalone" }} primary: replicaCount: {{ optional .primary `replicaCount` 1 }} {{- end }}Chế độ inline là dạng viết thông thường cho các Recipes có nội dung ánh xạ nhỏ đến trung bình (dưới ~50 dòng). Thân template nằm inline cùng phần còn lại của vỏ Recipe; nội dung của Recipe là tự chứa.
Chế độ 2: File $import:. Giá trị của trường là một map chỉ chứa $import: với một đường dẫn tệp cục bộ:
spec: valuesMapping: $import: ./mappings/api-server.tmplTrình biên dịch tải nội dung của tệp (một Go template), kết xuất template đó với ngữ cảnh template chuẩn của Recipe, và coi kết quả là đầu ra ánh xạ. Đường dẫn được phân giải tương đối theo thư mục của Recipe — đường dẫn tương đối được neo vào thư mục chứa recipe.yaml khai báo nó, không phải thư mục nơi build được gọi — và đường dẫn phải nằm bên trong thư mục đó, như Đường dẫn nội dung nằm bên trong thư mục riêng của Recipe giải thích. Chế độ file phù hợp với nội dung ánh xạ trung bình đến lớn (~50+ dòng) và các quy trình review mà thay đổi ánh xạ hiện thành diff của một tệp riêng.
Chế độ 3: Thư viện $import:. Giá trị của trường là một map chỉ chứa $import: với một tham chiếu định danh dạng tên trần tới một mục của MappingLibrary:
spec: valuesMapping: $import: DatastoreHelpers#/mappings/MariaDBCoreTrình biên dịch phân giải tham chiếu dựa trên tập MappingLibrary đã phân giải (catalog cục bộ cộng với mọi thư viện được ghim trong lockfile), tải nội dung của mục, và coi đó là đầu ra ánh xạ; một mục có thân tự nó là một $import: ở gốc trường sẽ được phân giải đệ quy. Tham chiếu không mang host registry — tên thư viện được phân giải theo định danh và phiên bản lấy từ lockfile của từng Release, với một mức sàn phiên bản tối thiểu tùy chọn :<version> (<Library>:<version>#/mappings/<entry>). Nội dung thư viện dùng chung ngữ cảnh template chuẩn của Recipe. Chế độ thư viện phù hợp để tái sử dụng giữa các Recipe — các mẫu ánh xạ lặp lại trên nhiều Recipes (nhiều Recipes kho dữ liệu dùng chung logic helper kho dữ liệu; nhiều Recipes của provider Helm dùng chung các mẫu pod-template). Thực thể MappingLibrary cung cấp quản lý phiên bản, ghim trong lockfile và hiển thị trên hub-UI.
Quy tắc phân phối. Trình biên dịch duyệt nút YAML và phân phối theo hình dạng nội dung:
- Nếu nút là một string scalar, phân phối theo chế độ inline (Chế độ 1).
- Nếu không, nút là một map; kiểm tra khóa
$import:. - Nếu giá trị
$import:là một tham chiếu thư viện dạng tên trần (<Library>#/mappings/<Entry>, tùy chọn kèm mức sàn:<version>), phân phối theo chế độ thư viện (Chế độ 3). - Nếu không (một đường dẫn tệp cục bộ), phân phối theo chế độ file (Chế độ 2).
- Mọi hình dạng khác (một map không có
$import:, một map có thêm khóa ngoài$import:, v.v.) đều gây lỗi lúc build.
Chỉ $import: một nguồn. $import: chấp nhận một nguồn duy nhất. Hợp nhất nhiều nguồn không được hỗ trợ tại valuesMapping:. Một Recipe cần ghép nhiều mảnh ánh xạ sẽ dùng một mục MappingLibrary với cách ghép nội bộ bằng Go template define / template, một tệp cục bộ với các chỉ thị Go template template gọi các tệp cùng cấp, hoặc ghép inline cho nội dung ngắn. Xem entities/mappinglibrary về thực thể thư viện, vocabulary/cross-document-ref về sự phân biệt rộng hơn giữa $ref: / $import:.
Nguồn gốc. Thông báo lỗi từ các lần kết xuất template thất bại trích dẫn nguồn gốc phù hợp theo từng chế độ: template inline trích dẫn file:line của Recipe nơi block scalar bắt đầu; file import trích dẫn nội dung của tệp được import; library import trích dẫn vị trí nguồn của mục MappingLibrary, với định danh thư viện không có host (<Library>#/mappings/<entry>) làm con trỏ chuẩn cho các tham chiếu ổn định — host registry trong một tham chiếu bị từ chối, nên vị trí vật lý không bao giờ đi vào con trỏ.
C. Hỗ trợ IaC nguyên bản
Một nhóm Ops mang theo hạ tầng dưới dạng mã của riêng mình sẽ giữ nó trong thư mục riêng của Recipe — một thư mục module hoặc template như ./src, được chỉ định bởi source: — hoặc tải nó bằng một source: có cấu trúc (một module Terraform từ kho git của nó, với kind: git-repository), hoặc viết nó dưới dạng các thân có template dưới artifacts:. Lớp ánh xạ (valuesMapping: — inline, import tệp hoặc import thư viện) cung cấp ngữ cảnh trừu tượng cho mã đó, và provider xuất kết quả theo định dạng riêng của đích; không ngôn ngữ cấu hình nào bị chuyển thành ngôn ngữ khác:
- Terraform: một module được vendor từng tệp một, và một thân do tác giả viết được xuất ra đúng như đã viết, dù là HCL gốc (
main.tf) hay Terraform JSON (.tf.json) — CLIterraformđọc được cả hai. Cấu hình gốc của boundary,aggrega.modules.tf, gọi thư mục của mỗi component như một khốimodule, và đầu ravaluesMapping:của một module lấy từ nguồn trở thành các đối số của khối đó. Xem provider terraform. - CloudFormation: một template lấy từ nguồn, YAML hoặc JSON, và các mảnh tài nguyên mà một Recipe viết được chuẩn hóa thành JSON dạng dài và hợp nhất thành một template stack cho mỗi boundary, với đầu ra
valuesMapping:điền các tham số mà template lấy từ nguồn khai báo. Xem provider cloudformation.
Một giá trị chỉ tồn tại sau khi hạ tầng được áp dụng vẫn là một con trỏ mà đích phân giải — một phép nội suy Terraform ${ ... }, một Ref hay Fn::GetAtt của CloudFormation — và không bao giờ được đánh giá lúc build.
Ví dụ A: Helm chart từ xa (ánh xạ inline và hợp đồng locals)
apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: mariadb-chart version: 1.0.0spec: capability: helm implements: core/datastore/mariadb:1.0.0 source: # The shipped fetch form: { kind, url, version }. 'kind' selects a built-in # resolver (helm-oci-chart, helm-https-chart, compose-https-fragment). kind: helm-oci-chart url: oci://registry-1.docker.io/bitnamicharts/mariadb # Default chart version. Override via infra.source_version. version: "{{ optional .infra `source_version` \"25.0.8\" }}"
locals: primary_compute: mariadb listen_port: "3306" volumes_path: "/spec/template/spec/volumes" root_path: "/-" # The Base Recipe EXPLICITLY dictates the physical secret name to the Wasm # pipeline: the suffix it follows the rendered name with. A local cannot read # .context.rendered_name, so each template writing the full name joins the two. secret_target_db_password: "mariadb-auth"
provides: # The chart's primary Service, named by the fullnameOverride pinned below host: "{{ .context.rendered_name }}" port: "3306" # Every key the Component's provides contract declares is published user: "{{ .values.user }}" database: "{{ .values.database }}" protocol: "mariadb"
valuesMapping: | fullnameOverride: "{{ .context.rendered_name }}" auth: # Reads the suffix from the local rather than restating it, so the secret # name is authored once and every reader follows that one definition existingSecret: "{{ .context.rendered_name }}-{{ .locals.secret_target_db_password }}" primary: persistence: size: "{{ .infra.storage.size }}"Ví dụ B: Module Terraform cục bộ (ánh xạ bằng tệp)
apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: aws-s3-tf version: 1.0.0spec: capability: terraform implements: aws/s3-bucket:1.0.0 source: "./src"
locals: primary_compute: bucket_instance resource_path: "/resource/aws_s3_bucket/main" root_path: "/data"
# Guaranteeing global uniqueness across multiple AWS environments valuesMapping: | bucket_name: "{{ .metadata.release_name }}-{{ .context.instance_id }}-data" region: "{{ .infra.aws_region }}"Ví dụ C: Recipe cụ thể cho Component (gắn kết hạ tầng)
Ops ánh xạ giao diện chung vào thực tế vật lý. (Đây là nơi các chi tiết mạng L4 được gắn kết — hoặc được mã hóa cứng, hoặc, như cổng proxy bên dưới, lấy từ khối infra mà Release điền vào.)
apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: kong-gateway version: 1.0.0spec: capability: helm implements: core/gateway/kong:1.0.0 source: # A chart repository root paired with the chart's name. kind: helm-https-chart url: https://charts.konghq.com chart: kong version: "{{ optional .infra `source_version` \"3.4.1\" }}"
provides: # The chart's proxy Service: it suffixes the name pinned below with "-proxy" host: "{{ .context.rendered_name }}-proxy" port: "{{ .infra.proxy_port }}" protocol: "http" # The contract's other keys: empty while nothing is wired to the models # socket, and while metrics are off endpoint: '{{ with optional .values "model" "" }}http://{{ $.context.rendered_name }}-proxy:{{ $.infra.proxy_port }}/{{ . }}/v1{{ end }}' model: '{{ optional .values "model" "" }}' metrics_endpoint: '{{ if .values.metrics_enabled }}http://{{ .context.rendered_name }}-status:8100/metrics{{ end }}'
valuesMapping: | fullnameOverride: "{{ .context.rendered_name }}"Kỷ luật đặt tên tài nguyên đám mây.
Các Recipes phát sinh tên tài nguyên đám mây — tên bucket S3, định danh cơ sở dữ liệu RDS, tên vai trò IAM, tên stack CloudFormation, và bất kỳ trường nào khác có giá trị chiếm một không gian tên toàn cục tại nhà cung cấp đám mây — phải ghép {{ .metadata.release_name }} và/hoặc {{ .context.instance_id }} vào tên được kết xuất để tránh xung đột khi cùng một Recipe chạy trên nhiều Releases hoặc nhiều thể hiện component. bucket_name: "{{ .metadata.release_name }}-{{ .context.instance_id }}-data" của Ví dụ B là mẫu chuẩn.
Kỷ luật này áp dụng ở bất cứ đâu một không gian tên toàn cục duy nhất ràng buộc tên. Tên bucket AWS S3 dùng chung một không gian tên toàn cục trên mọi tài khoản trong một vùng; hai Releases của cùng một Aggregate (prod-billing và staging-billing) không thể cùng triển khai bucket tên customer-data — lần triển khai thứ hai thất bại lúc chạy do AWS từ chối. Ghép release_name giúp phân biệt Release; ghép context.instance_id giúp phân biệt theo từng thể hiện component; ghép cả hai giúp phân biệt theo từng component trên từng Release.
Những gì trình biên dịch kiểm tra và không kiểm tra. Trình biên dịch không kiểm tra đầu ra của valuesMapping: để tìm các trường tên tài nguyên đám mây thiếu các phép nội suy này. Kỷ luật này được duy trì bởi tác giả Recipe (những người biết trường nào đặt tên cho tài nguyên duy nhất toàn cục đối với provider đích) và người review (những người phát hiện các mẫu tài nguyên chưa được đặt tên khi review PR). Một plugin linter có thể đánh dấu các Recipes mà đầu ra valuesMapping: tham chiếu tới trường tên tài nguyên đám mây mà không nội suy release_name / instance_id; socket linter đã có và chạy qua aggrega lint (xem plugins/plugin-contract.md “Placement criterion: the linter socket vs the governance verdict roles”), và không quy tắc nào của linter xuất bản kiểm tra điều này.
Kỷ luật này là một trong số các khế ước xã hội được duy trì bằng quy ước — kỷ luật soạn thảo mà tác giả học từ tài liệu chứ không phải từ sự cưỡng chế của trình biên dịch. Xem vocabulary/social-contracts.md để biết danh sách đầy đủ các quy ước và lý do kiến trúc cho cách phân loại từng khế ước.
Tạo mẫu cho trường source.
Trường source của một Recipe tự nó cũng là một bề mặt tạo mẫu. Cả hai dạng của source đều chấp nhận Go template: dạng chuỗi phổ quát
source: "{{ optional .infra `module_path` \"./src\" }}"và dạng đối tượng có cấu trúc (mỗi trường con có giá trị chuỗi được đánh giá như template; các trường con không phải chuỗi được giữ nguyên). Những gì một template source có thể đọc phụ thuộc vào việc source có chỉ định một artifact từ xa hay không. Tọa độ của một source từ xa — version, chart, ref và module_subdir của một khối có cấu trúc chỉ định một registry, một kho chart hoặc một kho git — được đánh giá khi aggrega pull phân giải artifact để ghim nó, chỉ dựa trên .values, .infra và .locals, với các hàm trợ giúp riêng của Aggrega (optional, capitalizedWords và index) và không có hàm nào của Sprig. .context không có trên bề mặt đó, nên artifact nào được ghim cho một component được quyết định bởi các giá trị và infra mà nó được cấp, và không bao giờ bởi tên instance của nó. Các mục locals: được đánh giá ở đó là những mục mà các trường ấy đọc, và những mục mà một mục như vậy lại đọc tiếp: một mục không được trường source nào đọc thì không được đánh giá khi source được phân giải, nên một local chỉ cần cho quá trình render — một local gọi hàm Sprig, hoặc đọc .context.instance_id — không ảnh hưởng đến việc ghim, và được đánh giá khi node render. Một trường đọc .locals theo cách không chỉ định một mục cụ thể nào, chẳng hạn {{ index .locals "version" }}, sẽ khiến mọi mục đều được đánh giá. Một source chỉ định một đường dẫn trong workspace, như ví dụ ở trên, không được phân giải để ghim: template của nó được đánh giá khi node render, dựa trên cùng ngữ cảnh tự chứa như Recipe locals — .context.instance_id, .values, .infra, và .locals, toàn bộ khối đã phân giải của node — nên nó chấp nhận và từ chối cùng các gốc tham chiếu như một mục locals:, với một khác biệt có lợi cho nó: nó có thể đọc bất kỳ mục nào mà khối khai báo, không chỉ các mục nằm phía trên nó. Một tọa độ từ xa cũng có thể đọc bất kỳ mục nào mà khối khai báo. .provides không có trong ngữ cảnh nào, và một template source tìm cách truy cập provides của chính node của nó sẽ dừng build và nêu tên tham chiếu vi phạm. Đó là một thuộc tính cố định của bề mặt chứ không phải một khoảng trống chờ công việc sau này — các locals của một node được phân giải trước provides của nó để provides: có thể đọc .locals, và một template source đọc chính các locals đã phân giải đó thay vì vươn tới provides. Các tham chiếu đến .context.inject và .context.uses bị cấm vì cùng lý do tự chứa; URI của source phải được phân giải trước khi pipe topology được hydrate và trước khi bất cứ thứ gì phía sau tải phần thân chart, module hoặc artifact mà URI trỏ tới. Các quy tắc đầy đủ về tính khả dụng và lý do cấm tham chiếu nằm ở Template Expansion Matrix hàng #5. Cách dùng chuẩn là một override infra.source_version do Component phơi ra được truyền vào trường version của source — xem entities/component “The infra Pillar” — để một catalog không cần phát hành lại một Recipe mỗi khi có lần nâng phiên bản upstream tương thích.
Danh mục scheme của trường source. Trường source: chấp nhận một số biến thể hình dạng trong schema. Mức hỗ trợ lúc chạy của mỗi biến thể khác nhau theo provider; bảng dưới đây ghi lại tác dụng của từng hình dạng.
| Hình dạng | Ví dụ | Trạng thái |
|---|---|---|
| Đường dẫn hệ thống tệp tương đối dạng thuần | source: "./charts/postgres" | available — mọi provider đã phát hành (helm, helm-chart, compose, terraform, cloudformation) đều chấp nhận một chuỗi đường dẫn hệ thống tệp thuần. |
| Đường dẫn hệ thống tệp tuyệt đối dạng thuần | source: "/abs/path/to/chart" | accepted but blocked — schema chấp nhận nó và mọi lệnh đọc Recipe đều từ chối nó: một đường dẫn tuyệt đối chỉ tới một vị trí trên máy nơi nó được viết chứ không phải nội dung bên trong thư mục riêng của Recipe, nên nó sẽ không đi cùng Recipe. Hãy chuyển chart vào thư mục của Recipe và đặt tên tương đối với thư mục đó; xem Đường dẫn nội dung nằm trong thư mục riêng của Recipe. |
| Chuỗi rỗng | source: "" | accepted but blocked — schema chấp nhận chuỗi rỗng và mọi lệnh tải Recipe đều từ chối nó ngay khi Recipe được đọc, vì một chuỗi rỗng không chỉ định chế độ nào. Lời từ chối nêu sự mơ hồ cùng hai lối ra: bỏ trường để dùng chế độ không source, hoặc cung cấp một đường dẫn hay URI thực để dùng chế độ có source. aggrega validate <recipe-file> báo lỗi này cho Recipe, còn aggrega pull, aggrega build và aggrega validate --release báo lỗi này cho một Release chạm tới Recipe. Xem errors/fatal-halts.md “Recipe source: is an empty string (source: của Recipe là một chuỗi rỗng)”. |
Đối tượng có cấu trúc mà url: mang một scheme truyền tải | source: { url: "oci://…/mariadb", version: "25.0.8" } | available — source-resolver tích hợp sẵn đọc dạng {kind, url, version, chart, ref, module_subdir} (scheme của url: chọn kind — oci:// → chart OCI, https://….tgz → kho lưu trữ chart, gốc repo https:// đi kèm chart: → chart trong repo — hoặc đặt tên kind bằng kind:), tải về và ghim artifact khi chạy aggrega pull, rồi bản build trích xuất nó từ bộ nhớ đệm. Việc vendor một chart cục bộ được hỗ trợ như một phương án thay thế, và không bắt buộc. Schema chấp nhận một đối tượng có cấu trúc mở. Xem providers/helm.md “Bộ khóa source:”. |
Đối tượng có cấu trúc mà url: chỉ tới một đường dẫn hệ thống tệp | source: { kind: helm-oci-chart, url: "./charts/postgres", version: "1.0.0" } | available — một url: không mang lược đồ truyền tải sẽ chỉ định một đường dẫn, nên không có gì được tải về và không có gì được ghim; bản dựng đọc nội dung từ đĩa. Một url: tương đối được neo vào thư mục chứa recipe.yaml khai báo nó, và một đường dẫn rời khỏi thư mục đó — kể cả đường dẫn tuyệt đối — sẽ bị từ chối: đây là cách đọc giống như hai hàng đường dẫn trần ở trên, và hình dạng bạn dùng để viết nó không làm thay đổi điều đó. Chỉ có url: quyết định nội dung được đọc từ đâu; các trường khác chọn những gì sẽ được tải về, và vẫn đến được các template của Recipe dưới dạng .source.*. |
URI OCI (oci://...) | source: "oci://hub.aggrega.ai/recipe/helm/postgres:1.0.0" | planned — mục tiêu thiết kế cho việc phân phối catalog. Bộ phân giải ba tầng hiện nay (các tệp mà một Release nêu theo đường dẫn, catalog của workspace, registry OCI từ xa) được mô tả tại architecture/13-catalog-and-registry.md; bộ phân giải cấp thực thể tiêu thụ URI OCI qua chuỗi tầng đó, nhưng dạng OCI của trường source: theo từng Recipe hiện chưa được nối vào các provider. |
Các scheme URL khác (https://, git+https://, v.v.) | (minh họa) | planned — được ghi nhận là ý định thiết kế trong lộ trình nguồn có thể cắm thêm của kiến trúc; hiện chưa có provider nào hỗ trợ. |
Cách một đường dẫn source: được neo.
Việc neo chỉ áp dụng cho đường dẫn hệ thống tệp, và áp dụng bất kể hình dạng nào trong hai hình dạng mang đường dẫn. Một đường dẫn tương đối được neo vào thư mục chứa recipe.yaml khai báo nó, và một đường dẫn rời khỏi thư mục đó — kể cả đường dẫn tuyệt đối — sẽ bị từ chối, như Đường dẫn nội dung nằm trong thư mục riêng của Recipe giải thích. Một tham chiếu mang transport scheme — oci://, https://, http://, git://, ssh://, git+ssh://, hoặc bất kỳ tham chiếu nào kết thúc bằng .git — chỉ tới thứ cần tải về chứ không phải một đường dẫn, nên nó được giữ nguyên đúng như bạn viết và không bao giờ được nối vào một thư mục.
Ở dạng có cấu trúc, đường dẫn là trường url:, và nó được đọc theo cùng một cách: một url: tương đối được neo vào thư mục chứa recipe.yaml, một đường dẫn rời khỏi thư mục đó bị từ chối, và một đường dẫn mang transport scheme thì được tải về. Mọi trường khác của một source: có cấu trúc đều được chuyển qua nguyên vẹn, kể cả các trường do provider định nghĩa.
Một source: được viết dưới dạng template được neo theo giá trị mà template tạo ra, không theo văn bản của chính template. Một template không chỉ tới gì cho đến khi được đánh giá, nên cách đọc ở trên được áp dụng cho kết quả của nó: kết quả là đường dẫn tương đối được neo vào thư mục chứa recipe.yaml, kết quả rời khỏi thư mục đó — kể cả đường dẫn tuyệt đối — làm dừng bản build, và kết quả mang transport scheme được giữ nguyên và tải về. Do đó một template có thể tự do tạo ra bất kỳ hình dạng nào trong bảng liệt kê ở trên, và mỗi hình dạng được xử lý đúng như cùng giá trị đó khi được viết trực tiếp; điểm khác biệt chỉ là thời điểm đường dẫn có thể được đánh giá, mà với template là khi bản build đánh giá nó chứ không phải khi Recipe được đọc.
Một template không tạo ra gì — kết quả rỗng — để lại Recipe không có nguồn, tức là chế độ không nguồn. Điều đó khác với việc bạn tự viết source: "", vốn không chỉ định chế độ nào và bị từ chối; xem hàng tương ứng trong bảng liệt kê ở trên.
Danh mục này là tài liệu tham chiếu chuẩn về những gì tác giả có thể đặt vào source:; các nhãn của nó là những nhãn mà 10-status.md định nghĩa.
Đường dẫn nội dung nằm trong chính thư mục của Recipe
Nội dung của một Recipe nằm trong chính thư mục của Recipe đó, vì mọi tệp mà một bản phát hành của nó mang theo đều được lấy từ đó. Mọi đường dẫn mà một Recipe viết cho nội dung nó mang theo — source: của nó, dù là một đường dẫn trần hay url: của dạng có cấu trúc, và mỗi tệp mà các mục valuesMapping:, workload: và artifacts: của nó nhập bằng $import: — đều được đọc theo thư mục chứa recipe.yaml và phải nằm bên trong thư mục đó. Những đường dẫn đó cũng là thứ mà một bản phát hành mang theo: các tệp chúng chỉ tới đi cùng Recipe, và không có gì khác trong thư mục của nó đi cùng (xem aggrega push). Một đường dẫn rời khỏi thư mục sẽ trỏ tới một tệp không đi cùng Recipe, nên tệp đó không có mặt với bất kỳ ai sử dụng nó, và một pin được ghi lại trên tệp đó sẽ bảo chứng cho những byte mà họ không thể có được.
Có hai dạng rời khỏi thư mục, và cả hai đều bị từ chối:
- một đường dẫn đi lên phía trên thư mục, chẳng hạn
../shared/charts/app; - một đường dẫn tuyệt đối, chẳng hạn
/opt/charts/app, chỉ tới một vị trí trên máy mà nó được viết ra.
Một đường dẫn đi lên rồi quay trở lại bên trong là một đường dẫn bình thường bên trong thư mục: ./charts/../values.tmpl chỉ tới values.tmpl nằm cạnh Recipe. Điều được xét là nơi đường dẫn dừng lại, tính từ thư mục của Recipe mà không rời khỏi nó — vì vậy một đường dẫn đi ra ngoài rồi nêu lại tên thư mục trên đường quay về, chẳng hạn ../1.0.0/values.tmpl được viết trong một thư mục tên là 1.0.0, cũng bị từ chối. Tên của chính thư mục không đi cùng: một Recipe đã phát hành được đọc từ một thư mục do bộ đệm của người sử dụng đặt tên, nơi tên đó không tìm thấy gì.
Nơi nó bị từ chối. Mọi lệnh đọc Recipe đều từ chối một đường dẫn như vậy ngay khi đọc nó, trước khi bất cứ thứ gì được tải về, kết xuất hay phát hành: aggrega validate, trên catalog hoặc trên chính tệp của Recipe, aggrega pull, aggrega build, aggrega pin và aggrega push. Một source: được viết dưới dạng template không chỉ tới gì cho đến khi quá trình build đánh giá nó, nên một template tạo ra đường dẫn nằm ngoài thư mục sẽ bị quá trình build từ chối, vào thời điểm giá trị đó tồn tại. Lỗi dừng là A path names content outside the entity’s own directory (Một đường dẫn chỉ tới nội dung nằm ngoài thư mục của chính thực thể), và nó nêu đường dẫn bạn đã viết.
Nên làm gì thay vào đó. Đặt tệp vào thư mục của Recipe, hoặc vào một thư mục bên dưới nó, và đặt tên tương đối theo Recipe: ./charts/app, ./extras/netpol.yaml. Một chart được nhiều Recipes sử dụng sẽ được sao chép vào thư mục của từng Recipe, vì mỗi Recipe được phát hành riêng; một phần thân mapping, workload hoặc artifact mà nhiều Recipes dùng chung thuộc về một MappingLibrary, WorkloadLibrary hoặc ArtifactLibrary, mà mỗi Recipe tham chiếu theo định danh.
Vì sao một Release lại khác. Một Release trỏ tới các thực thể khác — Aggregate của nó, Manifest của nó, Release mà nó mở rộng — và không bao giờ được phát hành, nên không có gì nó đọc được mang đi đâu cả. Những tham chiếu đó, và tệp mà parameters: của nó nhập, được đọc đúng như đã viết, đó là điều cho phép một Aggregate được dùng chung bởi các biến thể Release trong các thư mục con. Xem entities/release.md.
Giới hạn tương tự cũng áp dụng cho một FeatureRecipe, và cho mọi schema mà một Component hoặc một Feature nhập.
Trường workload: — loại đầu vào tổng hợp
Recipe.spec.workload: khai báo phần thân Workload mà trình biên dịch tổng hợp thành các tài nguyên gốc của provider. Đây là một trong ba loại đầu vào mà một Recipe có thể khai báo, bên cạnh source: (kết xuất từ nguồn) và artifacts: (các manifest phụ trợ). Với mọi provider, phải có ít nhất một trong ba loại; một dịch vụ mà bản build không cấp phát sẽ khai báo một workload: có form: reference.
Trường này chấp nhận ba chế độ soạn thảo — block scalar nội tuyến, $import: tệp, hoặc $import: thư viện. Trình biên dịch phân nhánh theo hình dạng nội dung của trường; không cần chú thích $mode:.
Chế độ 1: Nội tuyến (scalar chuỗi Go template). Giá trị là một block scalar YAML có đầu ra được phân tích thành aggrega.ai/v1beta1 Workload:
spec: capability: helm implements: core/web-server:1.0.0 workload: | apiVersion: aggrega.ai/v1beta1 kind: Workload replicas: {{ optional .infra "replicas" 1 }} containers: app: image: "{{ .values.image }}" ports: http: 8080Các trường của một Workload nằm ở gốc tài liệu — không có lớp bọc spec: — và containers: cùng ports: của mỗi container là các map theo khóa tên thay vì các chuỗi, với thứ tự của tác giả được giữ nguyên. Provider chuyển hình dạng đó thành dạng gốc của riêng nó, nên một mục trong map container xuất hiện trong đầu ra kết xuất của helm dưới dạng một phần tử containers[] được đặt tên theo khóa của nó; hình dạng được soạn là map, không phải danh sách được kết xuất.
Chế độ 2: $import: tệp. Giá trị là một map với một khóa $import: duy nhất trỏ tới một tệp Go template cục bộ:
spec: workload: $import: ./workload/web-server.yaml.tmplViệc phân giải đường dẫn giống như valuesMapping:: một đường dẫn tương đối được neo vào thư mục chứa recipe.yaml khai báo nó, không phải thư mục nơi bản build được gọi, và nó phải nằm bên trong thư mục đó. Phần thân được import là một Go template được đánh giá trong ngữ cảnh kết xuất của Recipe, đúng như một phần thân nội tuyến.
Chế độ 3: $import: thư viện. Giá trị là một map với một khóa $import: duy nhất mang một tham chiếu định danh dạng tên trần tới một mục của WorkloadLibrary:
spec: workload: $import: BaseWorkloads#/workloads/StatelessServiceFragment #/workloads/ là thứ chọn một mục Workload, và chính fragment này phân biệt tham chiếu này với dạng #/mappings/ mà valuesMapping: sử dụng — dạng đó trỏ tới một mục MappingLibrary và không đặt tên cho một phần thân Workload. Tham chiếu không mang host registry, phiên bản được phân giải đến từ lockfile của từng Release, có thể khẳng định một ngưỡng phiên bản tối thiểu :<version> tùy chọn dưới dạng <Library>:<version>#/workloads/<Entry>, và một mục có phần thân tự nó là một $import: ở gốc trường sẽ được phân giải đệ quy. Phần thân được import là một Go template được đánh giá trong ngữ cảnh kết xuất của Recipe sử dụng nó, nên .values, .infra và .features truyền vào nó đúng như vào một phần thân nội tuyến. Xem entities/workloadlibrary về thực thể thư viện và ngữ pháp tham chiếu đầy đủ.
Provider đích phải hỗ trợ tổng hợp (theo quy ước, catalog thư viện chuẩn khai báo workloadSchema trên các provider như vậy); việc nhắm tới một provider không thể tổng hợp bị từ chối khi node được kết xuất, với chẩn đoán về khả năng của provider — dựa trên khả năng của provider, không dựa trên sự hiện diện của workloadSchema. Về ngữ pháp Workload đầy đủ, các trường truyền thẳng theo hình dạng K8s và hành vi chuyển đổi theo từng provider, xem entities/workload.md. Về mô hình ba loại đầu vào rộng hơn và bộ lắp ráp hợp nhất kết quả tổng hợp với đầu ra kết xuất từ nguồn và các artifact, xem architecture/16-recipe-input-composition.md.
Chuyển các giá trị riêng của một thành phần đến image riêng của nhà phát triển. Theo quy ước của catalog thư viện chuẩn, một Recipe chạy image do nhà phát triển build được kỳ vọng sẽ chuyển mọi thứ mà các khối inject: của nhà phát triển đã phân giải, từ .context.inject, và cũng có thể chuyển các giá trị riêng của thành phần dưới những tên do chính nó đặt. Khi Component khai báo spec.inject, chính khối của nhà phát triển sẽ chọn tên, và .context.self_inject cho Recipe biết giá trị riêng duy nhất mà template của mỗi mục đọc — values.<key> đối với một mục chỉ đọc đúng một giá trị riêng và không đọc gì khác. Quy ước của catalog thư viện chuẩn là coi các tên mà một Recipe đặt cho những giá trị đó là tên mặc định chứ không phải là một hợp đồng mà mã của nhà phát triển phải đọc, và chỉ chuyển một giá trị dưới tên mặc định của nó khi không có mục nào ánh xạ tới nó; một catalog doanh nghiệp có thể chọn cách khác. Hợp đồng ngữ cảnh template đưa ra các quy tắc chính xác của map này và một template mẫu hoàn chỉnh.
Trường artifacts: — các manifest phụ trợ
Recipe.spec.artifacts: là một map từ tên mục → phần soạn thân artifact, trong đó mỗi mục phát ra thêm các tệp manifest bên cạnh đầu ra chính được lấy từ nguồn hoặc được tổng hợp của Recipe. Đây là một trong ba loại đầu vào (từ nguồn / tổng hợp / artifacts) — một Recipe có thể chỉ khai báo artifacts:, hoặc khai báo cùng với workload: và/hoặc source:.
Giá trị của mỗi mục mang một trong ba chế độ được phân định theo hình dạng nội dung, song song với workload: — nội dung nội tuyến, một tệp $import:, hoặc một thư viện $import:. Trình biên dịch phân định theo hình dạng nội dung của giá trị; không cần chú thích $mode:. Ở cả ba chế độ, khóa của map đặt tên cho thứ mà mục đó phát ra: với hai chế độ một tệp, đó là tên tệp đầu ra, còn với chế độ gói, đó là thư mục chứa các tệp của gói. Vì khóa đặt tên cho đầu ra, nó bị giới hạn trong những gì một tên tệp đơn lẻ có thể là: một chữ cái hoặc chữ số ở đầu, sau đó là chữ cái, chữ số, dấu chấm, dấu gạch nối và dấu gạch dưới. Dấu chấm giữ được phần mở rộng mà một khóa theo quy ước thường mang — main.tf, template.yaml, serviceaccount.yaml — trong khi bảng ký tự không cho phép /, vốn sẽ khiến một khóa đặt tên cho một đường dẫn thay vì một tệp, và không cho phép . ở đầu, nên một khóa không bao giờ có thể là đoạn thư mục cha. Một khóa nằm ngoài bảng ký tự đó sẽ không vượt qua kiểm tra envelope khi tải workspace, khi chạy aggrega validate, và trong chẩn đoán của trình soạn thảo.
spec: capability: helm implements: core/web-server:1.0.0 artifacts: extra-configmap.yaml: | apiVersion: v1 kind: ConfigMap metadata: name: "{{ .context.instance_id }}-extras" data: threshold: "{{ .values.threshold }}" network-policy.yaml: $import: ./artifacts/network-policy.tmpl operator-support: $import: PlatformArtifacts#/artifacts/OperatorSupportChế độ 1: Nội tuyến (scalar chuỗi Go template). Giá trị là một block scalar, và khóa của map là tên tệp đầu ra, được dùng đúng như đã viết — mục đầu tiên ở trên phát ra extra-configmap.yaml.
Chế độ 2: Tệp $import:. Giá trị là một map với một khóa $import: duy nhất trỏ tới một tệp Go template cục bộ, và khóa của map là tên tệp đầu ra, đúng như ở chế độ 1. Tệp được import cung cấp nội dung; nó không cung cấp tên. Mục thứ hai ở trên có khóa network-policy.yaml và phát ra network-policy.yaml, dù tệp mà nó import có tên là network-policy.tmpl. Vì vậy, tác giả muốn có một tên tệp đầu ra cụ thể thì viết tên đó làm khóa, và hai mục import các tệp khác nhau tình cờ trùng tên — ./extras/shared.yaml và ./overrides/shared.yaml — là hai đầu ra riêng biệt. Việc phân giải đường dẫn giống như valuesMapping: và workload:: một đường dẫn tương đối được neo vào thư mục chứa recipe.yaml khai báo nó, không phải thư mục nơi lệnh build được gọi, và nó phải nằm trong thư mục đó.
Chế độ 3: Thư viện $import:. Giá trị là một map với một khóa $import: duy nhất mang một tham chiếu định danh bằng tên trần tới một gói ArtifactLibrary, <Library>#/artifacts/<name>. Một gói là một tập hợp tệp được import như một đơn vị, nên một mục mở rộng thành một đầu ra cho mỗi tệp trong gói, mỗi đầu ra nằm dưới khóa của map theo dạng <key>/<filename> — khóa đặt tên cho nơi sử dụng và là thư mục chứa các tệp đó, chứ không phải tên của bất kỳ tệp nào trong số đó. Mục thứ ba ở trên có khóa operator-support; nếu PlatformArtifacts#/artifacts/OperatorSupport khai báo crd.yaml và rbac.yaml, thì mục duy nhất đó phát ra operator-support/crd.yaml và operator-support/rbac.yaml. Tham chiếu không mang registry host — dạng có host oci://… bị từ chối — phiên bản được phân giải đến từ lockfile theo từng Release, và có thể khẳng định một mức phiên bản tối thiểu tùy chọn :<version> theo dạng <Library>:<version>#/artifacts/<name>. Xem entities/artifactlibrary để biết về thực thể thư viện và toàn bộ ngữ pháp tham chiếu.
Một tệp $import: được ghim bên cạnh Recipe. aggrega pin ghi lại digest của các byte của mỗi tệp được import vào entity.lock trong thư mục của Recipe, theo khóa của map của mục đó, và aggrega build tính lại digest của tệp và dừng với [CATALOG_ERROR E0026] khi nó không còn khớp — hoặc dừng trước với E0130 khi lockfile của Release, được ghi trước lần chỉnh sửa, ghi nhận Recipe theo những gì nó mang — nên một tệp bị chỉnh sửa sau khi đã được ghim không bao giờ được render mà không qua xác minh. Nếu thay đổi là có chủ ý, hãy chạy aggrega pin trên Recipe để ghi lại digest mới; nếu không, hãy khôi phục tệp. Một mục nội tuyến là một phần của tệp Recipe, và một mục thư viện được ghim theo phiên bản thư viện mà lockfile ghi lại, nên cả hai đều không mang ghim riêng. aggrega pull mô tả tệp này.
Template của mỗi mục artifact được đánh giá với cùng ngữ cảnh template như valuesMapping:, bất kể chế độ nào cung cấp thân của nó. Hai đầu ra mang cùng tên tệp sẽ dừng build khi node được render. Hai mục của cùng một map artifacts: không thể đặt tên cho cùng một đầu ra: một khóa của map là duy nhất trong một tài liệu và biểu thị một tên tệp duy nhất, nên đầu ra của một mục một tệp chính là khóa của nó, và các tệp của một mục gói nằm dưới một thư mục được đặt tên theo khóa của nó — đoạn đầu tiên của mọi đường dẫn mà một mục phát ra là khóa đã tạo ra nó, nên các khóa khác nhau vẫn là các tên đầu ra khác nhau bất kể các tệp được import có tên gì. Điều mà việc dừng bao quát là một tên tệp được đóng góp bởi hai loại đầu vào khác nhau — một template chart và một mục artifact cùng tạo ra servicemonitor.yaml — được báo cáo đối với Recipe đó bằng một chẩn đoán nêu tên mọi nguồn gốc đóng góp.
Trường hợp sử dụng. artifacts: là nơi dành cho các tài nguyên phụ trợ mà chart hoặc module chính không tạo ra: một NetworkPolicy đi kèm một workload, một HPA ghép với một Deployment, một sidecar ConfigMap dựa theo instance_id. Các tài nguyên phụ trợ xuyên suốt áp dụng cho nhiều component (ví dụ một sidecar sao lưu gắn vào mọi datastore) thuộc về Resource Generation của FeatureRecipe thay vì artifacts: theo từng Recipe — xem entities/featurerecipe.md để biết bề mặt mở rộng của FeatureRecipe.
Khối boundary: — các tệp cho đầu ra dùng chung của boundary
Hầu hết các Recipes không bao giờ cần đến khối này. Mọi thứ khác mà một Recipe ghi ra đều thuộc về component của chính nó: provider đặt nó dưới vị trí riêng của component đó trong đầu ra của boundary. Tuy nhiên, một số tệp lại thuộc về toàn bộ boundary — một tệp mà đích đọc một lần cho mọi thứ boundary triển khai. Cấu hình provider của Terraform là trường hợp phổ biến: tài liệu của Terraform giữ các khối provider ngoài một module được cấu hình khác gọi tới, và một module tự mang khối như vậy không thể được gọi với depends_on, count hoặc for_each. spec.boundary.artifacts là nơi một Recipe ghi ra tệp như vậy.
spec: capability: terraform implements: core/api-gateway/azure-api-management:1.0.0 artifacts: main.tf: $import: ./module/main.tf boundary: artifacts: # Terraform reads this beside the root configuration; one copy serves every # component of the boundary that declares it. provider-azurerm.tf: | provider "azurerm" { features {} }Khối này là artifacts: ở một phạm vi thứ hai. artifacts là thành viên duy nhất của nó, và nó có đúng hình dạng của artifacts: riêng của Recipe: cùng ba chế độ — nội dung nội tuyến, một tệp $import:, một thư viện $import: mà các tệp của nó nằm dưới khóa của mục theo dạng <key>/<filename> — cùng quy tắc từ khóa sang tên tệp và cùng bảng ký tự cho khóa, và cùng ngữ cảnh template, nên một mục đọc .values, .infra, .locals và phần còn lại đúng như một mục artifacts: làm. Khối cần ít nhất một mục, và mọi thành viên khác dưới boundary: đều bị từ chối khi Recipe được đọc. Một FeatureRecipe không có khối như vậy.
Tệp được ghi ở đâu. Một lần, trong thư mục chứa đầu ra đã lắp ráp của boundary, bên cạnh các tệp mà phần lắp ráp riêng của provider ghi ở đó — với terraform, là bên cạnh cấu hình gốc aggrega.modules.tf thay vì bên trong module của component. Provider không được giao tệp nào trong số này: compiler tự đánh giá và tự ghi chúng, và không đóng dấu gì vào tệp để cho biết nó đến từ component nào, vì nó thuộc về mọi component đã khai báo nó. Một mục có template render ra rỗng thì không ghi tệp nào.
Nhiều bên đóng góp gặp nhau thế nào. Mỗi mục được đánh giá cho từng component mà Recipe render trong boundary, và các tệp mà mọi bên đóng góp vào boundary khai báo được hợp nhất theo tên. Một tên được đánh giá ra cùng các byte — bởi hai component gắn với một Recipe, hoặc bởi hai Recipes cấu hình một provider giống hệt nhau — là một tệp. Một tên được đánh giá ra các byte khác nhau sẽ dừng build, nêu tên tệp và mọi bên đóng góp, vì không có tệp đơn lẻ nào là thứ tất cả bọn họ đã ghi; một tên mà phần lắp ráp riêng của provider ghi ra, chẳng hạn aggrega.modules.tf, cũng vậy. Cả hai đều là xung đột đầu ra đã lắp ráp. Hai Recipes cấu hình một provider dưới hai tên tệp khác nhau thì không được hợp nhất — mỗi tệp đều được ghi — và khi đó chính đích sẽ báo cấu hình trùng lặp, vì vậy các Recipes muốn dùng chung một cấu hình provider sẽ dùng chung tên tệp của nó, theo quy ước là một tệp được đặt tên theo provider mà nó cấu hình.
Những provider nào chấp nhận khối này. Việc một tệp đặt cạnh đầu ra đã lắp ráp của boundary có ý nghĩa gì hay không là một thuộc tính của đích của provider, nên nó là một phần trong khai báo riêng của provider. Một Recipe khai báo khối này mà provider của nó không chấp nhận sẽ bị từ chối trước khi bất cứ thứ gì được render, bất kể các mục của nó render ra gì; xem The provider does not support boundary artifacts (Provider không hỗ trợ boundary artifacts). Bảng năng lực liệt kê khai báo của từng provider.
| Provider | boundary.artifacts: |
|---|---|
terraform | Được chấp nhận. Mỗi tệp được ghi bên cạnh cấu hình gốc của boundary, mà Terraform đọc cùng với mọi tệp cấu hình khác trong thư mục đó. |
helm, compose, helm-chart, cloudformation | Bị từ chối trước khi bất cứ thứ gì được render. |
Một tệp $import: ở đây được ghim giống như một tệp mà một mục artifacts: import. Entity lock ghi lại digest của nó trong cùng danh sách artifactDigests, dưới boundary/<key> thay vì chỉ dưới khóa, nên mục của mỗi khối được viết dưới cùng một khóa được ghim riêng biệt. Bước pin ghi lại nó, một lệnh pull không pin sẽ dừng khi ghim của nó bị thiếu hoặc không còn khớp, và một lệnh build từ chối một tệp bị chỉnh sửa kể từ khi được ghim, đúng như cách nó từ chối một tệp artifacts:.
Trường outputLabels: — các nhãn do tác giả khai báo trên đầu ra được kết xuất
Recipe.spec.outputLabels: là một ánh xạ từ khóa nhãn → giá trị mà provider gắn lên mọi đối tượng do đầu ra kết xuất của Recipe tạo ra. Đây là nơi đúng đắn cho một đặc điểm hiện thực hóa — một thuộc tính về cách một Recipe cụ thể hiện thực hóa một component, khác với việc component đó là gì. Lấy ví dụ cơ chế lưu trữ mà một bản hiện thực hóa dùng để lưu dữ liệu, được viết bên dưới với khóa minh họa example.io/storage-backing: một Recipe Helm gắn một PersistentVolumeClaim và một Recipe Compose gắn một named volume cùng hiện thực hóa một component qua các cơ chế khác nhau, nên chúng mang các outputLabels khác nhau và công cụ ở hạ nguồn (phân bổ chi phí, chính sách, kiểm kê) có thể phân biệt chúng trên các tài nguyên được phát ra. Khóa này chỉ mang tính minh họa — example.io/ là một namespace ví dụ, và một catalog tự chọn các khóa mà công cụ của chính nó đọc.
spec: capability: helm implements: core/datastore/postgres:1.0.0 outputLabels: example.io/storage-backing: persistent-volume example.io/team: platformCác nhãn đầu ra đi chung đường với các nhãn nguồn gốc bản dựng cố định: chúng được hợp nhất vào tập nhãn mà mọi bề mặt phát ra đều gắn, nên chúng xuất hiện ở bất cứ đâu thông tin nguồn gốc xuất hiện. Điểm khác biệt là quyền sở hữu — các khóa nguồn gốc thuộc về trình biên dịch, còn outputLabels thuộc về tác giả Recipe.
Nhãn định danh của chính một component không được viết ở đây — đây là một quy ước của catalog, không phải một quy tắc mà trình biên dịch áp đặt. Các khóa nêu component là gì thay vì cách một Recipe hiện thực hóa nó — phân loại nhận thức, kiểu vận hành, các nhãn năng lực theo vai trò, ai vận hành tài nguyên bên dưới, loại giấy phép của thứ mà nó bao bọc — được khai báo trong metadata.labels của Component; xem entities/component “The Semantic Label Taxonomy” để biết các trục. Một Recipe đưa một trong các khóa đó lên đầu ra kết xuất của mình bằng cách nêu tên khóa trong outputComponentLabels: bên dưới, chứ không phải bằng cách viết khóa và một giá trị ở đây. Lý do là một mục literal là bản sao thứ hai của một giá trị mà component đã mang, và bản sao thứ hai có thể mâu thuẫn với bản đầu tiên: tác giả Recipe có thể viết một tư thế trên một nút mà Component của nó khai báo một tư thế khác, khiến người đọc ở hạ nguồn nhận được điều mà đồ thị không nói. Một mục được nâng lên sao chép theo tham chiếu nên không có bản sao thứ hai nào để lệch đi. Lõi chấp nhận bất cứ cách nào bạn viết, ngoài quy tắc namespace dành riêng bên dưới; quy ước này do các tác giả catalog duy trì.
Các namespace dành riêng. Các namespace aggrega.ai/ và app.kubernetes.io/ được dành riêng cho thông tin nguồn gốc gốc của nền tảng. Một Recipe khai báo một khóa outputLabels dưới một trong hai tiền tố này sẽ bị từ chối khi nạp, kèm một lỗi catalog rõ ràng nêu tên khóa vi phạm. Mọi khóa khác đều được chấp nhận. Ngoài ra lõi không kiểm soát khóa hay giá trị — một khóa hoặc giá trị không hợp lệ đối với bề mặt nhãn của engine đích là trách nhiệm của tác giả, và môi trường chạy ở hạ nguồn sẽ từ chối nó; trình biên dịch không can thiệp ngoài quy tắc namespace dành riêng.
Cách hiển thị theo từng provider. Mỗi provider chuyển các nhãn lên bề mặt đầu ra của riêng nó:
- helm, tổng hợp workload — trên cả
metadata.labelscủa đối tượng lẫnmetadata.labelscủa pod-template, khớp với nơi quá trình tổng hợp đặt thông tin nguồn gốc. - helm, source-render và artifacts — trên
metadata.labelscủa đối tượng. - compose — trên ánh xạ
labels:của mỗi service. - terraform — dưới dạng tag theo từng tài nguyên trên các phần thân artifact
.tf.jsoncó thể định địa chỉ theo cấu trúc, theo kiểu nỗ lực tối đa: một khối tài nguyên đã khai báo ánh xạtags(AWS/azurerm) hoặclabels(Google) sẽ nhận các nhãn đầu ra ở đó, một khóa do tác giả khai báo không bao giờ bị ghi đè, và một tài nguyên không có thuộc tính như vậy được giữ nguyên (không bao giờ tự tạo thuộc tính). Các phần thân HCL gốc (main.tf,*.tf) và các module được vendor được phát ra nguyên văn và không mang tag nào được chèn vào. Thông tin nguồn gốc Terraform tiếp tục đi trong tệp chú thích đi kèm, tách biệt khỏi đường tag.
Các nhãn đầu ra chỉ là nhãn; không có bề mặt annotation đầu ra riêng. outputLabels do tác giả Recipe khai báo (tầng hiện thực hóa do bộ phận vận hành viết), không phải do Aggregate — nó mô tả việc hiện thực hóa, không bao giờ mô tả định danh trong đồ thị trừu tượng của nhà phát triển.
Trường outputComponentLabels: — nâng các nhãn riêng của một component lên đầu ra
Recipe.spec.outputComponentLabels: là một danh sách các khóa nhãn, không phải các cặp khóa-giá trị. Với mỗi khóa được nêu, provider gắn khóa đó lên đầu ra được kết xuất với giá trị mà khóa đó mang trên instance component đang được kết xuất. Trong khi outputLabels nêu một giá trị, outputComponentLabels chỉ ra nơi cần đọc giá trị đó.
spec: capability: helm implements: core/datastore/postgres:1.0.0 outputLabels: example.io/team: platform outputComponentLabels: - component.aggrega.ai/hostingVới một Component có metadata.labels khai báo component.aggrega.ai/hosting: managed, mọi đối tượng mà Recipe này kết xuất cho component đó đều mang component.aggrega.ai/hosting: managed. Gắn cùng Recipe đó vào một component khai báo self-hosted thì các đối tượng của component đó sẽ mang self-hosted thay vào đó — một Recipe, một khóa được nêu tên, mỗi component một giá trị.
Việc nâng lên là theo tham chiếu, và đó chính là mục đích. Giá trị được đọc từ component mỗi khi đầu ra được kết xuất, nên nó không thể lệch khỏi danh tính mà nó bắt nguồn: không có bản sao thứ hai nào cần giữ đồng bộ khi nhãn của component thay đổi. Một mục outputLabels dạng giá trị cố định nhắc lại nhãn của một component chính là bản sao thứ hai đó, và hai bên sẽ mâu thuẫn ngay khi một trong hai thay đổi. Vì vậy, hãy dùng outputLabels khi giá trị là một thuộc tính của cách Recipe này hiện thực hóa component, và dùng outputComponentLabels khi giá trị đã tồn tại trên component và đầu ra được kết xuất cũng cần mang nó.
Một khóa được nâng lên sẽ xuất hiện trên đúng cùng bề mặt như một khóa cố định — cách hiển thị theo từng provider mô tả ở trên áp dụng không đổi, và không provider nào phân biệt một khóa được nâng lên với một khóa được viết trực tiếp.
Các namespace dành riêng. Các namespace aggrega.ai/ và app.kubernetes.io/ được dành riêng cho provenance gốc của nền tảng, và một khóa được nâng lên nằm dưới một trong hai tiền tố đó sẽ bị từ chối khi nạp, kèm một lỗi catalog nêu tên khóa và trường chứa nó. Phép kiểm tra dựa trên tiền tố trần: một khóa như component.aggrega.ai/hosting nằm trong một namespace riêng chứ không nằm dưới gốc dành riêng, nên có thể được nâng lên.
Một khóa chỉ thuộc về một trong hai khối. Khai báo cùng một khóa trong cả outputLabels và outputComponentLabels sẽ bị từ chối khi nạp, để mọi khóa được gắn chỉ có một nguồn duy nhất — hoặc giá trị cố định viết trên Recipe, hoặc nhãn riêng của component, không bao giờ cả hai.
Một khóa được nâng lên mà component không khai báo thì không gắn gì cả. Quá trình build tiếp tục và phát ra một cảnh báo nêu tên node, Recipe và khóa bị thiếu. Điều này là có chủ ý: một Recipe được gắn vào các component có tập nhãn khác nhau vẫn kết xuất được, và sự khác biệt được báo ra thay vì làm dừng build.
Component một tư thế — một quy ước, không phải một quy tắc. Việc nâng lên mang theo bất kỳ giá trị nào component khai báo, và trình biên dịch không diễn giải giá trị đó. Vì thế, một component có nhãn danh tính chứa một giá trị giữ chỗ đại diện cho “thay đổi tùy trường hợp” sẽ nâng giá trị giữ chỗ đó lên mọi đối tượng được kết xuất cho nó. Khi một component thực sự có nhiều hơn một tư thế, quy ước catalog của thư viện chuẩn là để mỗi Recipe nêu tư thế của chính cách hiện thực hóa của nó thông qua một khóa outputLabels do Recipe sở hữu, thay vì qua khóa danh tính của component — khóa mà cùng quy ước đó chuyển qua outputComponentLabels: — hoặc không gắn gì cả. Hai khóa trả lời hai câu hỏi khác nhau và không khóa nào thay thế khóa nào: khóa danh tính cho biết component là gì trên mọi cách hiện thực hóa, còn khóa do Recipe sở hữu cho biết cách hiện thực hóa cụ thể này làm gì. Đó là một quy ước catalog được các tác giả của nó duy trì, không phải một ràng buộc mà trình biên dịch áp đặt.
Khối locals:
Recipe.spec.locals: là Trạng thái vận hành riêng tư (Private Ops State) — một map gồm các chuỗi Go template có tên, mà đầu ra đã render của chúng cung cấp một map .locals.* cho các template phía sau của Recipe. Đây là không gian làm việc để tính toán các thực tế vật lý (container đích, đường dẫn JSON, hostname dẫn xuất) một lần và tái sử dụng chúng trong các payload provides:, source:, valuesMapping:, workload:, artifacts:, assertions: và pipeline[].with mà không phải tính lại. Đầu ra đã render của mỗi mục được lưu với khoảng trắng ở đầu và cuối đã bị loại bỏ.
spec: capability: helm implements: core/postgres-db:1.0.0 source: ./charts/postgresql locals: primary_compute: postgresql listen_port: "5432" secret_target_db_password: "postgres-auth" volumes_path: "/spec/template/spec/volumes" valuesMapping: | primary: auth: existingSecret: "{{ .context.rendered_name }}-{{ .locals.secret_target_db_password }}"locals: không bao giờ được cung cấp cho bên gọi — các component phía sau sử dụng Recipe này qua uses: chỉ thấy provides:. Các template provides:, source:, valuesMapping:, workload:, artifacts:, assertions: và pipeline[].with của chính Recipe đều thấy map .locals.* đã được phân giải. Giá trị của từng khóa có thể là chuỗi thuần hoặc Go template; trình biên dịch phân giải toàn bộ khối trong phần mở đầu locals, trước provides: của node đó, nên mọi template phía sau đều thấy các giá trị đã phân giải ổn định.
Mỗi mục được đánh giá dựa trên một ngữ cảnh cục bộ của node, tự chứa: .context.instance_id, .values, .infra và các mục của chính khối này đã được phân giải. Một local không thể đọc .provides — trụ cột đó không có trên bề mặt này, và một mục tìm cách đọc nó sẽ dừng biên dịch. Local cũng không thể đọc .context.rendered_name, tên mà một provider như helm đặt cho các tài nguyên nó render cho node, nên một local đặt tên cho một trong các tài nguyên đó chỉ mang phần đứng sau tên đó, như secret_target_db_password ở trên, và template viết tên đầy đủ sẽ ghép hai phần lại.
Thứ tự viết có ảnh hưởng thực sự
Các mục được phân giải theo thứ tự chúng được viết, và một mục có thể đọc một mục anh em được định nghĩa phía trên nó, nhận giá trị đã phân giải của mục đó:
spec: locals: db_identifier: "{{ .context.instance_id }}-postgres" # defined first secret_target: "{{ .locals.db_identifier }}-auth" # reads the entry aboveViệc nối chuỗi chỉ chạy theo chiều xuống. Khi một mục đọc một mục khác, thứ tự các mục quyết định bản build có thành công hay không: di chuyển db_identifier xuống dưới secret_target thì bản build sẽ dừng. Trình biên dịch không bao giờ sắp xếp hay đổi thứ tự khối để một tham chiếu được phân giải, nên thứ tự đã viết chính là hợp đồng — đổi thứ tự một khối locals: là một thay đổi về hành vi, không phải thay đổi về hình thức.
Hai lỗi dừng khác nhau phân biệt hai sai lầm mà tác giả có thể mắc phải, vì chúng có cách sửa khác nhau:
- Một tham chiếu đến mục mà khối định nghĩa phía sau sẽ dừng biên dịch và nêu lỗi thứ tự; cách sửa là di chuyển định nghĩa lên trên mục đọc nó.
- Một tham chiếu đến khóa mà khối hoàn toàn không khai báo sẽ dừng biên dịch và nêu tên khóa; cách sửa là sửa lại chính tả.
Việc kiểm tra theo dõi cả bí danh của khối. Một khóa được truy cập qua dấu chấm mà phần thân with .locals gán lại, hoặc qua một biến được gán cho .locals, được kiểm tra theo đúng các điều kiện như cách viết trực tiếp: {{ with .locals }}{{ .nope }}{{ end }} và {{ $l := .locals }}{{ $l.nope }} đều dừng và nêu tên .locals.nope, giống như {{ .locals.nope }}, và {{ (.locals).nope }} cùng {{ ($.locals).nope }} cũng vậy, vì cặp ngoặc trả về chính khối đó và không gì hơn. Có một cách viết thoát khỏi việc kiểm tra: khóa được truy cập qua một lời gọi mà văn bản template không thể nêu tên kết quả — {{ index .locals "nope" }}, hoặc {{ (default dict .locals).nope }} — vì kết quả của lời gọi như vậy được quyết định khi template chạy chứ không phải bởi những gì được viết. Một khóa không tồn tại được đọc như một trường từ kết quả của lời gọi như vậy sẽ không dừng biên dịch, và nó render ra văn bản nguyên văn <no value> thay vì không có gì. Một khóa không tồn tại được truy cập qua index sẽ dừng và nêu tên khóa, vì index dừng trên mọi bề mặt template khi map nó đọc không chứa khóa được yêu cầu — một báo cáo khác với báo cáo của việc kiểm tra này, được mô tả tại errors/fatal-halts.md dưới mục “A template indexes a map with a key the map does not hold (Một template truy cập map bằng một khóa mà map không chứa)”. Do đó, index vẫn là cách để truy cập một khóa có tên được tính toán, chẳng hạn {{ index .locals (printf "secret_target_%s" .values.slot) }}, và một tên được tính toán mà khối không khai báo vẫn được báo cáo theo khóa của nó.
provides: đọc .locals và nhận các giá trị đã được phân giải, vì locals của một node được phân giải trước provides của nó. Một template provides: nêu tên một khóa mà khối locals không khai báo sẽ dừng lại. Điều này có nghĩa là một giá trị mà cả một mục provides: lẫn một artifact đều cần được viết một lần, trong locals:, và được đọc từ cả hai nơi.
Về phần tương ứng ở API công khai, hãy xem The provides: block bên dưới. Bề mặt FeatureRecipe tuân theo cùng các quy tắc — xem entities/featurerecipe.md “Khối locals:”.
Khối provides:
Recipe.spec.provides: là API công khai cho nhà phát triển — một map từ tên → chuỗi Go template khai báo các giá trị mà Recipe này đóng góp vào các đường ống .context.inject và .context.uses của các bên gọi ở hạ nguồn. Trình biên dịch đánh giá các template provides: ở giai đoạn đánh giá provides (tự chứa, theo thứ tự bất kỳ); các khóa inject của bên gọi được phân giải theo các giá trị này ở giai đoạn hydrat hóa inject.
spec: capability: helm implements: core/postgres-db:1.0.0 source: ./charts/postgresql provides: # The Service this chart names after its release name, suffixed "-postgresql" host: "{{ .context.rendered_name }}-postgresql" port: "5432" database: "{{ .values.db_name }}"Template của mỗi mục được đánh giá trên bề mặt đánh giá provides tự chứa — .context.instance_id, .context.rendered_name khi provider của node báo cáo giá trị này, .values, .infra, .locals đã được phân giải của node, và văn bản tĩnh. Namespace mà node được đặt vào không có trên bề mặt này, nên một host được công bố không mang namespace nào: một bên tiêu thụ ở namespace khác tự định danh đầy đủ nó ở phía mình. .locals có trên bề mặt này vì locals của node được phân giải trong phần mở đầu của cùng giai đoạn, trước provides của nó; một template provides gọi tên một khóa mà khối locals không khai báo sẽ dừng biên dịch. Việc tách đánh giá provides khỏi inject hydration là điều mang tính nền tảng: provides: của một Recipe không thể tham chiếu trạng thái của bất kỳ bên gọi nào vì các bên gọi chưa được phân giải khi đánh giá provides chạy — provides: là tự chứa theo bất biến kiến trúc. Sau đó các bên gọi đọc các giá trị này qua .context.uses.<alias>.provides.<provided-name> trong template của chính mình — các tên được cung cấp lồng dưới provides trên cạnh, bên cạnh các trường khác của cạnh. Một bên gọi khai báo danh sách cho phép inject: trên cạnh sẽ truy cập cùng các giá trị đó qua đường ống .context.inject của nó.
Các khóa provides: là một phần của bề mặt hợp đồng của Recipe. Đổi tên hoặc xóa một khóa là thay đổi phá vỡ tương thích đối với mọi bên gọi dựa vào tên cũ; phiên bản interface implements: nên phản ánh sự tiến hóa của hợp đồng. Để biết ngữ nghĩa phân giải theo tầng, hợp đồng đường ống inject và các ví dụ minh họa về định tuyến xuyên namespace và xuyên vùng, xem architecture/06-data-taxonomy-and-composition.md §3 và templates/expansion-matrix.md.
Đọc các giá trị được công bố của một attachment
Một Recipe đọc các Features được gắn vào component của nó tại .features.<instance-name> và các Features thông tin xác thực tại .features.<slot>. Cả hai có cùng một dạng attachment — .type, .values, .infra, .provides — nên một attachment được đọc theo cùng một cách bất kể map nào chứa nó; điều khác nhau giữa chúng là thứ mà attachment tạo ra.
.provides là đầu ra được công bố của attachment, được phân giải từ FeatureRecipe gắn với nó. Đây là phần đối ứng của khối provides: ở trên, nhìn từ phía tiêu thụ: trong khi một Recipe công bố cho các bên gọi của nó, một attachment công bố cho component chủ của nó.
workload: | # The identity attachment emits a ServiceAccount and publishes its name; # the pod binds to that published name rather than restating it. serviceAccount: "{{ .features.identity.provides.name }}" containers: main: env: DB_SECRET: "{{ .features.app_credentials.provides.name }}"Đọc giá trị được công bố thay vì tính lại nó từ cùng các đầu vào values/infra chính là sự khác biệt giữa một lần khai báo một tên và hai lần khai báo có thể lệch nhau. Dạng đầy đủ theo từng trường, bao gồm các quy tắc về tính khả dụng, có tại templates/template-context-contract.md.
Một attachment được viết trên một trong các kết nối của component — một thông tin xác thực mà component xuất trình cho một đích — được đọc theo cùng dạng dưới kết nối đó, tại .context.uses.<alias>.features.<slot>, và không bao giờ nằm trong .features. Một Recipe kết nối tới nhiều đích sẽ đọc thông tin xác thực riêng của mỗi đích dưới alias của đích đó, và một vòng lặp trên .features chọn các attachment theo kiểu chỉ gặp những attachment của chính component:
artifacts: routes.yaml: | {{- range $alias, $edge := .context.uses }} - name: {{ $alias }} {{- with $edge.features }}{{ with .credential }} api_key_secret: {{ .provides.name }} {{- end }}{{ end }} {{- end }}Xem Các attachment của một kết nối để biết dạng và thứ tự mà một template duyệt qua các kết nối.
Trường pipeline:
Recipe.spec.pipeline: là một mảng tuần tự các bước pipeline Wasm chạy sau khi render trên tập tài liệu đã render, mỗi bước trả về các bản vá RFC 6902 và các tác dụng phụ. Mỗi mục khai báo một id (định danh của từng bước: chữ cái, chữ số và dấu gạch dưới), một plugin (thực thể Plugin mà bước chạy, được giới hạn theo loại plugin của nó — pipeline-step/<name>, có thể kèm phiên bản; một tham chiếu .wasm hay artifact trần sẽ bị từ chối), một function (export của plugin cần gọi), một thân Go template with: tùy chọn cung cấp payload cho plugin, và một Go template when: tùy chọn quyết định bước có chạy hay không — kết quả falsy sẽ bỏ qua bước đó như một bước chuyển tiếp, giữ nguyên tập tài liệu. Cổng when:, tính độc lập của nó với optional:, và quy tắc truthiness của nó được trình bày đầy đủ trong entities/featurerecipe.md “Conditional steps — when:”:
spec: capability: helm implements: core/web-server:1.0.0 source: { kind: helm-oci-chart, url: "oci://…", version: "…" } pipeline: - id: inject_sidecar plugin: pipeline-step/envoy-sidecar:1.0.0 function: Inject with: | target_container: "{{ .locals.primary_compute }}" envoy_version: "{{ .values.envoy_version | default "1.30.0" }}"Trình biên dịch thực thi các bước pipeline: của một Recipe cơ sở theo thứ tự khai báo, giống như cách nó thực thi pipeline: của một FeatureRecipe: nó gọi plugin Wasm được đặt tên của từng bước trên đầu ra đã render, áp dụng các thao tác JSON Patch được trả về lên các tài liệu được nhắm tới, và phát ra các tác dụng phụ của bước đó. Trường pipeline: của FeatureRecipe có cùng dạng schema và cùng cách thực thi — xem entities/featurerecipe.md “Authoring Contract” và Trạng thái của ngôn ngữ để biết trạng thái thực thi của từng bề mặt.
Cơ chế của trường này tương ứng với ngữ nghĩa của FeatureRecipe: đánh giá tuần tự theo thứ tự khai báo, các thao tác JSON Patch được áp dụng vào các tài liệu đã render, các tác dụng phụ được phát ra cùng với chúng, và các lỗi được báo kèm thông tin nguồn gốc trỏ tới bước gây lỗi. Một bước có cổng when: render ra falsy sẽ bị bỏ qua như một bước chuyển tiếp, giữ nguyên tập tài liệu cho bước tiếp theo.
Khối assertions:
Recipe.spec.assertions: là một map tùy chọn gồm các quy tắc có tên biểu diễn các bất biến triển khai của Recipe — các quy tắc liên trường đúng với chart hoặc module cụ thể mà Recipe lấy làm nguồn. Mỗi khóa là một định danh quy tắc xuất hiện trong thông báo lỗi; mỗi giá trị là phần thân của một Go template. Khác với các assertion của Component (biểu diễn các bất biến ở mức hợp đồng bất kể Recipe nào được liên kết), các assertion của Recipe là thuộc tính của triển khai cụ thể đã được chọn.
spec: implements: core/datastore/mariadb:^1.0.0 source: kind: helm-oci-chart url: oci://registry-1.docker.io/bitnamicharts/mariadb version: "20.0.0" assertions: # Bitnami 20.x: serviceMonitor namespace requirement. service-monitor-namespace-required: | {{- if and (eq .values.architecture "replication") .values.metrics.serviceMonitor.enabled -}} {{- if not .values.metrics.serviceMonitor.namespace -}} {{- fail "Bitnami MariaDB 20.x requires metrics.serviceMonitor.namespace when architecture=replication and metrics.serviceMonitor.enabled=true" -}} {{- end -}} {{- end -}}Quy tắc ở trên chỉ dành riêng cho Bitnami chart 20.x; nó không áp dụng nếu một Recipe MariaDB khác được liên kết. Các quy tắc ở mức Component từ hợp đồng vẫn áp dụng song song, được đánh giá ở một giai đoạn sớm hơn của pipeline.
Các assertion của Recipe được đánh giá sau khi liên kết Recipe và trước khi render, khi locals và provides của mọi node đã được phân giải. Ngữ cảnh template bao gồm .provides, .locals và .recipe.source của Recipe, bên cạnh các trường của thể hiện thực thể (.values, .infra, .uses, .features). .uses và .features ở đó là các dạng hẹp hơn của bề mặt assertion, không phải của một template Recipe: mục của một kết nối mang đích và bí danh của nó, labels của đích, values riêng của kết nối và các attachment được viết trên nó dưới features, nhưng không có gì mà đích công bố; còn mục của một attachment, dù của chính component hay của một kết nối, mang type, resolved_version và values của nó nhưng không có infra lẫn provides — FeatureRecipe của một attachment chưa phân giải provides của nó khi assertion chạy. Do đó, một tham chiếu tới .features.<name>.provides sẽ dừng build, và một lần đọc có kiểm tra sự hiện diện sẽ trả về giá trị dự phòng của nó. Để xem toàn bộ ngữ pháp soạn thảo, sự phân chia trách nhiệm giữa các quy tắc ở mức hợp đồng và ở mức triển khai, cùng các ví dụ minh họa, xem templates/assertions-block.md.
Trường omits: — loại bỏ các tài liệu đã render khỏi một source
Hầu hết các Recipes không bao giờ cần đến điều này. Nó dành cho một source mà bạn dùng nguyên trạng — thường là một chart được tải về từ một registry — nhưng lại render ra một tài liệu mà Release của bạn không được phép phát hành: chẳng hạn một Secret mà chart tạo mới ở mỗi lần render, khiến hai bản build khác nhau và, khi được áp dụng, ghi đè lên Secret mà người vận hành đã cung cấp. Bạn không chỉnh sửa một chart đã tải về, và không quy tắc ignore nào chạm được vào bên trong nó, nên omits: là cách một Recipe loại tài liệu như vậy ra khỏi bản build. Một tệp compose được tải về cũng tương tự: nó có thể đi kèm một service, một volume hoặc một config mà Release không được có, và một lớp phủ valuesMapping: có thể thay đổi nhưng không bao giờ xóa được chúng. Một template CloudFormation được tải về cũng vậy, vì nó có thể khai báo một tài nguyên mà Release không được tạo: một valuesMapping: có thể điền các tham số nó khai báo nhưng không bao giờ xóa được tài nguyên nào của nó.
spec: capability: helm implements: core/gateway/kong:1.0.0 source: kind: helm-oci-chart url: oci://registry.example.com/charts/gateway version: "2.4.0" omits: # The chart generates this key on every render; the operator supplies it. - kind: Secret name: "{{ .context.rendered_name }}-session-key" # Left out only where the Release asks for it. - when: "{{ .infra.without_dashboards }}" kind: ConfigMap name: "{{ .context.rendered_name }}-dashboards" namespace: monitoringPhạm vi áp dụng. Chỉ những gì source: render ra. Một workload: và các mục artifacts: không bao giờ bị lọc: bạn tự viết chúng trong Recipe, nên một tài liệu bạn không muốn có ở đó là tài liệu bạn không viết ra. Khóa này yêu cầu có source:; một tài liệu vi phạm quy tắc này sẽ bị từ chối ngay khi được đọc, kèm tên quy tắc.
Một mục. Mỗi mục chỉ định thứ cần loại bỏ bằng ba trường, và trường thứ tư quyết định mục đó có được áp dụng hay không. Những gì ba trường đầu chỉ định thuộc về bộ từ vựng riêng của provider cho những gì source của nó render ra, được trình bày theo từng provider trong bảng dưới đây:
kind— loại của thứ mà source render ra: với một chart, đó là kind của một tài liệu đã render —Secret,ConfigMap,Deployment; với một tệp compose, làservice,volumehoặcconfig; với một template CloudFormation, làTypecủa một tài nguyên —AWS::S3::Bucket. Nó không liên quan đếnkind:mà mộtsource:có cấu trúc mang theo, vốn chỉ định cách source được tải về.name— tên của nó:metadata.namecủa một tài liệu; khóa của một đơn vị compose dướiservices:,volumes:hoặcconfigs:; logical ID của một tài nguyên CloudFormation, tức khóa của nó dướiResources.namespace(tùy chọn) — namespace chứa tài liệu, đối với provider có đầu ra phân theo namespace. Khi không có trường này, mục chỉ định kind và name trong bất kỳ namespace nào; mộtnamespacerender ra rỗng được coi như không có.when(tùy chọn) — mục có áp dụng cho bản build này hay không. Trường này được đánh giá trước tiên và được đọc theo cùng quy tắc vớiwhen:của một bước pipeline: kết quả false sẽ bỏ mục đó, nên các trường khác của nó không được đánh giá và nó không được chuyển cho provider cũng như không bị kiểm tra, còn mộtwhen:vắng mặt hoặc rỗng sẽ giữ lại mục.
kind và name là bắt buộc, và một mục mang bất kỳ trường nào khác sẽ bị từ chối khi Recipe được đọc.
Mọi giá trị đều là một template, được đánh giá trên cùng ngữ cảnh với valuesMapping:. Ngữ cảnh đó mang .context.rendered_name, tên mà provider đặt cho các tài nguyên của node và cũng là tên mà một chart thường dùng để đặt tên cho chúng, nên một mục có thể chỉ định một tài liệu chính xác như chart sẽ đặt. Một template render thất bại sẽ dừng bản build giống như một template valuesMapping: thất bại.
Mọi mục được áp dụng đều phải loại bỏ được thứ gì đó. Provider báo cáo số đơn vị mà mỗi mục đã loại bỏ, và một mục không loại bỏ được gì sẽ dừng bản build, kèm tên mục đó; xem An omits entry left out nothing the source rendered (Một mục omits không loại bỏ được gì trong những gì source đã render). Nguyên nhân thường gặp là một lần nâng cấp source đổi tên hoặc xóa tài liệu, và việc dừng này chính là điều ngăn một tài liệu bị đổi tên lọt vào đầu ra của bạn mà không ai hay biết. Để chỉ đôi khi mới loại bỏ một tài liệu, hãy nói rõ điều đó bằng when: thay vì trông cậy vào việc tài liệu không có mặt.
Source vẫn được render đầy đủ. Chỉ đầu ra của nó bị lọc: mọi template của chart vẫn chạy, nên một template thất bại vẫn làm bản build thất bại, và một tài liệu bị loại bỏ vẫn được render rồi mới bị bỏ đi. Khi đã bị bỏ, nó không đến được bất cứ bước nào bản build thực hiện sau đó — không có tệp nào được xuất ra, không có tên nào được so sánh với tên của các component khác, không có thông tin nào về lần render mà một Feature đọc, không có gì được chuyển cho một bước pipeline.
Một Release tác động đến khóa này thông qua infra và parameters. Khóa này thuộc về Recipe, nên một Release không thể viết nó. Tuy vậy Release vẫn có thể quyết định một mục làm gì: các template của một mục đọc infra mà Release điền vào, và các parameters mà nó cung cấp sẽ đến .values của Recipe ở bất cứ đâu Aggregate định tuyến chúng tới. Vì vậy một Release bật hoặc tắt một mục bằng when:, như mục thứ hai ở trên, hoặc quyết định mục đó chỉ định thứ gì.
Bạn tự chịu trách nhiệm về những gì mình loại bỏ. Không thành phần nào trong bản build biết một tài liệu dùng để làm gì. Loại bỏ một tài liệu mà phần còn lại của chart phụ thuộc vào lúc chạy — Secret mà một Deployment mount, ServiceAccount mà một pod chạy dưới danh nghĩa — sẽ tạo ra đầu ra build thành công nhưng thất bại khi được áp dụng, trừ khi một thứ khác được áp dụng cùng cung cấp tài liệu đó. Với một tệp compose và một template CloudFormation thì bản build có kiểm tra, vì mỗi loại tự nêu các tham chiếu của mình: phần còn lại mà vẫn chỉ đến một đơn vị đã bị loại bỏ — một service chỉ đến một service đã bị loại bỏ, một tài nguyên hoặc một output chỉ đến một tài nguyên đã bị loại bỏ — sẽ dừng bản build, như bảng dưới đây mô tả.
Những provider nào hỗ trợ khóa này. Loại bỏ một tài liệu là việc chỉ provider làm được, vì chỉ provider biết source của nó render ra gì, nên việc một provider có hỗ trợ khóa này hay không là một phần trong khai báo riêng của provider. Một Recipe khai báo omits: mà provider của nó không hỗ trợ sẽ bị từ chối trước khi bất cứ thứ gì được render, bất kể when: của các mục render ra gì; xem The provider does not support omits (Provider không hỗ trợ omits).
| Provider | omits: |
|---|---|
helm | Được hỗ trợ. Một mục chỉ định một tài liệu mà chart render ra — từ một template hoặc từ thư mục crds/ của nó — theo kind, metadata.name của chính tài liệu và, khi mục có chỉ định, namespace chứa tài liệu. Xem helm → Chế độ sourced. |
compose | Được hỗ trợ. Một mục chỉ định một service, một volume hoặc một config của tệp compose được source theo khóa của nó dưới services:, volumes: hoặc configs:, được so khớp sau khi valuesMapping: đã được gộp vào tệp, và không chỉ định namespace: một mục chỉ định kind khác, hoặc một namespace, sẽ dừng bản build khi component được render. Một tệp mà phần còn lại vẫn chỉ đến một đơn vị đã bị loại bỏ — qua depends_on, links, volumes_from, chế độ network hoặc namespace service:, extends, một build context, hoặc một mục volumes: hay configs: — sẽ dừng bản build, kèm tên từng tham chiếu. Xem compose → Chế độ sourced. |
cloudformation | Được hỗ trợ. Một mục chỉ định một tài nguyên của template được source theo Type và logical ID của nó, trong mọi template của một source dạng thư mục, và không chỉ định namespace: một mục mang namespace sẽ dừng bản build khi component được render. Một template mà phần còn lại vẫn chỉ đến một tài nguyên đã bị loại bỏ — qua Ref, Fn::GetAtt, DependsOn hoặc một biến Fn::Sub — sẽ dừng bản build, kèm tên từng tham chiếu. Xem cloudformation → Loại bỏ tài nguyên khỏi một template được source. |
helm-chart, terraform | Bị từ chối: provider chuyển source của nó đi để được render khi triển khai, nên lúc build không có tài liệu nào tồn tại để loại bỏ. Với một chart hoặc module cục bộ, một dòng trong .aggregaignore đặt cạnh Recipe sẽ loại bỏ một tệp của nó thay thế. |
Khóa tương tự cũng được viết trên một FeatureRecipe; xem entities/featurerecipe.md.
Để xem một ví dụ hoàn chỉnh — Secret được sinh ra của một chart tải về bị loại bỏ, lần dừng do tính tất định mà cùng chart đó gặp khi không có mục, và lần dừng với một mục không khớp gì, mỗi trường hợp từ một bản build thực tế — xem ai-gateway-own-webhook-certificate.