Bỏ qua để đến nội dung
AggregaAggrega
Chọn ngôn ngữ: Tiếng Việt
Trang này được dịch bằng máy. Đọc bản gốc tiếng Anh.

FeatureRecipe

Vai trò khái niệm của thực thể FeatureRecipe (Miền 3 — phần triển khai một giao diện Feature do Wasm-plugin điều khiển) được trình bày trong architecture/04-entity-taxonomy.md. Trang này đề cập đến bề mặt soạn thảo catalog của FeatureRecipe.

Vị trí trong catalog

Các FeatureRecipes được tổ chức với provider ở phân đoạn đầu tiên của đường dẫn (cùng mẫu như các Recipes):

aggrega-catalog/
└── feature-recipe/
└── {provider}/ # e.g., `helm`, `compose`
└── {feature-recipe-name}/
└── {version}/
└── recipe.yaml

URI OCI: hub.aggrega.ai/featurerecipe/{provider}/{name}:{version} (ví dụ: hub.aggrega.ai/featurerecipe/helm/k8s-secret-from-parameter:1.0.0).

Hợp đồng soạn thảo

Các FeatureRecipes liên kết với một giao diện Feature thông qua implements và khai báo một provider cụ thể. Bề mặt soạn thảo của chúng là toàn bộ tập hợp các loại đầu vào của Recipe cơ sở cộng thêm hai khối dành riêng cho FeatureRecipe:

  1. Ba loại đầu vào — source + valuesMapping (lấy từ nguồn), workload (tổng hợp) và artifacts: có hình dạng giống hệt Recipe cơ sở (xem Recipe Input Composition và entities/recipe.md). Một FeatureRecipe mang bất kỳ loại nào trong số này là tạo tài nguyên — nó kết xuất các tài nguyên bên cạnh component cơ sở. Nơi các tài nguyên đó được đặt mang theo component mà Feature được gắn vào và sau đó là tên mà nó được gắn dưới đó, theo dạng nào trong hai dạng mà bố cục riêng của đích chấp nhận: dưới dạng một thư mục {component}--{instance}/ bên cạnh thư mục của host, nằm dưới thư mục mà đích đó dùng để chứa các thành phần đóng góp, trên một đích có provider cấp cho mỗi thành phần đóng góp một vị trí riêng; dưới dạng một tiền tố tên tệp {component}--{instance}-- bên cạnh các tệp riêng của component, trên một đích chỉ đọc các tệp nằm trực tiếp trong một thư mục. Trên một provider gộp các thành phần đóng góp vào một tài liệu duy nhất, các tài nguyên thay vào đó được gộp vào tài liệu đó — bất kể Feature thuộc họ nào: một CRD ServiceMonitor hoặc ExternalSecret dưới dạng artifacts: nội tuyến hoặc $import; một chart hoặc module bên ngoài thông qua source: + valuesMapping:; hoặc tài nguyên tính toán riêng của nó (ví dụ một Deployment sidecar-agent) thông qua workload:. valuesMapping: dùng chung ba chế độ soạn thảo của Recipe cơ sở (khối scalar nội tuyến, $import: tệp, $import: thư viện tới một mục MappingLibrary) — xem entities/recipe.md “The valuesMapping field — three authoring modes”. Theo quy ước, một FeatureRecipe sửa đổi component cơ sở hoặc thêm tài nguyên bên cạnh nó, nhưng schema không giới hạn những loại đầu vào mà nó có thể dùng — trình biên dịch kết xuất bất cứ thứ gì FeatureRecipe khai báo, chỉ bị giới hạn bởi khả năng của provider được liên kết, và vẫn không có quan điểm riêng về việc một loại nhất định có “phù hợp cho việc sửa đổi” hay không (xem các bất biến nền tảng). Việc tổng hợp (workload:) cần một provider hỗ trợ nó; nếu không, bản dựng sẽ dừng ở bước kết xuất với chẩn đoán về khả năng của provider.
  2. injectMapping (chặn trước khi kết xuất): Một khối Go template gốc được thực thi trước khi Recipe cơ sở kết xuất. Nó xuất ra một từ điển JSON hoặc YAML mà trình biên dịch deep-merge một cách tự nhiên lên memory pipe .context.inject của caller, cho phép thay đổi các biến môi trường và chuỗi kết nối ở phía caller mà không cần Wasm.
  3. pipeline: Một mảng tuần tự các bước plugin WebAssembly (Wasm) dùng cho việc thay đổi Workload sau kết xuất (ví dụ: chèn một sidecar Envoy qua JSONPatch, hoặc gắn một volume secret). Trường plugin của mỗi bước chỉ định một thực thể Plugin theo URI của nó, luôn được giới hạn theo loại socket riêng của plugin (<pluginType>/<name>, có thể kèm phiên bản, như trong parser/yaml hoặc parser/yaml:1.0.0); bản dựng phân giải thực thể thành artifact .wasm được định địa chỉ theo nội dung của nó, được định vị từ danh tính của plugin và registry đã cấu hình, và một .wasm trần hay một tham chiếu artifact không được chấp nhận ở đây. Xem hướng dẫn phát triển plugin Wasm để biết cách soạn và tham chiếu một plugin, và architecture/04-entity-taxonomy.md §“Domain 3: Infrastructure Base” về Nguyên tắc Plugin hai phần (Fetcher / Injector). Trình biên dịch thực thi từng bước theo thứ tự khai báo: nó gọi export guest của plugin được chỉ định trên đầu ra đã kết xuất và áp dụng các JSON Patch được trả về cùng các hiệu ứng phụ được phát ra; xem 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 pipeline. Một pipeline: tự đứng riêng: một FeatureRecipe có thể khai báo một pipeline mà không có loại đầu vào nào, khi đó nó không phát ra tài nguyên riêng nào và toàn bộ tác dụng của nó là những gì các bước của nó vá vào, hoặc phát ra bên cạnh, các tài liệu mà bản dựng đã kết xuất.

Một FeatureRecipe cũng có thể không mang khối nào trong số này: một Feature chỉ để nối dây, có tác dụng là cạnh uses mà nó mang, không kết xuất gì cả, và FeatureRecipe của nó chỉ tồn tại để đáp ứng việc phân giải — mọi instance feature đều phân giải tới một FeatureRecipe, giống như mọi component đều phân giải tới một Recipe. Trong các khối trên, injectMapping là trường duy nhất không có trường tương ứng ở Recipe cơ sở; ba loại đầu vào và pipeline được dùng chung với Recipe cơ sở.

Những gì được ghim bên cạnh một FeatureRecipe cũng là những gì được ghim bên cạnh một Recipe: digest của mỗi tệp mà một mục artifacts nhập vào, và của mỗi source: từ xa có tọa độ được viết đầy đủ, trong một entity.lock nằm trong thư mục riêng của FeatureRecipe, do aggrega pin ghi và bạn commit bên cạnh nó. Một lần pull trên một FeatureRecipe mà lock không ghi các ghim đó sẽ dừng và nêu tên bước đó, trừ khi lần pull được yêu cầu chạy bước đó. Một bản dựng dừng khi một tệp được nhập không còn khớp với digest của nó, và khi digest của một source không khớp với digest mà lockfile của Release ghi lại (một source được viết tại một ref: git được ghi lại tại commit mà nó phân giải tới và không được so sánh); bản thân tệp FeatureRecipe không bao giờ bị ghi vào. aggrega pull mô tả tệp này và cách xử lý từng trường hợp dừng.

Template hóa trường source

source: của một FeatureRecipe là một bề mặt tạo mẫu theo cùng các điều kiện như của một Recipe: template được đánh giá khi phân giải nguồn, và những gì nó tạo ra là những gì bản dựng sau đó phân giải. Cả hai dạng đều chấp nhận Go template — dạng chuỗi phổ quát, và dạng đối tượng có cấu trúc mà các trường con có giá trị chuỗi được đánh giá như template trong khi các trường con không phải chuỗi được giữ nguyên. Danh mục các dạng, cách xử lý scheme và cách hiểu về việc neo đường dẫn là những gì đã được trình bày trong entities/recipe.md “Source field templating”, “Source field scheme inventory” và “How a source: path is anchored”; phần này chỉ nêu những điểm khác biệt đối với một attachment.

locals:
chart_dir: ./charts/exporter
source: "{{ .locals.chart_dir }}"

Một kết quả tương đối được phân giải dựa trên cái gì. Thư mục chứa tài liệu FeatureRecipe đã khai báo nó — tệp riêng của attachment, không bao giờ là của component — và kết quả phải nằm trong thư mục đó, đúng như đối với một Recipe: một kết quả leo ra khỏi thư mục, hoặc là một đường dẫn tuyệt đối, sẽ trỏ tới một tệp không đi cùng FeatureRecipe và làm dừng bản build. Một kết quả mang scheme truyền tải sẽ được tải về thay vì được nối vào một thư mục. Một FeatureRecipe được phân giải từ registry được đọc từ các tệp mà archive đã phát hành của nó mang theo, được bố trí trong content cache, nên một kết quả tương đối được phân giải bên trong những gì đã được phát hành đúng như cách nó được phân giải bên cạnh FeatureRecipe trong một thư mục catalog, và chịu cùng giới hạn.

Template có thể đọc những gì. Tập tham chiếu là tập mà các mục locals: của chính FeatureRecipe được kiểm tra theo, khác với của một Recipe ở hai điểm, xuất phát từ việc thứ được phân giải là một attachment chứ không phải một component:

  • .attachment_name khả dụng, đặt tên cho instance mà Feature được gắn vào. Template nguồn của một Recipe từ chối nó, vì nguồn của một Recipe được phân giải cho một node và không có attachment nào tham gia.
  • .context.instance_id đặt tên cho component chủ mà attachment đang được phân giải cho, không phải attachment, và .context.rendered_name mang tên mà provider riêng của component chủ báo cáo cho component chủ — chỉ có mặt khi provider đó báo cáo một tên, và làm dừng bản build khi nó không báo cáo. Xem Đặt tên cho một tài nguyên được kết xuất.

