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.

Release

Vai trò khái niệm của thực thể Release (Miền 4 — bộ định tuyến triển khai gắn một Aggregate với một Manifest và ánh xạ các component vào các ranh giới vật lý) được trình bày trong architecture/04-entity-taxonomy.md. Cơ chế sắp xếp thứ tự theo thời gian (syncWave theo từng ranh giới), Dynamic Addressing Polyfill và mẫu Parameter Hoisting được trình bày trong architecture/12-day-two-lifecycles.md. Trang này đề cập đến bề mặt soạn thảo của Release.

Vai trò của Release

Release liên kết một aggregate với một manifest và ánh xạ các component vào các ranh giới triển khai vật lý (ví dụ: aws-eks-production). Đây là điểm vào duy nhất cho quá trình biên dịch: aggrega build --release release.yaml.

Release hiện thực hóa hợp đồng aggregate trừu tượng bằng cách chỉ đưa các yếu tố thực tế vật lý vào khối parameters, và đưa thông số kích thước vật lý (như CPU hoặc cổng) qua namespace song song infra.

Mỗi Release khai báo một trường manifest: chỉ định Manifest của nó (trừ khi Release dùng extends:, khi đó nó kế thừa con trỏ manifest của cha). CLI aggrega build đọc trực tiếp trường này; không tồn tại cờ CLI --manifest, nên đặc tả phụ thuộc luôn được commit vào Git cùng với chính Release, giúp lịch sử triển khai có thể kiểm toán thông qua lịch sử Git của chính Release.

Các trường aggregate: và manifest: được phân giải theo định danh hoặc theo tệp đường dẫn tương đối, giống như cách phần còn lại của ngôn ngữ phân giải các tham chiếu — không bao giờ như một phần gốc tên tệp tương đối với release. Một giá trị ./ hoặc ../ là một tệp cục bộ tường minh, được đọc trực tiếp tương đối với Release. Một token trần là một định danh — metadata.name của thực thể được tham chiếu. Một định danh manifest: được phân giải bằng cách quét thư mục của chính Release (Manifest là cấu hình vận hành phía triển khai, nên không có tầng catalog hay registry). Một định danh aggregate: được phân giải qua toàn bộ chuỗi tầng — thư mục của Release, rồi catalog, rồi registry — nên một Release có thể gọi tên một Aggregate đã xuất bản theo định danh, và cùng một module đã xuất bản được phân giải như nhau dù nó là spec.aggregate cấp cao nhất của một Release hay một sub-aggregate bên trong một Aggregate khác. Mô hình định danh-hoặc-đường dẫn này cho phép một Aggregate dùng chung làm nền cho nhiều biến thể Release mà không gắn tham chiếu với tên tệp, và cho phép triển khai trực tiếp một Aggregate đã xuất bản theo tên.

Đường dẫn luôn nằm trong workspace. Một giá trị ./ hoặc ../ chỉ đến một tệp mà workspace chứa, và mọi đường dẫn khác mà một Release viết cũng vậy — extends: của nó và một $import: trong parameters, xem bên dưới. Đường dẫn nào vượt ra ngoài workspace theo cách nó được viết, hoặc bị một liên kết tượng trưng trên đường đi dẫn ra ngoài, đều bị từ chối trước khi đọc bất cứ thứ gì từ tệp mà nó chỉ đến. Để triển khai một Aggregate nằm ngoài workspace, hãy gọi nó theo định danh và liệt kê thư mục chứa nó làm thư mục catalog trong cấu hình workspace; Manifest, Release mà một extends: chỉ đến và tệp parameters được đọc cạnh Release và không bao giờ được tra cứu theo tên, nên chúng phải nằm trong workspace. Một Release nằm ngoài workspace mà bạn chỉ định trên dòng lệnh, hoặc do cấu hình workspace chỉ định, là một gốc riêng: mọi đường dẫn nó viết — và mọi đường dẫn mà một Release trong chuỗi extends: của nó viết — phải dẫn đến một tệp bên trong thư mục chứa Release đó, và đường dẫn nào vượt ra ngoài thư mục đó, hoặc bị một liên kết dẫn ra ngoài, sẽ bị từ chối theo cùng cách. Hãy đặt những gì Release như vậy chỉ đến ngay cạnh nó, hoặc build nó trong workspace chứa cả hai. Xem errors/fatal-halts.md §“A reference to another file leads out of the directory it must stay inside (Một tham chiếu đến tệp khác dẫn ra ngoài thư mục mà nó phải nằm bên trong)”.

Release quyết định đích đến của các artifact đã biên dịch; việc điều phối provider thuộc về Manifest mà Release trỏ tới (xem Manifest và Release: phân tách mối quan tâm để biết cách phân chia vai trò).

Siêu dữ liệu môi trường

Mọi khối metadata của Release đều chấp nhận trường environment: — một chuỗi dạng tự do xác định môi trường mà Release được triển khai tới (các giá trị thường gặp: production, staging, dev). Trường này chỉ mang tính thông tin: nó không có kiểu liệt kê, không có mẫu ở cấp schema và không có kiểm tra liên thực thể nào ngoài type: string. Trình biên dịch phát giá trị của nó dưới dạng nhãn aggrega.ai/environment trên mọi Kubernetes manifest mà provider helm kết xuất, cùng với phần còn lại của bộ nhãn nguồn gốc Aggrega — giữ nguyên như đã viết khi đó là một giá trị nhãn Kubernetes hợp lệ, và nếu không thì được viết lại thành một giá trị hợp lệ, với giá trị chính xác được mang trong annotation aggrega.ai/environment (vì vậy eu/prod được gắn nhãn eu-prod); provider helm-chart thêm cùng các nhãn đó vào mỗi artifact được tải bằng $import: mà nó đặt vào một sub-chart, còn các template riêng của sub-chart thì mang những gì tác giả của chúng đã viết. Provider compose mang cùng giá trị đó dưới dạng nhãn aggrega.ai/environment trên mỗi service mà nó phát ra.

Năm mẫu thực tế định hướng việc viết environment::

  1. Phân bổ chi phí OTel/FinOps. Các bảng điều khiển chi phí đám mây (AWS Cost Explorer, Datadog Cloud Cost Management, CloudHealth) lọc các pod Kubernetes theo thẻ môi trường. Nhãn aggrega.ai/environment: production được đưa vào nhãn pod thông qua cơ chế chèn nhãn của Provider Helm; các báo cáo chi phí nhóm chi tiêu theo aggrega.ai/environment mà không cần gắn thẻ thủ công cho từng tài nguyên.

  2. Lọc trace và log OTel. Các bảng điều khiển quan sát (Datadog, New Relic, Honeycomb, Grafana Tempo) lọc dữ liệu đo từ xa theo nhãn môi trường. aggrega.ai/environment: staging cho phép người vận hành giới hạn truy vấn log và tra cứu trace trong môi trường staging mà không cần lọc theo quy ước namespace hay tên chart — một nhãn chuẩn duy nhất trên toàn bộ bề mặt được kết xuất.

  3. Nhắm mục tiêu cho Kubernetes operator. Các bộ điều khiển GitOps (ArgoCD, Flux) và các policy operator (Kyverno, OPA Gatekeeper) đôi khi lọc tài nguyên theo nhãn môi trường cho các chính sách riêng theo môi trường (ví dụ: “tài nguyên chỉ dành cho production phải có nhãn approved-image-source”). Nhãn aggrega.ai/environment cung cấp một bộ chọn ổn định, tách biệt với các quy ước namespace hay mẫu đặt tên.

  4. Phân biệt production đa vùng. Một nhóm chạy một Release production-us-east cùng với một Release production-eu-west — cả hai đều có metadata.environment: production — sẽ nhận cùng nhãn aggrega.ai/environment: production trên các vùng. Kết hợp với một nhãn vùng riêng, điều này cho phép tổng hợp chi phí liên vùng (“tổng chi tiêu production”) và xem chi tiết theo từng vùng.

  5. Giới hạn phạm vi tuân thủ. Việc thu thập bằng chứng SOC 2, PCI và HIPAA giới hạn phạm vi theo môi trường (kiểm toán chỉ production, v.v.). Nhãn aggrega.ai/environment được các công cụ thu thập bằng chứng tuân thủ (Vanta, Drata) sử dụng để lọc tài nguyên theo phạm vi kiểm toán.

