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.

Biến mẫu đường dẫn

Các trường directory: và subDirectory: trên một ranh giới Release là các Go template được đánh giá tại thời điểm build. Chúng kiểm soát nơi các artifact đã render được ghi ra đĩa và, theo đó, những artifact nào được lắp ráp cùng nhau — hai ranh giới được đánh giá ra cùng một bộ (path, provider) sẽ dùng chung một trình lắp ráp và tạo ra một đầu ra hợp nhất (một Chart.yaml, một docker-compose.yaml). Trang này là tài liệu tham khảo dành cho người viết về các biến mà những template đó có thể tham chiếu, ngữ nghĩa đánh giá nghiêm ngặt, và các quy tắc phân tầng cho phép các ranh giới kế thừa từ ranh giới cha.

Để tìm hiểu về mặt khái niệm của việc phân tách theo không gian và việc điều phối theo từng (path, provider), xem architecture/16-recipe-input-composition.md. Về bề mặt viết Release ở cấp thực thể, xem entities/release.md. Các hệ quả phía provider nằm trong providers/architecture.md và các trang riêng cho từng provider.

Đánh giá nghiêm ngặt: missingkey=error

Các template đường dẫn được đánh giá ở chế độ missingkey=error của Go. Một tham chiếu đến trường chưa được khai báo, một khóa parameters.X chưa được đặt, hoặc một lỗi đánh máy như {{ .parmaeters.region }} sẽ tạo ra một lỗi tường minh thay vì âm thầm render một chuỗi rỗng vào đường dẫn.

Mức độ nghiêm ngặt này bất đối xứng so với phần còn lại của trình biên dịch — valuesMapping, injectMapping và các bề mặt render giá trị khác dùng missingkey=zero theo quy ước của Helm/Sprig. Việc phát sinh đường dẫn khác biệt về mặt cấu trúc: một template render giá trị tạo ra chuỗi rỗng sẽ rơi vào một trường của manifest, nơi hậu quả là có giới hạn; một template đường dẫn tạo ra chuỗi rỗng sẽ rơi vào bố cục thư mục, nơi hậu quả là không có giới hạn (xung đột, lắp ráp bị hỏng, đường dẫn ma). Chế độ template đường dẫn nghiêm ngặt tồn tại để làm lộ ra các lỗi đó ở thời điểm build thay vì ở thời điểm triển khai.

Kiểm tra danh sách cho phép tại thời điểm phân tích cú pháp

Ngoài tính nghiêm ngặt khi chạy, các path template còn được kiểm tra tại thời điểm phân tích cú pháp đối chiếu với một danh sách cho phép khép kín gồm các tên biến. Một tham chiếu tới tên biến không nằm trong danh sách cho phép sẽ dừng quá trình build trước khi bất kỳ công việc kết xuất nào bắt đầu, kèm một thông báo chẩn đoán nêu tên trường vi phạm và boundary nơi nó xuất hiện.

Danh sách cho phép được thiết kế khép kín: các bề mặt như .context.inject, .values và .locals được cố ý không cung cấp cho path template. Việc phát sinh đường dẫn là một mối quan tâm về cấu trúc, không phải mối quan tâm về kết xuất giá trị; gắn đường dẫn assembly với các giá trị theo từng component sẽ khiến đồ thị đường dẫn phụ thuộc vào dữ liệu và làm suy yếu bất biến về đầu ra tất định.

Ma trận biến

Biếndirectory:subDirectory:Mô tả
{{ .capability }}cócóKhả năng kết xuất (helm, helm-chart, compose, terraform, cloudformation) mà Recipe của component đóng góp khai báo, cho các artifact được phát ra tại đường dẫn này.
{{ .boundary_name }}cócóTên được đặt cho boundary trong Release (ví dụ: production, eu-prod).
{{ .parameters.X }}cócóBất kỳ tham số có kiểu nào được khai báo trên Aggregate và được Release cung cấp giá trị. Truy cập nghiêm ngặt — tham chiếu .parameters.unknown sẽ dừng bản dựng.
{{ .manifest.recipe_name }}cócóTên Recipe được phân giải qua Manifest cho component đóng góp. Hữu ích để định tuyến các artifact theo từng Recipe vào các thư mục con theo từng Recipe.
{{ .parent_boundary.* }}cócóTruy cập theo tầng tới các giá trị đã được đánh giá của boundary bao ngoài. Xem Tầng kế thừa từ boundary cha bên dưới.
{{ .component_id }}—cóID instance của thành phần đóng góp. Với một Feature được gắn tại một ranh giới mà FeatureRecipe của nó chạy một lần cho ranh giới đó (executionScope: boundary), đây là danh tính tổng hợp mà các tài nguyên của attachment đó mang trong nhãn aggrega.ai/component-id — bfr--app--shared cho một attachment shared tại ranh giới app, được rút gọn ở nơi nhà cung cấp của attachment giới hạn tên — để đầu ra của attachment nằm trong một thư mục được đặt tên theo nhãn đó. Chỉ khả dụng trong subDirectory: vì directory: là một thuộc tính theo từng ranh giới — chuỗi thư mục được tính một lần cho mỗi ranh giới, trước khi bất kỳ việc định tuyến theo từng thành phần nào diễn ra.