.locals mang tập mà các template khác của FeatureRecipe này đọc: khối đã phân giải của chính nó, với khối của Recipe chủ bên dưới, nên một khóa mà attachment khai báo sẽ thắng một khóa chủ cùng tên. Một tham chiếu tới khóa mà tập đó không có sẽ dừng và nêu tên khóa đó, thay vì kết xuất bỏ khóa. .provides, .context.inject và .context.uses bị từ chối trên cùng cơ sở tự chứa mà bề mặt nguồn của một Recipe từ chối chúng.

Một FeatureRecipe phạm vi boundary thay vào đó đọc boundary. Một Feature có FeatureRecipe khai báo executionScope: boundary được kết xuất một lần cho boundary thay vì một lần cho mỗi component, nên template nguồn của nó không có component chủ nào để đọc. Nó đọc .boundary.* — cùng các trụ cột mà locals: và provides: của nó đọc — và các trụ cột theo từng component (.context, .workload, .attachment_name, .inject) không khả dụng với nó.

Một kết quả rỗng. Một template không tạo ra gì sẽ để attachment không có nguồn, tức là chế độ không nguồn — cùng cách đọc mà nguồn của một Recipe áp dụng, và khác với việc bạn tự viết source: "".

.source đọc gì sau đó. Source được đánh giá trước valuesMapping:, giống như source của một Recipe được đánh giá trước phần ánh xạ của chính nó, và những gì nó tạo ra là .source trên mọi template chạy sau nó: valuesMapping:, omits:, phần thân workload: và artifacts:, và các bước pipeline:. Vì vậy một valuesMapping: đọc .source sẽ đọc source của chính FeatureRecipe này, không bao giờ là source của component mà nó được gắn vào, và không đọc được gì khi FeatureRecipe này không khai báo source nào hoặc template của nó không tạo ra gì. Một FeatureRecipe có phạm vi ranh giới đọc source của chính nó theo cùng cách. injectMapping: chạy trước khi source của attachment được đánh giá, nên .source ở đó là của component chủ.

Tính độc quyền của injectMapping

Trường injectMapping chỉ dành riêng cho FeatureRecipes — nó được cố ý loại khỏi schema Recipe cơ sở. Tính độc quyền này tách biệt 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 đó, nhờ đó hai bên luôn tách rời nhau. Xem mục chặn inject-mapping bên dưới để biết cơ chế này vận hành ra sao, và architecture/10-compilation-pipeline.md về inject mapping để biết đầy đủ ngữ nghĩa của việc chặn trước khi render.

Chặn bắt inject mapping: cách injectMapping hoạt động

Khi một bên gọi cần chuỗi kết nối tới đích của nó có dạng khác với .provides.host chưa sửa đổi của đích — nối thêm namespace cho DNS Kubernetes xuyên ranh giới, thêm tiền tố mã vùng cho gateway đa vùng, hoặc thêm hậu tố chế độ SSL vào DSN — injectMapping xử lý việc biến đổi tại bên gọi, trước khi valuesMapping của Recipe cơ sở nhìn thấy đường ống inject.

Trường injectMapping là một Go text/template mà trình kết xuất đánh giá tại bước inject mapping, trước khi quá trình kết xuất của Recipe cơ sở chạy. Template xuất ra một từ điển JSON hoặc YAML với các khóa cơ chế tùy chọn (env, file, arg, hoặc một cơ chế tùy chỉnh mà Recipe của component đọc tại .context.inject.<name>), hoặc một map phẳng mặc định thuộc về env, và trình kết xuất deep-merge lớp phủ này lên pipe .context.inject của nút caller. Việc định tuyến phía caller thông qua injectMapping chạy tại bước inject mapping mà không cần gọi sandbox Wasm cho các thao tác chuỗi đơn giản; các plugin Wasm vẫn được dành cho những thay đổi cấu trúc AST thông qua mảng pipeline.

Hãy ghi mỗi giá trị thông qua toJson. Trình kết xuất đọc đầu ra của template dưới dạng YAML, nên một giá trị được nội suy nguyên trạng giữa hai dấu ngoặc kép hoặc sẽ làm hỏng đầu ra đó, hoặc sẽ bị đọc lại với nội dung bị thay đổi ngay khi nó chứa dấu ngoặc kép hoặc dấu gạch chéo ngược — mật khẩu là trường hợp thường gặp. toJson ghi giá trị dưới dạng một chuỗi JSON, mà YAML đọc lại chính xác, nên giá trị được chuyển giao với đầy đủ mọi ký tự mà nó chứa:

injectMapping: |
env:
{{ .values.key }}: {{ .values.origin | toJson }}

Một giá trị được ghép từ nhiều phần thì được ghép trước rồi ghi qua toJson một lần, như các ví dụ bên dưới.

Một đầu ra không thể đọc được sẽ dừng build. Khi đầu ra của template không được đọc theo dạng nào trong hai dạng — nguyên nhân thường gặp là một scalar trong ngoặc kép bị chính giá trị bên trong làm hỏng — không khóa nào của nó có thể được chuyển giao, nên build dừng lại và nêu tên attachment cùng FeatureRecipe thay vì kết xuất component như thể không có gì được chuyển giao; xem fatal-halts.md “An attached Feature’s injectMapping output cannot be read (Không thể đọc đầu ra injectMapping của một Feature được đính kèm)”. Lý do mà việc dừng đưa ra sẽ bị giữ lại khi lý do đó phụ thuộc vào một giá trị được khai báo là nhạy cảm. Một đầu ra rỗng, hoặc được phân tích thành một từ điển không chuyển giao gì, thì không chuyển giao gì và không phải là lỗi.

Một khóa cấp cao nhất là một cơ chế, và all không phải là cơ chế. Mỗi khóa cấp cao nhất của một đầu ra dạng từ điển nêu tên cơ chế dùng để chuyển giao các mục của nó: env, file và arg, hoặc bất kỳ tên nào khác, được chuyển giao như một cơ chế riêng dưới tên đó. .context.inject.all được xây dựng từ các cơ chế đó sau khi hợp nhất và không bao giờ được hợp nhất từ một đầu ra, nên các mục được viết dưới all: sẽ không tới được đâu; thay vào đó build dừng lại, nêu tên attachment, khóa và FeatureRecipe, đồng thời cho biết một đầu ra được phép mang những khóa nào — xem fatal-halts.md “An attached Feature’s injectMapping output writes deliveries under a key nothing delivers (Đầu ra injectMapping của một Feature được đính kèm ghi các phần chuyển giao dưới một khóa mà không gì chuyển giao)”. Hãy viết các mục như vậy dưới cơ chế mà component đọc chúng từ đó.

Việc biến đổi hoàn toàn cục bộ tại bên gọi. FeatureRecipe chỉ sửa đổi đường ống inject của nút mà nó được gắn vào, không bao giờ sửa đầu ra .provides của đích. .provides.host của một đích có thể được nhiều bên gọi trong cụm sử dụng; injectMapping phía bên gọi chỉ hợp nhất vào đường ống của bên gọi cụ thể, nên các biến đổi định tuyến chỉ giới hạn ở cạnh đã yêu cầu chúng.

Một mapping có thể ghi lại những gì. Mọi khối inject: đều đã được phân phối vào lúc các mapping kết xuất, nên đầu ra của một mapping luôn được merge lên các khóa mà một thứ khác đã ghi, và việc ai đã ghi một khóa quyết định điều gì xảy ra. Một khóa do chính khối inject: của caller hoặc một trong các khối inject: của các kết nối của nó phân phối thì mapping được phép ghi lại: đó là sự chặn bắt, và giá trị của mapping thay thế đúng mục đó. Một khóa do chính attachment của mapping phân phối qua khối inject: của nó cũng thuộc quyền ghi lại của mapping. Một khóa mà một Feature được gắn khác đã phân phối, qua khối inject: của chính nó hoặc qua injectMapping của FeatureRecipe của chính nó, thì không: bản build dừng lại và nêu tên cả hai attachment, thay vì để mapping nào chạy sau cùng quyết định giá trị mà caller đọc. Vì vậy hai Features định tuyến có thể mỗi cái định danh một khóa của riêng mình, nhưng hai Features không thể cùng phân phối một khóa, kể cả khi hai Features định tuyến ghi lại cùng một khóa của cùng một kết nối, vì cái đầu tiên là sự chặn bắt còn cái thứ hai gặp phải sự phân phối của cái đầu tiên; xem fatal-halts.md “Two attached Features deliver one key, the later through its FeatureRecipe’s injectMapping (Hai Features được gắn cùng phân phối một khóa, cái sau thông qua injectMapping của FeatureRecipe của nó)”.

Suy luận đích không ghép nối

Vì trình biên dịch nhúng các annotation đã lan truyền của mỗi đích vào đường ống .context.uses của bên gọi, template injectMapping có thể trích xuất tọa độ định tuyến mà Ops không cần mã hóa cứng danh tính của đích vào infra của Feature:

  1. Template tìm kiếm trong .context.uses để tìm đúng cạnh tô-pô đã inject biến mà nhà phát triển yêu cầu.
  2. Nó trích xuất release_annotations đã lan truyền của đích (ví dụ: aggrega.ai/namespace).
  3. Nó định dạng tên miền đầy đủ (FQDN) hoặc chuỗi kết nối.
  4. Nó phát ra từ điển ghi đè.

Trình biên dịch vẫn không phụ thuộc vào ngữ nghĩa mạng — namespace Kubernetes, vùng đám mây, tô-pô bridge-proxy — và chỉ thực hiện hợp nhất sâu với bất cứ thứ gì template tạo ra. Khi valuesMapping của Recipe cơ sở chạy sau đó, nó sử dụng các chuỗi đã bị chặn bắt và ghi lại từ .context.inject.env như thể chúng là bản gốc của nhà phát triển.