Schema yêu cầu environment: trên mọi Release; giá trị này chỉ mang tính thông tin, và trình biên dịch chỉ đọc nó để ghi nhãn aggrega.ai/environment.

Các ràng buộc ở cấp schema

Hai bảo đảm về cấu trúc bảo vệ Aggregate với vai trò Nguồn sự thật duy nhất (Single Source of Truth):

  • values: bị cấm. Để bảo vệ Aggregate với vai trò Nguồn sự thật duy nhất, schema của Release cấm một khối values: một cách cơ học — Operator không thể khai báo values trên bất kỳ Component hay Feature nào từ một Release. Lệnh cấm mở rộng sang các cạnh uses: một mục uses theo từng cạnh của Release mang infra và các phần đính kèm mà nó ghi trên kết nối, và những phần đó cũng mang infra — không bao giờ mang values (các giá trị theo từng cạnh hướng tới developer, cùng các giá trị của một phần đính kèm trên kết nối, vẫn nằm trong Aggregate). Sự thay đổi theo từng môi trường của các giá trị hướng tới Developer đi qua Parameter Hoisting: Developer công bố một trường parameters.* có kiểu trong Aggregate, template values của Component tham chiếu tới nó, và Release đáp ứng tham số đó cho môi trường của mình. Xem architecture/06-data-taxonomy-and-composition.md §8 Constraint 4 để biết lệnh cấm ở cấp schema được nêu rõ ràng. Bề mặt cạnh uses của Release — những gì nó có thể cấu hình và nối — được mô tả trong Cấu hình kết nối theo từng cạnh bên dưới.
  • extends + aggregate: bị từ chối. Để ngăn các Releases “thay đổi aggregate” không thể truy vết, khi một Release dùng extends, việc khai báo một con trỏ aggregate sẽ bị schema của Release từ chối. Release con phải ánh xạ tới chính xác cùng một Developer Intent như Release cha. Tuy nhiên, manifest trở thành tùy chọn, mở ra “Late Binding” — cho phép Operator kế thừa toàn bộ topology vật lý nhưng thay thế chính xác Manifest.

Khối parameters:

Một Release đáp ứng hợp đồng tham số có kiểu mà Aggregate khai báo. spec.parameters: là bề mặt soạn thảo — một map YAML có các khóa khớp với các khai báo parameters.* của Aggregate và có các giá trị cung cấp phần đáp ứng cho từng môi trường.

# Aggregate declares the typed contract
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: my-app
version: 1.0.0
spec:
parameters:
db_size: { type: string, required: true }
timeout_seconds: { type: integer, default: 30 }
region: { type: string, enum: [us-east-1, eu-west-1], required: true }
# Release fulfills the contract for this environment
apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: prod-release
version: 1.0.0
environment: production
spec:
aggregate: my-app
manifest: prod-manifest
parameters:
db_size: "100Gi"
timeout_seconds: 60
region: "us-east-1"

Mỗi giá trị phải vượt qua bước kiểm tra schema do Aggregate khai báo ở tầng hợp đồng tham số, và bản build dừng lại khi một Release bỏ qua một tham số bắt buộc (E0165, parameter-missing) hoặc cung cấp một giá trị mà hợp đồng của vị trí đó từ chối (E0164, parameter-contract-violation). Các tham số được khai báo với default: sẽ nhận giá trị mặc định khi Release bỏ qua vị trí đó; hợp đồng có kiểu là từ vựng soạn thảo duy nhất.

Hai chế độ soạn thảo — phân nhánh theo hình dạng nội dung. parameters: chấp nhận hoặc một map YAML nội tuyến (Chế độ 1, như ở trên) hoặc một khóa $import: duy nhất trỏ tới một tệp cục bộ (Chế độ 2):

spec:
aggregate: my-app
manifest: prod-manifest
parameters:
$import: ./prod-parameters.yaml

Một đường dẫn $import: tương đối được phân giải từ thư mục chứa Release viết nó, bất kể lệnh được chạy từ đâu, nhờ vậy dòng lệnh và trình soạn thảo đọc cùng một tệp; một đường dẫn tuyệt đối tự chỉ ra vị trí của nó, và cả hai đều phải dẫn tới một tệp nằm bên trong workspace — hoặc, với một Release được chỉ định từ bên ngoài workspace, nằm bên trong thư mục chứa Release đó. Hai chế độ loại trừ lẫn nhau tại vị trí này, và chỉ có thể nhập một tệp duy nhất. Việc phân lớp tham số từ nhiều tệp là phạm vi của các chuỗi extends: của Release: Release cha cung cấp một tập tham số cơ sở và Release con kế thừa rồi ghi đè theo từng môi trường. Xem Composite Release / extends: inheritance ở phần dưới để biết mẫu này.

Ranh giới giữa tham số và infra. Tham số mang ý định nhận thức của Developer, được biểu đạt dưới dạng các vị trí có kiểu mà Aggregate khai báo; Release đáp ứng chúng. infra: trên Release mang kích thước vật lý của Operator (số bản sao, giới hạn CPU/bộ nhớ, lớp lưu trữ) gắn với các component cụ thể hoặc các phần gắn kèm Feature. Tham số chảy vào các template values: của Aggregate qua .parameters.X; infra: chảy vào template valuesMapping: của Recipe qua .infra.X. Xem architecture/06-data-taxonomy-and-composition.md §3 về phân loại các trụ cột dữ liệu và templates/parameters-context.md về vòng đời của tham số qua pipeline.

Các boundary và phạm vi mặc định

Một Release nhóm các component thành các boundary — các đơn vị triển khai vật lý, mỗi đơn vị có thư mục đầu ra và chuỗi annotation lan truyền riêng. Trường hợp một boundary là trường hợp phổ biến, nên nó không cần thủ tục gì.

Phạm vi đơn (mặc định). Khai báo các component trực tiếp dưới spec.components: và bỏ qua khối boundaries:. Trình biên dịch gộp chúng vào một boundary default được tổng hợp, có đầu ra phẳng — các artifact nằm trực tiếp dưới dist/ (theo từng provider, qua giá trị mặc định an toàn của subDirectory bên dưới: dist/compose/, dist/helm/, …), không có đoạn tên boundary trong đường dẫn. Đây là cách triển khai đơn giản nhất: aggrega build trên một đích Compose phẳng hoặc một cluster duy nhất mà không cần đặt tên boundary.

spec:
aggregate: aggregate
manifest: manifest
components:
db:
infra:
engine_version: "11.4"
web:
infra:
port: 8080

Nhiều phạm vi. Khi một Release trải rộng trên nhiều nhóm vật lý — các cluster, vùng hoặc sync wave riêng biệt — hãy khai báo các boundary có tên dưới boundaries:. Mỗi boundary mang directory:, chuỗi annotation lan truyền và syncWave: riêng, và các component được tham chiếu trong boundary của chúng.

