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.

Quy ước đặt tên

Chương này trình bày các quy tắc đặt tên và viết hoa áp dụng cho nội dung Aggrega được soạn thảo: mẫu cho tên instance do người dùng soạn, quy tắc viết hoa cho tên trường trong DSL, cách viết hoa mà nền tảng dùng cho các định danh do nó định nghĩa thay vì bạn, và cú pháp chú thích dùng ở bề mặt soạn thảo YAML.

Tên instance

Tên instance do người dùng soạn — các khóa mà nhà phát triển viết cho component, feature, aggregate, subsystem, boundary, cùng socket và alias uses — đều khớp một mẫu duy nhất: ^[a-zA-Z0-9_-]+$. Cả kebab-case (pii-filter, my-agent) lẫn snake_case (openai_key, db_credentials) đều hợp lệ; các nhóm có thể áp dụng quy ước nào họ muốn.

Ký tự được phép: chữ và số (a-z, A-Z, 0-9), dấu gạch nối (-) và dấu gạch dưới (_). Không ký tự nào khác được phép.

Ví dụ:

components:
web-server: # kebab-case
finance_worker: # snake_case
features:
pii-filter: # kebab-case
audit_logger: # snake_case
openai_key: # snake_case — natural for a credential attachment
db-password: # kebab-case — also valid
MẫuPhạm viVí dụ
^[a-zA-Z0-9_-]+$Mọi tên instance do người dùng soạnweb-server, openai_key, pii-filter

Mẫu này được áp dụng khi phân giải thông qua patternProperties của JSON Schema.

Tên component tốn gì, và vì sao chữ hoa tốn hơn ở một số target

Mẫu ở trên cho biết bạn được viết gì. Một tên tốn gì là câu hỏi khác, và nó khác nhau tùy target mà component được triển khai tới — vì vậy nên biết điều này trước khi chọn tên, thay vì đến lúc một bản build từ chối nó.

Tên của một component trở thành danh tính được gắn lên mọi tài nguyên nó phát ra, và mỗi target suy ra tên riêng của mình từ danh tính đó: trình cài đặt chart suy ra tên release, trình điều phối container suy ra tên service. Một target có bảng chữ cái hẹp hơn mẫu không thể mang một ký tự nó không chấp nhận, và Aggrega sẽ không lặng lẽ gộp ký tự đó thành một ký tự tương tự — hai tên mà tác giả phân biệt được không được trở thành một tên trong cluster. Vì vậy, ký tự mà target không chấp nhận sẽ được viết ra dưới dạng escape, và escape dài hơn ký tự nó thay thế.

Hệ quả thực tế: một chữ hoa không tốn gì ở một số target và tốn kém ở các target khác.

  • Ở target có tên chấp nhận chữ hoa — chẳng hạn một tệp compose điều phối container — PaymentsAPI được giữ nguyên đúng như bạn viết và tốn mười một ký tự.
  • Ở target chỉ chấp nhận tên chữ thường — tên release của trình cài đặt chart — mọi chữ hoa đều bị escape, và chỉ riêng một tên gồm sáu chữ hoa đã vượt quá giới hạn target đó chấp nhận.

Có hiệu ứng thứ hai, và nó nghiêm trọng hơn: escape bắt đầu bằng dấu gạch nối. Do đó, target yêu cầu tên phải bắt đầu bằng chữ thường hoặc chữ số sẽ từ chối tên có ký tự đầu tiên là ký tự nó không chấp nhận, dù phần còn lại ngắn đến đâu — không cách rút ngắn nào khắc phục được điều đó.

Hướng dẫn suy ra từ hai hiệu ứng này. Ưu tiên chữ thường và chữ số, có dấu gạch nối giữa các từ, và bắt đầu tên bằng chữ thường. payments-api được giữ nguyên bởi mọi target mà Aggrega cung cấp provider. payments_api được giữ nguyên bởi tệp compose nhưng không bởi target helm, vốn có tên tài nguyên không chấp nhận dấu gạch dưới: các Service, workload và release mà nó đặt theo tên component được viết thành payments-zuapi. PaymentsAPI còn tốn hơn ở đó. Một Recipe công bố địa chỉ của tài nguyên như vậy sẽ đọc cách viết riêng của target thay vì đoán trước nó — xem templates/rendered-resource-names.md.