Ví dụ minh họa: trình phân giải DNS K8s

Catalog chuẩn cung cấp ví dụ này dưới dạng core/k8s-dns-resolver với một FeatureRecipe helm. Vì tên biến môi trường phải là duy nhất trong một container, target_var (ví dụ API_HOST) đóng vai trò định danh duy nhất toàn cục cho một hợp đồng injection cụ thể trong caller. Bằng cách lặp qua các cạnh tường minh trong .context.uses và kiểm tra cạnh nào đã nhận target_var, template xác định đúng nút đích và đọc namespace của nó. Tham số duy nhất là biến cần ghi lại; đích và namespace của nó được phát hiện, không bao giờ được hardcode.

Schema của Feature định tuyến (core/k8s-dns-resolver):

infra: {
target_var: string # Ops dictates WHICH injected var to rewrite
}

Phần triển khai FeatureRecipe:

injectMapping: |
# 1. Grab the atomic base host directly from the flattened pipe, or an
# empty value when nothing was injected under target_var
{{ $base_host := optional .context.inject.env .infra.target_var "" }}
# 2. Dynamically locate the specific edge that injected this variable
{{ $target_edge := dict }}
{{ range $alias, $edge := .context.uses }}
{{ if hasKey $edge.inject.env $.infra.target_var }}
{{ $target_edge = $edge }}
{{ end }}
{{ end }}
# 3. Read the target's namespace from its cascaded release annotation,
# coalescing an absent namespace to "default"
{{ $ns := "default" }}
{{ if $target_edge.annotations }}{{ if $target_edge.annotations.release }}
{{ $raw := optional $target_edge.annotations.release "aggrega.ai/namespace" "" }}
{{ if $raw }}{{ $ns = $raw }}{{ end }}
{{ end }}{{ end }}
# 4. Qualify the host with the namespace — but only when a target connection
# and a base host were actually found, so a target_var that matches no
# connection injects nothing instead of a spurious variable. An unset
# namespace resolves to "default", where the helm provider deploys an
# unannotated workload, so the qualified host always matches the service's
# actual location and is never malformed.
{{ if and $target_edge $base_host }}
{{ $resolved_host := printf "%s.%s" $base_host $ns }}
# 5. Emit the precise override dictionary for the compiler to deep-merge
env:
{{ .infra.target_var | toJson }}: {{ $resolved_host | toJson }}
{{ end }}

Các trường hợp sử dụng ngoài định tuyến

injectMapping thường được dùng nhất cho việc phân giải địa chỉ xuyên ranh giới (như trình phân giải DNS K8s ở trên), nhưng việc biến đổi phía bên gọi đó áp dụng cho mọi tình huống cần chặn và định dạng ý định của nhà phát triển trước khi kết xuất hạ tầng. Hai mẫu sau đây minh họa phạm vi đó.

Định dạng bảo mật động (bộ nối SSL). Nếu một doanh nghiệp yêu cầu mọi kết nối cơ sở dữ liệu bên ngoài phải dùng xác minh TLS nghiêm ngặt, một Feature có thể chặn DB_URL mà nhà phát triển yêu cầu và nối thêm chế độ SSL cần thiết để ứng dụng khởi động với các tham số bảo mật đúng.

# Inside force-ssl-feature
injectMapping: |
{{ $base_url := index .context.inject.env .infra.target_var }}
env:
{{ .infra.target_var | toJson }}: {{ printf "%s?sslmode=verify-full" $base_url | toJson }}

Thêm tiền tố cho gateway đa vùng. Nếu một component API chung được triển khai toàn cầu, một Feature định tuyến theo vùng có thể tự động tra cứu các annotation ranh giới môi trường của chính nó để thêm tiền tố vào các chuỗi kết nối được inject cho các bên gọi của nó.

# Inside regional-router
injectMapping: |
{{ $base_host := index .context.inject.env .infra.target_var }}
{{ $region_code := index .context.annotations.release "cloud.aggrega.ai/region" }}
env:
{{ .infra.target_var | toJson }}: {{ printf "%s.%s" $region_code $base_host | toJson }}

Ranh giới của injectMapping. Cơ chế này chỉ giới hạn ở việc biến đổi pipe bộ nhớ .context.inject (Hợp đồng phân phối). Nó không thể thêm container mới, gắn volume, hay thay đổi đầu ra valuesMapping của Recipe cơ sở. Mọi biến đổi đòi hỏi thay đổi cấu trúc đối với AST đã kết xuất (như mảng JSON hoặc YAML) thuộc về mảng pipeline của FeatureRecipe, được thực thi thông qua các plugin WebAssembly.

Ranh giới mục tiêu vá của pipeline. Một bước pipeline chỉ vá đầu ra mà provider kết xuất thành một cây có cấu trúc. Đầu ra dạng YAML và JSON là có cấu trúc — bao gồm cả các module Terraform viết bằng JSON .tf.json — nên JSONPatch của một bước chỉnh sửa tại chỗ các giá trị được trỏ tới, giữ nguyên mọi byte khác (chú thích, thứ tự, định dạng). Đầu ra mà provider phát ra dưới dạng một thân mờ đục, chẳng hạn cấu hình Terraform viết bằng HCL gốc, không phải là mục tiêu vá: một bản vá nhắm vào thân mờ đục sẽ dừng bản dựng với một chẩn đoán thay vì sửa đổi văn bản mà nó không thể trỏ tới theo cấu trúc. Vì vậy, việc viết một bước pipeline nhắm vào đầu ra mờ đục là một lỗi thiết kế được bộc lộ bằng một lần dừng rõ ràng, chứ không phải một thao tác rỗng âm thầm.

Các đầu vào của một module Terraform được vendor không phải là đích patch, và sự vắng mặt này đáng được nêu rõ. Chúng là các đối số của khối module của component đó, mà provider terraform ghi vào cấu hình gốc của ranh giới: HCL gốc, nên là mờ đục theo quy tắc ở trên, và là một artifact của toàn bộ ranh giới chứ không phải của node có đầu ra mà bước đó patch. Vì vậy không có vị trí nào mà từ đó một bước pipeline có thể trỏ tới chúng, và nó không thể làm gì để thay đổi những gì một module Terraform được lấy nguồn nhận được. Các giá trị đó được định hình tại nơi chúng được viết — trong valuesMapping: của Recipe cơ sở.

Bước có điều kiện — when:

Một bước pipeline có thể mang trường when: tùy chọn: một template Go nội tuyến mà trình biên dịch đánh giá tại thời điểm duyệt pipeline, dựa trên cùng ngữ cảnh template và bộ đánh giá mà phần thân with: của bước sử dụng. Kết quả được render 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: tập tài liệu được chuyển sang bước kế tiếp mà không thay đổi, và bước bị bỏ qua không đóng góp gì — không có patch, không có tác dụng phụ, không có bản ghi nào cho thấy nó đã chạy.
  • Một when: rỗng hoặc vắng mặt luôn chạy bước.

when: và optional: độc lập với nhau. when: quyết định một bước có chạy hay không; optional: làm nhẹ lỗi của một bước đang chạy. Một bước có thể khai báo cả hai — when: kiểm soát việc đi vào, và nếu bước thực sự chạy, optional: quyết định cách xử lý lỗi bên trong nó. Một template when: không render được là lỗi soạn thảo và dừng quá trình build bất kể optional:.

Văn bản when: sau khi render được đánh giá theo quy tắc template boolean dùng chung: các chuỗi true, True và TRUE, mọi số khác không, và mọi chuỗi không rỗng khác là đúng; các chuỗi false, False và FALSE, chuỗi rỗng và số không là sai.

Mẫu FeatureRecipe cho thông tin xác thực

Khi một FeatureRecipe hiện thực một Feature thông tin xác thực (một Feature được gắn nhãn feature.aggrega.ai/kind: secret), nó có thể tuân theo Nguyên tắc Plugin hai phần: một pipeline nối một plugin Fetcher (tạo CRD dành riêng cho vault) và một plugin Injector (gắn secret vào container đích), hình dạng mà examples/04-secrets mô tả. Các FeatureRecipes thông tin xác thực của thư viện chuẩn không khai báo pipeline: nào và tự render tài nguyên secret; xem examples/05-credential-features.

Một credential FeatureRecipe được render qua cùng lượt Resource Generation như của bất kỳ attachment nào khác, và pipeline: của nó thực thi theo cùng các điều kiện: trình biên dịch duyệt mọi attachment có việc trong lượt đó như một chuỗi có thứ tự duy nhất và chạy pipeline đã khai báo của từng attachment, với cùng ngữ nghĩa tập tài liệu /own và /host. Một attachment tham gia chuỗi đó vì một trong hai lý do — FeatureRecipe của nó khai báo một input kind, nên nó tự sinh tài nguyên của riêng mình, hoặc nó khai báo một pipeline:, nên nó viết lại các tài liệu đã được phát ra. Do đó, một credential attachment có thể can thiệp vào các tài liệu đã render của component chủ — gắn một secret volume, thêm một tham chiếu env — đúng như một attachment vận hành có thể làm, và khác biệt duy nhất giữa hai loại là nơi các tệp do chính nó sinh ra được đặt.