Loại trừ lẫn nhau. spec.components: và spec.boundaries: loại trừ lẫn nhau tại gốc của Release — một Release khai báo một trong hai, không bao giờ cả hai. Một tài liệu khai báo cả hai sẽ dừng ngay khi tải với một lỗi envelope. Bề mặt components cấp cao nhất mang cùng hình dạng vận hành theo từng component như components của một boundary (infra:, annotations:, uses:).

Một boundary được khai báo có tên default. Đầu ra phẳng là thuộc tính của boundary mặc định được tổng hợp, không phải của cái tên. Một Release khai báo tường minh một boundary tên default dưới boundaries: là một boundary có tên thông thường: đầu ra của nó theo directory: (mặc định là dist/boundaries/default/), giống hệt mọi boundary được khai báo khác.

Xem architecture/06-data-taxonomy-and-composition.md §7 về mẫu phạm vi mặc định.

Phân tách không gian và đường dẫn đầu ra

Mỗi boundary khai báo một directory đầu ra vật lý cho các artifact đã biên dịch của nó; các component trong một boundary có thể ghi đè thông qua subDirectory theo từng component. Trình biên dịch tính đường dẫn artifact cuối cùng bằng cách nối chúng lại, ở dạng phân tách bằng dấu gạch chéo trên mọi nền tảng: Final_Path = Clean(Join(Evaluated(directory), Evaluated(subDirectory))).

  • Một thư mục, một cách viết. Đường dẫn đã đánh giá được chuẩn hóa một lần, nên out/a, out//a, ./out/a và out/a/ là cùng một thư mục. Các boundary có đường dẫn chuẩn hóa về cùng một thư mục và được kết xuất qua cùng một provider sẽ được lắp ráp cùng nhau, đúng như các boundary được viết với đường dẫn giống hệt nhau.
  • Đường dẫn luôn nằm bên dưới thư mục gốc đầu ra. Một đường dẫn leo ra khỏi thư mục gốc đầu ra (.., ../escape, a/../..), một đường dẫn tuyệt đối, hoặc một đường dẫn không chỉ tới thư mục nào cả — rỗng, hoặc chuẩn hóa về chính thư mục gốc đầu ra — sẽ dừng quá trình build trước khi bất cứ thứ gì được ghi ra. Thông báo nêu tên Release, boundary, trường bị lỗi (directory: hoặc subDirectory:) và giá trị mà nó được đánh giá thành, vì giá trị đó thường là kết quả của một template.
  • Mặc định an toàn. Nếu subDirectory bị bỏ qua hoặc rỗng, trình biên dịch tự động áp dụng subDirectory: "{{ .capability }}" — các artifact của mỗi capability kết xuất (Helm, Helm-chart, Compose, Terraform, CloudFormation) nằm trong thư mục con riêng của nó, tránh xung đột artifact lẫn lộn trong các công cụ CI/CD phía sau. Một subDirectory: "" được viết ra được hiểu đúng như khi bị bỏ qua, nên nó cũng nhận mặc định này.
  • Ghi đè dạng phẳng. Để tắt hoàn toàn thư mục con (mọi artifact nằm trực tiếp dưới directory), hãy đặt subDirectory: ".". Một template subDirectory được đánh giá thành chuỗi rỗng — chẳng hạn "{{ .parameters.sub }}" với sub được đặt là "" — cũng tắt nó.
  • Biến template. directory được đánh giá với {{ .capability }}, {{ .boundary_name }}, {{ .parameters.X }}, {{ .manifest.recipe_name }}, và {{ .parent_boundary.* }} cho dữ liệu lan truyền từ một boundary bao ngoài. subDirectory được đánh giá với cùng tập đó cộng thêm {{ .component_id }} (chỉ với ghi đè theo từng component). Trình biên dịch đánh giá template đường dẫn với missingkey=error — tham chiếu tới một biến chưa khai báo sẽ dừng build kèm một chẩn đoán chính xác. Xem biến template đường dẫn để biết ma trận theo từng ngữ cảnh và các quy tắc lan truyền từ boundary cha.

Annotation của boundary lan truyền xuống mọi component chứa trong nó; infra được giữ cục bộ nghiêm ngặt cho component mà nó nhắm tới. Map boundaries đệ quy cho phép lồng nhau tùy ý (boundary trong boundary trong boundary) trong khi các bất biến về lan truyền annotation và infra cục bộ được giữ ở mọi cấp.

Ví dụ minh họa:

apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: spatial-release
version: 1.0.0
environment: production
spec:
aggregate: spatial-app
manifest: prod-manifest
boundaries:
eu-prod:
directory: "deploy/eu-prod"
# Scenario A: Safe Default. Compiler automatically applies `subDirectory: "{{ .capability }}"`.
annotations:
"aggrega.ai/namespace": "finance-frontend" # Merges downwards as annotations
components:
api-server:
infra: { replicas: 5 } # Strictly local
aws-rds:
# Scenario B: Bespoke Enterprise Naming.
subDirectory: provisioning
postgres-db:
# Scenario C: The Flat Directory Override.
subDirectory: "." # not "", which takes the default

Các annotation được lan truyền bằng cơ chế này xuất hiện trong các template Recipe phía sau qua .context.annotations.release; xem Viết Recipe và Ma trận mở rộng template để biết cách các renderer sử dụng chúng.

Giá trị annotation có cấu trúc. Khi một binding của Manifest khai báo nhiều đường định tuyến infra-pillar cho một khóa annotation, giá trị annotation phía Release có thể là một đối tượng có cấu trúc mang giá trị cho nhiều trường schema của Feature trong một khai báo:

boundaries:
prod:
annotations:
feature.myco/db-pool:
pool_size: 20
max_connections: 100
components:
api:
annotations:
feature.myco/db-pool:
max_connections: 200 # closer-level override
# pool_size not listed → inherits 20 from boundary

Giá trị có cấu trúc lan truyền với hợp nhất sâu theo từng khóa con; khóa con ở cấp gần hơn ghi đè khóa con của cấp cha. null theo từng khóa con loại bỏ một khóa con trong khi các khóa con anh em vẫn giữ nguyên. Phía Release chỉ kích hoạt các khóa con có pillar trong binding-map là infra; các khóa con định tuyến tới values thuộc về annotation phía Aggregate. Để xem toàn bộ nội dung về giá trị có cấu trúc — kết hợp giữa hai phía, kiểm tra kiểu theo từng khóa con, nguyên tắc mặc định nới lỏng — xem providers/well-known-annotations.md §“Structured annotation values”.

Annotation phổ biến. Ngoài các khóa tùy biến, thư viện chuẩn của Aggrega định nghĩa một tập annotation phổ biến trong các namespace aggrega.ai/ và feature.aggrega.ai/, được nhóm thành các loại bố trí, mạng, bảo mật và khả năng quan sát. Người viết thêm annotation vào một boundary của Release nên tham khảo providers/well-known-annotations.md để xem ma trận đầy đủ cùng các quy tắc sử dụng theo từng provider — trang này ghi lại những provider nào áp dụng từng khóa phổ biến và hành vi chúng tạo ra khi khóa có mặt.

Cấu hình kết nối theo từng cạnh