Trường directory: mặc định là boundaries/ theo sau là đường dẫn boundary (một định danh ổn định tại thời điểm dựng, được suy ra từ cây boundary); một Release liệt kê các component mà không khai báo boundary sẽ ghi chúng mà không có đoạn thư mục nào. Trường subDirectory: mặc định là {{ .capability }} để artifact của mỗi khả năng nằm trong thư mục con riêng dưới thư mục của boundary — dù trường này bị bỏ qua hay được viết là subDirectory: "", vốn được đọc giống hệt như khi bỏ qua. Đặt subDirectory: ".", hoặc viết một template được đánh giá thành chuỗi rỗng, sẽ làm phẳng cách nhóm đó.

Điều các template này không quyết định: vị trí của artifacts:

Có một đoạn của đường dẫn đầu ra không do path template đặt. Một tệp được khối artifacts: của một Recipe nêu tên sẽ được ghi dưới một thư mục mang tên component đã khai báo nó, bên trong bất kỳ giá trị nào mà subDirectory: được đánh giá thành. Đoạn đó cố định và luôn hiện diện, đối với một target ghi các tệp của những thành phần đóng góp cạnh nhau thay vì lồng mỗi thành phần đóng góp vào một chart hay một module riêng.

Lý do nằm ở thứ đặt tên cho tệp. Một manifest mà target kết xuất hoặc tổng hợp được target đặt tên theo component mà nó thuộc về, nên nó đã xác định component của mình. Một artifact được đặt tên theo khóa mà tác giả của nó viết — app-config.yaml, netpol.yaml — và khóa đó không nói gì về component, vì Recipe khai báo nó không biết những component nào sẽ được gắn với nó. Hai component trong cùng một boundary được gắn với cùng một Recipe sẽ ghi vào cùng một đường dẫn, và cả tác giả Recipe lẫn tác giả Release đều không có chỗ nào để tách chúng ra.

Chỉ thư mục được thêm vào; tên tệp vẫn là khóa đã viết, nên tệp mà tác giả đọc lại trong đầu ra mang đúng cái tên họ đã viết.

subDirectory: vẫn mang lại gì, và hai cơ chế kết hợp ra sao. subDirectory: di chuyển mọi tệp mà một thành phần đóng góp phát ra — manifest được kết xuất, manifest được tổng hợp và artifact cùng lúc — nên đây là công cụ để cho một component một thư mục riêng phục vụ công cụ hạ nguồn hoạt động trên toàn bộ tập manifest của một component, hoặc để định tuyến nhiều component vào một thư mục dùng chung. Đoạn artifacts: được áp dụng bên dưới bất kỳ giá trị nào mà nó được đánh giá thành. Do đó, viết subDirectory: "{{ .capability }}/{{ .component_id }}" trên một component có Recipe khai báo artifacts: sẽ tạo ra tên component hai lần — artifact nằm tại <capability>/<component>/<component>/<key> trong khi manifest được kết xuất của component đó nằm tại <capability>/<component>/<key>. Hãy dùng phần ghi đè khi bạn muốn gom toàn bộ đầu ra của component, và bỏ nó đi khi bạn chỉ cần tách các artifact, điều mà mặc định đã làm.

.capability được phân giải theo từng component, và directory: của một boundary được đánh giá cho hai mục đích khác nhau. Lần đánh giá theo từng boundary, vốn công bố .parent_boundary.directory cho các boundary con, chạy trước khi bất kỳ component nào được gắn, nên .capability ở đó là rỗng. Lần đánh giá theo từng component, vốn xác định nơi artifact của một thành phần đóng góp thực sự được đặt, mang khả năng của component đó. Do đó, một boundary cha viết directory: "d-{{ .capability }}" sẽ công bố d- xuống tầng kế thừa trong khi artifact của chính nó nằm dưới d-compose.