Trên một component, khai báo độ nhạy cảm trên Feature đi theo valuesMapping: của FeatureRecipe đúng như khai báo của một Component đi theo Recipe của nó. Khi một FeatureRecipe render từ một source: không có valuesMapping:, các giá trị mà target của nó nhận được có khóa là các đường dẫn lá mà Feature khai báo, nên một lá được khai báo sensitive: true sẽ đánh dấu khóa đã render của nó. Khi FeatureRecipe khai báo một valuesMapping:, các khóa là do chính template đó tự đặt ra, không khai báo nào gọi tên chúng, và bản build in ra một cảnh báo tư vấn cho mỗi lá như vậy, nêu tên attachment, lá và FeatureRecipe. Một Feature gắn vào một boundary không phát sinh cảnh báo nào: .values của nó luôn rỗng, nên không lá đã khai báo nào có giá trị để đánh dấu — xem A declared-sensitive value reaches the target through a values mapping (Một giá trị được khai báo nhạy cảm đến được target thông qua một values mapping).

Khối provides: — công bố cho bên tiêu thụ

Khối provides: của một FeatureRecipe là đầu ra được công bố của nó: một map giá trị chuỗi gồm các Go template được đánh giá trong phạm vi riêng của attachment (.values, .infra, .locals đã được phân giải đầy đủ của FeatureRecipe, cùng .context.instance_id và .context.rendered_name của node chủ). Các local được phân giải trước, nên một mục provides: đọc chúng và nhận các giá trị đã phân giải; việc nêu tên một khóa mà khối locals: không khai báo sẽ dừng build. Đây là cách một attachment cho bên tiêu thụ biết nó đã tạo ra gì — tên của một resource được phát ra, một khóa dữ liệu được sinh ra, một danh tính cloud — mà bên tiêu thụ không phải suy ra lại danh tính đó từ cùng các đầu vào.

Bên tiêu thụ đọc nó tại .features.<instance-name>.provides.<key> (hoặc .features.<slot>.provides.<key> đối với một attachment credential), tương tự .context.uses.<alias>.provides đối với một cạnh uses. Khi attachment được viết trên một trong các kết nối của bên tiêu thụ, bên tiêu thụ đọc cùng map đó dưới kết nối ấy, tại .context.uses.<alias>.features.<slot>.provides.<key>, và attachment không nằm trong .features của nó (xem Các attachment của một kết nối). Khối inject: riêng của attachment phân giải các tham chiếu from: của nó dựa trên cùng map đó, nên tác giả có thể chọn một trong hai kênh: provides để đọc trong template, inject để đưa vào một biến môi trường, tệp hoặc đối số.

# FeatureRecipe: emits a ServiceAccount and publishes its name.
provides:
name: "{{ .infra.service_account_name }}"
# Consuming Recipe: binds the pod to what the attachment published.
workload: |
serviceAccount: "{{ .features.identity.provides.name }}"

Khi Feature mà FeatureRecipe này implements khai báo một hợp đồng schema.provides, hợp đồng đó được áp dụng lên FeatureRecipe: mọi khóa mà Feature khai báo phải xuất hiện trong provides: của FeatureRecipe, nếu không build sẽ dừng và nêu tên khóa bị thiếu. Các khóa được công bố thêm đều được phép — hợp đồng là mức sàn, không phải mức trần. Các giá trị không bao giờ bị kiểm tra; chúng là các con trỏ tất định, không trong suốt, được runtime phân giải.

Việc phân giải diễn ra một lần cho mỗi attachment, trước khi bên tiêu thụ render, và cùng một map đã phân giải được dùng cho lần đọc của bên tiêu thụ, cho việc kiểm tra hợp đồng và cho Resource Generation riêng của attachment — vì vậy những gì bên tiêu thụ đọc và những gì attachment phát ra không thể mâu thuẫn nhau.

Provider & implements

spec.capability là bắt buộc và nêu tên provider có plugin kết xuất Wasm kết xuất đầu ra của FeatureRecipe (helm, helm-chart, compose, v.v.), theo cùng điều kiện như spec.capability của một Recipe (xem entities/recipe.md): một bản ghim phiên bản chọn phiên bản nào của plugin đó kết xuất đầu ra, và không thuộc tên của FeatureRecipe — một Manifest ánh xạ một FeatureRecipe khai báo capability: "compose:1.2.3" thành compose/<name>:<version>, và một giá trị ánh xạ ghi bản ghim vào tên 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. Trường implements gắn FeatureRecipe với giao diện Feature của nó và hỗ trợ khớp chính xác, khớp theo dải tương thích phiên bản chính, hoặc khớp không theo phiên bản — xem vocabulary/inheritance-and-interface để biết ngữ nghĩa khớp phiên bản của implements.

Phạm vi thực thi — spec.executionScope

Enum tùy chọn spec.executionScope chọn mô hình điều phối cho Resource Generation. Hai giá trị được chấp nhận; giá trị mặc định khi bỏ qua trường này là component.

  • component (mặc định). Resource Generation của FeatureRecipe chạy một lần cho mỗi instance component được gắn. Mỗi lần gọi nhận một ngữ cảnh template riêng cho từng component, có gốc tại .context.*: .context.instance_id, .context.inject, .context.uses, .context.annotations, v.v. Các khối valuesMapping:, workload: và artifacts: của nó cũng đọc .context.used_by, tức các component có mục uses trỏ tới host — mỗi component kèm danh tính, socket, những gì nó công bố, cùng namespace và boundary mà nó được đặt vào — điều mà không template nào do chính host render có thể thấy.
  • boundary. Resource Generation chạy một lần cho mỗi boundary được gắn, bất kể có bao nhiêu component trong cây con của boundary tiêu thụ feature đó. Mỗi lần gọi nhận một ngữ cảnh template ở phạm vi boundary, có gốc tại .boundary.* thay vì .context.*.

Cơ chế chặn injectMapping mô tả ở trên luôn áp dụng theo từng consumer bất kể executionScope. Mỗi component dùng feature vẫn nhận bản viết lại .context.inject riêng ở phía caller. Chỉ bước Resource Generation (source/valuesMapping và mảng pipeline) được khử trùng lặp ở phạm vi boundary.

Vì vậy, các template của một FeatureRecipe phạm vi boundary chạy trong hai phạm vi. injectMapping của nó chạy một lần cho mỗi component mà attachment chạm tới, trên ngữ cảnh của component đó — chính ngữ cảnh mà injectMapping của một FeatureRecipe phạm vi component đọc: .context.*, .attachment_name, .features, và .values, .infra và .locals riêng của attachment. .infra của nó là khối infra: của attachment boundary, và .locals của nó là khối được đánh giá một lần cho boundary. Mọi template khác mà nó viết — trong đó có locals:, provides:, source:, valuesMapping: và artifacts: của nó cùng with: và when: của các bước pipeline — chạy một lần cho boundary, trên ngữ cảnh phạm vi boundary mô tả bên dưới. Mỗi template được kiểm tra theo phạm vi mà nó chạy: một valuesMapping: đọc .context.instance_id làm dừng bản dựng, còn một injectMapping đọc nó sẽ render danh tính của component đó. .boundary không được đặt trong ngữ cảnh của bất kỳ component nào, nên một injectMapping đọc nó làm dừng bản dựng và nêu tên tham chiếu, bất kể executionScope của FeatureRecipe là gì.

Ngữ cảnh template phạm vi boundary

Khi executionScope: boundary, các template của FeatureRecipe ngoài injectMapping của nó được đánh giá dựa trên một khung nhìn .boundary.* của boundary mà feature được gắn vào. Khung nhìn này cung cấp:

  • .boundary.path — đường dẫn của boundary Release mà feature được gắn vào: tên các boundary từ ngoài cùng vào trong, nối bằng / (bridge, bridge/frontend). Nó nêu tên boundary, không phải thư mục mà đầu ra của nó được ghi vào — thư mục đó do directory: đặt (thay thế .context.instance_id).
  • .boundary.assembly_path — thư mục, tương đối so với thư mục đầu ra của bản dựng, mà đầu ra riêng của attachment được lắp ráp vào: directory: và subDirectory: đã đánh giá của boundary, tức thư mục mà bản dựng định tuyến đầu ra đó tới (bridge/compose). Nó bằng source_assembly_path hoặc target_assembly_path của một đầu mút kết nối đúng khi đầu mút đó render vào cùng tệp đã lắp ráp, nên một FeatureRecipe so sánh chúng để phân biệt một kết nối nằm trong tệp của chính nó với một kết nối ở tệp khác.
  • .boundary.boundary_name — tên của boundary như được viết trong Release.
  • .boundary.components — một map với khóa là instance ID, chứa mọi component trong cây con của boundary (instance_id, component, resolved_version, boundary_path).
  • .boundary.internal_uses_edges — các cạnh uses: có cả hai đầu mút nằm trong cây con của boundary này (mẫu compose-bridge liệt kê các cạnh này, giữ lại những cạnh có hai đầu mút được lắp ráp vào tệp compose của chính nó và được đặt trên các mạng khác nhau của tệp đó, để suy ra cấu hình proxy cho từng cạnh). Mỗi cạnh mang các provides đã phân giải của đầu mút, các biến môi trường được inject, và vị trí đặt của từng đầu mút: source_namespace và target_namespace, annotation aggrega.ai/namespace áp dụng cho đầu mút đó — là thiết lập trong mục Release của chính nó nếu có, nếu không thì của boundary chứa nó; source_boundary_path và target_boundary_path, đường dẫn của boundary Release chứa nó; và source_assembly_path và target_assembly_path, thư mục dưới thư mục đầu ra của bản dựng mà provider của nó lắp ráp nó vào, được ghép từ directory: và subDirectory: đã đánh giá của boundary chứa nó (bridge/compose). Hai đầu mút có cùng một đường dẫn lắp ráp sẽ render vào một tệp đã lắp ráp, và compose provider đọc đường dẫn lắp ráp làm mạng của đầu mút khi không có namespace nào áp dụng.
  • .boundary.outgoing_cross_boundary_uses_edges — các cạnh có nguồn nằm trong cây con và đích nằm ngoài.
  • .boundary.incoming_cross_boundary_uses_edges — các cạnh có đích nằm trong cây con và nguồn nằm ngoài (được dùng bởi các bộ tổng hợp kiểu ingress).
  • .boundary.cross_boundary_uses_edges — hợp của các cạnh liên boundary đi vào và đi ra, khi FeatureRecipe cần khung nhìn liên boundary đầy đủ.
  • .boundary.labels — hợp của các label trong cây con, giữ nguyên thứ tự do tác giả viết.
  • .boundary.annotations — các annotation riêng của boundary cộng với phần kế thừa theo cascade.
  • .boundary.feature_attachments — mọi feature được gắn tại boundary này (để một FR phạm vi boundary có thể xem xét các feature ngang hàng nếu cần).