Một component trong boundary có thể mang một khối uses: để cấu hình hoặc nối các cạnh topology trong phạm vi các socket mà usesSchema trong catalog của Component khai báo. Đây là bề mặt cấu hình theo từng kết nối của operator, được giới hạn để nhà phát triển giữ quyền sở hữu kiến trúc mà họ đã viết:

  • Cấu hình một cạnh có sẵn. Đặt infra theo từng cạnh trên một cạnh mà nhà phát triển đã khai báo. Mục này nêu alias của nhà phát triển và cung cấp infra; nó hoặc nêu đúng đích mà nhà phát triển đã nối, hoặc bỏ qua đích. infra được kiểm tra theo infraSchema của socket.
  • Nối một socket chưa được gắn. Tạo một cạnh vào một socket mà usesSchema của Component khai báo nhưng nhà phát triển để trống, trỏ tới một component có sẵn. Cạnh được tạo cũng có thể mang infra theo từng cạnh.
  • Gắn trên một kết nối. Đặt các attachment dưới features: của mục, với khóa là một slot mà socket khai báo trong featuresSchema — cũng chính các slot mà mục kết nối của nhà phát triển điền vào. Mỗi attachment mang type, một description tùy chọn và infra, và không bao giờ mang values. Dưới một slot mà nhà phát triển đã điền trên cùng kết nối, mục này định cỡ attachment đó: chỉ viết infra, vì type và values đến từ Aggregate (một type viết ở đây phải khớp với type của Aggregate, nếu không build dừng tại mục này và nêu cả hai). Dưới một slot mà nhà phát triển để trống, attachment là của riêng Release và bắt buộc có type. Dù theo cách nào, phần điền đều phải tuân theo selector của slot và được tính vào một slot required, đúng như phần điền của nhà phát triển.

Bề mặt này là tạo-mới-không-đổi-đích: một Release có thể thêm một cạnh vào một socket chưa được gắn, nhưng không được chuyển hướng một cạnh mà nhà phát triển đã khai báo. Một mục theo từng cạnh nêu một đích khác với cạnh của nhà phát triển sẽ dừng build; một mục nêu cùng đích (hoặc bỏ qua đích) sẽ cấu hình cạnh đó. Release cũng không được khai báo values trên một cạnh hoặc trên một attachment mà nó viết ở đó (các giá trị hướng tới nhà phát triển nằm trong Aggregate), gắn một socket mà usesSchema không khai báo, hoặc trỏ một cạnh tới một component không tồn tại — mỗi trường hợp là một lỗi dừng nghiêm trọng. Một mục đặt infra hoặc features trên một kết nối không tồn tại sau khi mọi cạnh đã được vẽ cũng vậy, trừ khi component tiêu thụ bị tắt bằng active: false. Xem errors/fatal-halts.md §“When building the topology”.

Ba lỗi dừng nữa giữ các attachment của một kết nối nằm trên kết nối của chúng:

  • Một tên mà socket không khai báo slot nào sẽ dừng build, đúng như trên mục kết nối của Aggregate, tại mục này trong Release, nêu các slot mà socket khai báo và bất kỳ slot nào chỉ cách tên đó một lần chỉnh sửa.
  • Một attachment chỉ Release tạo ra, được viết mà không có type, sẽ dừng tại mục kết nối, nêu tên slot. Một attachment do Release tạo ra không mang values, nên nó phù hợp với một Feature mà values không yêu cầu gì; một Feature có schema yêu cầu một giá trị sẽ dừng vì thiếu giá trị tại cùng mục đó. Các Features thông tin xác thực của thư viện chuẩn mang locator của bên gọi không yêu cầu gì trong values: mỗi Feature cũng nhận nó trong infra (xem bên dưới).
  • Tên ghép được viết ở bất kỳ đâu ngoài kết nối sẽ dừng build. Một attachment của kết nối trở thành một attachment của component tiêu thụ có tên <alias>.<slot> (xem mục kết nối của Aggregate), và cả các khóa features: riêng của một mục component lẫn của một boundary đều chấp nhận dấu chấm. Một mục component viết tên đó, hoặc một boundary viết nó sao cho nó tới được một component có kết nối mang nó — một component đặt trong boundary đó hoặc trong một boundary lồng bên trong, kể cả các component của một sub-module được định tuyến — sẽ dừng và nêu cả hai cách viết, một lần cho mỗi component mà nó tới được. Slot của một socket được điền trên từng kết nối và không bao giờ bởi một attachment lan xuống từ một phạm vi rộng hơn.
spec:
components:
router:
uses:
models:
# Size the attachment the Aggregate declared on the "gpt" connection: infra only.
gpt:
features:
credential:
infra: { rotation: hourly }
# Attach on a connection the developer left without one: the type is required.
plain:
features:
credential:
type: core/generated-secret

Một credential trên kết nối do Release nối sẽ ghi tên secret của nó trong infra. Một kết nối do Release nối không có mục nào trong Aggregate, nên không có gì ở đó ghi values của credential, và Release không ghi values ở bất kỳ đâu. Vì vậy, mỗi Feature credential của thư viện chuẩn mang locator của bên gọi — core/referenced-secret, core/referenced-secret-set, core/secret-value và core/secret-provided — chấp nhận nó trong infra cũng như trong values: origin, hoặc entries đối với core/referenced-secret-set, với cùng hình dạng và cùng khai báo sensitive: true ở cả hai pillar. Mọi hiện thực đều đọc pillar nào đang mang nó.

spec:
components:
router:
uses:
models:
gpt:
target: gpt # wire the socket the developer left unbound
features:
credential:
type: core/referenced-secret
infra:
origin: openai-team-a # the secret the operator names

Locator được ghi trong đúng một pillar cho mỗi attachment. Một attachment mang nó ở cả hai — values của Aggregate và infra của Release cho cùng một slot — hoặc không ở pillar nào sẽ dừng tại assertion riêng của Feature (E0033), nêu tên Feature, attachment và component, đồng thời cho biết đó là trường hợp nào trong hai. Quy tắc này thuộc về các thực thể catalog của những Features đó, không thuộc về trình biên dịch; trình biên dịch đánh giá assertion của chúng như đánh giá assertion của bất kỳ Feature nào. Các trường khác ngoài locator giữ nguyên pillar của chúng: key vẫn là một lá values, nên một attachment chỉ do Release tạo sẽ đọc data key mặc định của Feature, value. Lệnh cấm values: không thay đổi — locator của operator là infra.

core/secret-provided là cái duy nhất không phù hợp với một kết nối: nó công bố giá trị của mình để khối inject: riêng của attachment chuyển giao, và attachment của một kết nối không mang khối inject: nào trong cả hai tài liệu, nên trên một kết nối không có khối inject: nào chuyển giao nó. Hãy dùng core/referenced-secret hoặc core/secret-value ở đó.

spec:
aggregate: spatial-app
manifest: prod-manifest
boundaries:
eu-prod:
components:
api-server:
uses:
databases:
# Configure the developer-declared edge "primary": add per-edge infra.
# The target matches what the Aggregate wired (or is omitted) — a configure, not a retarget.
primary:
infra: { storage_class: fast-ssd }
caches:
# Wire an edge into the declared-but-unbound "caches" socket to an existing component.
main:
target: redis-prod
infra: { storage_class: standard }

infra theo từng cạnh đã được phân giải sẽ đi vào ngữ cảnh render của component tiêu thụ tại .context.uses.<alias>.infra.<key>; nó không bao giờ xuất hiện trong ngữ cảnh của component đích, nên đầu ra render của một đích là bất biến đối với các bên tiêu thụ cấu hình cạnh trỏ vào nó. Một attachment trên kết nối cũng nằm trên component tiêu thụ, như một trong các attachment của nó: infra của nó được hợp nhất với values của Aggregate cho cùng slot, và FeatureRecipe của nó render dựa trên cả hai. Recipe của component tiêu thụ đọc nó dưới kết nối của nó, tại .context.uses.<alias>.features.<slot>, và Workload của nó chuyển giao nó bằng cách nêu tên kết nối bên cạnh slot — xem Chuyển giao một credential mà kết nối mang theo.

