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.

Ma trận mở rộng template

Tham chiếu mở rộng template — Ma trận đầy đủ

DSL của Aggrega hỗ trợ mở rộng Go text/template (với thư viện Sprig được đăng ký sẵn) tại nhiều vị trí trong các thực thể YAML. Mỗi vị trí có một tập tham chiếu khả dụng riêng, được quyết định bởi thời điểm dữ liệu trở nên cụ thể trong quá trình biên dịch. Trang này là tài liệu tham chiếu về những gì có thể được tham chiếu ở đâu.

1. Cây thời điểm của pipeline (khi nào dữ liệu trở nên cụ thể)

Để hiểu những tham chiếu nào khả dụng, bạn cần hiểu khi nào từng phần dữ liệu được phân giải. Các giai đoạn dưới đây được liệt kê theo thứ tự chúng chạy, và mỗi giai đoạn được đặt tên theo việc nó làm — phần còn lại của trang này dùng tên đó để gọi nó:

Resolution — resolver and syntax validator
├── .parameters → Interpolated into the Aggregate's text; the merged map
│ then stays readable to path templates only
├── .values → schema-validated against the Component's pillar schema, concrete
├── .infra → Release-merged into target components/features, concrete
└── Catalog entities → Resolved (extends merged, pillar schemas composed, usesSchema extracted)
Topology construction
├── .context.instance_id → Node identity, written as a name (e.g., "data-layer-zdmain-db")
└── .context.labels → From Catalog + label-transform mutations
Graph finalization
├── .context.annotations.release → Cascaded from boundary hierarchy
├── .context.annotations.catalog → From Component metadata.annotations
├── .context.annotations.aggregate → Cascaded from subsystem hierarchy
└── feature_values_mapping → 5-Tier Onion Model normalized
Rendering begins. Provides evaluation — locals preamble, then provides
├── .context.rendered_name → Asked of each node's provider before the preamble; present only where
│ that provider derives a name for the node's output
├── .locals (per node) → Block resolved in author order; an entry reads earlier siblings
└── .provides (all nodes) → Self-contained templates evaluated (any order), reading .locals
Inject hydration — self-inject resolution
└── component.inject → value: literals expanded, from: own provides resolved
Inject hydration — uses-inject resolution
└── uses[].inject → from: target provides resolved
Inject mapping — injectMapping interception
└── .context.inject → Fully populated pipe, intercepted by FeatureRecipe injectMappings
Base rendering
└── Full template context → Everything available
The plugin pipeline — post-render mutation
└── Full template context + .steps → Inter-step pipeline outputs available

2. Ma trận mở rộng template

Mọi vị trí trong DSL nơi các biểu thức Go template được đánh giá, và chính xác những tham chiếu nào khả dụng:

#LocationThực thểĐược đánh giá trongTham chiếu khả dụng
1{{ .parameters.X }} trong các chuỗi YAML của AggregateAggregatePhân giải (nội suy)Chỉ .parameters. Mọi dữ liệu khác chưa được phân giải.
2{{ .parameters.X }} trong các chuỗi YAML của ReleaseReleaseKhông được đánh giáKhông có. Các chuỗi của Release được đọc đúng như đã viết: một {{ .parameters.X }} dưới infra:, trong một annotation hoặc làm giá trị parameters: sẽ đến đích dưới dạng văn bản literal đó. Release cung cấp các giá trị tham số (map parameters: inline và các giá trị được nạp bằng $import: được kết hợp thành map tham số đã hợp nhất); các chuỗi của Aggregate đọc chúng (#1), và các path template cũng vậy (#3).
3Các template directory / subDirectoryBoundary của ReleaseKết xuất (đánh giá đường dẫn).capability, .boundary_name, .parameters.X, .manifest.recipe_name, .parent_boundary.*, và .component_id (chỉ subDirectory: — một template directory: từ chối nó).
4Các chuỗi value: trong inject của ComponentComponent của AggregatePhân giải self-inject.values, .infra, .context.instance_id, .context.labels, .context.annotations.* (cả 3 nhóm), .metadata.* (release_name, release_version, environment, aggregate_name). BỊ CẤM: .context.inject (vòng lặp — pipe đang được xây dựng), .context.uses (hãy dùng uses[].inject để kết nối giữa các component). Template nằm trong văn bản của Aggregate, vốn được phép nội suy tham số của #1 đọc trước, nên hãy viết nó ở dạng thoát — value: '{{"{{"}} .metadata.release_name }}' — để nó đến được giai đoạn này; nếu viết trực tiếp, phép nội suy sẽ đánh giá nó và dừng, vì văn bản của một Aggregate không định nghĩa gốc nào ngoài .parameters.
5Các chuỗi của trường source (chuỗi cấp cao nhất HOẶC các trường con có giá trị chuỗi của một map source: có cấu trúc)Recipe / FeatureRecipePhân giải sourceHai bề mặt, được quyết định bởi thứ mà source chỉ tới. Một tọa độ từ xa — version, chart, ref và module_subdir của một khối có cấu trúc chỉ tới một registry, một kho chart hoặc một kho git — được đánh giá khi aggrega pull phân giải artifact để ghim nó: chỉ .values, .infra, .locals và chuỗi tĩnh, với các hàm trợ giúp riêng của Aggrega (optional, capitalizedWords, index) và không có hàm nào của Sprig, và không có gốc .context. Các mục .locals được đánh giá ở đó là những mục mà các trường đó đọc, trực tiếp hoặc thông qua một mục khác — mọi mục, khi một trường đọc .locals theo cách không chỉ tới một mục cụ thể nào — vì vậy một mục không trường nào đọc sẽ được để lại cho bước kết xuất. Một source chỉ tới một đường dẫn trong workspace được đánh giá khi thực thể được kết xuất: .context.instance_id, .values, .infra, .locals (toàn bộ khối đã phân giải của thực thể khai báo), chuỗi tĩnh. Ở đó source của một FeatureRecipe còn đọc thêm .attachment_name — một attachment là thứ đang được phân giải — và .context.instance_id của nó chỉ tới component chủ, bên cạnh .context.rendered_name, tên được báo cáo của component chủ (xem #9); một FeatureRecipe ở phạm vi boundary đọc .boundary.* và không đọc trụ cột nào theo từng component. BỊ CẤM trên cả hai: .context.inject, .context.uses, .provides (bất biến tự chứa — bề mặt source trong workspace chia sẻ ngữ cảnh với locals của chính thực thể khai báo, nên hai bề mặt chấp nhận và từ chối cùng những tham chiếu, và một tọa độ từ xa đọc một tập con của ngữ cảnh đó; việc phân giải source phải hoàn tất trước khi pipe topology được hydrate và trước khi bất kỳ chart, module hay nội dung artifact nào được nạp).
6Các template provides của RecipeRecipeĐánh giá provides.context.instance_id, .context.rendered_name (tên mà provider của node đặt cho đầu ra nó kết xuất cho node — từ source do tác giả cung cấp, hoặc từ một workload mà nó tổng hợp; đọc nó trên một node có provider không báo cáo tên như vậy sẽ dừng — xem Đặt tên cho một tài nguyên được kết xuất), .values, .infra, .locals (toàn bộ khối đã phân giải của node — các locals được phân giải trong phần mở đầu của giai đoạn này, trước provides), chuỗi tĩnh. BỊ CẤM: mọi gốc khác — .context.inject, .context.uses (liên node), .context.annotations.*, .context.labels, .context.metadata, .metadata.* (gắn với vị trí/triển khai), và .attachment_name (không có attachment nào đang được phân giải trong khi đánh giá provides của một Recipe cơ sở). Việc kiểm tra là một danh sách cho phép tích cực: tham chiếu tới bất kỳ gốc nào mà ngữ cảnh provides không cung cấp sẽ dừng (bất biến tự chứa — cho phép đánh giá song song mà không cần sắp xếp topo). Một .locals.<key> chỉ tới một khóa mà khối locals không khai báo cũng dừng, vì trụ cột này là một map khóa mở mà riêng việc kiểm tra gốc không thể kiểm soát.
7valuesMapping của Recipe (inline, $import: tệp, hoặc $import: thư viện)RecipeKết xuất cơ sởNgữ cảnh template đầy đủ: .values, .infra, .context.* (instance_id, rendered_name, labels, annotations, inject, uses), .locals, .provides, .features, .metadata. Một tham chiếu .context.rendered_name viết inline sẽ dừng trên một node có provider không báo cáo tên như vậy, như ở #6; một tham chiếu nằm trong nội dung được nạp bằng $import: thì không được kiểm tra, và kết xuất rỗng trên node như vậy.
8injectMapping của FeatureRecipeFeatureRecipeÁnh xạ injectNgữ cảnh template đầy đủ: .values, .infra, .context.* (bao gồm .context.inject — pipe đang bị chặn — và .context.uses). .context.used_by ở đây rỗng: đầu ra của ánh xạ đi vào pipe phân phối của chính host. .context.render_facts không có: ánh xạ chạy trước khi host kết xuất. .context.rendered_name là tên được báo cáo của component chủ, như ở #9; một ánh xạ đọc nó không được kiểm tra, và kết xuất nó rỗng trên một host có provider không báo cáo tên nào. Ngữ cảnh là như nhau bất kể executionScope của FeatureRecipe: ánh xạ của một FeatureRecipe phạm vi boundary chạy một lần cho mỗi component mà attachment đi tới, đọc .context.* của component đó, và đọc .features.<attachment>.provides cùng .locals như kết quả của lần đánh giá boundary duy nhất. BỊ CẤM: .boundary, thứ mà ngữ cảnh của không component nào mang — một tham chiếu sẽ dừng build.
9valuesMapping của FeatureRecipe (cùng workload: và artifacts: của nó)FeatureRecipeKết xuất cơ sởNgữ cảnh template đầy đủ + .attachment_name, .inject (các mục inject: của chính attachment, khi attachment viết một khối inject:), .context.render_facts — những gì provider của host báo cáo về lần kết xuất của host — và .context.used_by — các component sử dụng host, mỗi component mang render facts của riêng nó khi FeatureRecipe đặt readsCallerRenderFacts: true. Mỗi kết nối trên .context.uses mang render facts của đích của nó, tại .render_facts, khi FeatureRecipe đặt readsTargetRenderFacts: true. .context.instance_id và .context.rendered_name là danh tính của component chủ và tên mà provider của chính host báo cáo cho nó — cùng giá trị mà Recipe của host đọc, trên cả locals: và provides: của FeatureRecipe — và một tham chiếu tới .context.rendered_name viết inline sẽ dừng trên một host có provider không báo cáo tên như vậy. .source là source: đã được đánh giá của chính FeatureRecipe, không bao giờ là của component chủ, và không chứa gì khi FeatureRecipe không khai báo.
10Các khối with: của pipelineRecipe / FeatureRecipePipeline pluginNgữ cảnh template đầy đủ + .steps (đầu ra giữa các bước từ các bước pipeline trước đó). .context.used_by ở đây rỗng, và không kết nối nào trên .context.uses mang render facts của đích của nó: một bước có thể viết lại các tài liệu của chính host. Bước của một FeatureRecipe được gắn đọc .context.render_facts, render facts của chính host, như #9.
11Nội dung workload: của Recipe (mọi trường có template bên trong, dù inline hay được nạp bằng $import:)RecipeKết xuất cơ sởNgữ cảnh template đầy đủ. Mọi trường bên trong nội dung Workload — replicas, containers.<name>.image, containers.<name>.variables.<KEY>, containers.<name>.ports.<port>, services.<name>.ports.<port>, volumes.<name>.*, health.* — là một phần của cùng lần đánh giá template xử lý toàn bộ chuỗi Workload. Nội dung Workload là một Go template duy nhất được đánh giá một lần với ngữ cảnh template đầy đủ; các template cấp trường bên trong được phân giải trong cùng lần đánh giá đó chứ không phải trong một lần riêng.

Ghi chú về tính tự chứa. Các chuỗi source (#5) chia sẻ bất biến tự chứa của provides (#6): cả hai bề mặt đều từ chối các tham chiếu .context.inject và .context.uses. Quá trình phân giải nguồn chạy trước bước hydrate inject vốn điền dữ liệu vào .context.inject, và trước khi bất kỳ bước nào phía sau sử dụng nguồn đã phân giải — vì vậy quy tắc này cùng lý do của nó áp dụng cho cả hai bề mặt. Điểm khác nhau giữa hai bề mặt là trụ provides: một source trong workspace chia sẻ ngữ cảnh với locals của thực thể khai báo, và một tọa độ từ xa đọc một tập con của ngữ cảnh đó, nên cả hai đều từ chối .provides, trong khi bản thân provides chính là bề mặt đang được phân giải. Cả hai đều đọc .locals. Quy tắc này áp dụng cho source của một FeatureRecipe theo cùng điều kiện như cho nguồn của một Recipe, mỗi bên được kiểm tra theo bề mặt locals riêng của chính thực thể đó.

Ghi chú về template trong phần thân Workload (#11). Phần thân Workload là một chuỗi template duy nhất mà bộ render đánh giá như một tổng thể, rồi phân tích kết quả thành một tài liệu Workload. Các template cấp trường bên trong (chỗ này là replicas: {{ .infra.replicas | default 1 }}, chỗ kia là LOG_LEVEL: "{{ .values.log_level }}" bên trong containers.app.variables) không phải là các vị trí đánh giá template riêng biệt — tất cả đều tham gia vào một lần đánh giá base rendering duy nhất tạo ra Workload. Tác giả không cần một quy tắc khả dụng riêng cho các trường bên trong Workload; quy tắc cho toàn bộ Workload (#11) bao quát mọi template cấp trường bên trong.

Giá trị dự phòng có nhận biết phân biệt bên trong phần thân Workload. Ví dụ replicas: {{ .infra.replicas | default 1 }} ở trên gộp chung “tác giả không đặt replicas” với “tác giả đặt replicas thành 0” — default kích hoạt trong cả hai trường hợp. Khi một Release chủ ý khai báo infra.replicas: 0 để biểu thị scale-to-zero (một mẫu phổ biến của Knative / KEDA), dạng | default 1 âm thầm ghi đè ý định đó. Dạng có nhận biết phân biệt là replicas: {{ optional .infra "replicas" 1 }} — optional kiểm tra sự hiện diện của khóa và trả về giá trị đã khai báo (kể cả số không đã khai báo) khi khóa được đặt, chỉ dùng 1 khi khóa vắng mặt. Xem sprig-functions.md để biết đầy đủ ngữ nghĩa và hướng dẫn khi nào nên ưu tiên dùng.

3. Các tham chiếu bị cấm và lý do

LocationTham chiếu bị cấmLý do
inject value: của Component (#4).context.injectTại thời điểm đó pipe inject đang được xây dựng — một template value: self-inject không thể đọc từ pipe mà nó đóng góp vào.
inject value: của Component (#4).context.usesViệc kết nối giữa các component nằm trong uses[].inject. Các template value: self-inject của một component chỉ đóng kín trên dữ liệu riêng của component đó.
provides của Recipe (#6).context.injectCác template provides được đánh giá theo thứ tự bất kỳ và chỉ đóng kín trên dữ liệu riêng của node (.values, .infra, .locals, .context.instance_id, .context.rendered_name). Pipe inject chưa được điền cho đến bước hydrat hóa inject, bước này chạy sau khi provides của mọi node đã được đánh giá.
provides của Recipe (#6).attachment_nameLượt provides của một Recipe cơ sở không phân giải attachment nào, nên tên sẽ được render rỗng. Root này bị từ chối thay vì được trả về trống.
source (#5).providesKhông bề mặt source nào mang trụ provides: bề mặt workspace-source dùng chung ngữ cảnh với locals riêng của thực thể khai báo, vốn không có trụ này, và một tọa độ từ xa đọc một tập con của ngữ cảnh đó. Locals được phân giải trước provides để provides: có thể đọc .locals; template source đọc cùng các locals đó thay vì quay ngược lại tìm provides.
locals của Recipe (phần mở đầu của #6).providesLocals được phân giải trước provides, nên provides riêng của node chưa tồn tại khi một local được đánh giá. Một local cần một giá trị mà provides cũng công bố sẽ tính giá trị đó trực tiếp từ .values / .infra — và mục provides sau đó đọc local.
locals của Recipe (phần mở đầu của #6).context.rendered_nameLocals của một Recipe dùng chung ngữ cảnh với template source của nó (#5), và bề mặt đó không cung cấp tên: việc node có cung cấp source hay không, điều do template source quyết định, là một trong những yếu tố mà tên phụ thuộc vào. Tham chiếu này dừng với chẩn đoán unknown-root, liệt kê .context.instance_id là những gì .context định nghĩa ở đó. Thay vào đó, hãy đọc khóa trong một mục provides, hoặc trong một template của giai đoạn base rendering.
provides của Recipe (#6).context.uses.context.uses tham chiếu đến provides của các node khác, và bước đánh giá provides chạy chúng theo thứ tự tùy ý. Các template provides giữ tính tự chứa để việc đánh giá không phụ thuộc thứ tự.
locals, provides, source (#5) của FeatureRecipe và các template render inline (#9, #10), trên một host có provider không báo cáo tên.context.rendered_nameTrên một attachment Feature, khóa này mang tên đã báo cáo của component host, và một host chỉ đặt một tập artifact, hoặc render thông qua một provider không suy ra tên như vậy, thì không có tên nào để mang. Tham chiếu này dừng với chẩn đoán unknown-root, liệt kê .context.instance_id trong số những gì .context định nghĩa ở đó; thay vào đó hãy đọc định danh, vốn là thứ mà các tài nguyên riêng của host được đặt tên theo trên một host như vậy.
source (#5).context.injectViệc phân giải source chạy trước bước hydrat hóa inject điền dữ liệu cho .context.inject. Pipe chưa được điền khi URI source được đánh giá.
source (#5).context.usesViệc phân giải source phải hoàn tất trước khi bất kỳ bước nào phía sau tải chart, module hoặc phần thân artifact của thực thể khai báo. Cho phép tham chiếu giữa các node sẽ ràng buộc việc phân giải source với thứ tự duyệt topology, điều mà thiết kế cố ý tránh.
Parameters (mọi nơi trừ các template đường dẫn)Mọi bề mặt value-template sau bước interpolationInterpolation tiêu thụ mọi tham chiếu {{ .parameters.X }} trong YAML đã viết và ghi giá trị đã phân giải vào vị trí đó, nên một bề mặt value-template nhận giá trị literal đã phân giải thay vì trụ parameter. Các template đường dẫn do operator viết là ngoại lệ duy nhất và đọc trực tiếp .parameters.X.

4. Đường phân giải self-inject

Phân giải self-inject là nửa đầu của bước hydrat hóa inject, và nó chạy sau khi provides của mọi node đã được đánh giá. Khi một component khai báo một khối inject: cấp component, trình biên dịch đánh giá nó tại đó:

  1. Chuỗi value: literal: Nếu giá trị chứa biểu thức template Go, trình biên dịch đánh giá chúng với ngữ cảnh từ hàng #4 của ma trận (.values, .infra, .context.instance_id, .metadata.*, v.v.), được viết ở dạng thoát như hàng #4 chỉ ra. Các chuỗi thuần được giữ nguyên.
  2. Tham chiếu from:: Trình biên dịch tra cứu khóa trong từ điển provides riêng của node, vốn đã được phân giải vào lúc đó. Nếu khóa không tồn tại, trình biên dịch dừng bản build với lỗi invalid-inject-key.
  3. Kiểm tra xung đột: Trước khi hợp nhất vào pipe .context.inject, trình biên dịch xác minh rằng không có khóa nào xung đột với các khóa uses-inject mà nửa sau của bước hydrat hóa inject phân giải. Xung đột sẽ dừng bản build với lỗi duplicate-delivery-key.

Các chuỗi kết quả được hợp nhất vào .context.inject.env, .context.inject.file, .context.inject.arg (và mọi cơ chế tùy chỉnh), cùng với các kết quả phân giải uses-inject đó. Khi inject mapping (injectMapping) chạy, pipe đã chứa tất cả giá trị inject do nhà phát triển viết từ cả hai nguồn.