Chữ số đứng đầu là hợp lệ khi viết và không tốn gì ở tệp compose, nhưng target helm từ chối nó. Tên Service của Kubernetes phải bắt đầu bằng một chữ cái, và các Service mà chart hoặc workload được tổng hợp phát ra được đặt theo tên component, nên component tên 1cache sẽ dừng bản build helm — lời từ chối nêu tên component và cho biết tên Service phải bắt đầu bằng chữ cái — thay vì render ra các Service mà cluster sẽ từ chối.

Không điều nào ở đây là quy tắc mà trình biên dịch tự áp dụng — nó không nắm quy tắc đặt tên của target nào và không tự đặt ra giới hạn nào. Provider của mỗi target chịu trách nhiệm cho tên của chính nó, nên một tên chỉ bị từ chối khi target mà component thực sự được triển khai tới nói rằng nó không dùng được tên đó, và lời từ chối mang lý do riêng của target đó và trỏ tới khóa spec.components mà bạn đã viết. Một tên ổn ở target này nhưng bị từ chối ở target khác là hành vi được mong đợi chứ không phải sự không nhất quán.

Các tên do chính Aggrega ghép lại — chẳng hạn danh tính của một feature gắn tại một boundary — được xử lý theo cách ngược lại: chúng được rút ngắn cho vừa target thay vì bị từ chối, vì chúng được lắp từ các phần viết ở nhiều nơi và không tác giả nào thấy được độ dài chúng đạt tới. Chỉ tên do bạn viết mới bị từ chối.

Dấu chấm là ký tự phân tách đường dẫn được dành riêng

Ký tự dấu chấm (.) được dành riêng, không dùng trong mọi tên instance do người dùng viết. Dấu chấm đảm nhận vai trò cấu trúc là ký tự phân tách đường dẫn do trình biên dịch sinh ra cho các tham chiếu component xuyên aggregate.

Khi một Aggregate gốc import một sub-aggregate tên data-layer chứa một component tên main-db, trình biên dịch tạo ID tuyệt đối đã làm phẳng data-layer.main-db bằng cách nối tên instance của aggregate và tên instance của component bằng một dấu chấm. Đường dẫn có dấu chấm này xuất hiện trong:

  • Các đích uses của nhà phát triển: target: data-layer.public_db — tham chiếu một component được export từ một aggregate lồng nhau.
  • Các chẩn đoán của chính bản build: một lần dừng hoặc một cảnh báo về component đó gọi nó bằng đường dẫn có dấu chấm, nên tên bạn đọc được chính là tên bạn có thể tìm trong tài liệu của mình.

Ký tự phân tách không đi vào tên

Đường dẫn có dấu chấm là một địa chỉ bên trong tài liệu của bạn, và nó không phải là tên mà một đích triển khai sẽ chấp nhận. Tên Service của Kubernetes hoàn toàn không cho phép dấu chấm; tệ hơn, dấu chấm trong một địa chỉ cluster là thứ phân tách một service với namespace chứa nó, nên một tên có dấu chấm được giao cho consumer làm host sẽ phân giải tới một service khác thay vì báo lỗi.

Vì vậy ký tự phân tách được viết thoát khỏi mọi tên và nhãn mà bản build suy ra từ danh tính của một component, và nó được viết thoát chứ không bị thay thế: data-layer.main-db trở thành data-layer-zdmain-db. Thay nó bằng một ký tự mà đích chấp nhận sẽ khiến hai component khác nhau đi tới cùng một tên — data-layer.main-db và một component mà ai đó viết là data-layer-main-db — và một tên mà hai component cùng đạt tới thì không định danh được component nào.