Trường aggregates: — định tuyến các sub-module lồng nhau vào các boundary

Khi Aggregate khai báo các sub-module lồng nhau qua spec.aggregates:, Release quyết định các component của mỗi sub-module nằm trong boundary nào bằng cách khai báo aggregates: bên cạnh components: bên trong boundary đích:

# Aggregate declares two sub-aggregates
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: platform
version: 1.0.0
spec:
aggregates:
finance:
type: finance-module:1.2.0
analytics:
type: analytics-module:2.0.0
components:
gateway:
type: core/ingress
---
# Release routes each sub-aggregate into a specific boundary
apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: prod-release
version: 1.0.0
environment: production
spec:
aggregate: platform
manifest: prod-manifest
boundaries:
eu-prod:
directory: "deploy/eu-prod"
aggregates:
finance: {}
components:
gateway: {}
us-prod:
directory: "deploy/us-prod"
aggregates:
analytics: {}

Đặt mỗi sub-aggregate được liệt kê dưới Aggregate.spec.aggregates: vào đúng một boundary.

Định tuyến là đặt các component. Mọi component của một sub-module được định tuyến đều nằm trong boundary định tuyến nó và nhận directory, subDirectory, syncWave cùng chuỗi annotation kế thừa của boundary đó — cùng ngữ cảnh mà một component được nêu tên trực tiếp dưới components: nhận được, kể cả dấu nguồn gốc aggrega.ai/boundary-path được đóng lên các artifact được xuất ra. Do đó, định tuyến một sub-module và chỉ định từng component của nó bằng đường dẫn có dấu chấm đầy đủ với phần thân rỗng sẽ tạo ra các artifact giống hệt nhau; định tuyến là cách viết ngắn hơn, và là cách duy nhất để viết điều đó mà không cần biết nội dung của sub-module.

Một component thuộc về đúng một boundary, và quá trình build dừng khi một tài liệu đặt một component hai lần — cùng một sub-module được định tuyến vào hai boundary, một sub-module được định tuyến vào một boundary trong khi một component của nó được nêu tên ở boundary khác, hoặc một component được nêu tên cả trực tiếp lẫn qua một mục định tuyến. Thông báo chẩn đoán nêu cả hai vị trí, vì giữ lại vị trí nào là quyết định của tác giả. Định tuyến một sub-module vào một boundary và nêu tên một component của nó dưới cùng boundary đó không phải là xung đột: việc định tuyến đặt component, còn mục được nêu tên cấu hình nó.

Một sub-aggregate mà Release không đặt ở đâu cả sẽ làm dừng build. Việc đặt được xét trên cả hai cách viết, nên build chỉ dừng khi không cách nào chạm tới sub-module: không boundary nào định tuyến nó dưới aggregates:, và không boundary nào nêu tên bất kỳ component nào của nó dưới components: bằng đường dẫn có dấu chấm đầy đủ. Riêng mỗi cách viết đều đủ để đặt nó, và một sub-module mà mọi component đều được nêu tên riêng thì không cần mục định tuyến. Cách sửa nằm trong khối aggregates: của Aggregate đã import sub-module — là Aggregate mà Release triển khai, với sub-module được import trực tiếp, và là tài liệu riêng của sub-module import nó, với sub-module lồng nhau. Thông báo chẩn đoán nêu mục đó bằng khóa mà tài liệu import dùng để viết nó, nên với một sub-module lồng nhau, nó hiển thị tên cục bộ thay vì đường dẫn có dấu chấm.

Có hai trường hợp cố ý không dừng. Một sub-module không đóng góp component nào thì không có gì để đặt. Một sub-module có toggle active: phân giải thành false chưa bao giờ được kết hợp, nên không có component nào của nó tồn tại để được đặt.

Việc đặt một phần không làm dừng quy tắc này: một sub-module được coi là đã đặt ngay khi bất kỳ component nào của nó tới được một boundary, nên nêu tên một trong số đó là đủ cho sub-module. Điều đó không có nghĩa là phần còn lại có thể bị bỏ qua. Mỗi component mà boundary không nêu tên khi đó không được gì đặt cả, và quy tắc về component bên dưới báo lỗi nó tại khóa của chính nó — nên một sub-module được đặt một phần sẽ làm dừng build một lần cho mỗi component nó bỏ sót, không phải tại sub-module. Hai cách viết đặt toàn bộ một sub-module trong một dòng là mục định tuyến và nêu tên mọi component; mọi cách ở giữa chỉ đặt những gì nó nêu tên, không hơn.

Một component mà Release không đặt ở đâu cả cũng làm dừng build, ở cấp sâu hơn một bậc. Quy tắc trên hỏi liệu một sub-module có tới được boundary hay không; quy tắc này hỏi điều tương tự cho mọi component mà bản kết hợp chứa. Một component tới được một boundary bằng cách được nêu tên dưới components: của boundary đó, hoặc bằng cách nằm trong một sub-module mà một boundary định tuyến vào. Một component không tới được bằng cách nào sẽ render bên ngoài mọi boundary mà Release khai báo, nhận directory, subDirectory, syncWave, chuỗi annotation kế thừa và infra: theo từng component từ hư không — nên build dừng lại và nêu tên component thay vì xuất ra các artifact mà cấu hình boundary chưa bao giờ chạm tới.

Hai quy tắc phân chia phạm vi bằng cách hỏi về sub-module của component, chứ không chỉ hỏi liệu nó có sub-module hay không. Một component của một sub-module mà Release không đặt ở đâu cả được để cho quy tắc về sub-module, quy tắc này báo lỗi tác giả đó một lần tại mục aggregates: thay vì một lần cho mỗi component mà module chứa. Một component của một sub-module mà Release đặt một phần thuộc về quy tắc này, vì quy tắc về sub-module coi module như vậy là đã đặt và không nói gì về nó — nên mỗi component mà boundary không nêu tên được báo ở đây, tại khóa của chính nó bên trong tài liệu khai báo nó. Vì vậy, đặt một sub-module một phần sẽ nêu tên đúng những gì bạn định nêu, và cho bạn biết về từng component bạn đã không nêu.

Và một mục boundary nêu tên một component mà Aggregate được triển khai không chứa sẽ làm dừng build. Hai quy tắc trên xét việc đặt từ phía component — có gì đặt nó không. Quy tắc này xét từ phía Release: tên có phân giải được không. Một mục phân giải thành không gì cả thì không đặt gì, nên subDirectory, các annotation, infra: theo từng component và uses: của nó cấu hình một component không tồn tại, và build dừng lại thay vì xuất ra một bản triển khai mà mục đó chưa bao giờ chạm tới. Cả hai cách viết đều được kiểm tra: một tên dưới components: của boundary được đọc là id mà component mang khi việc kết hợp hoàn tất, còn một tên dưới components: của mục định tuyến được đọc là tên cục bộ mà nó mang bên trong sub-module đó. Thông báo chẩn đoán báo id mà mục đã chỉ định, mà với cách viết định tuyến thì không phải là tên trong tệp — tệp viết nửa cục bộ và sub-module cung cấp tiền tố của nó.