Trụ cột .infra trên một FR phạm vi boundary phân giải thành khối infra: của feature gắn vào boundary (kích thước vật lý do phía Release viết cho lần gắn boundary đó). .values luôn rỗng đối với các FR phạm vi boundary: quy tắc tách trụ cột của schema Release cấm values: trên các lần gắn Feature ở cấp Release, nên một feature gắn vào boundary không mang giá trị nào để chiếu. Các FR phạm vi boundary cần dữ liệu dạng tham số nên tiêu thụ nó qua .infra (bề mặt viết cấu hình boundary-feature của operator) hoặc qua .boundary.annotations (các giá trị chuỗi có thể phân giải theo cascade, được viết trên boundary hoặc bất kỳ boundary tổ tiên nào); .parameters không thuộc khung nhìn, và một template đọc nó sẽ dừng lại, nêu tên các gốc mà khung nhìn định nghĩa. .locals vẫn là khối locals riêng của FR. .steps và .metadata giữ nguyên không đổi.

Danh sách trường template được phép ở phạm vi boundary

Các FR phạm vi boundary chỉ được tham chiếu các trường có trong khung nhìn phạm vi boundary, trong mọi template trừ injectMapping. Viết một template như vậy tham chiếu trường chỉ dành cho từng component (ví dụ .context.instance_id, .context.inject, .context.uses) khi executionScope: boundary khiến FeatureRecipe không qua được kiểm tra hợp lệ lúc parse, với lỗi nêu tên FR, trường vi phạm và các trường mà khung nhìn phạm vi boundary định nghĩa. Quy tắc đối xứng áp dụng theo chiều ngược lại: một FR phạm vi component tham chiếu các trường .boundary.* cũng không qua được cùng bộ kiểm tra đó. injectMapping được kiểm tra theo ngữ cảnh của component mà nó chạy trong đó, ở cả hai phạm vi, nên nó có thể đọc .context.*, và một tham chiếu tới .boundary trong nó sẽ dừng lại, nêu tên tham chiếu và các gốc mà ngữ cảnh đó định nghĩa.

Bộ kiểm tra chạy cùng phép duyệt template-AST mà danh sách biến được phép của path-template sử dụng, với một tập tham chiếu khác nhau cho mỗi phạm vi.

Khử trùng lặp và đầu ra của Resource Generation

Với executionScope: boundary, trình biên dịch khử trùng lặp Resource Generation theo bộ (boundary_path, FR-instance). Hai component trong cùng một cây con boundary cùng tiêu thụ một feature gắn vào boundary sẽ kích hoạt một lần gọi FR, không phải hai. Các lần gắn cùng feature ở những boundary khác nhau chạy độc lập theo từng boundary.

Một FR phạm vi boundary xuất ra một tập tệp không trung gian cho mỗi bộ (boundary_path, FR-instance), và vị trí của chúng tùy thuộc vào cách provider kết hợp đầu ra của boundary. Riêng tên instance là tọa độ ở đây, trong khi một lần gắn phạm vi component còn mang cả component của nó: một feature phạm vi boundary được gắn vào boundary chứ không vào component nào, nên thư mục boundary bao quanh đã nói lên mọi điều mà một phân đoạn component sẽ nói, và không có component nào để đặt tên.

Một provider ghi từng tài liệu trực tiếp tại thư mục boundary sẽ khai báo rằng đích của nó chỉ đọc các tệp nằm trực tiếp trong một thư mục. Do đó không có thư mục bao quanh nào để một lần gắn nằm trong, và tên instance trở thành tiền tố tên tệp: <boundary_directory>/<fr-provider>/<feature-instance>--<file>, bên cạnh các tệp riêng của boundary. Tên instance được mã hóa, vì tên tệp không có dấu phân cách nào để dựa vào, và nó gặp tên riêng của tệp tại một ranh giới hai ký tự mà không tọa độ đã mã hóa nào có thể chứa — nên hai lần gắn cùng xuất một tên tệp vẫn tạo ra hai tệp.

Một provider kết hợp đầu ra của boundary vào một cấu trúc bao quanh — một chart chứa một chart cho mỗi bên đóng góp, một cấu hình gốc chứa một module cho mỗi bên đóng góp — đặt mỗi bên đóng góp vào một thư mục con riêng, và một lần gắn boundary cũng là một bên đóng góp như mọi bên khác. Khi đó đầu ra của nó nằm tại <boundary_directory>/<fr-provider>/<contributors-directory>/<feature-instance>/, trong đó <contributors-directory> là tên mà đích đó gọi nơi chứa các đơn vị con. Thư mục con mang tên instance của lần gắn, chính là tên bạn đã viết cho nó trong khối features: của boundary, nên thư mục do một lần build tạo ra là thư mục bạn có thể tìm thấy trong những gì bạn đã viết.

Đầu ra trung gian chảy tới bộ lắp ráp theo từng (path, provider) của boundary, tại đường dẫn đã đánh giá của FR, dưới spec.capability riêng của FR — đây là cơ chế mà Feature core/compose-bridge dùng để gộp một dịch vụ bridge cùng với các bên đóng góp compose theo từng component tại cùng một đường dẫn lắp ráp. Đầu ra như vậy chỉ được ghi như một phần của tệp được lắp ráp tại đó từ các component của boundary, nên khi không component nào rơi vào đường dẫn đó — chẳng hạn mọi component đều bị subDirectory: của nó gửi đi nơi khác — bản dựng dừng lại, nêu tên boundary, Feature, đường dẫn mà đầu ra của nó được định tuyến tới và provider, thay vì ghi đầu ra vào hư không (xem “A boundary-level Feature’s output reaches no assembled file (Đầu ra của một Feature cấp boundary không tới được tệp đã lắp ráp nào)” trong fatal-halts.md).

Phân giải provides: có nhận biết cascade

Các FR phạm vi boundary tạo ra một tập provides: cho mỗi bộ (boundary_path, FR-instance), được đánh giá một lần. Template provides: của FR được đánh giá với ngữ cảnh template phạm vi boundary (nên nó có thể tham chiếu .boundary.components, .boundary.path, .infra, nhưng không thể tham chiếu các trường theo từng consumer và không thể tham chiếu .values). Các giá trị provides là hằng số đối với các consumer — mọi consumer trong cây con của boundary đều thấy cùng các giá trị được cung cấp.

Phân giải phía consumer đối với provides của FR phạm vi boundary đọc cùng một lần đánh giá đó ở mọi nơi. Mỗi component mà attachment chạm tới đọc nó tại .features.<instance-name>.provides.<key> — trong các template của Recipe của chính nó và trong injectMapping riêng của FeatureRecipe, vốn chạy trong ngữ cảnh của component đó. Một Component consumer đọc qua một cạnh uses mà attachment mang theo, tại .context.uses.<feature-alias>.provides.<provided-name>, nhận được cùng các giá trị: trình biên dịch phân giải nó thành provides: của FeatureRecipe phạm vi boundary cho boundary mà consumer nằm trong đó, đi từ cạnh uses của consumer — cạnh mang danh tính feature-instance theo từng attachment — đến provides: của FR phạm vi boundary. Một bước tiền xử lý đánh giá các provides đó trước khi lắp ráp consumer, nên các giá trị đã có sẵn khi pipe của consumer được xây dựng.

Một hiệu ứng theo từng consumer là một bảng trong provides: được injectMapping đọc. Một FeatureRecipe phạm vi boundary cần thay đổi điều gì đó cho từng consumer sẽ tính, một lần, một bảng có khóa theo consumer từ các kết nối của boundary trong provides: của nó, và injectMapping của nó đọc các dòng của component hiện tại — (index .features .attachment_name).provides, có khóa theo .context.instance_id — rồi cung cấp chúng qua pipe riêng của consumer, theo quy tắc mà mọi ánh xạ đều tuân theo (xem Một ánh xạ có thể viết lại những gì). Trình biên dịch chuyển tiếp bảng mà FeatureRecipe đã viết và không đọc gì trong đó.

Mẫu compose-bridge

FeatureRecipe compose-bridge là mẫu FR phạm vi boundary chuẩn mực, và nó là nội dung catalog được viết bằng các cơ chế nêu trên: cả trình biên dịch lẫn compose provider đều không chứa logic nào của bridge, nên một catalog có thể hiện thực Feature core/compose-bridge theo cách khác. Một feature core/compose-bridge được gắn tại một boundary cha chứa hai boundary con (ví dụ services-net và data-net) có chung directory:, mỗi boundary con mang annotation aggrega.ai/namespace riêng (aggrega.ai/namespace: services-net, aggrega.ai/namespace: data-net) để mỗi cái nằm trên một mạng riêng; không có các annotation này, cả hai dùng chung một mạng được đặt tên theo đường dẫn của tệp compose của chúng và tiếp cận nhau mà không cần bridge. executionScope: boundary của nó chạy FR một lần cho mỗi lần gắn vào boundary cha.

