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.

Hợp đồng ngữ cảnh template

Trang này mô tả khung nhìn thời gian chạy mà trình biên dịch đưa vào các Go template của Recipe và FeatureRecipe: cấu trúc ngữ cảnh template, mức độ sẵn có của từng trường qua pipeline biên dịch, và hợp đồng chuẩn mà các tác giả nâng cao cần khi viết template sử dụng trạng thái liên component. Mức độ sẵn có theo từng vị trí template (trường nào có mặt tại vị trí đánh giá nào) được trình bày tại expansion-matrix.md; trang này mô tả cấu trúc các trường và ngữ nghĩa của chúng.

Tổng quan

Trình biên dịch tập hợp một ngữ cảnh template cho mỗi nút trong quá trình kết xuất và đưa nó vào mọi Go template mà trình kết xuất đánh giá cho nút đó. Ngữ cảnh này chỉ tồn tại trong bộ nhớ — nó không bao giờ được lưu xuống đĩa và không bao giờ đi qua Wasm ABI dưới dạng một payload duy nhất. Mỗi vị trí template nhận một khung nhìn của cùng một đối tượng ngữ cảnh; một số trường được điền muộn (.workload xuất hiện ở bước tổng hợp workload; .source ở bước phân giải nguồn; .steps được điền bởi quá trình thực thi pipeline: khi mỗi bước hoàn tất, xem Trạng thái của ngôn ngữ → Các giai đoạn của pipeline biên dịch).

Schema cho cấu trúc lúc chạy là template-context-v1beta1.schema.json (được phân phối kèm bản phân phối schema của Aggrega).

Các trường cấp cao nhất

Các trường cấp cao nhất nằm ở gốc của template context — được truy cập dưới dạng .field từ bên trong một template.

  • .values (map). Tải trọng nhận thức do nhà phát triển soạn từ Aggregate. Các giá trị theo từng component được chuyển tới Recipe đã render tại trường này. Được xác thực bởi schema: của Catalog (khai báo JSON Schema 2020-12 của Component hoặc Feature) khi phân giải. Khi giá trị zero / rỗng / false được soạn của một trường có ý nghĩa khác với việc trường đó vắng mặt, hãy dùng optional (xem sprig-functions.md) thay vì default.
  • .infra (map). Kích thước vật lý do bộ phận vận hành soạn từ Release. Được xác thực bởi schema: của Catalog (khai báo JSON Schema 2020-12 của Component hoặc Feature) khi phân giải. Hướng dẫn về optional so với default như đối với .values cũng áp dụng ở đây — nên dùng optional khi giá trị zero hoặc false được soạn là một ý định hợp lệ (scale-to-zero, không thử lại, tắt feature flag).
  • .locals (map giá trị chuỗi). Trạng thái riêng của Recipe — các tên được khai báo trong khối locals: của Recipe, được phân giải trong phần mở đầu locals và được công bố lên trụ cột này khi phân giải source. Các mục được phân giải theo thứ tự tác giả viết và một mục có thể đọc một mục cùng cấp được định nghĩa phía trên nó, vì vậy thứ tự là quan trọng ở bất cứ đâu một mục đọc mục khác. Chỉ truy cập được trong các template của chính Recipe; không bao giờ được lộ ra cho bên gọi.
  • .provides (map giá trị chuỗi). Các chuỗi đầu ra công khai của Recipe — hợp đồng mà các khối inject: của bên gọi dùng để phân giải các tham chiếu from:. Được điền khi đánh giá provides.
  • .features (map các attachment). Duyệt qua các Features được gắn vào Component này (cấp Aggregate + cấp subsystem + cấp Release + do chú thích Manifest điều khiển, theo Mô hình Củ hành 5 tầng), được đánh khóa theo tên instance mà tác giả đặt cho attachment. Mọi mục đều mang cùng các trường — xem hình dạng attachment bên dưới. Một attachment được viết trên một trong các kết nối của Component không nằm trong số đó: nó được đọc dưới kết nối đó, tại .context.uses.<alias>.features.<slot>, vì vậy một template duyệt .features chỉ gặp các attachment của chính Component.
  • .metadata (struct). Định danh Release để đặt tên tất định: release_name, release_version, environment, aggregate_name. Được điền cho mọi lần render; các giá trị bắt nguồn từ khối metadata: của Release.
  • .source. source: của Recipe, được phân giải bởi lần đánh giá template phân giải source. nil đối với các Recipes không có source; nil trước khi phân giải source chạy. Trên các template của một FeatureRecipe, nó là source: của chính FeatureRecipe đó, không bao giờ là của component chủ — xem Bề mặt FeatureRecipe của attachment.
  • .workload. Đối tượng Workload đã được phân tích, được điền khi tài liệu workload: đã render được giải mã và đã vượt qua bước xác thực kiểm soát nó: schema của Workload, featuresSchema của Component cho mọi attachment mà các container của nó khai báo, và khả năng phân giải những gì mỗi attachment tham chiếu. nil đối với các Recipes không được tổng hợp; nil trước khi tổng hợp workload chạy.
  • .steps (map các đầu ra của bước). Được điền bởi quá trình thực thi pipeline: khi các Plugins Wasm chạy, cung cấp các đầu ra trả về của một bước đã hoàn thành cho các bước tiếp theo qua .steps.<id>.outputs. Một bước đọc đầu ra của bước trước từ template with của chính nó; outputs của một bước chỉ hiển thị với các bước được khai báo sau nó. Rỗng khi node không khai báo pipeline, và trước khi bước đầu tiên của node hoàn thành.

Một trường cấp cao nhất không chứa gì cho node này — .workload trên một Recipe không tổng hợp cái nào, .source trên một Recipe không có source, .features trên một Component không có attachment nào — được đọc là rỗng trong một value template, đúng như một khóa chưa được đặt dưới .values: {{ .workload }} không kết xuất gì, một default áp lên nó cung cấp giá trị dự phòng của mình, và một if hoặc with áp lên nó đi vào nhánh false. Một range trên nó không lặp qua gì cả. Một lần đọc bên dưới nó — {{ .workload.containers }} — vẫn dừng lại, vì không có gì để đi sâu vào. Và một template vừa in một trường như vậy ở nơi nó luôn chạy — bên ngoài mọi if, with và range — vừa lặp qua nó sẽ dừng lại và nêu tên trường đó, như với bất kỳ đường dẫn nào không chứa gì mà được đọc theo cả hai cách, vì không có giá trị nào vừa được in ra thành rỗng vừa được lặp như rỗng: xem A template reads and iterates a path that holds nothing (Một template vừa đọc vừa lặp qua một đường dẫn không chứa gì).

Hình dạng của một attachment

