Lược đồ Release của Aggrega
Tài liệu tham khảo được sinh tự động. Không chỉnh sửa thủ công — hãy sinh lại từ JSON Schema đã xuất bản.
Id lược đồ: https://aggrega.ai/schemas/release-v1beta1.schema.json
Xem tài liệu tham khảo về cách soạn Release để có hướng dẫn bằng văn xuôi về cách soạn các thực thể Release; trang này mô tả lược đồ cấu trúc mà tài liệu tham khảo đó trình bày.
Kiểu cấp cao nhất: object
Thuộc tính
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
apiVersion | const “aggrega.ai/v1beta1” | có | Hằng số: "aggrega.ai/v1beta1" |
kind | const “Release” | có | Hằng số: "Release" |
metadata | object | có | |
spec | object | có | Những gì Release liên kết và định tuyến: Aggregate và Manifest mà nó triển khai (hoặc một base extends), việc đáp ứng tham số theo từng môi trường, và các boundary mà các component của nó được định tuyến vào. |
Không cho phép thuộc tính bổ sung.
release.metadata
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
name | string | có | Dài ít nhất 1 ký tự. |
environment | string | có | |
version | string | có | Phiên bản theo Semantic Versioning nghiêm ngặt của bản phát hành (ví dụ: 1.0.0). Mẫu: ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$. |
description | string | không | Thực thể này là gì và dùng để làm gì, viết cho người đang cân nhắc có nên dùng nó hay không. Mở đầu bằng một câu gọi tên nó, sau đó bổ sung những gì người đọc cần để chọn và dùng nó đúng cách — nó kỳ vọng gì từ nền tảng mà nó được triển khai lên, và bất cứ điều gì bất ngờ trong cách nó hoạt động. Độ dài thông thường là một đoạn văn ngắn. |
maintainers | object[] | không | Danh sách những người bảo trì sở hữu thực thể này. |
license | string | không | Mã định danh SPDX cho giấy phép của phần mềm mà thực thể này mô tả, chẳng hạn MIT hoặc AGPL-3.0. Nó ghi lại các điều khoản của phần mềm đó, không phải các điều khoản của tệp này. |
repository | string | không | URL đến kho Git chứa các tệp nguồn. |
home | string | không | URL của trang chủ, wiki hoặc tài liệu của thực thể này. |
keywords | string[] | không | Danh sách các từ khóa mô tả giúp dễ tìm kiếm trên giao diện người dùng. |
Không cho phép thuộc tính bổ sung.
release.metadata.maintainers[]
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
name | string | có | |
email | string | không | |
url | string | không |
Không cho phép thuộc tính bổ sung.
release.spec
Những gì Release liên kết và định tuyến: Aggregate và Manifest mà nó triển khai (hoặc một base extends), việc đáp ứng tham số theo từng môi trường, và các boundary mà các component của nó được định tuyến vào.
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
aggregate | string | không | Tham chiếu đến Aggregate (Developer Intent) mà release này triển khai. Một token trần được phân giải theo danh tính — metadata.name của Aggregate được tham chiếu, được tìm trong thư mục riêng của Release rồi đến catalog. Một giá trị bắt đầu bằng ’./’ hoặc ’../’ là một tệp cục bộ tường minh được phân giải tương đối với Release (ví dụ: ’../shared/app.yaml’ để dùng chung một Aggregate giữa các biến thể release trong một thư mục con). |
manifest | string | không | Tham chiếu đến Manifest phân giải các giao diện trừu tượng mà release này triển khai dựa trên. Một token trần được phân giải theo danh tính — metadata.name của Manifest được tham chiếu, được tìm trong thư mục riêng của Release. Một giá trị bắt đầu bằng ’./’ hoặc ’../’ là một tệp cục bộ tường minh được phân giải tương đối với Release. Một Manifest thuộc phía triển khai và không được lập chỉ mục trong catalog, nên nó chỉ được phân giải từ thư mục của Release hoặc từ một đường dẫn tường minh. |
extends | string | không | Tham chiếu đến một Release cơ sở mà Release này kế thừa bề mặt soạn thảo — cây boundary của nó cùng hạ tầng và các phần đính kèm Feature theo từng component bên dưới, các tham số, các annotation và con trỏ Manifest của nó. Giá trị là đường dẫn đến một tệp nằm cạnh Release này, bắt đầu bằng ’./’ hoặc ’../’; cả tên trần lẫn tọa độ registry đều bị từ chối, vì một Release thuộc phía triển khai và không được lập chỉ mục trong catalog. Những gì được kế thừa có thể được thay thế theo từng khóa, xuống đến giá trị không thể chia nhỏ đầu tiên — một scalar, một danh sách, một template — vốn được thay thế toàn bộ; một khóa được ghi là null sẽ loại bỏ những gì đã được kế thừa. Không có trường metadata nào được truyền sang, nên một Release con mang tên, phiên bản và môi trường riêng của nó. Việc khai báo ‘aggregate’ cùng với ‘extends’ bị schema này từ chối, nên một Release con triển khai cùng Developer Intent với Release cơ sở của nó; ‘manifest’ vẫn là tùy chọn và có thể được ghi đè để thay đổi lockfile phụ thuộc. |
parameters | object | không | Hợp đồng đáp ứng biến theo từng môi trường với hai chế độ soạn thảo thông qua phân luồng theo hình dạng nội dung. Chế độ 1 (nội tuyến): một map YAML trực tiếp chứa các giá trị tham số lồng nhau có cấu trúc. Chế độ 2 (nhập tệp): một map YAML có đúng một khóa, $import: ./relative/path.yaml, trỏ đến một tệp cục bộ duy nhất cung cấp các giá trị tham số. Tại vị trí này chỉ có một nguồn duy nhất — việc phân lớp nhiều tệp thuộc phạm vi của các chuỗi extends: của Release (Release cha cung cấp các tham số cơ sở; Release con extends + ghi đè). |
boundaries | map của boundary | không | Các hộp logic gốc mà các component của Aggregate được định tuyến vào. Khóa: một hoặc nhiều chữ cái, chữ số, dấu gạch dưới hoặc dấu gạch ngang. Không cho phép dấu chấm. Mẫu: ^[a-zA-Z0-9_-]+$. |
components | map của boundary_component | không | Các thực thể component cấp cao nhất mang hạ tầng của operator theo từng component, dành cho một Release một phạm vi không có boundary được đặt tên. Loại trừ lẫn nhau với boundaries: khai báo components cho một Release phẳng hoặc boundaries cho định tuyến nhiều đích, không bao giờ cả hai. Khi dùng components, trình biên dịch tổng hợp một boundary default chứa chúng và xuất các artifact của chúng vào dist/ theo dạng phẳng. Khóa: một hoặc nhiều chữ cái, chữ số, dấu gạch dưới hoặc dấu gạch ngang. Không cho phép dấu chấm. Mẫu: ^[a-zA-Z0-9_-]+$. |
Không cho phép thuộc tính bổ sung.
Định nghĩa
boundary_component
Một thực thể component được định tuyến vào một boundary, với định cỡ vật lý và các gắn kết feature tùy chọn.
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
description | string | không | Tài liệu tùy chọn mô tả vai trò của component này trong boundary này của Release. |
subDirectory | string | không | Ghi đè đường dẫn con ở cấp Component, được nối vào thư mục của boundary cha. Nếu bị bỏ qua hoặc để trống ở cả boundary lẫn component, giá trị mặc định là ’{{ .capability }}’; một chuỗi rỗng được viết ở đây được coi như bị bỏ qua. Đặt thành ’.’, hoặc thành một template có kết quả là chuỗi rỗng, để tắt việc tạo thư mục con. |
annotations | map của string hoặc object hoặc null | không | Các annotation của Operator riêng cho Component, ghi đè các annotation ở cấp boundary cho component này. Được deep-merge lên trên các annotation của boundary (component thắng khi trùng khóa; các giá trị có cấu trúc được merge theo từng khóa con với các giá trị cha có cấu trúc). Giá trị là chuỗi, đối tượng có cấu trúc, hoặc null. Được dùng để ghi đè theo từng component các annotation phổ biến của provider (ví dụ: aggrega.ai/namespace trên provider helm). Giá trị null tường minh trên một khóa được kế thừa từ boundary cha sẽ gỡ liên kết được kế thừa khỏi component này (cách từ chối Feature dựa trên annotation); các component cùng cấp vẫn giữ liên kết được kế thừa. |
infra | object | không | Định cỡ vật lý chỉ áp dụng cục bộ cho component này (ví dụ: replicas, disk IOPS). |
features | map của object | không | Các Features được gắn vào component này thông qua Release. Với các feature cũng được khai báo trong Aggregate, chỉ infra được cung cấp (values đến từ Aggregate). Với các feature chỉ có trong Release (do Operator chèn vào), type là bắt buộc. Khóa là tên thực thể feature và có thể mang URI đầy đủ của kiểu feature (cho phép dấu chấm và dấu gạch chéo). Release KHÔNG ĐƯỢC cung cấp values cho các feature — đây là phạm vi của Developer. Khóa: một hoặc nhiều chữ cái, chữ số, dấu gạch dưới, dấu chấm, dấu gạch chéo hoặc dấu gạch ngang. Mẫu: ^[a-zA-Z0-9_./-]+$. |
uses | release_uses_block | không | Bề mặt cạnh dành cho Operator. Trong phạm vi các socket do Architect khai báo, Release có thể nối một socket đã khai báo nhưng chưa được bind tới một component hiện có (target) và/hoặc cung cấp infra theo từng cạnh. Không có values (lệnh cấm values: của Release vẫn áp dụng) và không tạo compute; việc đổi target của một cạnh do developer khai báo sẽ dừng lại khi build. |
Không cho phép thuộc tính bổ sung.
release_uses_block
Bề mặt uses theo từng cạnh do Release viết, phân khóa theo socket rồi theo alias (phản chiếu hình dạng topology uses của Aggregate). Mỗi kết nối có thể đặt target (để tạo một cạnh vào một socket đã khai báo nhưng chưa được bind, trỏ tới một component hiện có), infra (cấu hình operator theo từng cạnh, được xác thực theo infraSchema của socket khi Release được phân giải) và features (các gắn kết lấp đầy các slot mà socket khai báo), theo bất kỳ tổ hợp nào. values bị cấm (lệnh cấm values: của Release); việc đổi target của một cạnh do developer khai báo là một rào chắn báo lỗi rõ ràng khi build.
Khóa: một hoặc nhiều chữ cái, chữ số, dấu gạch dưới hoặc dấu gạch ngang. Không cho phép dấu chấm. Mẫu: ^[a-zA-Z0-9_-]+$.
Giá trị là map of object.
Không cho phép bất kỳ khóa nào khác.
release_connection_attachment
Một gắn kết mà một mục kết nối của Release mang theo: Feature lấp đầy một slot mà socket của kết nối khai báo, cùng với định cỡ của operator cho nó.
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
type | string | không | URI của Feature. Bắt buộc với một gắn kết chỉ do Release tạo. Phải khớp với type của Aggregate nếu cả hai cùng khai báo. |
description | string | không | Tài liệu tùy chọn giải thích lý do Operator gắn feature này vào kết nối. |
infra | object | không | Định cỡ vận hành cho gắn kết này, được xác thực theo khai báo schema của Feature. |
Không cho phép thuộc tính bổ sung.
aggregate_routing
Định tuyến các component nội bộ của một module con Aggregate lồng nhau vào boundary này. Phản chiếu cấu trúc component/aggregate của boundary để phục vụ việc kết hợp đệ quy.
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
components | map của boundary_component | không | Các thể hiện Component trong aggregate lồng nhau cần định tuyến vào boundary này. Khóa là tên cục bộ mà mỗi component mang bên trong sub-module đó — ‘main-db’ cho component mà map components của chính một boundary gọi là ‘data.main-db’ — vì đó là tên duy nhất nó có ở đó. Khóa: một hoặc nhiều chữ cái, chữ số, dấu gạch dưới hoặc dấu gạch nối. Không cho phép dấu chấm. Mẫu: ^[a-zA-Z0-9_-]+$. |
aggregates | map of aggregate_routing | không | Các aggregate lồng sâu hơn bên trong aggregate con này (cho việc kết hợp module lồng nhau nhiều tầng). Khóa: một hoặc nhiều chữ cái, chữ số, dấu gạch dưới hoặc dấu gạch ngang. Không cho phép dấu chấm. Mẫu: ^[a-zA-Z0-9_-]+$. |
Không cho phép thuộc tính bổ sung.
boundary
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
description | string | không | Tài liệu tùy chọn mô tả mục đích và đích vật lý của boundary này (ví dụ: ‘Primary production EKS cluster in us-east-1, PCI-DSS compliant’). |
directory | string | không | Đường dẫn đầu ra vật lý để sinh artifact GitOps. Hỗ trợ các biến template Go ({{ .capability }}, {{ .boundary_name }}, {{ .parameters.X }}). Được nối với subDirectory theo kiểu nối đường dẫn để tạo ra đường dẫn artifact cuối cùng. |
subDirectory | string | không | Đường dẫn con ở cấp boundary được nối thêm vào directory. Nếu bị bỏ qua hoặc để trống ở cả boundary lẫn component, mặc định là ’{{ .capability }}’ để tự động phân vùng CI/CD; một chuỗi rỗng viết ở đây được hiểu là bị bỏ qua. Đặt thành ’.’, hoặc thành một template cho kết quả là chuỗi rỗng, để vô hiệu hóa. |
syncWave | integer | không | Wave triển khai tùy chọn theo từng boundary (số nguyên có dấu, mặc định 0). Mọi component trong boundary này kế thừa wave của boundary vào node của nó. Cho phép giá trị âm (chạy trước mọi thứ khác); giá trị lớn hơn chạy sau giá trị nhỏ hơn. Trên K8s và Helm, wave là thứ quyết định thứ tự triển khai: nó trở thành annotation argocd.argoproj.io/sync-wave, và trên một resource mà chart đã đánh dấu là Helm hook, nó cũng trở thành helm.sh/hook-weight của hook đó. Trên compose, wave vừa được ghi lại dưới dạng label của service vừa sắp thứ tự các service của tệp mà nó được render vào, thông qua depends_on giữa chúng — vì vậy nó áp dụng cho mọi service trong đúng tệp đó và không gì bên ngoài. Trên cloudformation, wave sắp thứ tự việc cấp phát stack mà boundary được lắp vào: mọi resource trong một wave được khai báo là phụ thuộc vào các resource của wave trước nó, điều này cố định thứ tự chúng được tạo và, theo chiều ngược lại, thứ tự chúng bị xóa. Đó chỉ là thứ tự tạo và xóa — một stack template không thể hiện khái niệm resource đã sẵn sàng, nên không có gì chờ một resource trở nên khả dụng. Trên terraform, wave sắp thứ tự các khối module của cấu hình gốc mà boundary được lắp vào: mọi module trong một wave được khai báo là phụ thuộc vào các module của wave trước nó, điều này cố định thứ tự engine thực hiện các hành động. Đó chỉ là thứ tự hành động — một cấu hình không thể hiện khái niệm resource đã sẵn sàng, nên không có gì chờ một resource trở nên khả dụng — và giá trị này cũng được ghi lại cùng thông tin nguồn gốc build của node. Trình biên dịch mang cùng giá trị này lên mọi node trong boundary dưới dạng sync_wave của node đó, nơi hành vi theo từng đích được mô tả lại từ phía node. Các boundary lồng nhau không ngầm kế thừa — mỗi boundary tự khai báo wave của riêng mình. |
annotations | map của string hoặc object hoặc null | không | Các annotation Operator trên toàn boundary, truyền xuống bucket .context.annotations.release. Giá trị là chuỗi, đối tượng có cấu trúc hoặc null. Một giá trị có cấu trúc mang cấu hình theo từng khóa con, được deep-merge với giá trị cha có cấu trúc (theo từng khóa con, giá trị con thắng) và đi qua quá trình mở rộng Feature dựa trên annotation; chỉ các giá trị vô hướng xuất hiện trong ngữ cảnh render. Null tường minh trên một khóa kế thừa từ boundary cha sẽ gỡ liên kết được kế thừa khỏi tập annotation hiệu lực của boundary này (từ chối Feature dựa trên annotation), lan truyền đến mọi component được định tuyến vào boundary này trừ khi một ghi đè sâu hơn đưa liên kết trở lại. |
features | map của object | không | Các feature trên toàn boundary áp dụng cho mọi component lồng bên trong (ví dụ: security mesh mặc định). Khối uses của một feature được chiếu tới mọi component trong boundary, khai báo một phụ thuộc dùng chung một lần tại boundary thay vì lặp lại trên từng component. Khóa là tên instance của feature và có thể mang URI đầy đủ của kiểu feature (cho phép dấu chấm và dấu gạch chéo). Khóa: một hoặc nhiều chữ cái, chữ số, dấu gạch dưới, dấu chấm, dấu gạch chéo hoặc dấu gạch nối. Mẫu: ^[a-zA-Z0-9_./-]+$. |
boundaries | map của boundary | không | Các boundary logic lồng nhau (ví dụ: các namespace trong một cluster). Khóa: một hoặc nhiều chữ cái, chữ số, dấu gạch dưới hoặc dấu gạch nối. Không cho phép dấu chấm. Mẫu: ^[a-zA-Z0-9_-]+$. |
components | map của boundary_component | không | Những component nào từ Aggregate được đặt vào boundary này. Khóa là tên instance của component; component của một aggregate con được tham chiếu bằng đường dẫn đầy đủ phân tách bằng dấu chấm (ví dụ: ‘data.main-db’ — tên instance của aggregate, một dấu chấm, tên component). Khóa: một hoặc nhiều chữ cái, chữ số, dấu gạch dưới, dấu chấm hoặc dấu gạch nối. Mẫu: ^[a-zA-Z0-9_.-]+$. |
aggregates | map of aggregate_routing | không | Định tuyến các component của module con Aggregate lồng nhau vào boundary này. Khóa là tên instance của aggregate khớp với map spec.aggregates của Aggregate. Nếu có định nghĩa boundary, mọi instance aggregate phải được đặt vào đúng một boundary. Khóa: một hoặc nhiều chữ cái, chữ số, dấu gạch dưới hoặc dấu gạch nối. Không cho phép dấu chấm. Mẫu: ^[a-zA-Z0-9_-]+$. |
Không cho phép thuộc tính bổ sung.
uses_block
Cấu trúc liên kết — do Developer sở hữu. Khai báo các cạnh mạng logic và các phụ thuộc.
Khóa: một hoặc nhiều chữ cái, chữ số, dấu gạch dưới hoặc dấu gạch ngang. Không cho phép dấu chấm. Mẫu: ^[a-zA-Z0-9_-]+$.
Giá trị là string[] or map of object.
Không cho phép bất kỳ khóa nào khác.
inject_block
Định tuyến injection không phụ thuộc cơ chế trên một kết nối. Ánh xạ các biến cục bộ sang các khóa provides của đích. Mỗi cơ chế phân phối (env, file, arg hoặc custom) được viết dưới dạng một mảng các mục {in, from} — với ‘from’ tường minh cho các tham chiếu provides. Một cơ chế tùy chỉnh có thể mang bất kỳ tên nào ngoại trừ all: một template đọc mọi cơ chế được gộp thành một khung nhìn tại .context.inject.all, nên một cơ chế mang tên đó sẽ bị khung nhìn này che khuất, và việc đặt tên như vậy sẽ dừng bản build.
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
env | inject_delivery | không | Một cơ chế phân phối duy nhất, được viết dưới dạng một mảng các mục. Mỗi mục mang một ‘in’ (định danh cục bộ — tên biến môi trường, đường dẫn tệp, cờ đối số, hoặc khóa riêng của cơ chế tùy chỉnh) cùng đúng một trong hai: ‘from’ (một khóa provides cần phân giải) hoặc ‘value’. Trên một Release, mọi mục đều nằm trên một kết nối, nên ‘from’ được phân giải theo provides của đích và một mục mang ‘value’ sẽ bị từ chối. |
file | inject_delivery | không | Một cơ chế phân phối duy nhất, được viết dưới dạng một mảng các mục. Mỗi mục mang một ‘in’ (định danh cục bộ — tên biến môi trường, đường dẫn tệp, cờ đối số, hoặc khóa riêng của cơ chế tùy chỉnh) cùng đúng một trong hai: ‘from’ (một khóa provides cần phân giải) hoặc ‘value’. Trên một Release, mọi mục đều nằm trên một kết nối, nên ‘from’ được phân giải theo provides của đích và một mục mang ‘value’ sẽ bị từ chối. |
arg | inject_delivery | không | Một cơ chế phân phối duy nhất, được viết dưới dạng một mảng các mục. Mỗi mục mang một ‘in’ (định danh cục bộ — tên biến môi trường, đường dẫn tệp, cờ đối số, hoặc khóa riêng của cơ chế tùy chỉnh) cùng đúng một trong hai: ‘from’ (một khóa provides cần phân giải) hoặc ‘value’. Trên một Release, mọi mục đều nằm trên một kết nối, nên ‘from’ được phân giải theo provides của đích và một mục mang ‘value’ sẽ bị từ chối. |
inject_delivery
Một cơ chế phân phối duy nhất, được viết dưới dạng một mảng các mục. Mỗi mục mang một ‘in’ (định danh cục bộ — tên biến môi trường, đường dẫn tệp, cờ đối số, hoặc khóa riêng của cơ chế tùy chỉnh) cùng đúng một trong hai: ‘from’ (một khóa provides cần phân giải) hoặc ‘value’. Trên một Release, mọi mục đều nằm trên một kết nối, nên ‘from’ được phân giải theo provides của đích và một mục mang ‘value’ sẽ bị từ chối.
Loại: object[]