Điều đó ảnh hưởng tới gì, và không ảnh hưởng tới gì:

  • Nó ảnh hưởng tới các tên và nhãn suy ra từ danh tính — metadata.name trên tài nguyên do Aggrega tổng hợp, các nhãn aggrega.ai/component-id và app.kubernetes.io/name, các selector khớp với chúng, các tên tệp được xuất ra, {{ .context.instance_id }}, và tên mà một provider tự suy ra cho mình, chẳng hạn tên release của helm. Chúng thay đổi cùng nhau, nên một địa chỉ mà một Recipe tạo từ khóa đặt tên cho tài nguyên — .context.instance_id khi đích đặt tên theo danh tính, .context.rendered_name khi đích báo cáo một tên riêng — vẫn gọi đúng tài nguyên mà bản build xuất ra.
  • Nó không ảnh hưởng tới tên bạn đã viết. Một tên component không chứa ký tự phân tách được giữ nguyên từng byte, nên chỉ component do một Aggregate được import đóng góp mới có cách viết trong đầu ra khác với trong tài liệu.
  • Nó không ảnh hưởng tới các tên bên trong chart hoặc fragment do tác giả cung cấp. Những tên đó thuộc về người đã viết chúng, và một tên lấy từ chart của bên thứ ba — một tên custom resource có dạng <plural>.<group>, nơi dấu chấm là hợp lệ — được xuất ra đúng như chart đó đã viết.

🔴 Điểm cuối cùng đó kéo theo một hệ quả cho những gì một Recipe nên công bố, và đây là điều dễ làm sai nhất trên trang này. Các template của một chart được cung cấp đặt tên tài nguyên theo danh tính mà nền tảng giao cho chúng — một tên release, được viết theo bảng chữ cái của chính nền tảng đó chứ không theo bảng chữ cái ở trên — và đích helm đặt tên các workload mà nó tổng hợp theo chính tên release đó. Vì vậy, với đầu ra được render từ nguồn bạn cung cấp, và với một workload được tổng hợp dưới một đích như vậy, {{ .context.instance_id }} không phải là tên mà các tài nguyên đó mang, và một địa chỉ công bố từ nó sẽ không gọi tới gì cả mỗi khi hai bảng chữ cái khác nhau. Khóa mang tên của nền tảng, và những provider nào báo cáo tên đó, được trình bày trong templates/rendered-resource-names.md.

Việc viết thoát ký tự phân tách tốn thêm ký tự, và một tên có giới hạn độ dài có thể hết chỗ. Ký tự phân tách được thay bằng một chuỗi thoát ngắn chứ không phải bằng một ký tự đơn, nên một danh tính đầy đủ khi được viết ra sẽ dài hơn một chút so với khi đọc trong tài liệu của bạn. Điều đó chỉ quan trọng khi tên mà nó trở thành có giới hạn: đích render một component cho biết giá trị nhãn dài tối đa bao nhiêu mà nó chấp nhận, và khi danh tính đã viết ra vượt quá mức đó, bản build dừng lại thay vì xuất ra một giá trị mà đích sẽ từ chối. Thông báo dừng nêu độ dài mà chính danh tính phải nằm gọn trong đó — độ dài trước khi được viết thoát, nên một tên được chọn trong giới hạn đó sẽ hoạt động ngay lần đầu — và cách sửa là rút ngắn các phần do tác giả viết: tên mà tài liệu import đặt cho sub-aggregate, hoặc tên riêng của component bên trong nó.

Ký tự phân tách là lý do thường gặp khiến một tên được viết ra dài hơn khi đọc, nhưng không phải là lý do duy nhất. Hai dạng mà một tên do tác giả viết có thể hợp lệ mang cũng không thể được giữ nguyên như đã viết, vì giữ nguyên chúng sẽ làm chuỗi thoát trở nên mơ hồ: một tên kết thúc bằng dấu gạch nối, và một tên có dấu gạch nối theo ngay sau là z. Mỗi dạng được viết thoát theo cùng một cách, với cùng chi phí. Mọi tên khác do tác giả viết đều được giữ nguyên từng byte, nên một tên tạo từ chữ cái, chữ số, dấu gạch dưới và dấu gạch nối giữa các từ không bị ảnh hưởng bởi bất kỳ điều nào ở đây.