Một tên bị từ chối vì phân giải thành không gì cả, không bao giờ vì hình dạng của nó: tên có dấu chấm là bình thường, vì một component nằm sâu một module mang tiền tố của module đó. Một component có toggle active: phân giải thành false vẫn có thể được nêu tên — tắt một component không đòi hỏi phải sửa Release cấu hình nó.

Một subsystem không đóng góp gì vào đường dẫn đủ điều kiện, nên một boundary định địa chỉ một component bằng tên trần của nó, bất kể Aggregate nhóm nó theo cách nào. Chỉ việc kết hợp sub-module mới thêm tiền tố cho một id. Một component của Aggregate được triển khai là store dù tác giả viết nó ở cấp cao nhất hay bên trong một subsystem tên data; một component nằm sâu một module là data.store, và data ở đó là tiền tố của module chứ không phải của subsystem nào. Vì vậy, một mục boundary viết data.store cho một component nằm trong một subsystem tên data không định địa chỉ được gì: bản thân mục đó dừng build theo quy tắc ở trên, và component mà nó nhắm tới cũng không đến được boundary nào. Sửa mục thành store sẽ giải quyết cả hai.

Do đó, việc đặt một sub-module đòi hỏi boundaries:. Dạng phạm vi đơn không có bề mặt định tuyến — aggregates: là một khóa của boundary, không phải của spec: — và map components: cấp cao nhất chỉ chấp nhận tên không được định danh đầy đủ, vì vậy một Release triển khai một Aggregate có import các sub-module sẽ khai báo boundaries:.

Định tuyến đệ quy. aggregates: có tính đệ quy — mỗi mục dưới aggregates: của một boundary có thể tự khai báo một map aggregates: lồng nhau cho việc kết hợp module lồng sâu.

Khối định tuyến theo từng aggregate. Một mục định tuyến chấp nhận đúng hai khóa và không gì khác: components:, để cấu hình từng component riêng lẻ của sub-module đó, và một aggregates: lồng nhau cho các module lồng sâu hơn. annotations: thuộc về boundary, còn infra: theo từng component thuộc về một mục dưới chính components: của mục định tuyến.

Bên trong một mục định tuyến, một component được đặt khóa bằng tên nó mang bên trong sub-module của nó — consumer, không phải data.consumer — vì đó là tên duy nhất nó có ở đó. Đường dẫn có dấu chấm đầy đủ là cách map components: của chính boundary chỉ định cùng component đó; hai cách viết không thể thay thế cho nhau, và một mục định tuyến từ chối khóa có dấu chấm.

boundaries:
eu-prod:
directory: "deploy/eu-prod"
annotations:
aggrega.ai/namespace: "finance-zone"
aggregates:
finance:
components:
ledger: # the component's name inside the finance module
infra:
replicas: 3
aggregates:
reporting: {} # a module nested inside finance

Các component và Features riêng của sub-aggregate không được khai báo lại ở Release — Release định tuyến chúng thay vì viết lại, và chỉ nêu tên một component khi cần cấu hình nó.

Sắp xếp thứ tự theo thời gian — syncWave theo từng boundary

Mỗi boundary trong Release có thể tùy chọn khai báo một trường số nguyên syncWave:, cho phép Operator kiểm soát rõ ràng thứ tự triển khai mà không cần chạm vào Aggregate của Developer. Số wave là một thuộc tính của chính boundary; mọi component nằm trong cây con của boundary đều kế thừa giá trị wave của boundary đó khi artifact được phát ra.

apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: prod-release
version: 1.0.0
environment: production
spec:
aggregate: my-app
manifest: prod-manifest
boundaries:
infra:
directory: "deploy/infra"
syncWave: 0
components:
core-vpc: {}
postgres-db: {}
migrations:
directory: "deploy/migrations"
syncWave: 1
components:
db-migration-task: {}
apps:
directory: "deploy/apps"
syncWave: 2
components:
web-server: {}
ai-agent: {}

Ngữ nghĩa của giá trị wave. syncWave: là một số nguyên có dấu (dương, bằng không hoặc âm). Giá trị mặc định khi bỏ qua trường này là 0. Giá trị wave không được kế thừa từ boundary cha — mỗi boundary muốn có wave khác mặc định phải khai báo tường minh. Components không thể ghi đè wave của boundary chứa chúng (wave là thuộc tính của đơn vị không gian, không phải của từng component riêng lẻ).

Phát ra theo từng provider. Trình biên dịch phát giá trị wave của boundary vào đầu ra đã render dưới dạng gốc của provider. Ba trong số các dạng được trình bày chi tiết bên dưới; tác dụng của wave trên mọi provider của thư viện chuẩn, kể cả terraform, được lập bảng tại providers/reference-matrix.md “What a boundary’s syncWave does on each provider”.

  • Kubernetes (provider helm / helm-chart). Khi wave khác 0, mọi tài nguyên Kubernetes mà provider helm kết xuất cho boundary đều mang annotation chuẩn GitOps argocd.argoproj.io/sync-wave: "<N>"; các Helm hook còn mang thêm annotation helm.sh/hook-weight: "<N>" để cùng một giá trị wave điều khiển thứ tự pre/post-install của chính Helm. ArgoCD đọc annotation sync-wave và Helm đọc weight của hook, và mỗi bên sắp xếp thứ tự áp dụng tài nguyên tương ứng. Provider helm-chart sao chép các template của chart nguồn đúng như tác giả đã viết, nên các tài nguyên riêng của một sub-chart chỉ mang wave ở những nơi các template đó ghi nó; một artifact được tải bằng $import: mà provider này thêm vào thì mang argocd.argoproj.io/sync-wave và không mang helm.sh/hook-weight (xem providers/helm-chart.md).
  • Compose. Mọi service trong tệp compose mà một boundary render vào đều chờ, thông qua depends_on, các service của wave liền trước đã đóng góp vào cùng tệp đó — chờ đến khi đích khỏe mạnh nếu đích khai báo healthcheck, và chờ đến khi đích khởi động nếu không. Vì vậy wave sắp xếp thứ tự các service của một tệp và không gì bên ngoài nó: các boundary render vào các tệp docker-compose.yaml riêng biệt là các dự án compose riêng biệt, và việc sắp xếp thứ tự giữa chúng là việc của operator. Các cạnh uses: tiếp tục biểu thị thứ tự theo từng cạnh song song với wave. Xem providers/compose.md.
  • CloudFormation. Mọi tài nguyên trong template stack đã lắp ráp đều phụ thuộc, thông qua DependsOn, vào các tài nguyên của wave liền trước đã đóng góp vào cùng stack đó — vì vậy wave cố định thứ tự tạo tài nguyên và, theo chiều ngược lại, thứ tự xóa chúng. Đây không phải là sắp thứ tự theo trạng thái sẵn sàng: template stack không có khái niệm một tài nguyên đã sẵn sàng phục vụ. DependsOn riêng của một fragment được mở rộng chứ không bị thay thế. Components được lắp ráp vào một stack khác thì nằm ngoài phạm vi, và việc sắp thứ tự giữa hai stack là việc của operator. Xem providers/cloudformation.md.

Đơn vị khai báo wave và đơn vị triển khai. Boundary là đơn vị khai báo wave. Đơn vị triển khai là đường dẫn lắp ráp mà các component phát vào — mặc định tương ứng 1:1 với boundary, nhưng hai boundary anh em dùng chung một directory: sẽ gộp thành một đầu ra lắp ráp duy nhất (một Chart.yaml, một docker-compose.yaml). Khi đó, đầu ra lắp ráp có thể chứa tài nguyên từ nhiều wave; một ArgoCD Application đọc đầu ra đó sẽ sắp xếp, trong Application, từng tài nguyên theo annotation sync-wave mà tài nguyên đó mang — trên helm là mọi tài nguyên được kết xuất cho một wave khác 0, còn trên helm-chart chỉ là artifact được tải bằng $import:, các template riêng của sub-chart thì mang những gì tác giả của chúng đã viết. Việc sắp xếp thứ tự giữa các Application qua các đường dẫn là việc của CI của operator.