.features.<name> và .features.<slot> có cùng hình dạng — một attachment, được đọc theo một cách:

  • .type (string). URI catalog của Feature được gắn.
  • .resolved_version (string). Phiên bản của Feature được gắn sau khi phân giải Manifest — phiên bản thực sự được ràng buộc cho bản build này, thay vì một phiên bản ghim được nhắc lại ở phía sử dụng. Tương ứng với .context.uses.<alias>.resolved_version. Rỗng khi type của attachment không phân giải tới thực thể catalog nào.
  • .labels (map giá trị chuỗi). Các nhãn catalog của Feature được gắn, được mang nguyên văn theo thứ tự Feature khai báo — không có gì bị lọc, đổi tên hay bỏ tiền tố, nên template đọc đúng những gì tác giả của Feature đã viết. Tương ứng với .context.uses.<alias>.labels. Vắng mặt khi Feature không khai báo nhãn nào, và khi type của attachment không phân giải tới thực thể catalog nào.
  • .values (map). Trụ cột ý định của nhà phát triển riêng của attachment, được viết trên khai báo attachment trong Aggregate. Khác với .values cấp cao nhất của component chủ.
  • .infra (map). Trụ cột định cỡ vận hành riêng của attachment, được viết trên khai báo attachment trong Release. Khác với .infra cấp cao nhất của component chủ.
  • .provides (map giá trị chuỗi). Hợp đồng công khai đã phân giải của FeatureRecipe được ràng buộc với attachment này — tên của tài nguyên được phát ra, khóa dữ liệu của nó, một danh tính cloud, và mọi khóa bổ sung mà FeatureRecipe công bố. Đọc dưới dạng .features.<name>.provides.<key>, tương ứng với .context.uses.<alias>.provides: bên sử dụng đọc những gì bên tạo đã công bố thay vì tự suy ra lại. Một attachment có FeatureRecipe được ràng buộc không công bố gì thì hoàn toàn không có khóa provides thay vì một map rỗng, vì vậy hãy kiểm tra trước khi truy cập một khóa riêng lẻ.

.provides là thứ khiến một attachment có thể được sử dụng chứ không chỉ đơn thuần hiện diện. Một Feature khai báo hợp đồng schema.provides sẽ có hợp đồng đó được áp dụng đối với FeatureRecipe hiện thực hóa nó — FeatureRecipe phải công bố mọi khóa đã khai báo — và bên sử dụng đọc kết quả tại đây. Vì vậy, một Feature danh tính phát ra một ServiceAccount và công bố tên của nó sẽ cho phép Recipe sử dụng ràng buộc với nó:

workload: |
serviceAccount: "{{ .features.identity.provides.name }}"

Tên được phát ra được nêu một lần, bởi bên tạo, và được sử dụng — không bao giờ được nhắc lại ở phía sử dụng, nơi hai bên có thể không khớp nhau. Ví dụ workload-identity-binding render điều này từ đầu đến cuối.

.labels là thứ cho phép một template thích ứng với việc một attachment là gì mà không cần so khớp theo tên hay phân tích URI của nó. Trình biên dịch không đọc nhãn nào — nó chỉ mang các chuỗi, và tác giả template quyết định ý nghĩa của chúng.

Một Feature không khai báo nhãn nào thì hoàn toàn không có .labels thay vì một map rỗng, vì vậy hãy kiểm tra trước khi truy cập một nhãn riêng lẻ — truy cập qua một khóa không tồn tại sẽ dừng bản build. Hãy đọc một nhãn mà Feature có thể không khai báo thông qua optional, vì index dừng lại và nêu tên khóa khi map không chứa nó:

{{ if .features.db.labels }}
{{ if eq (optional .features.db.labels "feature.aggrega.ai/kind" "") "secret" }}...{{ end }}
{{ end }}

Vì các nhãn đến nguyên văn, namespace riêng của tác giả catalog đến được template mà không thay đổi, và một Recipe đọc đúng khóa mà Feature khai báo.

Khối .context

.context là ngữ cảnh thực thi do trình biên dịch lắp ráp cho một nút duy nhất — dữ liệu về định danh, cấu trúc liên kết và đường ống phân phối mà bộ kết xuất truyền qua mọi vị trí template. Các trường của nó:

  • .context.instance_id (string). Định danh của nút dưới dạng một tên — giá trị mà chính bản build dùng để đặt tên và gắn nhãn cho những gì nó phát ra, nên một template ghép tên tài nguyên hoặc địa chỉ trong cluster từ giá trị này sẽ dự đoán đúng tên mà bản build thực sự tạo ra. Đó là tên bạn đã viết cho một nút mà chính Aggregate của bạn khai báo. Với một nút do một Aggregate được import đóng góp, đó là định danh đã làm phẳng với dấu phân cách module được viết ra (data-layer.main-db trở thành data-layer-zdmain-db), vì dấu chấm không phải là ký tự mà tên tài nguyên có thể chứa và, trong một địa chỉ cluster, nó ngăn cách một service với namespace của nó. Dạng có dấu chấm là dạng mà các tài liệu của bạn và các chẩn đoán của bản build dùng để chỉ tới nút đó; xem Quy ước đặt tên.
  • .context.rendered_name (string). Tên mà provider của nút đặt cho các tài nguyên nó kết xuất cho nút — từ nguồn bạn cung cấp, chẳng hạn tên release mà một chart đọc, và từ một workload mà nó tổng hợp khi nó đặt tên các tài nguyên của workload đó theo một tên của riêng nó, như helm làm với cùng tên release đó. Chỉ có mặt khi provider đó suy ra được một tên. Trên các template của một attachment Feature, đó là tên của component chủ, cũng như .context.instance_id ở đó là định danh của component chủ; xem Đặt tên cho một tài nguyên được kết xuất.
  • .context.labels (map giá trị chuỗi). Các nhãn do catalog tạo cộng với mọi phần bổ sung từ label-transform được thực hiện khi xây dựng cấu trúc liên kết.
  • .context.annotations (ba nhóm, xem bên dưới). Các annotation được truyền tầng, nhóm theo nguồn gốc.
  • .context.inject (map các cơ chế, xem bên dưới). Đường ống phân phối đã được nạp sẵn và đã qua chặn — bề mặt chuẩn mà các template Recipe đọc để lấy giá trị liên component.
  • .context.uses (map các kết nối, xem bên dưới). Phép chiếu JOIN trên các cạnh cấu trúc liên kết đi ra.
  • .context.self_inject (map các cơ chế, xem bên dưới). Với mỗi tên mà developer đã viết trong khối inject: của chính component, đây là khóa provides riêng mà mục đó phân phối, hoặc một giá trị riêng duy nhất mà template của mục đó đọc.
  • .context.used_by (list, xem bên dưới). Các component có mục uses trỏ tới component này. Được đọc bởi một FeatureRecipe gắn vào component, trên các template tạo ra tài nguyên riêng của attachment; rỗng ở mọi nơi khác.
  • .context.render_facts (map của các list, xem bên dưới). Những gì provider của component báo cáo về đầu ra nó đã kết xuất, theo khóa là tên fact. Được đọc bởi một FeatureRecipe gắn vào component, trên mọi template của nó chạy sau khi component đã kết xuất; không có ở mọi nơi khác.