Phân tầng từ boundary cha

Các boundary lồng nhau nhận một khung nhìn .parent_boundary cung cấp đường dẫn đã được đánh giá của boundary cha trực tiếp cùng dữ liệu đã được phân giải theo phân tầng của chính nó. Phân tầng chỉ có một cấp — .parent_boundary của một boundary là cha trực tiếp của nó, không phải ông. Để truy cập lên cao hơn, chính boundary cha dùng .parent_boundary trong các template của nó, truyền các giá trị xuống cây một cách tường minh.

Các trường có sẵn trong .parent_boundary:

TrườngMô tả
.parent_boundary.directoryGiá trị directory: đã được đánh giá của boundary cha (sau khi áp dụng template).
.parent_boundary.boundary_nameTên do tác giả đặt của boundary cha.
.parent_boundary.parametersCùng map .parameters.* mà boundary cha thấy (giá trị tham số mang tính toàn cục trong Release, nhưng bí danh này được cung cấp để đối xứng).
.parent_boundary.annotationsCác annotation đã được phân giải theo phân tầng của boundary cha.

Mẫu chuẩn: một boundary cha khai báo directory: một lần, cùng các boundary con định tuyến artifact của chúng vào dưới boundary cha bằng cách khai báo directory: "{{ .parent_boundary.directory }}". Điều này gộp các boundary con vào đường dẫn lắp ráp của boundary cha, tạo ra một đầu ra hợp nhất chứa các contributor từ mọi boundary con. Feature core/compose-bridge dựa đúng vào điều này: một boundary cha chứa feature bridge, hai boundary con (ví dụ services-net và data-net) dùng chung directory: của boundary cha, và một tệp docker-compose.yaml hợp nhất chứa mọi component cùng với service bridge.

Trường hợp ngược lại: bỏ .parent_boundary.directory ở các boundary con (hoặc đánh giá ra một đường dẫn riêng) thì mỗi boundary con có phần lắp ráp riêng. Cả hai dạng đều được hỗ trợ đầy đủ như nhau.

Các bố cục minh họa

Bố cục 1 — phân tách mặc định theo từng boundary

spec:
boundaries:
api-prod:
directory: "deploy/api-prod"
components:
api: {}
cache: {}
data-prod:
directory: "deploy/data-prod"
components:
db: {}

Mỗi boundary được đánh giá thành một directory: riêng biệt, nên mỗi boundary có assembly riêng:

deploy/api-prod/<capability>/...
deploy/data-prod/<capability>/...

Giá trị mặc định subDirectory: "{{ .capability }}" phân tách các artifact theo từng capability bên trong thư mục của mỗi boundary. Hai boundary, hai đầu ra assembly cho mỗi capability, không có việc hợp nhất.

Bố cục 2 — assembly gộp lại qua thư mục cha dùng chung

spec:
boundaries:
cluster:
directory: "deploy/cluster"
annotations:
aggrega.ai/chart-name: "cluster-umbrella"
features:
bridge:
type: core/compose-bridge:1.0.0
boundaries:
services-net:
directory: "{{ .parent_boundary.directory }}"
annotations: { aggrega.ai/namespace: services }
components:
api: {}
data-net:
directory: "{{ .parent_boundary.directory }}"
annotations: { aggrega.ai/namespace: data }
components:
db: {}

Cả hai boundary con đều đánh giá directory: thành deploy/cluster (thư mục của boundary cha), nên mọi contributor được hợp nhất tại một đường dẫn assembly duy nhất. Với giá trị mặc định subDirectory: "{{ .capability }}", các contributor compose từ cả hai boundary con đều nằm trong deploy/cluster/compose/ và tạo ra một tệp docker-compose.yaml hợp nhất. Feature compose-bridge gắn tại boundary cha chạy một lần (dispatch ở phạm vi boundary) và đóng góp service bridge vào cùng tệp hợp nhất đó.

Annotation aggrega.ai/chart-name: "cluster-umbrella" của boundary cha được truyền xuống cả hai boundary con; nếu các boundary này cũng chứa contributor helm-chart, các sub-chart helm-chart của cả hai boundary con sẽ được kết hợp dưới một umbrella duy nhất tên là cluster-umbrella. Các giá trị chart-name không khớp nhau giữa các contributor tại cùng một đường dẫn sẽ làm dừng quá trình build.