Trường hợp sử dụng. Thứ tự wave quan trọng bất cứ khi nào việc khởi động một boundary phụ thuộc vào việc một boundary khác đã hoàn tất trước đó. Mẫu điển hình: một boundary infra ở wave 0 (VPC + cơ sở dữ liệu), một boundary migrations ở wave 1 (job migration schema) và một boundary apps ở wave 2 (ứng dụng sử dụng schema đã migrate). Nếu không có wave rõ ràng, cả ba sẽ triển khai đồng thời và ứng dụng bị crash-loop trong khi chờ migration hoàn tất.

Để xem toàn bộ khung kiến trúc — mô hình thực thi DAG, lý do đặt việc sắp xếp thứ tự theo thời gian trên Release thay vì Aggregate, và sự phân biệt giữa đơn vị khai báo wave và đơn vị triển khai — xem architecture/12-day-two-lifecycles.md §1.

Gắn Feature

Release có thể gắn Features ở cả phạm vi boundary (chính sách rộng) lẫn phạm vi riêng của từng component (nhắm mục tiêu chính xác), với việc thực thi tuân theo Mô hình Củ hành 5 tầng được định nghĩa trong architecture/10-compilation-pipeline.md. Features được khai báo trong Release đóng góp type, infra và uses; chúng không thể khai báo values (xem Ràng buộc ở cấp schema ở trên).

Một Feature được gắn tại một boundary được định danh bằng một tên instance do bạn chọn, và tên đó không thể là . hoặc ... Trên một provider cấp cho mỗi bên đóng góp một thư mục riêng — terraform, dưới modules/, và helm-chart, dưới charts/ — các tệp của một Feature cấp boundary được ghi vào một thư mục chỉ mang tên instance, và không tên nào trong hai tên đó là một thư mục riêng: bản build dừng lại, nêu tên Release, boundary và instance. Một tên chỉ đơn thuần chứa dấu chấm, chẳng hạn audit.v2, là một tên bình thường.

features: là bề mặt gắn duy nhất của Release, ở cả hai phạm vi — giống như của Aggregate. Một thông tin xác thực là một Feature mang nhãn feature.aggrega.ai/kind: secret, vì vậy một thông tin xác thực do Operator gắn được gắn dưới features: như mọi Feature khác, và nêu tên secret của nó trong infra đúng như một thông tin xác thực trên một kết nối (xem Cấu hình kết nối theo từng cạnh) — trên một component mà Aggregate để lại không có thông tin xác thực, hoặc làm phần định cỡ cho một lần gắn mà Aggregate đã khai báo mà không nêu tên secret. Không có từ khóa gắn thứ hai ở bất kỳ phạm vi nào; một tài liệu khai báo từ khóa như vậy bị từ chối khi tải với một lỗi envelope nêu tên thuộc tính không mong đợi.

Một feature được gắn trên toàn boundary có thể mang một khối uses:, và khối đó được chiếu tới mọi component được định tuyến vào boundary: mỗi component có thêm một cạnh phụ thuộc tới các đích được feature nêu tên và được tiêm provides của các đích đó. Cách này biểu đạt một phụ thuộc dùng chung một lần duy nhất tại boundary — “mọi component trong boundary này giao tiếp với cache / collector / message bus dùng chung” — thay vì lặp lại cùng một cạnh uses: trên từng component. Một lần gắn Feature ở cấp subsystem trong Aggregate cũng chiếu uses: của nó theo cùng cách tới các component của subsystem. uses là một khai báo nối dây topology, không phải một giá trị, nên được phép dùng trên Release. Phép chiếu không phụ thuộc vào phạm vi thực thi của Feature được gắn: một Feature có FeatureRecipe render một lần cho mỗi boundary vẫn chiếu uses: của nó cho từng component, trong khi bản thân tài nguyên dùng chung chỉ render một lần.

Một feature được gắn vào một component duy nhất mang cùng khối uses: và nối cùng cạnh từ chính component đó: component có thêm một cạnh phụ thuộc tới từng đích được nêu tên, được tiêm provides của các đích đó, và cạnh ghi nhận lần gắn là nguồn gốc của nó đúng như dạng gắn trên toàn boundary. Hai dạng này là một khai báo ở hai độ rộng — gắn tại boundary để nối mọi component trong đó, gắn trên một component để nối riêng component đó — và việc chọn giữa chúng là vấn đề phạm vi tác động, không bao giờ là vấn đề phép nối làm gì. Không dạng nào tạo ra compute: đích phải đã nêu tên một component mà Aggregate khai báo, và một đích không như vậy sẽ dừng bản build. Một kết nối do Feature vẽ không mang lần gắn nào của riêng nó: mục của nó nhận target và inject, và một khóa features: ở đó bị từ chối khi Release được tải.

boundaries:
cluster:
directory: ./dist/cluster
components:
api:
features:
shared_backend:
type: core/shared-backend
uses:
backend:
primary:
target: db # a component of the assembled graph
inject:
env:
- in: DB_HOST
from: host # db's `host` provides reaches api as DB_HOST
db: {}

Cách viết một đích. Một đích cạnh nêu tên một component của đồ thị đã lắp ráp, nên nó được viết bằng đường dẫn dấu chấm đầy đủ — data.store, không phải store — mỗi khi đích thuộc về một sub-module được định tuyến. Điều đó vẫn đúng ngay cả khi bản thân lần gắn nằm dưới một mục định tuyến, nơi các khóa components: là cục bộ theo module: khóa cho biết lần gắn nằm trên component nào và đích cho biết cạnh tới component nào, và chỉ cái thứ hai là tên trên toàn đồ thị. Một đích được viết bằng tên cục bộ theo module không khớp với component nào và dừng lại với cùng chẩn đoán mà mọi cạnh treo tạo ra.

Release tổng hợp và kế thừa extends:

Một Release có thể khai báo spec.extends: trỏ tới một Release cơ sở mà nó kế thừa bề mặt soạn thảo.

Tham chiếu là đường dẫn tới một tệp nằm cạnh Release khai báo — ./base-release.yaml, hoặc ../shared/base-release.yaml. Một Release thuộc phía triển khai và không được lập chỉ mục trong catalog, vì vậy một tham chiếu extends: không bao giờ được phân giải qua catalog. Đường dẫn tương đối là dạng duy nhất được chấp nhận: một tham chiếu viết dưới dạng tọa độ registry bị từ chối, một tên trần cũng vậy, và mỗi trường hợp đều có chẩn đoán nêu dạng đường dẫn tương đối. extends: của một Manifest là trường hợp gần giống nhưng được đọc khác — nó nhận một đường dẫn tương đối hoặc metadata.name trần của một Manifest nằm cạnh Release — vì vậy hai dạng này không thể thay thế cho nhau, và một tên trần phân giải được trên một Manifest sẽ không phân giải được ở đây. Mỗi mắt xích của chuỗi được đọc theo cùng một cách: một Release cha đặt ở thư mục khác nêu Release cha của chính nó bằng một đường dẫn nằm cạnh chính nó, bất kể Release bạn đã nêu nằm ở đâu, giống hệt như $import: của parameters được phân giải cạnh nó. Đường dẫn phải dẫn tới một Release bên trong workspace, như mọi đường dẫn mà một Release viết — hoặc, với một Release được nêu bên ngoài workspace, bên trong thư mục chứa Release đó, và mọi mắt xích trong chuỗi của nó đều phải tuân theo điều này: một đường dẫn leo ra ngoài, hoặc bị một mắt xích đưa ra ngoài, sẽ bị từ chối trước khi tệp mà nó nêu được đọc.