Tên socket trong khối uses riêng của một component hoặc khớp với một khóa trong usesSchema của thực thể catalog — một socket đã khai báo — hoặc đặt tên cho một socket ad-hoc của chính nhà phát triển, loại socket vẫn build được ngay cả trên một thực thể hoàn toàn không khai báo usesSchema; một tên chỉ cách một socket đã khai báo đúng một lần sửa sẽ gây ra cảnh báo nêu cả hai cách viết. uses theo từng cạnh của một Release, cũng như thiết lập tương ứng của một gắn kết Feature, chỉ được nêu tên một socket mà thực thể khai báo, và mọi tên khác đều thất bại với lỗi xác thực unknown-uses-socket.

Kiểu viết hoa của trường

DSL tách YAML dành cho nhà phát triển (do con người viết) khỏi các hợp đồng nội bộ của trình biên dịch (do template và công cụ sử dụng):

  • YAML dành cho nhà phát triển (camelCase): Tên trường nhiều từ trong các schema Aggregate, Release, Component, Feature, Recipe, FeatureRecipe, Manifest và Plugin dùng camelCase. Ví dụ: exportedComponents, syncWave, subDirectory, featuresSchema, usesSchema, valuesMapping, injectMapping, executionScope, appliesTo, appliesToAnyOf, conflictsWith. Tuân theo các quy ước API của Kubernetes.
  • Hợp đồng nội bộ (snake_case): Tên trường nhiều từ trong schema IR Graph và schema Template Context dùng snake_case. Các ví dụ mà tác giả Recipe gặp phải: instance_id (trong .context.instance_id — định danh của Recipe), inject_raw (trong .inject_raw, một trụ cột cấp cao nhất bên cạnh .inject chứ không phải một khóa dưới .context — hợp đồng injection chưa bị biến đổi), attachment_name (trong ngữ cảnh của một FeatureRecipe attachment — xác định khe mà attachment lấp đầy, hoặc tên mà nó được gắn vào). Tuân theo các quy ước JSON API và phù hợp với cách Go sinh struct tag JSON.
  • Trường một từ: Viết thường bất kể ngữ cảnh. Ví dụ: values, infra, inject, provides, locals, features, labels, annotations, boundaries, components, subsystems, pipeline, source.

Nhà phát triển không gặp snake_case trong YAML họ viết, và tác giả template không gặp camelCase trong Go template của họ. Các bổ sung vào schema tuân theo các quy ước này.

Ba kiểu viết hoa giao nhau trong một câu lệnh

Việc viết Recipe thường xuyên giao nhau cả ba quy ước viết hoa trong một câu lệnh: trường DSL do schema định nghĩa dùng camelCase, tên instance do người dùng viết dùng kebab-case hoặc snake_case, và tham chiếu tới template context dùng snake_case. Tác giả nào nhận ra các điểm giao nhau là những quy ước riêng biệt sẽ đọc YAML thu được một cách rõ ràng; tác giả nào cố gắng hợp lý hóa các kiểu viết hoa thành một quy ước sẽ gặp khó khăn ở các ranh giới.

Ví dụ minh họa chuẩn: template valuesMapping: của một Recipe tham chiếu tới instance Component được render thông qua template context.

# Recipe authored against a Component the developer instantiated as "web-server"
# (kebab-case instance name) in their Aggregate.
spec:
valuesMapping: | # camelCase — schema-defined DSL field
name: "{{ .context.instance_id }}" # snake_case — template context
# internal contract
image: "{{ .values.image }}" # snake_case — template context
# internal contract