Bố cục 3 — định tuyến theo từng component qua subDirectory: cùng với parameter

spec:
parameters:
region: "eu-west-1"
boundaries:
eu-prod:
directory: "deploy/{{ .parameters.region }}"
components:
api:
subDirectory: "{{ .capability }}/{{ .component_id }}"
db:
subDirectory: "{{ .capability }}/{{ .component_id }}"
ingress:
subDirectory: "shared"

directory: của boundary được đánh giá thành deploy/eu-west-1 (thay thế parameter). Các ghi đè subDirectory: theo từng component định tuyến mỗi contributor vào một thư mục con riêng cho từng component, trong đó component ingress ghi đè thành một thư mục con phẳng shared dành cho các artifact dùng chung:

deploy/eu-west-1/<capability>/api/...
deploy/eu-west-1/<capability>/db/...
deploy/eu-west-1/shared/...

Mẫu này phù hợp với các doanh nghiệp muốn có thư mục artifact riêng cho từng component, phục vụ các công cụ hạ nguồn hoạt động trên manifest của một component duy nhất. Khi Recipe của một component cũng khai báo artifacts:, hãy đọc Những gì các template này không quyết định ở trên trước khi chọn cấu trúc này: các tệp đó đã mang sẵn một phân đoạn component, nên ghi đè này sẽ thêm một phân đoạn thứ hai.

Chẩn đoán

Bề mặt path-template dừng bản dựng trong từng tình huống sau, và errors/fatal-halts.md ghi lại chúng dưới các tên này. Trang đó trích dẫn thông báo mà mỗi lần dừng phát ra; hãy đối chiếu đầu ra bản dựng với văn bản đó.

  • Path-template references a variable outside the allowlist (Path-template tham chiếu một biến nằm ngoài danh sách cho phép) — lúc phân tích cú pháp: một path template tham chiếu một biến không có trong danh sách cho phép.
  • Path collision (Xung đột đường dẫn) — lúc lắp ráp: hai contributor của boundary được đánh giá ra cùng một đường dẫn nhưng không thống nhất về một thuộc tính phải đồng nhất giữa các contributor tại đường dẫn đó.
  • Instance-ID collision (Xung đột ID instance) — lúc lắp ráp: hai boundary được đánh giá ra cùng một bộ (path, provider) đóng góp các component có ID instance giống hệt nhau.
  • Chart-name mismatch (Không khớp chart-name) — lúc lắp ráp: một assembly helm-chart đã hợp nhất nhận các contributor có annotation aggrega.ai/chart-name được phân giải qua cascade xung đột nhau.
  • Missing template key (Thiếu khóa template) — một path template tham chiếu một trường dưới một biến mở mà không phân giải ra giá trị nào (ví dụ: {{ .parameters.region }} khi Release bỏ qua region, hoặc một khóa .parent_boundary tại một boundary cấp cao nhất không có cha); missingkey=error tạo ra một thông báo rõ ràng nêu tên boundary, trường template (directory: hay subDirectory:), và khóa bị thiếu. .parameters và .parent_boundary là mở — các khóa của chúng là dữ liệu do người viết tạo ra — trong khi .manifest khai báo các khóa của nó, nên một khóa gõ sai dưới .manifest thay vào đó bị từ chối ngay lúc phân tích cú pháp như một tham chiếu không xác định, với chẩn đoán liệt kê các khóa mà .manifest định nghĩa.

Tham chiếu chéo

  • entities/release.md — soạn thảo Release, bao gồm phân tách theo không gian và các trường directory: / subDirectory:.
  • providers/architecture.md — điều phối provider và mô hình lắp ráp theo từng (path, provider).
  • providers/compose.md — đầu ra phía compose theo từng (path, provider), bao gồm kịch bản đường dẫn được hợp nhất.
  • providers/helm-chart.md — cách tổ hợp umbrella của helm-chart và quy tắc lan truyền chart-name cho các đường dẫn được hợp nhất.
  • entities/featurerecipe.md — các FeatureRecipes ở phạm vi ranh giới (Feature core/compose-bridge dựa vào mô hình lắp ráp đường dẫn hợp nhất được mô tả ở đây).
  • errors/fatal-halts.md — danh mục chẩn đoán đầy đủ, bao gồm các lỗi dừng điều phối đường dẫn được liệt kê ở trên.