Trình biên dịch theo dõi chuỗi khi Release được nạp — từ chối một chuỗi quay lại một tệp đã có trong chuỗi, một chuỗi vượt quá giới hạn độ sâu, và một tham chiếu không trỏ tới gì — rồi gộp chuỗi thành một Release đã phân giải duy nhất.

Những gì bạn kế thừa, bạn có thể thay thế theo từng khóa. Giá trị của bạn thắng, xuyên suốt xuống dưới, cho đến khi gặp một giá trị là một thể không thể chia nhỏ — một scalar, một danh sách, một template — mà bạn lấy nguyên hoặc thay thế nguyên. Bạn loại bỏ thứ đã kế thừa bằng cách viết nó là null. Đây là cùng quy tắc mà một Component, Feature và Manifest mở rộng tuân theo, nên tác giả đã gặp một trong số đó là đã gặp tất cả.

Áp dụng cho một Release: boundaries hợp nhất theo tên boundary và mỗi boundary theo từng khóa, components theo tên component, infra hợp nhất sâu, features theo tên instance rồi theo pillar; uses của một component theo socket rồi theo kết nối, trong đó một target mà con viết sẽ thay thế target được kế thừa, infra của kết nối hợp nhất theo từng khóa, và features của nó hợp nhất theo slot rồi theo pillar theo cùng quy tắc mà features riêng của một component tuân theo; directory, subDirectory, syncWave cùng các con trỏ Aggregate và Manifest là scalar và được thay thế.

Có hai thứ không được kế thừa:

  • Danh tính và nguồn gốc. Không trường metadata nào được kế thừa. metadata.environment là trường cần lưu ý: nó bắt buộc với mọi Release và về bản chất thuộc riêng từng Release, nên một Release con được render với môi trường của chính nó trong các nhãn nguồn gốc thay vì môi trường của Release cha.
  • Con trỏ Aggregate được kế thừa chứ không thể ghi đè. Release con không thể khai báo aggregate: — schema từ chối extends: và aggregate: trong cùng một tài liệu — nên Release con triển khai cùng Developer Intent với Release cơ sở.

Release con có thể bỏ qua manifest: để kế thừa của Release cơ sở, hoặc ghi đè nó cho Late Binding.

Một dạng định tuyến trên toàn chuỗi. boundaries: và components: loại trừ lẫn nhau trong một Release, và điều đó cũng đúng trên cả chuỗi: một Release cơ sở khai báo các boundary có tên và một Release con khai báo components cấp cao nhất sẽ bị từ chối, và chẩn đoán nêu cả hai tệp và cả hai khóa. Hãy chọn một dạng định tuyến và dùng nó xuyên suốt.

Mẫu cầu nối cho phát triển cục bộ. Trường hợp sử dụng điển hình là một nhà phát triển chạy Aggregate production của nhóm mình ở máy cục bộ mà không cần fork Aggregate hay sao chép topology boundary. Nhóm công bố một Release production; một Release cục bộ extends: nó và chỉ ghi đè con trỏ Manifest, thay các Recipes nhắm tới cloud bằng các bản tương đương cục bộ:

# production Release (committed; the source of truth for prod deployments)
apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: prod-release
environment: production
version: "1.0.0"
spec:
aggregate: my-app
manifest: prod-manifest
parameters:
region: us-east-1
db_size: 100Gi
out_dir: prod
boundaries:
prod:
# A directory is a TEMPLATE, not a fixed path. Writing it against a
# parameter is what lets a child render somewhere else without
# restating the boundary topology.
directory: deploy/{{ .parameters.out_dir }}
components:
api: { infra: { replicas: 5 } }
db: {}
---
# Local Release (developer-side; inherits everything, swaps the Manifest)
apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: local-release
environment: local
version: "1.0.0"
spec:
extends: ./prod-release.yaml
manifest: local-manifest # surgically overrides for local
parameters:
region: dev-local
db_size: 1Gi
out_dir: local # the inherited directory resolves here instead

local-release kế thừa topology boundary, các Feature được gắn và các ghi đè component của Release cơ sở; nhà phát triển chỉ giữ một local-release.yaml và chạy aggrega build --release local-release.yaml mà không sao chép cấu hình production nào.

Viết directory: dựa trên một tham số. Vì directory được kế thừa như mọi scalar khác, một Release con kế thừa một directory không chứa biến template sẽ render vào cùng đường dẫn mà Release cơ sở render vào, và không tùy chọn dòng lệnh nào chuyển hướng nó. Điều đó hợp lệ khi đó là ý định của bạn — chẳng hạn chỉ hoán đổi các Recipes để so sánh đầu ra — nên bản build báo cáo và tiếp tục thay vì từ chối. Viết directory dựa trên một tham số, như ở trên, giữ topology ở một nơi mà vẫn đưa đầu ra của mỗi Release tới một nơi riêng.

Phân lớp tham số nhiều tệp. Kế thừa Release là nơi dành cho phân lớp tham số nhiều tệp. Một Release cơ sở cung cấp bộ tham số chung; các Release con theo từng môi trường extends: Release cơ sở và ghi đè các slot khác biệt:

# base-release.yaml — common parameters
spec:
aggregate: my-app
parameters:
timeout_seconds: 30
feature_flags: { dark_mode: true }
---
# prod-release.yaml
spec:
extends: ./base-release.yaml
manifest: prod-manifest
parameters:
feature_flags: { dark_mode: false } # override one nested key
---
# staging-release.yaml
spec:
extends: ./base-release.yaml
manifest: staging-manifest

Mỗi Release con thấy các tham số kế thừa từ Release cơ sở được hợp nhất với tham số của chính nó. Tham số dạng map hợp nhất sâu với khóa của con thắng; tham số dạng scalar bị con thay thế; một khóa mà con viết là null bị loại bỏ thay vì được đặt thành rỗng.

Release cơ sở có thể import tham số và Release con vẫn có thể ghi đè từng khóa. Hai chế độ soạn thảo mô tả ở parameters: phía trên — inline, hoặc một $import: duy nhất — là quy tắc về một tài liệu, không phải về một chuỗi: mỗi Release trong chuỗi khai báo chế độ này hoặc chế độ kia, và import của mỗi Release được phân giải theo thư mục chứa Release đó trước khi chuỗi được gộp. Vì vậy một Release cơ sở import một tệp dùng chung và một Release con viết inline vài khóa sẽ hợp nhất theo từng khóa, giống hệt như hai khối inline:

# base-release.yaml — parameters arrive from a shared file beside it
spec:
aggregate: my-app
parameters:
$import: ./shared-params.yaml # tier: prod, region: eu
---
# local-release.yaml — overrides one key, inherits the rest
spec:
extends: ./base-release.yaml
manifest: local-manifest
parameters:
tier: local # region stays eu, from the imported file

Các chế độ lỗi. Chuỗi extends: vòng, con trỏ cha bị thiếu và khai báo aggregate: ở phía con đều dừng việc nạp workspace với chẩn đoán rõ ràng nêu Release vi phạm và vi phạm ở cấp schema. Xem errors/fatal-halts.md để biết dạng thông báo của từng lỗi.