Ba kiểu viết hoa, một câu lệnh:

  • valuesMapping — camelCase. Tên trường DSL mà schema định nghĩa cho template ánh xạ của Recipe. Dùng camel vì YAML dành cho nhà phát triển của ngôn ngữ tuân theo các quy ước API của Kubernetes.
  • web-server (được tham chiếu gián tiếp qua component được render) — kebab-case. Tên instance do người dùng viết trong Aggregate; nhà phát triển đã chọn dạng có gạch nối. Cũng có thể là web_server (snake_case); cả hai đều hợp lệ theo mẫu tên instance.
  • instance_id, image — snake_case. Tên trường bên trong template context (.context.instance_id, .values.image). Dùng snake vì IR Graph và template context tuân theo các quy ước JSON-API và phù hợp với cách Go sinh struct tag JSON.

Ba kiểu viết hoa không thể thay thế cho nhau. Tác giả Recipe nào viết {{ .context.instanceId }} (camelCase) sẽ làm build dừng: .context khai báo các khóa của nó, và instanceId không phải là một trong số đó, nên tham chiếu bị từ chối trước khi bất cứ thứ gì được render và chẩn đoán liệt kê các khóa mà .context có định nghĩa — xem errors/fatal-halts.md “Template references a root the render context does not define (Template tham chiếu tới một gốc mà render context không định nghĩa)”. Nhà phát triển nào viết web.server (có dấu chấm) sẽ bị mẫu tên instance từ chối vì dấu chấm được dành riêng làm dấu phân cách đường dẫn. Mục tiêu của kỷ luật này: ghi nhớ ba quy ước khi đọc hoặc viết; dựa vào các ranh giới (bạn đang ở đâu trong YAML hoặc template) để biết kiểu viết hoa nào được áp dụng.

Định danh do nền tảng định nghĩa

Mọi điều ở trên chi phối các tên trên bề mặt soạn thảo — một tên instance bạn chọn, một trường schema mà ngôn ngữ định nghĩa để bạn điền, một khóa template-context bạn đọc. Hai hệ đăng ký khác chi phối các định danh do chính nền tảng định nghĩa mà bạn chỉ đọc lại hoặc gõ vào. Chúng tách biệt vì chúng làm những việc khác nhau, và việc đó quyết định hình dạng.

Hệ đăng ký mô tả: kebab-case, thống nhất. Một định danh ở đây nói bằng lời điều nó đặt tên, nên bạn có thể đọc và hành động theo nó mà không cần tra cứu gì. Một cờ CLI, một id quy tắc publishing-lint, một mã lớp chẩn đoán, và mã mà một điều kiện dừng được đăng ký dưới đó đều thuộc về hệ này.

--no-unsupported-field-warnings # a CLI flag you type
category-matches-directory # a lint rule id, printed in `aggrega lint` output
unsupported-field # a diagnostic class code
artifact-provenance-skipped # another
parameter-contract-violation # the code a halting condition is registered under

Khi một lớp chẩn đoán có cờ chặn, mã và cờ là cùng các từ theo cùng thứ tự — unsupported-field được tắt bằng --no-unsupported-field-warnings — nên lớp bạn đã khớp cho bạn biết cờ cần dùng, không cần chuyển đổi gì. Mã lớp là tên ổn định mà công cụ khớp để nhận diện một phát hiện mà không phải phân tích văn bản thông báo; câu chữ của thông báo có thể được cải thiện, còn mã thì không thay đổi.

Hệ đăng ký mã ngắn: chữ E và bốn chữ số. Một điều kiện dừng cũng mang một mã ngắn — E0007 — và đó là định danh duy nhất do nền tảng định nghĩa không phải kebab-case. Lý do là vị trí: nó mở đầu mọi chẩn đoán dừng, bên cạnh danh mục, trước tệp và dòng mà bạn sắp đọc.

[DEVELOPER_ERROR E0007] aggregate.yaml at .spec.components.edge