provides: của nó tính bảng bridge, một lần. Từ .boundary.internal_uses_edges, nó giữ lại những cạnh có hai đầu mút được lắp ráp vào tệp compose của chính nó — source_assembly_path và target_assembly_path đều bằng .boundary.assembly_path — và nằm trên các mạng khác nhau của tệp đó; mạng của một đầu mút là aggrega.ai/namespace của nó, nếu không có thì là đường dẫn lắp ráp của nó. Một cạnh giữa hai tệp compose không được bắc cầu, và consumer của nó giữ tên riêng của đích. Mỗi cạnh được bắc cầu nhận một cổng lắng nghe — chính cổng của đích, hoặc, nếu một cạnh trước đó đã lắng nghe trên cổng đó, cổng trống đầu tiên bằng hoặc lớn hơn portBase của attachment (mặc định 10000) — và một upstream, tức host được công bố của đích (trường provides mà providesField của attachment nêu tên, mặc định host) và port của nó; upstream được suy ra từ cạnh, không bao giờ viết tay. Từ cùng bảng đó, nó tính bản viết lại của mỗi consumer: một biến mà cạnh cung cấp từ trường host trở thành aggrega-gw:<listen port>, hoặc aggrega-gw khi cùng cạnh đó cũng cung cấp một biến từ port, biến này khi đó trở thành cổng lắng nghe.

injectMapping của nó cung cấp các dòng của từng consumer. Chạy trong ngữ cảnh của mỗi consumer, nó đọc các dòng của consumer đó trong bảng tại .features.<attachment>.provides và cung cấp chúng đè lên các giá trị mà kết nối riêng của consumer đã cung cấp (ví dụ DB_HOST), tức là chặn; một consumer không có dòng nào thì không nhận được gì. Khi một Feature khác được gắn vào consumer đã cung cấp khóa đó — qua khối inject: của nó hoặc injectMapping của nó — bản build dừng lại, nêu tên cả hai Features, thay vì thay thế phần cung cấp đó (xem “Two attached Features deliver one key, the later through its FeatureRecipe’s injectMapping (Hai Features được gắn cùng cung cấp một khóa, cái sau qua injectMapping của FeatureRecipe của nó)” trong fatal-halts.md). listen của gateway và bản viết lại của consumer được đọc từ một bảng, nên chúng khớp nhau theo từng cạnh ngay từ cách xây dựng, kể cả các xung đột được gán lại bằng portBase.

valuesMapping của nó viết gateway. Mảnh compose riêng của FeatureRecipe khai báo dịch vụ aggrega-gw. Khi có bất cứ thứ gì được bắc cầu, valuesMapping của nó thêm một khối nginx stream server cho mỗi cạnh được bắc cầu (listen <port>; set $uN <target-host>:<target-port>; proxy_pass $uN;, dưới một chỉ thị resolver để mỗi upstream được phân giải lúc kết nối thay vì một lần lúc khởi động; ký tự $ trong các biến đó được viết thành $$ để cơ chế nội suy $ của Docker Compose để lại một $ nguyên văn cho nginx), được cung cấp dưới dạng một compose config được mount — một mục configs: cấp cao nhất với content: inline, được tham chiếu từ aggrega-gw và mount tại /etc/nginx/nginx.conf (nên nginx nạp nó mà không cần viết command:). configs.content inline yêu cầu Docker Compose ≥ 2.23.1. Nó cũng nêu tên mọi đầu mút được bắc cầu dưới x-aggrega-networks-of của gateway, mà compose provider phân giải thành các mạng nơi những đầu mút đó được đặt, nên gateway tham gia mọi mạng mà các cạnh được bắc cầu của nó trải qua (mạng của consumer và mạng của đích) — lúc runtime consumer có thể truy cập aggrega-gw:<port> và gateway có thể proxy_pass tới đích. Khi không có gì được bắc cầu, gateway mà mảnh compose khai báo vẫn được render, ở trạng thái nhàn rỗi: không có cấu hình, không có mạng bổ sung và không có bản viết lại.

Bộ lắp ráp compose theo từng (path, provider) gộp gateway cùng với các bên đóng góp theo từng component tại cùng đường dẫn đã đánh giá: một docker-compose.yaml chứa mọi component cùng với gateway bridge. Khi không component nào của boundary được lắp ráp vào tệp của gateway, bản build dừng lại thay vì ghi gateway vào hư không. Upstream là một con trỏ tới compose service, xác định tại thời điểm biên dịch; DNS runtime của compose phân giải nó (không có phân giải runtime tại thời điểm biên dịch).

Render sau các bên gọi — spec.readsCallerRenderFacts

Khóa tùy chọn spec.readsCallerRenderFacts (boolean, mặc định false) khai báo rằng các template của FeatureRecipe này đọc những gì các component kết nối tới host của nó đã render: các render fact mà provider của từng bên gọi đó báo cáo về đầu ra nó đã phát ra. Một provider báo cáo gì, và dưới những tên nào, là hợp đồng riêng của provider đó; Reporting facts about what a guest emitted (Báo cáo fact về những gì một guest đã phát ra) mô tả các fact mà một provider có thể báo cáo.

Khi nào một attachment như vậy render. Bản build render các component của nó lần lượt từng cái một, theo một thứ tự cố định, và một attachment thường render ngay sau component mà nó được gắn vào. Một component kết nối tới host và đứng sau trong thứ tự đó thì tại thời điểm ấy chưa render, nên chưa có gì nó phát ra để đọc. Một attachment có FeatureRecipe đặt readsCallerRenderFacts: true thay vào đó sẽ render khi mọi component trong bản build đã render xong, cùng với mọi attachment không đặt khóa này lẫn readsTargetRenderFacts — nhờ vậy bản render của từng bên gọi đã hoàn tất trước khi attachment được đánh giá. Đầu ra của nó nằm ở đúng chỗ lẽ ra nó nằm và dưới cùng các tên; khóa này thay đổi thời điểm attachment render, chứ không thay đổi những gì nó render. Có một hệ quả về thứ tự từ việc render muộn hơn: khi FeatureRecipe mang một pipeline viết lại các tài liệu của component host và provider của host ghi ra các tài liệu rời rạc, các bước đó chạy sau pipeline của các attachment khác của host thay vì theo thứ tự gắn của chúng.

Nó đọc gì. Khi khóa được đặt, mỗi mục của .context.used_by mang .render_facts: các render fact của bên gọi, được đánh khóa theo tên fact. Mọi render fact đều là một danh sách, nên template luôn duyệt qua nó — ngay cả khi nó chỉ chứa một mục. Các mục của nó có thể đến từ bản render riêng của bên gọi và từ bản render của các Features được gắn vào bên gọi: các danh sách mà một tên nhận được từ mỗi nguồn được nối thành một, các lần gọi provider của chính bên gọi đứng trước, sau đó là từng Feature của nó theo thứ tự chúng đã render. Một Feature của bên gọi mà bản thân nó cũng đặt khóa này thì cũng render sau mọi component, nên những gì nó báo cáo không nằm trong số đó. Một bên gọi có các provider không báo cáo gì sẽ mang một .render_facts rỗng, nên một tên không ai báo cáo sẽ được đọc là không có gì:

artifacts:
callers.yaml: |
callers:
{{- range .context.used_by }}
- component: {{ .component_id }}
ports:
{{- range .render_facts.ports }}
- {{ .port }}
{{- end }}
{{- end }}

Những tên fact nào tồn tại, và mỗi mục chứa gì, là hợp đồng được tài liệu hóa của provider của bên gọi — ví dụ, của helm provider là các render fact của nó, nêu tên các label của những pod mà nó đã render. Các fact của bên gọi nằm trên các kết nối mà valuesMapping:, workload: và artifacts: của FeatureRecipe đọc; with: và when: của một bước pipeline: hoàn toàn không thấy các component kết nối tới host, nên một bước chỉ đọc các fact của chính host. Mọi FeatureRecipe được gắn vào một component — dù có đặt khóa hay không — đều đọc các fact của chính component tại .context.render_facts, với cùng hình dạng; template context mô tả cả hai.

Khai báo nó mỗi khi một template đọc các fact. Một template viết inline trong một FeatureRecipe không đặt khóa — trong valuesMapping:, workload: hoặc một mục artifacts: của nó — mà đọc render_facts bên dưới .context.used_by sẽ dừng bản build trước khi bất cứ thứ gì được render, nêu tên tham chiếu và trường nơi nó được viết (xem “A template reads its callers’ render facts without declaring it (Một template đọc render fact của các bên gọi mà không khai báo)” trong fatal-halts.md). Phép kiểm tra đọc template như được viết, nên nó không thấy một tham chiếu được dựng trong lúc template chạy, hoặc một tham chiếu được viết trong nội dung nhập từ một tệp hay một thư viện — và một template đọc một trường tên render_facts từ một danh sách nào khác ngoài .context.used_by, hoặc đọc các fact của chính host dưới dạng .render_facts bên trong {{ with .context }} cạnh nó, sẽ bị coi là đọc các fact của bên gọi; hãy viết fact của chính host đầy đủ là .context.render_facts. Chính khóa, chứ không phải phép kiểm tra, quyết định khi nào attachment render, nên hãy đặt nó trên mọi FeatureRecipe có template đọc render fact của các bên gọi, bất kể chúng truy cập bằng cách nào; việc đặt nó không tốn gì ngoài việc render muộn hơn.

Một bước pipeline chỉ đọc các fact của chính host. Một bước có thể viết lại các tài liệu của chính component host, và đầu ra riêng của một component vẫn như nhau bất kể ai kết nối tới nó, nên with: và when: của một bước không bao giờ thấy các component kết nối tới host — dù FeatureRecipe có đặt khóa hay không, vì khóa chỉ quyết định khi nào attachment render và không ảnh hưởng gì tới những gì một bước thấy. Do đó, with: hoặc when: của một bước được viết inline mà đọc render_facts bên dưới .context.used_by sẽ dừng bản build trước khi bất cứ thứ gì được render, với mã ngắn E0326, nêu tên tham chiếu và trường của bước — thay vì render ra một giá trị rỗng. Hãy đọc các fact của chính host trong một bước tại .context.render_facts, viết đầy đủ, và đọc các fact của bên gọi trong valuesMapping:, workload: hoặc artifacts: của FeatureRecipe. Phép kiểm tra này đọc template như được viết, với cùng các giới hạn như phép kiểm tra ở trên.