.context.annotations — ba nhóm

Các annotation truyền tầng vào ba nhóm theo khóa là nguồn gốc:

  • .context.annotations.release — các annotation ranh giới Release (Domain 4). Dùng để chi phối các thực tế vật lý; bộ kết xuất định tuyến chúng vào các trường infra: khi thích hợp. Các annotation phổ biến aggrega.ai/* nằm trong nhóm này.
  • .context.annotations.catalog — các annotation metadata của Component từ Domain 2. Các đặc tính nội tại bất biến do Architect tạo; chủ yếu được các plugin chính sách Wasm sử dụng.
  • .context.annotations.aggregate — các annotation hệ thống con của Aggregate từ Domain 1. Metadata nhận thức; bộ kết xuất định tuyến chúng vào các payload values: khi thích hợp.

Mỗi nhóm là một map phẳng từ chuỗi sang chuỗi. Theo các quy tắc phân tách của kiến trúc, các nhóm được dự định cho những mục đích riêng biệt; engine không thực thi sự phân tách này, nên chính kỷ luật khi tạo nội dung giữ cho các nhóm khớp với ngữ nghĩa dự định của chúng. Xem chương 6 §2 Flow 5 để biết thiết kế annotation truyền tầng.

.context.inject — đường ống phân phối

Đường ống là map phân phối đã được phân giải trước của trình biên dịch. Khi một template Recipe chạy ở bước kết xuất cơ sở, mọi nguồn inject (các literal self-inject do nhà phát triển viết, các tham chiếu self-inject from: được phân giải theo provides của chính nó, các tham chiếu liên component uses[].inject được phân giải theo provides của đích, các phép chặn injectMapping của FeatureRecipe) đều đã được phân giải thành một giá trị chuỗi cuối cùng và được gộp vào map này.

Các trường:

  • .context.inject.env — map giá trị chuỗi từ tên biến môi trường → giá trị đã phân giải.
  • .context.inject.file — map giá trị chuỗi từ đường dẫn tệp → giá trị đã phân giải.
  • .context.inject.arg — map giá trị chuỗi từ cờ đối số → giá trị đã phân giải.
  • .context.inject.all — map giá trị chuỗi kết hợp các cơ chế env/file/arg/tùy chỉnh vào một từ điển phẳng; hữu ích để tuần tự hóa toàn bộ đường ống ({{ toJson .context.inject.all }}).

Một cơ chế chỉ có trong đường ống khi có thứ gì đó được phân phối qua nó. Một template đọc một cơ chế mà không có gì được phân phối qua — .context.inject.file khi không có phân phối tệp nào — sẽ đọc nó là rỗng, như một value template đọc bất kỳ khóa vắng mặt nào, và một range trên nó không render gì; lần đọc đó cung cấp giá trị rỗng cho toàn bộ template, nên một {{ toJson .context.inject }} trong cùng template hiển thị "file": "". hasKey .context.inject "file" cho biết có thứ gì được phân phối qua nó hay không.

  • Các cơ chế tùy chỉnh (ví dụ: ssm_param) — đọc được dưới tên trường của riêng chúng, .context.inject.<mechanism>.<key>, đúng như ba cơ chế cốt lõi. Giá trị của một cơ chế tùy chỉnh đến đường ống từ self-inject ở cấp component, từ một cạnh uses[].inject, từ ánh xạ inject: của một attachment Feature, và từ đầu ra injectMapping của một FeatureRecipe. Với self-inject ở cấp component, allowlist spec.inject của Component phải nêu tên cơ chế đó, và một cơ chế mà allowlist không nêu tên sẽ dừng bản build. Các mục của một cơ chế tùy chỉnh cũng xuất hiện trong .context.inject.all cùng với ba cơ chế cốt lõi. Một cơ chế tùy chỉnh có thể mang bất kỳ tên nào ngoại trừ all: tên đó chính là khung nhìn đã gộp, nên một cơ chế mang tên đó sẽ không bao giờ đọc riêng được. Một khối inject đặt tên một cơ chế là all, và một allowlist của Component hoặc Feature (spec.inject, inject của một socket) liệt kê nó, sẽ dừng bản build khi tài liệu được tải, và thông báo từ chối giải thích rằng tên đó thuộc về khung nhìn đã gộp này. Tên phân biệt chữ hoa chữ thường, nên ALL là một cơ chế tùy chỉnh bình thường.

Đường ống là trạng thái sau khi chặn — các khối injectMapping của FeatureRecipe đã gộp sâu các giá trị ghi đè của chúng lên đường ống này trong bước ánh xạ inject, trước khi các template Recipe đọc nó. Một ánh xạ có thể thay thế một khóa mà khối inject: của chính component, một trong các khối inject: của các kết nối của nó hoặc khối inject: của chính attachment của nó đã phân phối; một khóa mà hai Features được gắn cùng phân phối, qua các khối inject: hoặc các ánh xạ của chúng, sẽ dừng bản build thay vì đến đường ống này với một trong hai giá trị. Một Feature gắn vào ranh giới Release đến component theo cùng cách, qua injectMapping của FeatureRecipe của nó, vốn chạy trong ngữ cảnh của chính component bất kể executionScope của FeatureRecipe — việc cầu nối compose viết lại biến host của một consumer là một ánh xạ như vậy, tuân theo cùng quy tắc.

.context.self_inject — giá trị riêng nào được phân phối bởi mỗi tên của developer

Khi một Component khai báo spec.inject, developer có thể viết một khối inject: trên chính component đó và chọn các tên dùng để phân phối các giá trị và provides riêng của component. .context.inject chứa kết quả phân giải của các mục đó và .inject_raw chứa chúng đúng như đã viết; .context.self_inject cho biết, với mỗi mục, khóa provides riêng của component mà mục đó phân phối hoặc một giá trị riêng duy nhất mà template của nó đọc. Nó có cùng dạng với .context.uses.<alias>.inject của một kết nối — cơ chế, rồi đến tên của developer, rồi đến một khóa — với khóa chỉ đến một trong các provides hoặc giá trị riêng của component:

  • provides.<key> — một mục được viết với from: <key>, phân phối một trong các provides riêng của component.
  • values.<key> — một mục có template value: đọc đúng một trong các giá trị riêng của component và không đọc gì khác, với <key> là khóa cấp cao nhất của giá trị đó. Văn bản hay hàm xung quanh phép đọc không quan trọng, và việc template đọc sâu đến đâu vào giá trị cũng không quan trọng: '{{ .values.role }}', 'role={{ .values.role | upper }}' và '{{ with .values.role }}{{ . }}{{ end }}' đều ánh xạ tới values.role, còn '{{ .values.config.port }}', '{{ index .values.config "port" }}' và '{{ (default dict .values.config).port }}' đều ánh xạ tới values.config.
  • một chuỗi rỗng — mọi mục khác: một literal, một template đọc hai giá trị, một template đọc bất cứ thứ gì ngoài các giá trị (.infra, .metadata, .context), và một template mà văn bản không quy phép đọc các giá trị của nó về một khóa cấp cao nhất duy nhất — các giá trị được truyền cho một hàm qua gốc của chúng (index .values "role"), các giá trị được đọc toàn bộ (toJson .values, hoặc một trường được đọc bên trong {{ with .values }} hay qua một biến gắn với .values), hoặc toàn bộ ngữ cảnh được chuyển tiếp (toJson .).
# The developer's block on the component, in the Aggregate
inject:
env:
- { in: SERVICE_HOST, from: host }
- { in: AGENT_ROLE, value: '{{"{{"}} .values.role }}' }
- { in: MODE, value: batch }
- { in: ROLE_AND_GOAL, value: '{{"{{"}} .values.role }}-{{"{{"}} .values.goal }}' }
ssm_param:
- { in: /app/goal, value: '{{"{{"}} .values.goal }}' }
# What the Recipe reads at .context.self_inject
env:
SERVICE_HOST: provides.host
AGENT_ROLE: values.role
MODE: ""
ROLE_AND_GOAL: ""
ssm_param:
/app/goal: values.goal

Trong Aggregate, mỗi template value: bắt đầu bằng {{"{{"}} thay vì {{, vì toàn bộ văn bản của Aggregate được đọc một lần như một template, để nội suy tham số, trước khi các template riêng của khối được đánh giá; các template được trích dẫn trong danh sách trên được trình bày theo dạng chúng có sau lần thoát ký tự đó. Xem Văn bản tự mang dấu ngoặc nhọn kép.

Đây là điều cho phép một Recipe chạy image riêng của developer coi các tên biến của chính nó cho các giá trị riêng của component là mặc định — quy ước của catalog thư viện chuẩn, mà một catalog doanh nghiệp có thể chọn khác. Trước khi phân phối một giá trị riêng dưới một tên của chính nó, một Recipe như vậy kiểm tra xem khối của developer đã phân phối giá trị đó chưa, và bỏ qua mặc định của mình nếu đã có — nhờ vậy một developer đổi tên một giá trị vẫn giữ mọi mặc định khác:

workload: |
containers:
main:
variables:
{{- range $name, $value := .context.inject.env }}
{{ $name }}: {{ $value | quote }}
{{- end }}
{{- $named := dict }}
{{- with .context.self_inject.env }}{{ range $name, $key := . }}{{ $_ := set $named $key true }}{{ end }}{{ end }}
{{- if not (hasKey $named "values.role") }}
APP_ROLE: {{ .values.role | quote }}
{{- end }}

.context.self_inject có mặt trong mọi lần render và rỗng ở nơi developer không viết khối nào. Một cơ chế chỉ xuất hiện khi khối nêu tên nó, vì vậy hãy bảo vệ phép đọc một cơ chế mà khối có thể không nêu tên, như with ở trên làm. Một template nhận các tên đã được sắp xếp dù nó đọc chúng theo cách nào, giống như với mọi map. Map được đọc từ văn bản mà developer đã viết; không có gì trong đó là giá trị đã được phân giải, và trình biên dịch không gán ý nghĩa nào cho các tên hay các khóa.

.context.uses — phép chiếu JOIN

.context.uses là góc nhìn đã được làm giàu của trình biên dịch về mọi cạnh tô-pô đi ra từ nút hiện tại. Mỗi mục trong map được đánh khóa theo bí danh socket cục bộ (ví dụ: databases.primary trở thành .context.uses.primary khi Aggregate khai báo uses: { databases: { primary: { target: ... } } }) và mang một phép chiếu JOIN của trạng thái đã phân giải của đích cùng với hợp đồng phân phối phía bên gọi:

  • .target (string) — instance ID của nút đích.
  • .socket (string) — tên socket phía bên gọi (khóa usesSchema).
  • .provides (map giá trị chuỗi) — các khóa provides: đã phân giải của đích (các chuỗi đầu ra công khai mà Recipe đích đã xuất ra khi đánh giá provides).
  • .inject (map từ cơ chế → map từ khóa → giá trị) — các chỉ thị inject phía bên gọi cho cạnh này (khối inject: trên khai báo uses[].inject). Các khóa cơ chế là env/file/arg/tùy chỉnh; các mục map theo từng cơ chế là tham chiếu từ khóa cục bộ → khóa provides của đích.
  • .labels (map giá trị chuỗi) — các nhãn của đích, không bao giờ là của component tiêu thụ: tập nhãn mà .context.labels của chính đích mang, gồm các nhãn do catalog khai báo cùng mọi phần bổ sung label-transform được thực hiện khi xây dựng tô-pô.
  • .annotations (ba nhóm) — các nhóm annotation release/catalog/aggregate của đích.
  • .component (string) — URI kiểu Component của đích.
  • .resolved_version (string) — phiên bản Component của đích sau khi phân giải Manifest.
  • .boundary_path (string) — đường dẫn ranh giới Release của đích, được đặt bất kể đích nằm trong ranh giới của bên gọi hay trong một ranh giới khác.
  • .origin_feature (string) — được đặt khi cạnh được tổng hợp bởi một phần gắn Feature (ví dụ: một Feature sidecar đóng góp một cạnh uses tới một Feature thông tin xác thực).
  • .values (map) — cấu hình nhà phát triển theo từng cạnh đã phân giải cho kết nối này, được khai báo trên mục uses của Aggregate. Chỉ có mặt khi cạnh mang values theo từng cạnh.
  • .infra (map) — cấu hình vận hành theo từng cạnh đã phân giải cho kết nối này, được khai báo trên mục uses của Release. Chỉ có mặt khi cạnh mang infra theo từng cạnh.
  • .origin_release (boolean) — true khi Release nối kết nối này thay vì Aggregate khai báo nó; vắng mặt đối với kết nối do Aggregate khai báo.
  • .features (map các phần gắn) — các phần gắn được viết trên kết nối này, được đánh khóa theo tên slot mà socket khai báo; xem bên dưới. Chỉ có mặt khi kết nối mang một phần gắn.
  • .render_facts (map các danh sách) — những gì các lần render của đích báo cáo về đầu ra chúng đã phát ra, được đánh khóa theo tên fact, có cùng dạng với .render_facts của một bên gọi trên .context.used_by: mọi fact là một danh sách, các lời gọi provider của chính đích đứng trước rồi đến từng Features của nó theo thứ tự chúng đã render, các danh sách mà một tên nhận được từ mỗi bên được nối thành một. Chỉ có mặt đối với một FeatureRecipe đặt readsTargetRenderFacts: true — các phần gắn của nó render sau khi mọi component đã render, nên lần render của mọi đích đều đã hoàn tất — và khi đó có mặt trên mọi kết nối, rỗng đối với một đích mà các provider không báo cáo gì. Chỉ được đọc trong valuesMapping:, workload: và artifacts: của FeatureRecipe đó; vắng mặt trong các template Recipe của chính component, trong một injectMapping:, trong with: và when: của một bước pipeline:, và trong mọi FeatureRecipe không đặt khóa này — một template của FeatureRecipe như vậy mà đọc nó sẽ dừng bản build trước khi bất cứ thứ gì được render.

Cả hai map cấu hình theo từng cạnh đều có phạm vi bên tiêu thụ: chúng chỉ đi vào ngữ cảnh render của nút tiêu thụ, không bao giờ vào ngữ cảnh của đích.

Một giá trị được cung cấp được đọc tại .provides.<name> — các tên được cung cấp lồng dưới .provides thay vì nằm trực tiếp trên cạnh, nên .context.uses.<alias>.<name> không trỏ tới trường nào và không cho ra gì.

Trên một kết nối có hai đầu được render vào các đầu ra khác nhau, .provides chứa các giá trị thay thế chứ không phải các giá trị thật. Khi provider nối một kết nối như vậy bằng một tham chiếu của riêng nó sau khi cả hai đầu ra được lắp ráp — chẳng hạn một stack CloudFormation đọc giá trị của một stack khác — mỗi giá trị mà .context.uses.<alias>.provides mang là một placeholder mà provider sau đó thay thế bằng một tham chiếu liên stack hoặc bằng chính giá trị đó, như trang riêng của nó mô tả. Một giá trị như vậy phải được sao chép, không so sánh — cùng quy tắc mà giá trị một kết nối như vậy phân phối trên đường ống inject tuân theo, vốn cũng là một placeholder cùng loại. Hãy viết nó nguyên vẹn, bên trong một chuỗi lớn hơn, hoặc qua một hàm giữ nguyên nó, chẳng hạn quote. Một template so sánh một giá trị nó đọc từ .provides, rẽ nhánh theo nó, đo nó hoặc thay đổi nó sẽ đang quyết định dựa trên placeholder, nên thay vào đó build sẽ dừng, nêu tên template và từng giá trị nó đã đọc; hãy rẽ nhánh theo một giá trị của chính component sử dụng. Điểm dừng áp dụng cho mọi template đọc .provides của kết nối, kể cả injectMapping: của một FeatureRecipe được gắn, và một FeatureRecipe phạm vi boundary đọc cùng các kết nối đó dưới .boundary. Một kết nối có hai đầu được render vào một đầu ra duy nhất mang các giá trị của nó nguyên trạng.

Một bí danh đặt tên cho một kết nối, nên map chứa một mục cho mỗi kết nối mà component tạo ra. Map chỉ được đánh khóa theo bí danh, bất kể kết nối được nối vào socket nào, và không có hai kết nối nào của cùng một component dùng chung bí danh — dù trên cùng một socket hay trên hai socket, bất kể tài liệu hay phần gắn nào đã tạo ra mỗi kết nối. Bản build từ chối một cặp như vậy, nêu tên cả hai kết nối và nơi mỗi kết nối được viết, trước khi bất cứ thứ gì được render. Một danh sách nêu tên một đích hai lần là một cặp như vậy, vì bí danh của một mục danh sách là đích của nó; một kết nối local trên socket models bên cạnh một kết nối local trên socket databases cũng vậy.

Các template Recipe dùng phép chiếu này để tra cứu trạng thái phía đích mà không cần duyệt đồ thị IR. Các template injectMapping của FeatureRecipe dùng nó để truy cập annotation của đích cho các quyết định định tuyến xuyên ranh giới (mẫu bộ phân giải DNS K8s được mô tả trong entities/featurerecipe.md là ví dụ minh họa tiêu biểu).

Một template duyệt .context.uses sẽ thấy các kết nối theo thứ tự khóa — sắp xếp theo bí danh — chứ không theo thứ tự Aggregate đã viết chúng. Mọi map mà một template duyệt đều được duyệt theo cách đó, kể cả .features và .features của một kết nối, nên một template không bao giờ khôi phục được thứ tự đã viết bằng cách duyệt một map; khi thứ tự mang ý nghĩa, bề mặt khai báo mô hình hóa nó dưới dạng danh sách. Dù theo cách nào, đầu ra được render vẫn giống hệt từng byte giữa các bản build của cùng một đầu vào.

Các phần gắn của một kết nối — .context.uses.<alias>.features

Một phần gắn được viết trên một kết nối — dưới features: trên mục uses của một component trong Aggregate, hoặc trên mục của Release cho kết nối đó — lấp đầy một slot mà socket khai báo. Nó là phần gắn của component tiêu thụ đối với mọi thứ bản build làm với nó: Manifest ràng buộc hiện thực của nó, FeatureRecipe của nó render ở phía bên tiêu thụ, hợp đồng provides của nó được thực thi. Một template đọc nó dưới kết nối mà nó được viết trên đó:

{{- range $alias, $edge := .context.uses }}
- name: {{ $alias }}
api_base: {{ $edge.provides.endpoint }}
{{- with $edge.features }}{{ with .credential }}
api_key_secret: {{ .provides.name }}
api_key_key: {{ .provides.key }}
{{- end }}{{ end }}
{{- end }}
  • Được đánh khóa theo slot. .context.uses.<alias>.features.<slot> nêu tên slot mà socket của kết nối khai báo — credential ở trên — nên một bên tiêu thụ 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 bí danh của đích đó. Một kết nối không mang phần gắn nào thì không có .features, đó là lý do lần đọc được bảo vệ.
  • Dạng của phần gắn. Mỗi mục mang đúng những gì .features.<name> mang cho một phần gắn riêng của component — .type, .resolved_version, .labels, .values, .infra, và .provides đã phân giải của FeatureRecipe được ràng buộc với nó — xem dạng của phần gắn. Các provides đọc ở đây chính là những provides mà FeatureRecipe riêng của phần gắn render dựa trên, nên tên mà bên tiêu thụ tham chiếu và tên của tài nguyên mà FeatureRecipe đó phát ra là cùng một giá trị đã được đánh giá.
  • Không bao giờ nằm trong .features. .features riêng của component chỉ chứa các phần gắn được viết trên khối của chính nó. Do đó, một Recipe duyệt .features và chọn các phần gắn theo kiểu — {{ range $name, $f := (default dict .features) }}{{ if eq $f.type "core/referenced-secret" }}… — không bao giờ gặp thông tin xác thực của một kết nối, kể cả khi đó là cùng một Feature: một template truy cập phần gắn của kết nối thông qua kết nối của nó, không bao giờ thông qua .features. Điều này cũng đúng trên mọi bề mặt hiển thị các phần gắn của một component, bao gồm cả ngữ cảnh assertions.

Các component sử dụng component này — .context.used_by

.context.uses nhìn ra ngoài, vào các kết nối mà một component tạo ra. .context.used_by nhìn vào trong, vào các component có mục uses trỏ tới component này. Một FeatureRecipe được gắn vào component sẽ đọc nó, và đó là nơi đặt một tài nguyên mô tả hoặc giới hạn các kết nối đó — chẳng hạn một network policy chỉ cho phép các component được khai báo là gọi tới component này:

artifacts:
callers.yaml: |
apiVersion: v1
kind: ConfigMap
metadata:
name: {{ .context.rendered_name }}-{{ .attachment_name }}
data:
callers: |
{{- range .context.used_by }}
- component: {{ .component_id }}
socket: {{ .socket }}
selector: {{ .provides.selector }}
{{- with .source_namespace }}
namespace: {{ . }}
{{- end }}
{{- end }}

Mỗi mục mang:

  • .component_id (string) — ID instance của component kết nối ở dạng làm phẳng (frontend, data-layer.etl), là giá trị mà một template đường dẫn subDirectory: đọc dưới tên .component_id.
  • .socket (string) — socket mà kết nối lấp đầy trên component kết nối (khóa usesSchema của nó).
  • .provides (map giá trị string) — những gì component kết nối công bố, thu hẹp về các khóa mà Component của nó khai báo: cùng các giá trị mà một consumer của component đó đọc tại .context.uses.<alias>.provides. Một khóa mà Recipe của component công bố nhưng Component của nó không khai báo thì không nằm trong số đó.
  • .source_namespace (string) — namespace mà component kết nối được đặt vào: annotation aggrega.ai/namespace áp dụng cho nó, được truyền xuống qua các boundary của nó, trong đó mục riêng của nó trong Release được ưu tiên. Một component có mục Release đặt namespace, hoặc xóa nó bằng null, mang thiết lập riêng của nó thay vì của boundary, nên giá trị này chỉ namespace mà các tài nguyên riêng của component được render vào. Không có mặt khi không có namespace nào áp dụng cho component; hãy đọc nó qua with hoặc if, như ví dụ làm, thay vì in trực tiếp.
  • .source_boundary_path (string) — đường dẫn của boundary Release chứa component kết nối, với các boundary lồng nhau được nối bằng / (edge, edge/inner).
  • .render_facts (map của các list) — những gì các lần render của component kết nối đã báo cáo về đầu ra chúng phát ra, được khóa theo tên fact, cùng dạng với .context.render_facts. Mỗi fact là một list, nên template luôn duyệt range qua nó, kể cả khi nó chỉ có một mục. Các mục của nó có thể đến từ lần render riêng của component kết nối và từ các lần render của các Features được gắn vào nó: các list mà một tên nhận được từ mỗi nguồn được nối thành một, các lời gọi provider riêng của component trước, sau đó là từng Feature của nó theo thứ tự chúng đã render. Chỉ có mặt với một FeatureRecipe đặt readsCallerRenderFacts: true — các attachment của nó render khi mọi component đã render xong, nên lần render của mọi caller đều hoàn tất — và khi đó có trên mọi mục, rỗng với một caller mà các provider không báo cáo gì. Một FeatureRecipe không đặt khóa này không thấy .render_facts trên mục nào, và một template của nó đọc chúng sẽ dừng build trước khi bất cứ thứ gì được render.

Hai giá trị vị trí là những giá trị mà một FeatureRecipe phạm vi boundary đọc dưới tên source_namespace và source_boundary_path trên mục của cùng kết nối trong các list cạnh .boundary của nó: cả hai góc nhìn đọc vị trí đặt một component theo cùng một cách, nên chúng không bao giờ mâu thuẫn về điều đó. Một cạnh trong các list đó cũng mang đường dẫn lắp ráp của mỗi endpoint — source_assembly_path và target_assembly_path, thư mục bên dưới thư mục đầu ra của bản build mà provider của endpoint lắp ráp nó vào — điều mà một mục .context.used_by không mang.

Một FeatureRecipe đặt readsCallerRenderFacts: true đọc các fact của mỗi caller giống như cách nó đọc của host. Với một provider mô tả một fact tên ports mà mỗi mục mang một port:

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

Một caller có provider không báo cáo ports sẽ render một ports: rỗng thay vì thất bại, vì một tên không ai báo cáo được đọc là không có gì.

Cách list hoạt động:

  • Theo thứ tự được viết. Các mục theo thứ tự các component kết nối được viết, sau đó theo thứ tự các mục uses riêng của từng component. Một component kết nối hai lần xuất hiện hai lần, một lần cho mỗi kết nối. Vì đây là list chứ không phải map, một range gặp các caller theo thứ tự đó — không có gì được sắp xếp.
  • Chỉ ở nơi attachment render các tài nguyên riêng của nó. valuesMapping:, workload: và artifacts: của FeatureRecipe đọc nó. Nó rỗng trong các template Recipe riêng của component, trong một injectMapping:, và trong with: và when: của một bước pipeline:, vì những gì mỗi thứ đó tạo ra có thể nằm trong đầu ra đã render của chính component: một injectMapping: viết delivery pipe của component, và một bước pipeline có thể viết lại các tài liệu của component. Đó là điều giữ cho đầu ra riêng của một component không đổi bất kể ai sử dụng nó — nối thêm một caller vào một component sẽ thay đổi đầu ra của một Feature gắn vào nó có đọc các caller, và không thay đổi gì mà chính component render.
  • Không có gì về bản thân kết nối. Một mục không mang values hay infra theo từng kết nối và không mang attachment nào của kết nối; những thứ đó ở lại với component tiêu thụ, dưới .context.uses.<alias> của nó.
  • Rỗng khi không có gì sử dụng component. Khi đó một range qua nó không render gì.
  • Được truyền qua, không bao giờ được diễn giải. Danh tính, socket, các giá trị được công bố và vị trí là các chuỗi mà compiler truyền qua, còn các render fact là những gì các provider của mỗi caller đã báo cáo, được khóa theo tên. Nó không suy luận gì từ một tên, không tải gì, và không quyết định gì về việc một tài nguyên nên cho phép caller nào; template quyết định.

Những gì một provider đã báo cáo về một lần render — .context.render_facts

Provider của một component có thể báo cáo các fact về đầu ra nó đã render — các thuộc tính của tài liệu nó đã viết mà chỉ hiểu biết riêng của nó về định dạng mới thấy được. Provider báo cáo fact nào, dưới tên nào và với nội dung gì trong mỗi mục, là hợp đồng được tài liệu hóa riêng của provider đó; xem Reporting facts about what a guest emitted cho phía provider. Chẳng hạn, provider helm báo cáo các label của pod template nó phát ra, các selector của controller và Service của nó, và các port của container — xem render facts của nó. Một FeatureRecipe gắn vào component đọc những gì provider của component đã báo cáo tại .context.render_facts, được khóa theo tên fact. Với một provider mô tả một fact tên ports mà mỗi mục mang một name và một port:

artifacts:
ports.yaml: |
ports:
{{- range .context.render_facts.ports }}
- name: {{ .name }}
port: {{ .port }}
{{- end }}
  • Mỗi fact là một list. Provider báo cáo mỗi fact dưới dạng list, kể cả khi nó chỉ có một mục, nên template luôn duyệt range qua nó — không có giá trị đơn lẻ nào để đọc riêng.
  • Một list cho mỗi tên, được nối trên toàn bộ lần render của component. Render một component có thể cần nhiều lời gọi provider — chẳng hạn một lần render chart và một lần đặt artifacts — và mỗi lời gọi tự báo cáo. Các list mà một tên nhận được từ các lời gọi đó được nối thành một, theo thứ tự các lời gọi đã chạy. Những gì các Features gắn vào component đã render không nằm trong đó ở đây: một Feature chỉ đọc lần render riêng của component tại .context.render_facts, bất kể các Features khác của component đã phát ra gì.
  • Trên mọi template của một FeatureRecipe được gắn. valuesMapping:, workload: và artifacts: của nó đọc nó, và with: và when: của các bước pipeline: của nó cũng vậy — các fact đến từ lần render riêng của component, nên việc đọc chúng không khiến gì phụ thuộc vào ai kết nối tới component. Nó không có mặt trong các template Recipe riêng của component và trong một injectMapping:, vốn chạy trước khi component được render.
  • Rỗng chứ không thiếu. Khi provider của component không báo cáo gì, .context.render_facts là một map rỗng, và một tên không ai báo cáo được đọc là không có gì, nên một range qua nó không render gì thay vì thất bại.
  • Thứ tự. Một list giữ các mục theo thứ tự provider đã báo cáo. Một mục object là một map có khóa như mọi map khác trong context, nên một template duyệt range qua nó sẽ gặp các khóa theo thứ tự khóa.
  • Được truyền qua, không bao giờ được diễn giải. Compiler chỉ kiểm tra rằng giá trị của mỗi fact là một list. Nó không đọc gì về ý nghĩa của một tên hay một mục; template quyết định làm gì với nó.

.uses của một assertion — được đánh khóa theo socket, rồi theo alias

Một template assertions: đọc cùng các kết nối đó qua một góc nhìn hẹp hơn của riêng nó: .uses nằm ở gốc thay vì dưới .context, và không mang gì mà đích của một kết nối đã công bố, vì cả hai giai đoạn assertion đều được đánh giá trước khi render. Nó phản ánh dạng viết uses: <socket>: <alias>: { target: … } — được đánh khóa theo socket, và dưới mỗi socket theo alias của mọi kết nối trên socket đó; một kết nối được viết dưới dạng một mục danh sách lấy đích của nó làm alias. Mục của mỗi kết nối mang target, alias và, với một kết nối do một attachment Feature tạo ra, origin_feature, cùng ba trong số các dữ kiện mà .context.uses mang, dưới cùng tên và giữ cùng giá trị: .labels, các nhãn của đích; .values, các giá trị được viết trên kết nối; và .features, các attachment được viết trên kết nối, được đánh khóa theo slot. Mỗi trường trong ba trường này có mặt trên mọi mục, và rỗng khi kết nối không mang gì. Một attachment dưới .features chỉ mang type, resolved_version và values — đó là dạng mà một assertion đọc mọi attachment, kể cả attachment của chính một component, vì FeatureRecipe của một attachment chưa phân giải provides của nó khi một assertion chạy.

Một socket chứa một kết nối và một socket chứa nhiều kết nối có cùng dạng, nên một assertion đọc cả hai theo cùng một cách. Với một component có mục Aggregate viết uses: { models: { local: { target: llama }, fast: { target: turbo } } }:

assertions:
two-models-wired: |
{{- if lt (len (optional .uses "models" dict)) 2 -}}
{{- fail "wire two models to the models socket" -}}
{{- end -}}
local-is-llama: |
{{- if and (hasKey .uses "models") (hasKey .uses.models "local") (ne .uses.models.local.target "llama") -}}
{{- fail (printf "the local connection must point at llama; it points at %s" .uses.models.local.target) -}}
{{- end -}}

hasKey .uses "models" hỏi xem socket đã được nối hay chưa, len đếm số kết nối của nó, một range trên nó duyệt qua từng kết nối theo thứ tự bảng chữ cái của alias, và .uses.models.local.target đọc một kết nối. .uses.models.target không trỏ tới kết nối nào, và dừng lại dưới missingkey=error của bề mặt assertions. Mỗi kết nối có một mục riêng, vì cùng lý do như map của ngữ cảnh render: hai kết nối của cùng một component không bao giờ dùng chung một alias, vì bản build từ chối điều đó trước khi bất kỳ assertion nào chạy. Toàn bộ ngữ cảnh assertion được mô tả tại assertions-block.md.

Ngữ cảnh template có các trường dạng inject này, mỗi trường có ngữ nghĩa riêng. Tác giả Recipe và FeatureRecipe nên biết cần đọc bề mặt nào.

Bề mặtLoạiĐược điền khiCách dùng
.context.injectmap các cơ chế (luôn có mặt)Mọi lần renderĐường ống phân phối chuẩn đã được hydrate sẵn — đọc trường này trong các template valuesMapping:/workload:/artifacts: và tại mọi vị trí template của FeatureRecipe.
.inject (cấp cao nhất)map các cơ chế (có thể null)Khi render FeatureRecipe của một attachment, nếu attachment viết một khối inject:Các mục inject: riêng của attachment, nằm dưới mỗi cơ chế mà khối của nó nêu tên — env, file, arg, hoặc một cơ chế tùy chỉnh như vault_ref — với mỗi tên cục bộ được ánh xạ tới khóa mà from: của nó nêu tên. Khóa đó hoặc là khóa mà FeatureRecipe công bố trong provides: của nó, vốn cũng được trình biên dịch chuyển vào .context.inject của component, hoặc là khóa mà chính một FeatureRecipe đọc .inject tiêu thụ: một mục nêu tên một khóa mà FeatureRecipe không công bố sẽ dừng bản build, trừ khi một template mà FeatureRecipe đánh giá theo ngữ cảnh này — valuesMapping:, workload:, artifacts:, omits: của nó, hoặc with: hay when: của một bước pipeline — đọc .inject qua một đường dẫn mà template nêu tên: .inject, .inject.env, {{ with .inject }} và tương tự, chứ không phải chuyển giao toàn bộ ngữ cảnh như toJson .. injectMapping: của nó không được tính, vì nó được đánh giá theo ngữ cảnh của component, nơi không có .inject. Khối của một attachment không mang literal: một mục value: ở đó sẽ dừng bản build, và một literal mà component cần được viết trong khối inject: riêng của component. Một cơ chế tùy chỉnh được đọc tại .inject.<mechanism> đúng như .inject.env, và các mục của nó xuất hiện trong .inject.all cùng với ba cơ chế cốt lõi. Một lần đọc theo dấu chấm vào một cơ chế mà attachment không viết sẽ dừng như một khóa không xác định, ngay cả bên trong một if hoặc một with, nơi .context.inject.<mechanism> được đọc là rỗng; hãy đọc một cơ chế mà attachment có thể không viết thông qua {{ with .inject }}{{ if hasKey . "<mechanism>" }}{{ index . "<mechanism>" "<key>" }}{{ end }}{{ end }}, cách này build được dù attachment có viết cơ chế đó hay bất kỳ khối inject: nào hay không. Không có trong các template của một Recipe cơ sở và trong một attachment không viết khối inject: nào.
.inject_raw (cấp cao nhất)map các cơ chế (có thể null)Được đặt khi developer đã viết một khối inject: trên component chaÝ định nguyên vẹn của developer trước mọi sự can thiệp inject-mapping. Mỗi cơ chế mà khối nêu tên — env, file, arg, hoặc một cơ chế tùy chỉnh như ssm_param — nằm dưới tên riêng của nó, chứa các mục đúng như đã viết (in với from hoặc value), theo thứ tự đã viết: .inject_raw.ssm_param đọc một cơ chế tùy chỉnh theo cách .inject_raw.env đọc cơ chế lõi. Dùng cho các kiểm tra logic “developer ban đầu có yêu cầu khóa phân phối này không?”; không bị ảnh hưởng bởi việc FeatureRecipe injectMapping viết lại. Là nil nếu developer bỏ qua khối inject:.
.context.self_injectmap các cơ chế (luôn có mặt)Mọi lần render; rỗng ở nơi developer không viết khối inject: nào trên componentMỗi tên trong khối inject: của chính component được ánh xạ tới khóa riêng mà mục của nó phân phối — provides.<key>, values.<key> hoặc rỗng. Dùng để bỏ qua một tên mặc định cho một giá trị riêng mà developer đã phân phối; xem ở trên.

Tác giả cần phần phân phối đã được phân giải sau can thiệp nên đọc .context.inject. Tác giả cần ý định ban đầu bất biến (ví dụ, để phát hiện sự can thiệp hoặc để đưa ra hành vi dự phòng khi developer bỏ qua khối inject) nên đọc .inject_raw. Tác giả cần biết developer đã đặt tên cho những giá trị riêng nào của component nên đọc .context.self_inject.

Bề mặt FeatureRecipe của attachment

Khi renderer đánh giá các template của một FeatureRecipe attachment, một trường cấp cao nhất bổ sung được đặt:

  • .attachment_name (string) — tên instance của attachment: vị trí mà nó lấp trong featuresSchema của entity sở hữu, hoặc tên tự do mà tác giả đặt cho nó. Các locals:, provides:, injectMapping:, valuesMapping: và artifacts: của một FeatureRecipe đọc trường này để suy ra một định danh tài nguyên xác định — {{ .context.rendered_name }}-{{ .attachment_name | replace "_" "-" }} khi provider của host báo cáo một tên đã render, như helm, và {{ .context.instance_id }}-{{ .attachment_name }} khi nó không báo cáo tên nào — và để đặt tên cho attachment đang được xử lý.

Các template riêng của một Recipe cơ sở không phân giải một attachment, nên trường này không thuộc context của chúng: một template provides:, locals: hoặc source: của Recipe tham chiếu đến nó sẽ dừng lại và nêu tên tham chiếu đó thay vì render một giá trị rỗng. Một FeatureRecipe có executionScope: boundary render một lần cho boundary thay vì một lần cho mỗi component, nên trường này cũng không có cho các template chạy cho boundary; injectMapping: của nó chạy cho mỗi component mà attachment đi tới và đọc trường này ở đó.

Trên các template tạo ra tài nguyên riêng của attachment — valuesMapping:, workload: và artifacts: của nó — context của attachment cũng liệt kê các component sử dụng host của nó, tại .context.used_by, và, khi FeatureRecipe của nó đặt readsTargetRenderFacts: true, mang theo những gì mà mỗi component được nối với host của nó đã render, tại .context.uses.<alias>.render_facts. Các template đó và các bước pipeline: của nó cũng đọc những gì provider của host đã báo cáo về lần render của host, tại .context.render_facts. Một FeatureRecipe phạm vi boundary render các tài nguyên của nó mà không có component host và không có .context; thay vào đó, nó đọc mọi kết nối vào boundary của nó dưới .boundary.internal_uses_edges và .boundary.incoming_cross_boundary_uses_edges. injectMapping: của nó là template duy nhất nó viết mà chạy trong context của một component — context của mỗi component mà attachment đi tới, kể cả .context.* — và một tham chiếu tới .boundary ở đó sẽ dừng build.

Trường này là con đường duy nhất đến tên instance của attachment. .context.instance_id là component host mà attachment đang phân giải cho — nó biểu thị host trên mọi bề mặt template mà trình biên dịch đánh giá, kể cả locals: riêng của một FeatureRecipe — nên hai tên này không thể hoán đổi cho nhau, và không tên nào thay thế được tên kia.

.source là của chính attachment. Template source: của một FeatureRecipe được đánh giá trước valuesMapping: của nó, giống như ở một Recipe, và những gì nó tạo ra là nội dung mà .source giữ trên các template tạo ra tài nguyên của attachment — valuesMapping:, omits:, workload: và artifacts: của nó — và trên các bước pipeline: của nó. Nó không bao giờ là source của component chủ: một FeatureRecipe không khai báo source: nào, hoặc có template không tạo ra gì, sẽ không đọc được gì ở đó, ngay cả trên một host có Recipe khai báo source. Một FeatureRecipe có phạm vi boundary đọc source của chính nó trên cùng các template đó. Ngoại lệ duy nhất là injectMapping:, vốn chạy trước khi source của attachment được đánh giá và đọc .source như chính Recipe của component chủ.

.context.rendered_name cũng thuộc về component host: trên mọi template của một attachment theo từng component, nó mang tên mà provider riêng của host báo cáo cho host — giá trị mà Recipe riêng của host đọc — nên một attachment đặt tên tài nguyên theo host của nó bằng {{ .context.rendered_name }}-{{ .attachment_name }} và nhận được một tên mà nền tảng chấp nhận, ngay cả khi định danh của host chứa dấu gạch dưới hoặc chữ in hoa. Nó có mặt ở bất cứ đâu provider của host báo cáo một tên và vắng mặt khi provider không báo cáo tên nào, và việc đọc nó trên một host như vậy sẽ dừng bản build từ bất kỳ template nào mà FeatureRecipe viết inline ngoài injectMapping: của nó; xem Đặt tên cho một tài nguyên đã render.

Tính khả dụng theo từng vị trí

Tính khả dụng của các trường thay đổi theo vị trí template. Các template provides: của Recipe chạy ở giai đoạn đánh giá provides với ngữ cảnh tự chứa (không có .context.inject/.context.uses); valuesMapping: của Recipe chạy ở giai đoạn render cơ sở với ngữ cảnh template đầy đủ; injectMapping: của FeatureRecipe chạy ở giai đoạn inject mapping với ngữ cảnh template đầy đủ, bao gồm cả inject pipe đang bị chặn. Bảng tính khả dụng đầy đủ theo từng vị trí nằm ở expansion-matrix.md; trang này mô tả cấu trúc của các trường mà cột “available references” của ma trận trỏ tới.

Tham chiếu chéo