Một mã mô tả không thể đặt ở đó. Mã dài nhất trong số chúng tự nó đã lấp đầy một terminal hẹp, trước cả vị trí cho bạn biết cần nhìn vào đâu. Vì vậy phần đầu dùng một định danh được chọn theo độ rộng, và sự đánh đổi này là có chủ ý: bốn chữ số không nói gì về một điều kiện, đó là lý do mỗi mã ngắn được công bố bên cạnh điều kiện nó đặt tên và văn bản mà điều kiện đó hiển thị trong tài liệu tham khảo error-sentinels. Hãy trích dẫn mã ngắn trong báo cáo, gõ nó vào ô tìm kiếm, và tra cứu nó ở đó.

Cả hai hệ đăng ký đặt tên cho cùng các điều kiện từ hai hướng, và không hệ nào thay thế hệ kia. Hãy khớp mã mô tả khi bạn viết một công cụ dựa trên một điều kiện; hãy trích dẫn mã ngắn khi bạn trao đổi với một người về điều kiện đó.

Kebab-case xuất hiện ở đây và trong tên instance không phải là xung đột. Mẫu tên instance nói về điều bạn được phép viết — kebab-case và snake_case đều hợp lệ ở đó, và các nhóm chọn một. Hệ đăng ký này nói về điều nền tảng thực sự viết, nơi không có gì để chọn: bạn không bao giờ chọn cách viết của một id quy tắc lint, và nền tảng không bao giờ chọn cách viết tên component của bạn.

Nó giữ nguyên cách viết hoa của các trường. Các trường schema do người soạn viết vẫn là camelCase và các khóa template-context vẫn là snake_case. Không định danh nào trong hệ đăng ký này là một trường trên bề mặt nào — chúng là các tên ngắn, ổn định cho một cờ, một quy tắc, hoặc một lớp phát hiện — nên việc một mã chẩn đoán là kebab-case không nói gì về cách viết một trường schema.

Quy ước hậu tố đặt tên cho đường dẫn tài liệu

Một tập con các trường trong ngôn ngữ mang giá trị đường dẫn tài liệu — các chuỗi trỏ tới một vị trí bên trong một tài liệu khác (phần volumes của một Workload đã kết xuất, một mục featuresSchema của một Component, tầng mappings của một Manifest). Các giá trị tuân theo cú pháp RFC 6901 JSON Pointer — các token phân tách bằng dấu gạch chéo, xác định đường đi qua tài liệu đích.

RFC 6901 là nền tảng ngữ pháp đường dẫn cho mọi bề mặt đường dẫn tài liệu trong Aggrega. Hợp đồng plugin Wasm tiếp nhận các tài liệu JSON Patch RFC 6902 có đường dẫn là các con trỏ RFC 6901 (theo đầu ra JSONPatch của vai trò label-transform trong plugins/plugin-contract.md); danh mục chuỗi định dạng của ngữ pháp URI nêu RFC 6901 cùng với cú pháp Go template và các hàm trợ giúp Sprig (theo mục “Format-string inventory” trong vocabulary/uri-grammar.md); các export .locals theo từng Recipe dùng RFC 6901 để trỏ tới các vị trí trong Workload được tổng hợp mà các plugin Wasm Injector nhận trong pipeline plugin thông qua payload with của bước của chúng. Một ngữ pháp, nhiều bề mặt tiếp nhận.

Quy ước hậu tố đặt tên phân biệt hai phía biên soạn của các giá trị đường dẫn này thông qua một sự phân tách hậu tố có chủ đích, thống nhất với phần Field Casing rộng hơn ở trên:

  • Các trường schema mang JSON Pointer RFC 6901 dùng hậu tố camelCase *Path. Các trường này là một phần của schema YAML hướng tới nhà phát triển, nên chúng tuân theo quy ước camelCase. Không schema thực thể nào khai báo một trường như vậy; các đường dẫn tài liệu mà tác giả viết là các khóa export .locals bên dưới.
  • Các khóa export .locals mang JSON Pointer RFC 6901 dùng hậu tố snake_case *_path. Các khóa này là một phần của bề mặt export nội bộ của Recipe — được đọc bởi các template tiếp theo của chính Recipe đó, và bởi một pipeline plugin Wasm thông qua payload pipeline[].with tham chiếu tới .locals — nên chúng tuân theo quy ước snake_case. Ví dụ:
    • volumes_path — .locals.volumes_path: "/spec/template/spec/volumes" cung cấp vị trí mảng volumes của Workload được tổng hợp.
    • containers_path — .locals.containers_path: "/spec/template/spec/containers" cung cấp vị trí mảng containers.
    • resource_path — .locals.resource_path: "/resource/aws_s3_bucket/main" cung cấp một đường dẫn tài nguyên gốc của Terraform.
    • root_path — .locals.root_path: "/data" cung cấp đường dẫn gốc mà pipe của trình kết xuất tiếp nhận.