Phạm vi. Khóa áp dụng cho một FeatureRecipe render một lần cho mỗi component — executionScope: component, giá trị mặc định. Một FeatureRecipe khai báo executionScope: boundary render ở đúng chỗ nó luôn render dù có đặt khóa hay không, và các template tạo ra tài nguyên của nó đọc .boundary thay vì .context.

Kết xuất sau các đích — spec.readsTargetRenderFacts

Khóa tùy chọn spec.readsTargetRenderFacts (boolean, mặc định false) khai báo rằng các template của FeatureRecipe này đọc những gì mà các component được host của nó nối tới đã render: các render fact mà provider của từng target đó báo cáo về đầu ra nó đã phát ra. Khóa này đọc đầu kia của một kết nối so với readsCallerRenderFacts: các component mà các mục uses của host trỏ tới, thay vì các component có mục uses trỏ tới host. Mọi điều về bản thân các fact đều được đọc theo cùng một cách.

Khóa nào trong hai khóa cũng khiến attachment kết xuất sau mọi component. Một attachment có FeatureRecipe đặt readsCallerRenderFacts: true, readsTargetRenderFacts: true, hoặc cả hai, sẽ kết xuất khi mọi component trong bản build đã kết xuất xong, như phần trên mô tả — chỉ có một lần kết xuất muộn như vậy, và tác động của nó tới nơi đầu ra của attachment được đặt và tới thứ tự các bước pipeline của nó là như nhau, bất kể khóa nào đã chuyển attachment tới đó. Hai khóa chỉ khác nhau ở chỗ những kết nối nào mang fact trên context của attachment: một đích đứng sau host trong thứ tự của bản build đã kết xuất xong vào lúc đó, nên những gì nó phát ra đã có sẵn để đọc.

Những gì nó đọc. Khi khóa được đặt, mỗi mục của .context.uses mang .render_facts: các render fact của target, được đánh khóa theo tên fact, với cùng hình dạng mà mục của một caller mang. Mỗi render fact là một danh sách, vì vậy template luôn duyệt qua nó bằng range. Các mục của nó có thể đến từ lần render của chính target và từ các lần render của các Features được gắn vào target: các lời gọi provider của chính target đứng trước, sau đó là từng Feature của nó theo thứ tự chúng đã render. Một Feature của target mà bản thân nó render sau mọi component thì không nằm trong số đó. Một target có các provider không báo cáo gì sẽ mang một .render_facts rỗng. Template đọc các fact của một kết nối bên dưới alias của nó, .context.uses.<alias>.render_facts.<name>, hoặc lần lượt của từng kết nối:

artifacts:
targets.yaml: |
targets:
{{- range .context.uses }}
- component: {{ .target }}
ports:
{{- range .render_facts.ports }}
- {{ .port }}
{{- end }}
{{- end }}

Một FeatureRecipe không đặt khóa này sẽ không thấy .render_facts trên bất kỳ kết nối nào, dù nó đặt gì khác. Những tên fact nào tồn tại là hợp đồng được tài liệu hóa của provider của từng đích — của helm provider là các render fact của nó, nêu tên các label, controller selector và container port của các pod nó đã kết xuất, và do đó là những gì một egress policy cần để chọn chính xác các pod mà host của nó có thể truy cập.

Hãy khai báo nó mỗi khi một template đọc các fact. Một template viết inline trong một FeatureRecipe không đặt khóa này (trong valuesMapping:, workload: hoặc một mục artifacts: của nó) mà đọc render_facts bên dưới .context.uses sẽ dừng build trước khi bất cứ thứ gì được render, với mã ngắn E0347, nêu tên tham chiếu và trường mà nó được viết trong đó (xem “A template reads its targets’ render facts without declaring it (Một template đọc các render fact của các target mà không khai báo)” trong fatal-halts.md). Việc đặt readsCallerRenderFacts không gỡ bỏ lỗi này. Phép kiểm tra đọc template như được viết, với cùng các giới hạn mà phép kiểm tra của caller có: nó không thấy một tham chiếu được xây dựng trong lúc template chạy, hoặc một tham chiếu được viết trong nội dung nhập từ một tệp hay một thư viện. Và một template có đọc .context.uses mà đồng thời đọc một trường tên render_facts từ một giá trị khác, kể cả mục của một caller bên trong {{ range .context.used_by }}, sẽ được xem là đang đọc các fact của target. Một template đọc fact của cả hai đầu thì đặt cả hai khóa.

Một bước pipeline chỉ đọc các fact của chính host. with: và when: của một bước đọc các kết nối mà host tạo ra, như Recipe của chính host đọc chúng, và không bao giờ đọc render fact của các target, dù FeatureRecipe có đặt khóa này hay không. Một bước có thể viết lại các tài liệu của chính component host, và lần render của chính host đọc những gì các target của nó công bố, không bao giờ đọc những gì chúng đã phát ra. Vì vậy, with: hoặc when: của một bước được viết inline mà đọc render_facts bên dưới .context.uses sẽ dừng build trước khi bất cứ thứ gì được render, với mã ngắn E0348, nêu tên tham chiếu và trường của bước, thay vì render ra một giá trị rỗng. Hãy đọc các fact của target trong valuesMapping:, workload: hoặc artifacts: của FeatureRecipe.

Phạm vi. Giống như khóa của các caller: nó áp dụng cho một FeatureRecipe kết xuất một lần cho mỗi component. Một FeatureRecipe khai báo executionScope: boundary kết xuất ở nơi nó luôn kết xuất, dù có đặt khóa hay không, và các kết nối nó đọc dưới .boundary không mang render fact nào.

Khối locals:

FeatureRecipe.spec.locals: là một map gồm các chuỗi Go template có tên, tùy chọn, mà đầu ra sau khi render sẽ cung cấp một map .locals.* cho mọi template khác trong cùng FeatureRecipe. Đây là phiên bản riêng của FeatureRecipe tương đương với locals: của Recipe — nơi tính các chuỗi dẫn xuất một lần và tham chiếu chúng từ injectMapping, valuesMapping, pipeline[].with và provides mà không phải tính lại. Các assertions: của FeatureRecipe không đọc chúng: .locals của một assertion thuộc về Recipe của thành phần chủ, như assertions-block.md đã nêu. Đầu ra sau khi render của mỗi mục được lưu với khoảng trắng ở đầu và cuối đã bị loại bỏ. Khối này là một map, không phải một thân template đơn lẻ; một giá trị vô hướng ở vị trí này bị schema từ chối.

apiVersion: aggrega.ai/v1beta1
kind: FeatureRecipe
metadata:
name: regional-router
spec:
implements: core/regional-router:^1.0.0
capability: helm
locals:
region_prefix: "{{ .infra.region | lower }}"
fqdn_suffix: "{{ printf \"%s.svc.cluster.local\" .infra.namespace }}"
injectMapping: |
env:
"{{ .infra.target_var }}": "{{ .locals.region_prefix }}.{{ .infra.target_var | lower }}.{{ .locals.fqdn_suffix }}"

.locals.* áp dụng theo từng lần gọi: mỗi lần gọi FR tự phân giải khối locals: của riêng nó, và kết quả chỉ hiển thị với các template phía sau của chính lần gọi đó. Khối này được phân giải trước khi các template khác trên bề mặt soạn thảo của FR được đánh giá, nên mọi template đó đều thấy các giá trị đã phân giải.

Mỗi mục được đánh giá trên một ngữ cảnh khép kín: .context.instance_id, .context.rendered_name, .attachment_name, .values, .infra, và các mục của chính khối này đã được phân giải. Ngữ cảnh này được cố ý giới hạn hẹp hơn ngữ cảnh mà các template khác của FR đọc — một mục locals: không thể truy cập .context.annotations, .context.inject, .context.uses hay .provides, và một tham chiếu đến bất kỳ trường nào trong số đó sẽ làm dừng build, nêu tên tham chiếu. Các giá trị dẫn xuất cần đến những trụ cột đó thuộc về template đọc chúng, không thuộc về locals:.

Các tên trong ngữ cảnh đó trả lời những câu hỏi khác nhau, và một mục locals: đọc chúng đúng như các template khác của FeatureRecipe:

  • .context.instance_id là component chủ mà attachment đang được phân giải cho nó. Nó mang nghĩa component chủ trên mọi bề mặt template mà trình biên dịch đánh giá, nên cùng một tham chiếu được đọc theo cùng một cách dù bạn đang viết khối của thực thể nào.
  • .context.rendered_name là tên của component chủ theo cách provider của chính nó báo cáo — với helm, đó là tên release, tức danh tính của component chủ được viết bằng bảng ký tự mà một tên Kubernetes chấp nhận. Nó chỉ có mặt khi provider của component chủ báo cáo một tên, và việc đọc nó trên một component chủ mà provider không báo cáo tên nào sẽ làm dừng build.
  • .attachment_name là thể hiện attachment đang được phân giải — vị trí mà nó lấp trong featuresSchema của thực thể sở hữu, hoặc tên tự do mà bạn đặt cho nó.

Vì vậy, một mục locals: dẫn xuất tên cho một tài nguyên được phát ra sẽ kết hợp component chủ và attachment, đúng như một template artifacts: sẽ làm:

spec:
locals:
scrape_name: "{{ .context.instance_id }}-{{ .attachment_name }}" # api-scrape_target

Khi tên phải là tên mà nền tảng chấp nhận và provider của component chủ có báo cáo một tên, hãy kết hợp từ .context.rendered_name: với một component chủ tên my_api dưới helm và một attachment scrape, {{ .context.rendered_name }}-{{ .attachment_name }} cho ra my-zuapi-scrape, trong khi danh tính sẽ cho ra my_api-scrape, là tên mà Kubernetes từ chối. Xem Đặt tên cho một tài nguyên được render.

.values và .infra trong một mục locals: là các trụ cột của chính attachment, được khai báo trên phần khai báo attachment — không phải của component chủ.

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:
region_prefix: "{{ .infra.region | lower }}" # defined first
bucket: "{{ .locals.region_prefix }}-artifacts" # reads the entry above

Việc nối chuỗi chỉ chạy theo chiều xuống. Khi một mục đọc mục khác, thứ tự các mục quyết định build có thành công hay không: chuyển region_prefix xuống dưới bucket thì build sẽ dừng. Trình biên dịch không bao giờ sắp xếp lại khối để một tham chiếu phân giải được, nên việc sắp xếp lại một khối locals: là một thay đổi về hành vi, không phải thay đổi hình thức.

Một tham chiếu tới một mục mà khối định nghĩa ở phía sau sẽ dừng build và nêu lỗi thứ tự (hãy chuyển định nghĩa lên trên chỗ đọc nó); một tham chiếu tới một khóa mà khối hoàn toàn không khai báo sẽ dừng build và nêu tên khóa đó (hãy sửa chính tả). Việc kiểm tra đi theo 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, sẽ dừng build theo đúng các điều kiện mà cách viết trực tiếp gặp phải, và một khóa được đọc từ khối đặt trong ngoặc đơn cũng vậy — {{ (.locals).nope }} hoặc {{ ($.locals).nope }}. Có một cách viết thoát khỏi việc kiểm tra này: một khóa được truy cập qua một lời gọi mà văn bản template không thể gọi tên kết quả — {{ index .locals "nope" }}, hoặc {{ (default dict .locals).nope }}. Một trường được đọc từ kết quả của lời gọi như vậy không dừng build và hiển thị văn bản nguyên văn <no value>; cách đọc bằng index dừng build và nêu tên khóa, vì index dừng build trên mọi bề mặt template khi map mà nó đọc không chứa khóa đó — xem errors/fatal-halts.md “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)”. provides: đọc khối đã được phân giải đầy đủ, vì locals của FeatureRecipe này được phân giải trước provides của nó; một template provides: gọi tên một khóa chưa khai báo sẽ dừng build. Đây cũng chính là các quy tắc mà khối locals: của một Recipe tuân theo — xem entities/recipe.md “Khối locals:”.

Hành vi theo phạm vi. Với executionScope: component (mặc định), locals: được đánh giá cho từng thể hiện component được gắn, trên ngữ cảnh khép kín nêu trên. Với executionScope: boundary, locals: được đánh giá cho từng attachment boundary, trên khung nhìn phạm vi boundary có gốc tại .boundary.*; các trường theo từng component (.context.instance_id, .context.inject, .context.uses) và .attachment_name không khả dụng, vì FeatureRecipe chạy một lần cho boundary thay vì một lần cho mỗi component. Danh sách trường được phép cho template ở phạm vi boundary áp dụng cho locals: giống như cho các template khác trên bề mặt soạn thảo của FR. injectMapping, vốn chạy cho mỗi component mà attachment chạm tới, đọc lần đánh giá boundary duy nhất đó làm .locals của nó. Hợp đồng đánh giá — thứ tự viết, việc đọc mục anh em chỉ theo chiều xuống, hai trường hợp dừng — là giống hệt ở cả hai phạm vi; chỉ hình dạng ngữ cảnh xung quanh khác nhau.

Phân biệt với overlay injectMapping và mapping pipeline[].with. locals: tạo ra một map hiển thị trong ngữ cảnh cho các template phía sau; nó không đóng góp đầu ra. injectMapping ghi vào kênh .context.inject của bên tiêu thụ (thay đổi phía bên gọi). pipeline[].with cung cấp payload args cho Wasm plugin. Ba bề mặt này độc lập với nhau — một FeatureRecipe thường dùng cả ba cùng lúc, với locals: mang các chuỗi dẫn xuất dùng chung mà hai bề mặt kia tham chiếu.

Khối assertions:

FeatureRecipe.spec.assertions: là một map tùy chọn gồm các quy tắc có tên, biểu đạt các bất biến triển khai của FeatureRecipe — các quy tắc liên trường đúng với pipeline Wasm plugin, chart hoặc cơ chế cụ thể mà FeatureRecipe được xây dựng trê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à một thân Go template. Giống như các assertion của Recipe, các assertion của FeatureRecipe là thuộc tính của phần triển khai cụ thể; các quy tắc hợp đồng ở cấp Feature được áp dụng độc lập ở một giai đoạn pipeline sớm hơn.

spec:
implements: core/referenced-secret:^1.0.0
pipeline:
- id: fetch_secret
plugin: pipeline-step/aws-secrets-manager:1.2.0
function: step
assertions:
# aws-secrets-manager plugin 1.x requires an explicit region when none is
# implied through the Aggregate's infra block.
region-supplied-for-secrets-manager: |
{{- if not .values.region -}}
{{- if not .infra.aws.region -}}
{{- fail "aws-secrets-manager plugin 1.x requires either values.region or infra.aws.region to be set" -}}
{{- end -}}
{{- end -}}

Quy tắc ở trên dành riêng cho plugin aws-secrets-manager phiên bản 1.x; nó không áp dụng nếu một FeatureRecipe core/referenced-secret khác được gắn kết. Các quy tắc hợp đồng ở cấp Feature từ định nghĩa Feature vẫn được áp dụng song song.

Các assertion của FeatureRecipe được đánh giá sau khi gắn kết FeatureRecipe và trước giai đoạn Resource Generation. Ngữ cảnh template cho các FR phạm vi component phản chiếu ngữ cảnh assertion của Recipe (các trường của thể hiện thực thể cùng với .provides, .locals, .recipe.metadata, .recipe.source); đối với các FR phạm vi boundary (executionScope: boundary), các assertion được đánh giá theo khung nhìn phạm vi boundary (có các trường .boundary.*; không có các trường theo từng component). Để xem đầy đủ ngữ pháp soạn thảo và các ví dụ minh họa, hãy 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 FeatureRecipes không bao giờ cần đến trường này. Nó dành cho một FeatureRecipe có source: là một chart mà bạn dùng nguyên trạng — thường là một chart được tải về từ một registry — và chart đó render ra một tài liệu mà attachment không được phát ra: một Secret mà chart tạo mới ở mỗi lần render, hoặc một đối tượng mà component chủ hoặc operator đã cung cấp sẵn. omits: loại bỏ tài liệu như vậy khỏi những gì FeatureRecipe tạo ra — hoặc, đối với một tệp compose mà FeatureRecipe dùng làm source, là một service, một volume hoặc một config mà attachment không được đóng góp, và đối với một template CloudFormation mà nó dùng làm source, là một resource.

spec:
capability: helm
implements: core/observability/collector:1.0.0
source:
kind: helm-oci-chart
url: oci://registry.example.com/charts/collector
version: "0.9.1"
omits:
# The collector chart ships its own ServiceAccount; the host supplies one.
- kind: ServiceAccount
name: collector
- when: "{{ .infra.without_dashboards }}"
kind: ConfigMap
name: collector-dashboards

Khóa này được viết giống hệt trên một Recipe, và Recipe → Trường omits: là tài liệu tham chiếu đầy đủ của nó: mỗi trường của mục chọn gì, rằng when: được đánh giá trước và một giá trị false sẽ loại bỏ mục đó, rằng mọi mục được áp dụng phải loại bỏ được một thứ gì đó, nếu không bản dựng sẽ dừng lại và nêu tên mục đó, rằng nguồn vẫn được kết xuất đầy đủ và chỉ đầu ra của nó được lọc, và những provider nào tuân theo khóa này. Điều khác biệt trên một FeatureRecipe chỉ là nơi các template được đánh giá:

  • Các template của mỗi mục được đánh giá theo cùng ngữ cảnh mà valuesMapping: của FeatureRecipe này được đánh giá, ở phạm vi mà executionScope của nó chọn. Các mục của một FeatureRecipe phạm vi component được đánh giá một lần cho mỗi attachment, theo .values và .infra của attachment đó; các mục của một FeatureRecipe phạm vi boundary được đánh giá một lần cho mỗi boundary, theo khung nhìn phạm vi boundary và .infra của attachment boundary. Các quy tắc về những gì template của một attachment được phép đọc áp dụng cho các mục giống như cho valuesMapping: của nó.
  • Chỉ những gì source: của chính FeatureRecipe này render mới được lọc. workload: và artifacts: của nó thì không, và đầu ra của component chủ cũng không: các mục của một attachment chỉ tác động đến chart của chính nó, tệp compose của chính nó hoặc template CloudFormation của chính nó, và không gì khác — một compose service mà component chủ khai báo dưới cùng khóa trong docker-compose.yaml mà cả hai cùng được ghép vào sẽ không bị ảnh hưởng, và một resource mà component chủ khai báo dưới cùng logical ID trong stack mà cả hai cùng được ghép vào cũng vậy. Để thay đổi một tài liệu mà component chủ render, Recipe của component chủ phải khai báo mục đó, hoặc một bước pipeline: vá nó.

Một lần dừng do một mục sẽ nêu tên node, provider, FeatureRecipe này và vị trí của mục trong danh sách omits: của nó; đối với một FeatureRecipe phạm vi boundary, dòng phía trên thông báo nêu tên attachment và boundary của nó.

Để xem ví dụ minh họa về khóa này, được soạn trên một Recipe — một Secret được tạo ra của một chart đã tải về bị loại bỏ, cùng các lần dừng khi không có mục và khi có một mục không khớp với gì — hãy xem ai-gateway-own-webhook-certificate.