Hai quy ước hậu tố phản ánh quy ước hai tầng của phần Field Casing: các trường do schema định nghĩa dùng camelCase; các định danh do người dùng biên soạn hoặc riêng của Recipe dùng snake_case (hoặc kebab-case). Quy ước hậu tố *Path / *_path làm cho bản chất ngữ pháp đường dẫn của giá trị hiển hiện ngay ở cấp định danh — người đọc thấy một trong hai hậu tố sẽ biết giá trị tuân theo cú pháp RFC 6901 mà không cần kiểm tra chính giá trị đó.

Ví dụ minh họa: một Wasm Injector tiếp nhận các export *_path của một Recipe.

# Recipe (Domain 3) — declares .locals exports the Wasm Injector consumes
spec:
locals:
primary_compute: "worker-container"
containers_path: "/spec/template/spec/containers"
volumes_path: "/spec/template/spec/volumes"
# Credential FeatureRecipe (Domain 3) — attached to the component the Recipe
# above realizes. Its templates read `.locals`: an attachment sees the host
# Recipe's resolved locals merged with the attachment's own block.
spec:
pipeline:
- id: workload_injector
plugin: pipeline-step/k8s-workload-injector:2.0.0
function: inject_secret
with: |
target_container: "{{ .locals.primary_compute }}"
containers_path: "{{ .locals.containers_path }}"
volumes_path: "{{ .locals.volumes_path }}"

Các khóa *_path là các export riêng của Recipe; các giá trị containers_path / volumes_path là các chuỗi JSON Pointer RFC 6901. Plugin Injector tiếp nhận các chuỗi này để định vị đầu ra JSONPatch của nó trên AST của Workload đã kết xuất. Phần gắn kèm tiếp cận chúng trên trụ .locals của chính nó — không có trường .context.uses[].locals, nên một bên tiêu thụ không thể đọc locals của đích qua một cạnh uses; thứ đi qua một cạnh là provides của đích.

Để xem danh mục chuỗi định dạng rộng hơn (cú pháp Go template, các hàm Sprig, JSON Pointer cùng với regex SemVer và ngữ pháp label selector), xem mục “Format-string inventory” trong vocabulary/uri-grammar.md. Để xem bề mặt hợp đồng plugin Wasm tiếp nhận các bản vá RFC 6902 được định địa chỉ bằng con trỏ RFC 6901, xem plugins/plugin-contract.md.

Cú pháp chú thích

Ký tự chú thích phụ thuộc vào ngôn ngữ bao quanh:

  • Ngữ cảnh YAML (bề mặt soạn thảo mặc định cho mọi thực thể Aggrega): dùng #
  • Ngữ cảnh Go template (bên trong các block scalar valuesMapping: của Recipe, các block scalar injectMapping: của FeatureRecipe, các mục mapping của MappingLibrary, phần thân assertions: của khối assertion): dùng {{/* ... */}} cho các chú thích template mà template engine nhận biết và loại bỏ khi render, hoặc # cho các chú thích cấp YAML nằm ngoài phần thân template.

Các schema dạng rút gọn dưới schema:, usesSchema:, featuresSchema: và parameters: hoàn toàn là YAML; chú giải description: theo từng trường là bề mặt được tài liệu hóa để ghi tài liệu cho trường ngay trong dòng (port: { type: integer, description: "TCP listen port" }).